feat: introduce spec system + dashboard + health pipeline (AgentsMeeting template)

2026-07-19 10:50:34 +08:00
parent 81c6dd2314
commit 747fdfe467
19 changed files with 1826 additions and 0 deletions
@@ -0,0 +1,111 @@
+# MoFin — 健康监控管线
+
+> 版本: v1.0 | 部署目标: Linux 246
+
+---
+
+## 概述
+
+两层监控，通过 crontab 调度，聚合到 Dashboard F Tab。
+
+```
+                    ┌─────────────────────────────────┐
+                    │        Dashboard F Tab          │
+                    │   /api/monitor 聚合展示          │
+                    └──────────┬──────────────────────┘
+                               │ 读取报告文件
+                    ┌──────────┴──────────┐
+                    │                     │
+               ┌────▼─────┐          ┌────▼─────┐
+               │ Tier 1   │          │ Tier 2   │
+               │ 每 5 分钟 │          │ 每天 8:00│
+               └──────────┘          └──────────┘
+                    │                     │
+          agents_health_check    agents_daily_health
+                    │                  (规划中)
+               ┌────▼─────┐
+               │ TODO 文件 │
+               │ .jsonl   │
+               └──────────┘
+```
+
+---
+
+## Tier 1: 快速健康检查（每 5 分钟）
+
+**脚本**: `agents_health_check.py`
+**调度**: `crontab: */5 * * * *`
+
+**检查内容**:
+- 5 个服务：MoFin API (:8899) / Dashboard (:5804) / 知微 Gateway (:8643) / ejabberd (:5222) / MoFin DB
+- 检查方式：socket 端口 + HTTP /health + SQLite connect
+- 全正常时静默（不输出、不写日志）
+
+**异常处理**:
+- 写入 `gateway/temp/health_todos.jsonl`
+- 每条 TODO 包含：服务名、失败原因、时间戳
+- 写入 `gateway/temp/last_health_check.json` 供 Dashboard 读取
+
+**日志**: `gateway/logs/health_check.log`
+**报告**: `gateway/temp/last_health_check.json`
+
+---
+
+## Tier 2: 每日全面检查（规划中）
+
+**计划脚本**: `agents_daily_health.py`
+**计划调度**: `crontab: 0 8 * * * 1-5`（交易日 8:00）
+
+**计划检查内容**:
+- 在 Tier 1 基础上增加：
+  - 磁盘空间检查（阈值 10G 警告 / 2G 严重）
+  - crontab 存活检查（验证关键定时任务）
+  - MoFin DB 大小和新鲜度检查
+  - 生成结构化 JSON 报告
+
+**注意**: MoFin 已有 `system_health_check.py`（每日 9:00）和 `morning_health_check.py`（交易日 8:00，8层48项），Tier2 将与现有检查互补，不重复。
+
+---
+
+## Dashboard 集成
+
+### /api/monitor 端点
+
+聚合展示两层数据：
+
+```json
+{
+  "tasks": [
+    {"name": "agents-health-check", "status": "cron_ok"},
+    {"name": "agents-daily-health", "status": "not_deployed"},
+    {"name": "dashboard", "status": "running"}
+  ],
+  "tier1": { "services": [...], "summary": {"ok": 5, "total": 5} },
+  "tier2": { "services": [...], "summary": {"ok": 0, "total": 0} }
+}
+```
+
+### F Tab 展示
+
+- 系统概览（Tier1 通过率）
+- 定时任务状态（绿色=正常，黄色=未部署，红色=异常）
+- Tier1 服务详情
+
+---
+
+## 如何新增监控
+
+1. **添加服务到 Tier 1** — 编辑 `agents_health_check.py` 的 `SERVICES` 列表
+2. **更新 Dashboard** — 在 `dashboard.py` 的 `SERVICES` 中同步添加
+3. **写 Spec** — 在 `specs/` 创建或更新对应模块的 JSON
+
+---
+
+## 故障排查
+
+| 现象 | 检查 |
+|------|------|
+| F Tab 无数据 | `cat ~/MoFin/gateway/temp/last_health_check.json` 确认文件存在 |
+| Tier1 任务显示"未部署" | `crontab -l \| grep health` 确认 crontab 条目 |
+| TODO 堆积 | 手动检查失败服务的实际状态 |
+| Dashboard 不显示新服务 | 确认 dashboard.py 的 SERVICES 列表和 health_check 同步 |