From 4b2f8fa28b57d532afcda6153b227a53640811de Mon Sep 17 00:00:00 2001 From: sxbh_admin <2355579817@qq.com> Date: Wed, 27 May 2026 10:56:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=80=9A=E8=AE=AF?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E6=80=BB=E8=A7=88=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/communication-architecture.md | 188 +++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/communication-architecture.md diff --git a/docs/communication-architecture.md b/docs/communication-architecture.md new file mode 100644 index 0000000..93df745 --- /dev/null +++ b/docs/communication-architecture.md @@ -0,0 +1,188 @@ +# 通讯架构总览 + +> 编制时间：2026-05-27 +> 系统：Hermes Agent + OpenClaw Gateway +> 服务器：sxbh.ltd + +--- + +## 一、整体架构图 + +``` + ┌──────────────────────────────────────────────────────────────────┐ + │ 公网 (sxbh.ltd) │ + │ :443 │ + └──────────────────────────┬──────────────────────────────────────┘ + │ Nginx + │ + ┌─────────────────────────────────┼─────────────────────────────────────┐ + │ │ │ + ┌────────▼────────┐ ┌─────────▼─────────┐ ┌────────────▼────┐ + │ /plugins/digital│ │ /plugins/wecom/ │ │ 其他站点 │ + │ /{name}/ │ │ /agent/{name}/ │ │(cma/learn/...) │ + └────────┬────────┘ └─────────┬─────────┘ └─────────────────┘ + │ │ + ┌──────────┴──────────┐ ┌─────────────┴─────────────┐ + ▼ ▼ ▼ ▼ + ┌────────────┐ ┌──────────────┐ ┌─────────────────────────────────────────────┐ + │ Hermes │ │ Hermes │ │ OpenClaw Node Gateway │ + │ Python │ │ Python │ │ (PID 689975, :18789) │ + │ Gateway #1 │... │ Gateway #6 │ │ │ + │ (数字员工) │ │ (数字员工) │ │ ┌──────────┐ ┌────────┐ ┌───────────┐ │ + └──────┬─────┘ └──────┬───────┘ │ │ WeCom │ │ QQ Bot│ │ Weixin │ │ + │ │ │ │ (11个助理)│ │ │ │ (未配置) │ │ + │ │ │ └─────┬────┘ └───┬───┘ └───────────┘ │ + │ │ └───────┼────────────┼──────────────────────┘ + │ │ │ │ + ▼ ▼ │ │ + ┌──────────┐ ┌──────────┐ │ │ + │ Dev- │ │ Hermes │ │ │ + │ Architect│ │ API │ │ │ + │ Profile │ │ :8644 │◄─────────────┘ │ + │ :8661 │ │ │ │ + └──────────┘ └──────────┘ │ + │ + ┌───────────┴───────────┐ + │ QQ机器人群/私信 │ + │ (1903900435) │ + └───────────────────────┘ +``` + +--- + +## 二、数字员工通道（Hermes Python Gateway） + +每个数字员工独立运行一个 Hermes Python Gateway，通过企微自建应用的接收消息回调接收消息。 + +| 数字员工 | 企微AgentID | 企微应用名 | 回调路径 | Callback端口 | API端口 | +|---------|------------|----------|---------|-------------|--------| +| 数字员工-01-架构师 | 1000031 | dev-architect | `/plugins/digital/architect/wecom/callback` | 8661 | 8644 | +| 数字员工-02-前端开发 | 1000032 | dev-frontend | `/plugins/digital/frontend/wecom/callback` | 8652 | 8647 | +| 数字员工-03-后端开发 | 1000033 | dev-backend | `/plugins/digital/backend/wecom/callback` | 8653 | 8645 | +| 数字员工-04-运维部署 | 1000034 | dev-ops | `/plugins/digital/ops/wecom/callback` | 8654 | 8649 | +| 数字员工-05-测试工程师 | 1000035 | dev-qa | `/plugins/digital/qa/wecom/callback` | 8655 | 8650 | +| 数字员工-06-全栈开发 | 1000036 | dev-fullstack | `/plugins/digital/fullstack/wecom/callback` | 8656 | 8648 | + +**消息流转路径：** +``` +用户微信 → 企微服务器 → Nginx(:443) → /plugins/digital/{name}/ → Hermes Python Gateway(:callback端口) → DeepSeek API → 回复 +``` + +当前运行状态：6个数字员工全部 ✅ 正常运行 + +--- + +## 三、数字总控（dev-digital） + +数字总控是一个特殊的 Hermes Gateway，它监听**所有6个数字员工**的企微回调，可做集中路由或消息分发。 + +| 项目 | 值 | +|------|-----| +| Profile | dev-digital | +| 监听的AgentIDs | 1000031~1000036 | +| Callback端口 | 8630 | +| API端口 | 8646 | +| 回调路径 | `/plugins/digital/digital/wecom/callback` | + +**注意：** dev-digital 的 callback 端口 8630 在 Nginx 中没有独立配置，如需启用需要添加 Nginx 路由。 + +--- + +## 四、总经理助理及员工助理通道（OpenClaw Node Gateway） + +通过 OpenClaw Node Gateway 的 WeCom 插件，以 webhook 模式接收企微消息。 + +| 角色 | 企微AgentID | 企微应用名 | 模型 | 类型 | +|------|------------|----------|------|------| +| **总经理助理** | 1000020 | admin-ren | hermes/hermes-agent | 默认助理 | +| 助理-王婧 | 1000021 | wangjing | 默认 | 员工助理 | +| 助理-李亚玲 | 1000022 | liyaling | 默认 | 员工助理 | +| 助理-陈艳 | 1000023 | chenyan | 默认 | 员工助理 | +| 助理-董均国 | 1000024 | dongjunguo | 默认 | 员工助理 | +| 助理-蒋亚文 | 1000025 | jiangyawen | 默认 | 员工助理 | +| 助理-田顺利 | 1000026 | tianshunli | 默认 | 员工助理 | +| 助理-贾妮 | 1000027 | jiani | 默认 | 员工助理 | +| 助理-付世祥 | 1000028 | fushixiang | 默认 | 员工助理 | +| 助理-李巧玲 | 1000037 | liqiaoling | 默认 | 员工助理 | +| 助理-蒋晓荣 | 1000029 | jiangxiaorong | 默认 | 员工助理 | + +**消息流转路径：** +``` +用户微信 → 企微服务器 → Nginx(:443) → /plugins/wecom/agent/{name}/ → OpenClaw(:18789) + → Hermes Agent API(:8644/v1, dev-architect profile) → DeepSeek API → 回复 +``` + +总经理助理（admin-ren）默认使用 `hermes/hermes-agent` 模型，通过 OpenClaw 配置的 Hermes Provider (`http://127.0.0.1:8644/v1`) 调用 Hermes Agent API 处理。 + +当前运行状态：所有11个助理 ✅ 正常运行 + +--- + +## 五、QQ Bot 通道 + +| 项目 | 值 | +|------|-----| +| Bot ID | 1903900435 | +| 通道 | OpenClaw QQBot 频道/私信/群聊 | +| 状态 | ✅ WebSocket 已连接 | +| 默认模型 | deepseek/deepseek-chat | + +**消息流转路径：** +``` +用户QQ → QQ Bot服务器 → WebSocket → OpenClaw(:18789) → DeepSeek API → 回复 +``` + +--- + +## 六、微信个人号通道（wechat-renfuhai） + +| 项目 | 值 | +|------|-----| +| Profile | wechat-renfuhai | +| iLink账号 | 2783fe13fa99@im.bot | +| API端口 | 8651 | +| 状态 | ✅ 已连接（2026-05-27 重新扫码） | + +**消息流转路径：** +``` +用户微信 → iLink API → Hermes Python Gateway(:8651) → DeepSeek API → 回复 +``` + +⚠️ 注意：微信个人号由独立的 Hermes Python Gateway 管理，**不经过 OpenClaw**。 + +--- + +## 七、辅助服务 + +| 服务 | 端口 | 用途 | 状态 | +|------|------|------|------| +| wecom-auth | 4180 | 企微 OAuth2 登录认证 | ✅ 运行中 | +| wecom-contact-http | 18900 | 企微通讯录 HTTP MCP 服务 | ✅ 运行中 | +| erp-gateway | 8300 | ERP 数据只读接口网关 | ✅ 运行中 | +| Nginx | 80/443 | 反向代理 / SSL 终止 | ✅ 运行中 | + +--- + +## 八、端口总表 + +| 端口 | 服务 | Profile/用途 | +|------|------|-------------| +| 80 | Nginx HTTP | HTTP 重定向 | +| 443 | Nginx HTTPS | 主入口 | +| 18789 | OpenClaw Gateway | 企微/QQ通道 | +| 8642~8656 | 多个Hermes API | 数字员工 API Server | +| 8630 | dev-digital | 数字总控回调 | +| 8651 | wechat-renfuhai | 微信个人号 API | +| 8661 | dev-architect | 架构师回调 | +| 8652~8656 | 各数字员工 | 各数字员工回调 | +| 18900 | wecom-contact | 通讯录服务 | +| 4180 | wecom-auth | OAuth服务 | + +--- + +## 九、已知问题 / 待办 + +1. **dev-digital** 的 Nginx 路由未配置（端口8630），如果要启用数字总控的独立回调地址，需要在 Nginx 中添加 +2. **微信个人号** 的 iLink Token 会过期，需定期重新扫码 +3. 系统重启后，Hermes Python Gateway 需要手动启动（未配置 systemd 服务），建议后续配置 systemd 自动启动 +4. **Nginx** 存在多个 server_name 冲突警告（sxbh.ltd 在80/443端口重复） \ No newline at end of file