hmo/AgentsMeeting
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add HEALTH-PIPELINE + DASHBOARD, update DEPLOY/OPS/QUICKSTART/README — Linux 246 as production standard

Browse Source
This commit is contained in:
hmo
2026-07-19 10:09:42 +08:00
parent 94250e9dda
commit 0b345c2ca1
6 changed files with 438 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DASHBOARD.md
+119
View File
@@ -0,0 +1,119 @@
# AgentsMeeting — Dashboard 架构
> 版本: v1.0 | 部署: Linux 246 :5803 | 入口: http://192.168.1.246:5803
---
## Tab 结构
```
AgentsMeeting Dashboard
├── Agents — Agent 状态总览（在线/离线/消息量）
├── Kanban — 看板任务管理
├── Infrastructure — 平台服务 + EasyTier VPN + RDP + OpenCode Usage
└── 开发原则
├── G 规范 — 开发规范 / Spec 文档（dev-spec.md）
├── K 测试 — 测试报告（Tier1/Tier2）
├── F 健康 — 系统健康监控（三层管线）
└── H 需求 — 产品需求文档（PRD.md）
```
---
## API 端点清单
### Agent 管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/agents` | 所有 Agent 列表（状态/平台/JID/消息量） |
| GET | `/api/agents/<id>/logs?lines=50` | Agent 实时日志 |
| POST | `/api/agents/<id>/start` | 启动 Agent |
| POST | `/api/agents/<id>/stop` | 停止 Agent |
| POST | `/api/agents/<id>/restart` | 重启 Agent |
### 服务监控
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/services` | 所有注册服务状态（health ok/端口可达） |
| GET | `/api/expected` | 期望状态矩阵（含 key/spec/check 方式） |
| GET | `/api/monitor` | 聚合监控数据（tasks + Tier1 + Tier2） |
| GET | `/api/autoheal` | 最近一次自动修复记录 |
| GET | `/api/health` | Dashboard 自身健康检查 |
| GET | `/api/module-spec/<module>` | 读取 specs/{module}.json |
### 基础设施
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/platform` | 平台服务状态（xmpp_bot/article_processor 等） |
| GET | `/api/ejabberd` | ejabberd XMPP 服务器状态（在线用户列表） |
| GET | `/api/easytier` | EasyTier VPN 状态（各节点连通性） |
| POST | `/api/easytier/toggle` | EasyTier 开关 |
| GET | `/api/rdp` | RDP 远程桌面隧道状态 |
| POST | `/api/rdp/toggle` | RDP 隧道开关 |
| GET | `/api/usage` | OpenCode Go API 额度监控 |
| POST | `/api/usage/refresh` | 触发额度数据采集 |
### 知识管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/kanban` | 看板任务列表 |
| GET | `/api/spec` | 开发规范文档（dev-spec.md 渲染） |
| GET | `/api/spec/history` | 规范文档 Git 历史 |
| GET | `/api/tests` | 测试报告（Tier1/Tier2） |
| GET | `/api/prd` | 产品需求文档（PRD.md 渲染） |
| GET | `/api/prd/history` | PRD 文档 Git 历史 |
---
## 前端架构
### 技术栈
- 纯 HTML/CSS/JS（无框架）
- 深色主题（GitHub Dark 风格）
- 5 秒自动轮询（Agents / Infra 页）
### Spec 系统（?§ 按钮）
每个有 spec 的模块在 UI 上显示两个按钮：
- `?` → 调用 `showModuleHelp(module, 'human')` → 读取 `human_help` → 人类可读的帮助文档
- `§` → 调用 `showModuleHelp(module, 'ai')` → 读取 `ai_spec` → AI 可用的接口/约束/依赖
**Spec 文件位置**: `gateway/scripts/specs/{module}.json`
**API 端点**: `GET /api/module-spec/{module}` → 直接返回 JSON 文件内容
### F Tab 渲染逻辑
三层结构：
1. **系统概览** — 总健康状态 + 关键异常数 + T1 通过率
2. **异常服务** — critical 服务中实际状态异常的列表
3. **全部服务** — 按层分组（通信层 → AI网关 → 辅助服务），每项含 ?§ 按钮
定时任务单独渲染（从 `/api/monitor.tasks`），状态映射：
- `cron_ok` → 绿色 "正常"
- `not_deployed` → 黄色 "未部署"
- 其他 → 红色 "异常"
自动修复记录从 `/api/autoheal` 读取最近一次修复动作。
---
## 数据流
```
crontab (每 5 分钟)
├── agents_health_check.py → last_health_check.json
├── auto_heal.py → last_auto_heal.json
└── agents_daily_health.py → last_daily_health.json (每天)
Dashboard (:5803)
├── /api/monitor ← 聚合读取以上 JSON 文件
└── /api/services ← 实时 TCP/HTTP 检测
前端 (dashboard.html)
├── 5s 轮询 /api/services + /api/expected
└── 按需请求 /api/monitor（F Tab 打开时）
```
docs/DEPLOY.md
+20 -4
View File
@@ -1,6 +1,6 @@
# AgentsMeeting — 部署指南
> 版本: v2.0 | 日期: 2026-06-12
> 版本: v2.1 | 日期: 2026-07-19
---
@@ -9,11 +9,14 @@
| 组件 | 平台 | 守护 | 端口 |
|------|------|------|------|
| **Dashboard** | Linux (192.168.1.246) | systemd `agentsmeeting-dashboard` | 5803 |
| **health_check (Tier1)** | Linux (192.168.1.246) | crontab `*/5 * * * *` | — |
| **daily_health (Tier2)** | Linux (192.168.1.246) | crontab `0 8 * * *` | — |
| **todo_executor** | Linux (192.168.1.246) | crontab `*/10 * * * *` | — |
| **auto_heal** | Linux (192.168.1.246) | crontab `*/5 * * * *` | — |
| **xmpp_bot (xxm)** | Windows (192.168.1.16) | watchdog (30s) | 5802 |
| **wechat_agent** | Windows (192.168.1.16) | 内置看门狗 | 5801, 19088 |
| **api_proxy** | Windows (192.168.1.16) | watchdog | 8787 |
| **watchdog** | Windows (192.168.1.16) | 自身 | — |
| **health_check** | Windows (192.168.1.16) | Task Scheduler | — |
| **ejabberd** | Linux Docker (192.168.1.246) | Docker restart policy | 5222 |
| **hermes-gateway** | Linux (192.168.1.246) | systemd | 8642, 8643, 8645 |
| **mohe/xiaoguo/zhiwei bots** | Linux/Mac | systemd | — |
@@ -43,7 +46,20 @@ docker compose restart
docker exec ejabberd ejabberdctl connected_users
```
### 1.3 防火墙
### 1.3 健康监控管线
```bash
# 添加到 crontab
(crontab -l 2>/dev/null; echo '# AgentsMeeting health pipeline'; echo '*/5 * * * * cd /home/hmo/AgentsMeeting/gateway/scripts && /usr/bin/python3 agents_health_check.py >> ../logs/health_check.log 2>&1'; echo '0 8 * * * cd /home/hmo/AgentsMeeting/gateway/scripts && /usr/bin/python3 agents_daily_health.py >> ../logs/daily_health.log 2>&1'; echo '*/10 * * * * cd /home/hmo/AgentsMeeting/gateway/scripts && /usr/bin/python3 self_todo_executor.py >> ../logs/todo_executor.log 2>&1') | crontab -
# 验证
crontab -l | grep health
python3 gateway/scripts/agents_health_check.py # 手动跑一次，无输出=全正常
```
> 详见 `docs/HEALTH-PIPELINE.md`
### 1.4 防火墙
```bash
sudo ufw status | grep -E '5803|5802'
@@ -67,7 +83,7 @@ cd D:\F\NewI\opencode\daily-workspace\projects\AgentsMeeting
powershell -File deploy\windows\start.ps1
```
自动完成：停止旧进程 → api_proxy → wechat_agent → xmpp_bot → watchdog → health_check 定时任务
自动完成：停止旧进程 → api_proxy → wechat_agent → xmpp_bot → watchdog
### 2.3 验证
docs/HEALTH-PIPELINE.md
+169
View File
@@ -0,0 +1,169 @@
# AgentsMeeting — 健康监控管线
> 版本: v1.0 | 部署目标: Linux 246
---
## 概述
三层监控 + 两级自修复，零人工干预。所有组件在 246 上运行，通过 crontab 调度。
```
┌─────────────────────────────────┐
│ Dashboard F Tab │
│ /api/monitor 聚合展示 │
└──────────┬──────────────────────┘
│ 读取报告文件
┌──────────────────────┼──────────────────────┐
│ │ │
┌────▼─────┐ ┌────▼─────┐ ┌─────▼────┐
│ Tier 1 │ │ Tier 2 │ │ 自动修复 │
│ 每 5 分钟 │ │ 每天 8:00│ │ 双引擎 │
└────┬─────┘ └────┬─────┘ └─────┬────┘
│ │ │
agents_health_check agents_daily_health auto_heal (Linux侧)
│ │ self_todo_executor
│ │ │
┌────▼─────┐ ┌────▼─────┐ ┌─────▼────┐
│ 端口+HTTP │ │ 端口+HTTP │ │ systectl │
│ 6 个服务 │ │ +磁盘+cron│ │ restart │
│ │ │ +看门狗 │ │ docker │
└────┬─────┘ └────┬─────┘ │ restart │
│ 异常→TODO │ 异常→建议 └──────────┘
┌────▼─────┐
│ TODO 文件 │
│ .jsonl │
└──────────┘
```
---
## Tier 1: 快速健康检查（每 5 分钟）
**脚本**: `gateway/scripts/agents_health_check.py`
**调度**: `crontab: */5 * * * *`
**检查内容**:
- 6 个服务：dashboard、hermes_gateway_mohe、hermes_gateway_zhiwei、wechat_bridge、xmpp_bot_xxm、article_processor
- 检查方式：socket 端口连接 + HTTP /health 端点
- 本机服务用 `127.0.0.1`，远程服务用实际 IP + 更长超时
- 全正常时静默（不输出、不写日志）
**异常处理**:
- 写入 `gateway/temp/health_todos.jsonl`
- 每条 TODO 包含：服务名、失败原因、时间戳
- 写入 `gateway/temp/last_health_check.json` 供 Dashboard 读取
**日志**: `gateway/logs/health_check_report.log`
**报告**: `gateway/temp/last_health_check.json`
---
## Tier 2: 每日全面检查（每天 08:00）
**脚本**: `gateway/scripts/agents_daily_health.py`
**调度**: `crontab: 0 8 * * *`
**在 Tier 1 基础上增加**:
- 磁盘空间检查（`shutil.disk_usage`，阈值 10G 警告 / 2G 严重）
- crontab 存活检查（验证关键定时任务是否在 crontab 中）
- 看门狗日志新鲜度（超过 1 小时未更新 → 告警）
- 生成结构化 JSON 报告 + 人类可读日志
**输出**:
- `gateway/temp/last_daily_health.json` — JSON 报告
- `gateway/logs/daily_health_report.log` — 人类可读日志
---
## 自动修复：双引擎
### 引擎 A: auto_heal（Linux 侧，每 5 分钟）
**脚本**: `gateway/scripts/auto_heal.py`
**调度**: `crontab: */5 * * * *`
**工作原理**:
1. 调用 Dashboard `/api/expected` 获取所有 critical 服务的期望状态
2. 对实际状态为异常且 host 为本机（`is_local_host()`）的服务执行修复
3. 通过 `SERVICE_UNIT_MAP` 查找对应的 systemd 单元并 `systemctl restart`
4. Docker 容器通过 `DOCKER_MAP` 映射后用 `docker restart`
5. 记录修复动作到 `gateway/temp/last_auto_heal.json`
**可修复的服务**:
| 服务 | 修复命令 |
|------|---------|
| hermes_gateway_mohe | `systemctl restart hermes-gateway@mohe` |
| hermes_gateway_zhiwei | `systemctl restart hermes-gateway@zhiwei` |
| dashboard | `systemctl restart agentsmeeting-dashboard` |
| wechat_bridge | `docker restart wxBotWebhook` |
**不可修复（远程服务）**: `xmpp_bot_xxm`（Windows）、`article_processor`（Windows）
### 引擎 B: self_todo_executor（每 10 分钟）
**脚本**: `gateway/scripts/self_todo_executor.py`
**调度**: `crontab: */10 * * * *`
**工作原理**:
1. 读取 `health_todos.jsonl` 中 status=pending 的条目
2. 通过 `FIX_MAP` 查找对应修复命令并执行
3. 成功 → 标记 completed
4. 失败 → 标记 failed
5. "already running" 错误 → 标记 completed（服务已在运行）
**与 auto_heal 的分工**:
- `auto_heal` 从 Dashboard API 视角出发，修复本机服务（systemd/docker）
- `self_todo_executor` 从 Tier 1 检查视角出发，消费 TODO 文件
- 两者互补，auto_heal 负责 Linux 本机，executor 也能处理跨机场景
---
## Dashboard 集成
### /api/monitor 端点
聚合展示三层数据：
```json
{
"tasks": [
{"name": "agents-health-check", "status": "cron_ok"},
{"name": "agents-daily-health", "status": "cron_ok"},
{"name": "agents-todo-executor", "status": "cron_ok"}
],
"tier1": { "services": [...], "summary": {"ok": 6, "total": 6} },
"tier2": { "services": [...], "summary": {"ok": 6, "total": 6} }
}
```
### F Tab 展示
- **Layer 1**: 系统概览（服务数、异常数、T1 监控通过率）
- **Layer 2**: 异常服务列表（影响描述 + 状态）
- **Layer 3**: 全部服务按层级排列（通信层 / AI网关 / 辅助服务）
- **定时任务**: 三个 crontab 任务状态（绿色=正常）
- **自动修复记录**: auto_heal 最近一次修复动作
---
## 如何新增监控
1. **添加服务到 Tier 1** — 编辑 `agents_health_check.py` 的 `SERVICES` 列表
2. **添加服务到 Tier 2** — 编辑 `agents_daily_health.py` 的 `SERVICES` 列表
3. **添加修复命令** — 在 `auto_heal.py` 的 `SERVICE_UNIT_MAP` 和 `self_todo_executor.py` 的 `FIX_MAP` 中增加映射
4. **更新 Dashboard** — 在 `dashboard.py` 的 `/api/expected` 中添加检查条目
5. **写 Spec** — 在 `gateway/scripts/specs/` 创建 `{module}.json`
---
## 故障排查
| 现象 | 检查 |
|------|------|
| 任务显示"未部署" | `crontab -l \| grep health` 确认条目存在 |
| Tier1 无数据 | 检查 `gateway/temp/last_health_check.json` 是否存在 |
| TODO 堆积不减少 | 检查 `self_todo_executor.py` 是否在 crontab 中 |
| 修复失败 | 查看 `gateway/logs/todo_executor.log` |
| auto_heal 不工作 | 查看 `gateway/logs/auto_heal.log` |
docs/OPS.md
+36 -25
View File
@@ -1,6 +1,6 @@
# AgentsMeeting — 运维手册
> 版本: v2.0 | 日期: 2026-06-12
> 版本: v2.1 | 日期: 2026-07-19
---
@@ -38,10 +38,16 @@ Dashboard (:5803, Linux)
│
├── Docker exec ejabberdctl → 在线 JID 列表（跨平台权威）
├── GET 192.168.1.16:5802/health → xmpp_bot XMPP 连接状态
├── GET 192.168.1.16:5801/health → wechat_agent hermes 连接状态
└── TCP connect 192.168.1.16:8787 → api_proxy 端口可达性
├── GET 192.168.1.16:5810/health → article_processor 文章抓取服务
└── crontab 定时管线
├── */5 agents_health_check.py → Tier1 快速检查
├── 0 8 agents_daily_health.py → Tier2 每日全面检查
├── */10 self_todo_executor.py → TODO 自修复
└── */5 auto_heal.py → systemd/docker 自动重启
```
> 详见 `docs/HEALTH-PIPELINE.md`
---
## systemd 服务（Linux）
@@ -49,38 +55,43 @@ Dashboard (:5803, Linux)
| 服务 | 命令 |
|------|------|
| agentsmeeting-dashboard | `systemctl status/restart agentsmeeting-dashboard` |
| hermes-gateway@main | `systemctl status hermes-gateway@main` |
| hermes-gateway@mohe | `systemctl status hermes-gateway@mohe` |
| hermes-gateway@zhiwei | `systemctl status hermes-gateway@zhiwei` |
| hermes-gateway@xiaoguo | `systemctl status hermes-gateway@xiaoguo` |
| xmpp-bot-mohe | `systemctl status xmpp-bot-mohe` |
| xmpp-bot-zhiwei | `systemctl status xmpp-bot-zhiwei` |
**Docker 服务**: `docker restart wxBotWebhook`（微信桥接）、`docker compose restart`（ejabberd）
---
## 健康端点
| 服务 | URL | 含义 |
|------|-----|------|
| xmpp_bot | `GET :5802/health` | `xmpp_connected` = XMPP 是否在线 |
| wechat_agent | `GET :5801/health` | `hermes_connected` = 到莫荷 gateway 是否通 |
| Dashboard | `GET :5803/api/health` | Dashboard 自身是否正常 |
| Dashboard | `GET :5803/api/ejabberd` | ejabberd 在线用户列表 |
| Dashboard | `GET :5803/api/platform` | 平台服务状态 |
---
| 端点 | 说明 |
|------|------|
| `GET :5803/api/health` | Dashboard 自身健康 |
| `GET :5803/api/services` | 所有注册服务实时状态 |
| `GET :5803/api/expected` | 期望状态矩阵（含 key/spec） |
| `GET :5803/api/monitor` | 聚合监控（tasks + Tier1 + Tier2） |
| `GET :5803/api/autoheal` | 最近自动修复记录 |
| `GET :5803/api/ejabberd` | ejabberd 在线用户列表 |
| `GET :5803/api/platform` | 平台服务状态 |
| `gateway/temp/last_health_check.json` | Tier1 报告文件 |
| `gateway/temp/last_daily_health.json` | Tier2 报告文件 |
## 日志位置
| 日志 | Windows 路径 | 用途 |
|------|-------------|------|
| xmpp_bot.log | `gateway\logs\` | bot 连接/消息/HTTP 桥 |
| bridge.log | `gateway\logs\` | LLM API 调用 |
| watchdog.log | `gateway\logs\` | 看门狗启停 |
| health_check.log | `gateway\logs\` | 5 分钟健康检查 |
| dashboard.log | `gateway\logs\` | Dashboard 运行日志 |
| mohe_inbox.log | `gateway\logs\` | 莫荷消息记录 |
| 日志 | 路径（Linux 246） | 用途 |
|------|-------------------|------|
| health_check.log | `gateway/logs/` | Tier1 健康检查 |
| daily_health.log | `gateway/logs/` | Tier2 每日检查 |
| auto_heal.log | `gateway/logs/` | 自动修复引擎 |
| todo_executor.log | `gateway/logs/` | TODO 自修复执行器 |
| dashboard | `sudo journalctl -u agentsmeeting-dashboard -f` | Dashboard 运行日志 |
Linux Dashboard 日志：`sudo journalctl -u agentsmeeting-dashboard -f`
**Windows 端日志**（192.168.1.16）:
| 日志 | 路径 | 用途 |
|------|------|------|
| xmpp_bot.log | `gateway\logs\` | bot 连接/消息 |
| watchdog.log | `gateway\logs\` | 看门狗启停 |
---
docs/QUICKSTART.md
+72 -36
View File
@@ -1,45 +1,81 @@
# AgentsMeeting — 快速操作手册
## 每天例行
> 生产环境: Linux 192.168.1.246 | 所有运维操作在此执行
---
## 日常检查
```bash
# 打开 Dashboard 看全局
http://192.168.1.246:5803
# 命令行快速状态
ssh hmo@192.168.1.246 "curl -s http://127.0.0.1:5803/api/monitor | python3 -m json.tool | head -20"
```
---
## Dashboard 重启
```bash
ssh hmo@192.168.1.246 "cd ~/AgentsMeeting && git pull --rebase && sudo systemctl restart agentsmeeting-dashboard"
```
---
## 健康管线检查
```bash
# 查定时任务状态
ssh hmo@192.168.1.246 "crontab -l | grep -E 'health|todo|auto_heal'"
# 查看最近健康报告
ssh hmo@192.168.1.246 "cat ~/AgentsMeeting/gateway/temp/last_health_check.json | python3 -m json.tool"
# 手动跑一次健康检查（无输出 = 全正常）
ssh hmo@192.168.1.246 "cd ~/AgentsMeeting/gateway/scripts && /usr/bin/python3 agents_health_check.py"
# 查看自动修复日志
ssh hmo@192.168.1.246 "tail -20 ~/AgentsMeeting/gateway/logs/auto_heal.log"
```
---
## Gateway 重启
```bash
# 莫荷
ssh hmo@192.168.1.246 "sudo systemctl restart hermes-gateway@mohe"
# 知微
ssh hmo@192.168.1.246 "sudo systemctl restart hermes-gateway@zhiwei"
# 验证
ssh hmo@192.168.1.246 "curl -s http://127.0.0.1:8642/v1/health && curl -s http://127.0.0.1:8643/v1/health"
```
---
## Windows 端（192.168.1.16）
Windows 上的 xmpp_bot / article_processor 由 Windows 看门狗守护，通常不需要手动干预。
Dashboard 通过 HTTP 跨网监控这些服务。
```powershell
# 查状态
# Windows 本机操作
cd D:\F\NewI\opencode\daily-workspace\projects\AgentsMeeting
powershell -File deploy\windows\check.ps1
powershell -File deploy\windows\check.ps1 # 查状态
powershell -File deploy\windows\start.ps1 # 启动全套
```
## 查看群消息（不离开 TUI）
---
```powershell
# 查 mohe 说了什么
uv run python -c "import json,urllib.request; d=json.loads(urllib.request.urlopen('http://127.0.0.1:5802/messages?from=mohe').read()); [print(f\"{m['ts']} [{m['from']}] {m['body'][:200]}\") for m in d['messages']]"
```
## 常见问题
## 发消息到群里
```powershell
# 给 mohe 发消息
$body = @{message="这里是消息内容"} | ConvertTo-Json -Compress
Invoke-RestMethod "http://127.0.0.1:5802/send" -Method POST -Body $body -ContentType "application/json"
```
## Bot 无响应
```powershell
# 强制重启
Stop-Process -Name python* -Force
Start-Process -WindowStyle Hidden -FilePath "C:\Users\hmo\AppData\Local\Programs\Python\Python310\python.exe" `
-ArgumentList "D:\F\NewI\opencode\daily-workspace\projects\wechat-hermes-gateway\scripts\xmpp_bot.py"
```
## 启动全套服务
```powershell
powershell -File deploy\windows\start.ps1
```
## 健康检查日志
```powershell
Get-Content "D:\F\NewI\opencode\daily-workspace\projects\wechat-hermes-gateway\logs\health_check.log" -Tail 5
```
| 现象 | 操作 |
|------|------|
| F Tab 定时任务显示"未部署" | `ssh hmo@246 crontab -l \| grep health` — 确认条目存在 |
| Dashboard 不响应 | `ssh hmo@246 sudo systemctl restart agentsmeeting-dashboard` |
| auto_heal 不修复 | `ssh hmo@246 tail ~/AgentsMeeting/gateway/logs/auto_heal.log` |
| TODO 堆积 | `ssh hmo@246 cd ~/AgentsMeeting/gateway/scripts && python3 self_todo_executor.py` |