跳转至

Agent Portal — 04-02~03 Pipeline重构与健康监控

关键产品决策

  • Dad 决策：监控能力内建到 Portal
  • 不要部署独立的 Uptime Kuma 服务，把监控能力直接做进 Portal
  • 形成统一入口：项目管理 + 服务器监控 + 健康检查

  • PortalBot 已有前端、后端、Pipeline，监控功能应该集成其中

  • Dad 决策：Digest Pipeline 合并到 Portal

  • Daily Digest 应并入 Agent Portal，数据抓取、总结逻辑本质上都是为 Portal 服务
  • 整理成可移植、可部署到其他环境的结构

  • 原因：减少独立服务数量，统一维护入口

  • Dad 决策：监控目标重新定义

  • 监控页面目标是"监控指定服务"，不是把一堆服务器列出来
  • 暂时只需要开发环境站点监控，但也要把能做成 HTTP 检测的服务都纳入
  • 原因：聚焦可访问服务的健康状态，而不是展示服务器资源列表

技术问题与根因分析

监控面板空白问题

  • 现象：Dad 打开健康监控面板时"一条记录都没有"
  • 排查过程：
  • API 实际返回 10 条数据，后端不是完全坏掉
  • 前端调用 /api/monitors/uptime，实际返回的是 index.html 而不是 JSON
  • 根因：Caddy 把 API 请求转发到 3002，但当前 Portal 实例实际跑在 3013
  • 解决方案：
  • 进入 Docker 中的 Caddy 容器修改 Caddyfile
  • 更新持久化配置，杀掉旧的 3002 端口进程
  • 经验：Portal 空白页/空数据不一定是 React 或 API 问题，反向代理层是高频根因

监控数据 JOIN 失败

  • 现象：Uptime 数据显示异常
  • 根因：
  • AP_site_checks 中 dev 环境 name 是 "ClawCraft"，靠 kind=dev 区分
  • AP_monitors 中却写成 "ClawCraft Dev"，name 不匹配导致 JOIN 失败
  • 解决方案：
  • 修改 AP_monitors 的 name，去掉 " Dev" 后缀
  • 依赖 group_name 区分环境
  • 修复 seed 脚本，避免重新初始化时再次写入错误名称

Azure OpenAI 调用问题

  • 现象：Agent 多次超时/403，Digest pipeline LLM 调用失败
  • 根因：
  • .env 中 API Key 已过期
  • openclaw.json 中存在可用新 key
  • base URL 需使用 OpenAI-compatible 路径：/openai/v1/
  • pm2 进程不会自动继承 shell 中 source .env 的环境变量
  • 解决方案：
  • 更新 .env 中 key
  • 确认 base_url 以 / 结尾，供 pipeline 拼接 chat/completions
  • 重启 digest-trigger
  • 重要配置：Azure OpenAI 兼容调用格式应为 https://...cognitiveservices.azure.com/openai/v1/

Bot 架构/实现决策

健康监控体系重构

  • 架构调整：
  • 从"服务器/容器状态展示"转向"统一 HTTP health checks"
  • 清理旧 monitors 表中的陈旧数据
  • 在 server.cjs 内置健康检查器，定时写入 AP_monitors + site_checks
  • 实现结果：
  • 统计出约 12~13 个有意义的 HTTP 监控项
  • 健康检查启动后自动首轮执行，写入 response_ms 等指标
  • 移除临时 ContainerMonitorSection，MonitorPanel 回归统一展示

Pipeline 与 Portal 联动链路

  • 架构决策：
  • 不强行把 Pipeline 改成"经后端 API 写库"
  • 保持 Pipeline 直连 PG，后端负责广播刷新事件
  • 补充方案：
  • 新增轻量回调 endpoint：/api/digest/done
  • Pipeline 完成后调用该接口，后端广播 SSE
  • 前端监听 digest_done，触发 App 层重新 loadOverview + loadDashboard
  • 选型理由：直连数据库更简单可靠，避免增加 Pipeline 与 Portal API 的耦合

Digest Pipeline v5 重构

  • 代码精简：行数从 3472 → 2667，删除约 800 行废弃 v3 代码
  • 合并部署：Portal + Digest 合并到 msdevhub/agent-portal 仓库
  • PG 直连方案：
  • Node 侧：server.cjs 的 dbQuery / dbExec 改为直连 PG
  • Python 侧：新增 push/db.py，统一数据库访问层
  • 本地退场：本地 Digest 不再需要运行，crontab 任务注释掉，只保留 collector.py

里程碑

  1. 监控面板首版落地：10 条监控数据可见，CRUD API 全部通过，MonitorPanel 替代旧的 SiteStatusOverview
  2. 监控项扩充：批量添加服务器监控项，新增 28 个监控项，合计 38 个，分为 5 组
  3. Pipeline 直连 PG 完成：引入数据库抽象层，优先直连 PG，保留 Supabase HTTP fallback
  4. Portal + Digest 合并完成：统一维护入口，后续所有修改面向单一仓库
  5. 刷新机制打通：门户触发刷新后，pipeline 成功处理 9 个 bot、142 条时间线事件
  6. Trigger server 纳入 pm2 管理：Pipeline 启动稳定化

关键技术栈

  • 后端：Express 5 + PG direct pipeline
  • 进程管理：pm2
  • 反向代理：Caddy（Docker 容器内）
  • 数据库：PostgreSQL 直连
  • 认证：Logto + Bearer token
  • 实时推送：SSE /api/ops/stream

监控架构结论

  • 两层分离：容器状态展示与 HTTP 健康监控是两套语义，应分层处理
  • 当前选择：优先做"可访问服务"的 HTTP 监控，容器状态作为补充
  • 数据流：健康检查器 → AP_monitors + site_checks → MonitorPanel 展示

重要配置线索

  • API 端口：后端 3002，前端 3013
  • Caddy 配置：需要确认 API 转发到正确端口
  • 环境变量：DATABASE_URL、Azure API Key、base_url 格式
  • 仓库：msdevhub/agent-portal（Portal + Digest 合并）

这一阶段完成了 Portal 作为统一工作台的最后一块拼图：内建监控能力。从独立服务收敛到统一入口，数据链路从 Supabase 升级到 PostgreSQL 直连，Pipeline 与 Portal 完成架构整合。