docs: 添加通讯架构总览文档
This commit is contained in:
commit
4b2f8fa28b
188
docs/communication-architecture.md
Normal file
188
docs/communication-architecture.md
Normal file
@ -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端口重复）
|
||||
Loading…
Reference in New Issue
Block a user