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

2026-07-19 10:09:42 +08:00
parent 94250e9dda
commit 0b345c2ca1
6 changed files with 438 additions and 73 deletions
@@ -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 打开时）
+```