克微 App 私信（聊天）功能说明与配置指南

它不是 PHP「聊天插件」克微 App 的私信，不是单独装一个 emlog 聊天插件就能通的。

一、架构是三层配合：

可以把它理解成：PHP 负责「你是谁」；Go 负责「聊什么」；App 负责界面。

未配置 Go 地址时，App 里仍能点开私信，但只是本机预览（数据留在手机本地），换机 / 换账号看不到同一份会话。

二、App 里有哪些功能

1. 从文章进私信

• 文章详情作者行：「关注」旁边有 私信
• 点一下直接进入与该作者的一对一聊天（不用先回消息中心）
• 未登录会先去登录
• 自己的文章不显示私信；没有作者 UID 时隐藏按钮

2. 消息 Tab 里的私信列表

• 「消息」底部是 私信会话列表
• 只显示已经产生过内容的会话
• 未登录提示「登录后可查看私信」
• 已配置 Go 时，可显示未读数，并走远端同步

3. 聊天页

• 查看历史消息
• 发送文字私信
• 标记已读
• 配置了 Go + WebSocket 后，对方新消息可近实时推送（发信本身仍是 HTTP）

4. 隐私 / 策略（分两端）

三、服务端接口一览（Go）

Base：{GO_API_BASE}，例如生产 https://api.cweto.cn，本机 http://127.0.0.1:8093。

鉴权：请求头带 emlog 登录 Cookie（Web 可用 X-Emlog-Cookie；WS 还支持 query cookie=）。

健康检查：GET {GO_API_BASE}/health

四、怎么配置（按顺序做）

步骤 1：主站准备好克微 APP 插件

1. 安装并启用 克微 APP（emlog_client）
2. 后台打开开放接口，备好 API Key
3. 插件设置里保存 桥接密钥（Bridge Secret）

记下：

• 站点地址，如 https://www.cweto.cn
• 桥接地址：https://你的域名/content/plugins/emlog_client/api.php
• 桥接密钥、API Key

步骤 2：部署并配置 Go 服务

在服务器（或本机）进入仓库 go/ 目录：

cp .env.example .env

生产推荐（桥接模式）示例：

LISTEN_ADDR=127.0.0.1:8080
EMLOG_SITE_URL=https://www.cweto.cn
EMLOG_MODE=bridge
EMLOG_BRIDGE_URL=https://www.cweto.cn/content/plugins/emlog_client/api.php
EMLOG_BRIDGE_SECRET=这里填克微APP插件的桥接密钥
EMLOG_API_KEY=这里填emlog后台开放接口的API Key
WEBHOOK_SECRET=自拟一串给PHP回调用的密钥
CHAT_DATA_FILE=data/chat_store.json

说明：

• EMLOG_SITE_URL：PHP 主站，不要写成 api. 子域
• LISTEN_ADDR：生产建议只监听本机，前面用 Nginx / 宝塔反代到公网
• CHAT_DATA_FILE：一期私信落盘文件；要可写目录
• 三个密钥各管各的，不必相同

启动 Go 后验证：

curl -s http://127.0.0.1:8080/health

应能看到服务正常（桥接模式时 mode 为 bridge）。

步骤 3：给 Go 配公网域名（生产）

以克维为例：

• 主站：https://www.cweto.cn（PHP）
• API：https://api.cweto.cn → 反代到本机 127.0.0.1:8080

注意：

• api.cweto.cn 不用写进 Go 的 .env
• 在 DNS、宝塔「绑定域名」、反向代理里配即可
• WebSocket 路径 /api/v1/chat/ws 需要 Nginx 支持 Upgrade（长连接）

本机调试可把 Go 听在 8093，避免和 Flutter Web 默认 8080 打架：

LISTEN_ADDR=127.0.0.1:8093

步骤 4：App 写入 GO_API_BASE

复制 / 编辑品牌配置（如克微 brands/cweto/app_config.json → app_config.local.json）：

{
  "APP_DISPLAY_NAME": "克微",
  "API_PROXY_URL": "https://www.cweto.cn/content/plugins/emlog_client/api.php",
  "EMLOG_BRIDGE_SECRET": "与插件一致的桥接密钥",
  "GO_API_BASE": "https://api.cweto.cn"
}

本机联调示例：

"GO_API_BASE": "http://127.0.0.1:8093"

然后：

powershell -File tool\switch_brand.ps1 cweto -SkipIcons
flutter run --dart-define-from-file=app_config.local.json

步骤 5：（可选）后台私信策略

在克微 APP / CTR 相关「私信设置」里，可配置是否开放私信、是否允许陌生人、是否仅互关等。
App 发信前会结合策略接口判断；未配好时以插件默认策略为准。

五、怎么自测

1. 两个测试账号 A、B 都登录 App（或一端 App、一端能带 Cookie 的工具）
2. A 打开 B 的文章 → 点 私信 → 发一句
3. B 的「消息」私信列表应出现会话；聊天页能看到内容
4. 杀掉 App 再开：远端模式下会话仍在（本机预览模式只在本机有效）
5. 若配置了 WS：B 在线时，A 再发一条，B 应较快收到推送

常见失败：

六、和「消息四宫格」的区别

所以：装了克微 APP 插件 ≠ 私信已上线；还要部署 Go，并在 App 配置 GO_API_BASE。

七、小结

• 功能：一对一私信、会话列表、未读、已读、文章详情一键私信；可选 WebSocket 推送
• 配置：插件桥接 + Go .env + 反代域名 + App GO_API_BASE
• 没配 Go：界面在，数据只在本机
• 配好了：两端账号才能真正互通

更细的接口字段、改造清单见：

• docs/dm_feature_backend_todo.md
• go/README.md
• docs/app_config_guide.md（私信小节）