1 项服务需要关注

队列停止消费

进程在线，但待处理消息没有被 worker claim。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• pending 长时间存在且 attempts=0
• PM2 online 但最近 claim/done 不更新

修复方法

1. 检查 worker 心跳、最近 claim/done 和 queue 进程日志。
2. 确认数据库连接有效后重启 queue worker，并复检 pending 是否归零。

Queue worker 生命周期异常

主循环、辅助循环或资源关闭顺序不一致。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• worker_lifecycle_error
• 主循环退出后辅助 timer 仍运行

修复方法

1. 确认 fatal exit 会清理所有 timer，再关闭 PG pool。
2. 运行 worker 生命周期回归测试后再部署。

Queue worker 数据库连接池已关闭

worker 正在使用已经 end 的 PostgreSQL pool。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• db_pool_closed_error
• Cannot use a pool after calling end on the pool

修复方法

1. 停止僵尸进程并由进程管理器重新拉起。
2. 检查 closePgPool 调用路径和辅助 worker 清理顺序。

Queue worker 僵尸运行风险

进程管理在线，但心跳或消费活性已经停止。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• queue_zombie_risk
• worker heartbeat stale

修复方法

1. 对比 PM2 状态、worker heartbeat、pending attempts 和最近 done。
2. 恢复后验证 canary 被真实 worker 消费。

队列消息处理卡住

消息已被 claim，但超过处理窗口仍未完成。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• processing_stuck
• locked_at 超过 retry 窗口

修复方法

1. 定位 locked_by 对应 worker 和该消息 trace。
2. 确认处理是否可安全重试，再按 runbook 解锁或重启。

队列端到端 Canary 失败

内部测试消息未在窗口内完成真实 claim/done。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• canary_failed 或 canary_stale
• 业务消息较少时仍可复现

修复方法

1. 确认 canary Token、入口和 worker handler 配置。
2. 检查 canary attempts、trace 和最近 done；不要发送真实企微消息测试。

PM2 进程离线或错误

服务可能没有按预期由 PM2 托管，或者 PM2 进程已经退出。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 日志里出现“PM2 进程 ... 状态为 离线/错误”
• 服务接口正常，但 PM2 状态异常

修复方法

1. 执行 `pm2 status` 或 `pm2 jlist`，确认进程名和监控配置一致。
2. 如果服务已经改成 systemd 或裸进程运行，更新监控配置，不要继续绑定旧的 PM2 进程名。
3. 如果应当由 PM2 托管，重新启动对应进程并检查启动日志。

健康检查端点无法连接

监控访问不到目标端口，通常是服务未监听、反代未转发或本机网络失败。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 错误信息包含 `fetch failed`
• 端口未监听或服务未启动

修复方法

1. 先执行 `ss -ltnp | grep <port>` 确认端口是否监听。
2. 检查进程命令行和最近启动日志，确认服务是否真正启动到新版本。
3. 如果走域名，再核对 Caddy/Nginx 反向代理目标端口是否正确。

健康检查超时

端口仍在监听，但服务没有在监控阈值内返回，通常是事件循环卡住或健康接口依赖阻塞。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 错误信息包含 `Health check timeout`
• 源站延迟接近监控超时时间，例如 10000ms

修复方法

1. 先直接执行 `curl --max-time 20 <health-url>` 确认是否真实超时。
2. 检查服务日志，重点看健康接口依赖、数据库连接和原生模块加载错误。
3. 确认 PM2 进程虽然在线但事件循环是否卡住，必要时重启服务并继续查根因。

服务返回 503

服务进程在线，但内部依赖异常，健康检查主动返回不可用。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 错误信息包含 `HTTP 503`
• 通常伴随数据库、缓存、WebSocket 或外部 API 失败

修复方法

1. 打开目标服务自己的 `/health` 返回体，直接查看失败的子检查项。
2. 按子检查项继续排查依赖，例如 DB、Redis、WebSocket 或外部 API。
3. 修复后重新验证健康接口，不要只看进程是否存在。

PostgreSQL 数据库配置缺失

服务进程在线，但健康检查里的 database 子项失败，通常是运行环境没有加载 PG_HOST / PG_USER / PG_DATABASE 等数据库变量。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 健康接口返回 `HTTP 503`，并且 checks 里 `database` 为 unhealthy
• 错误信息包含 `数据库配置缺失`、`PG_HOST`、`PG_USER` 或 `PG_DATABASE`
• PM2 进程在线，但 PM2 环境或项目 `.env` 中没有 PostgreSQL 连接配置

修复方法

1. 先执行 `pm2 env <id>` 或检查 PM2 dump，确认运行中的进程是否真的带了 PG_HOST / PG_PORT / PG_USER / PG_DATABASE。
2. 核对项目 `.env` 是否包含正确的 PostgreSQL 配置；不要只看源码默认值，因为默认值可能指向错误库。
3. 确认目标 PostgreSQL 实例里确实存在对应 database、user 和 pgvector 扩展，然后再执行项目的数据库初始化或迁移脚本。
4. 修复配置后重启服务，并直接访问 `/health` 确认 database 子检查恢复 healthy。

LLM API Key 无效或过期

上游模型凭证失效，服务入口可能仍在线，但深度能力会失败。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 错误信息包含 `401`
• 错误信息包含 `API Key`、`invalid` 或 `expired`

修复方法

1. 核对环境变量中的上游 API Key 是否有效，并确认没有读到旧 `.env`。
2. 如果经过网关转发，继续核对网关上的 provider key 与虚拟 key 映射。
3. 更新密钥后执行一次深度健康检查，确认接口恢复正常。

LLM 余额不足

模型供应商额度不足会让深度检查失败，但不一定导致 HTTP 入口立刻挂掉。

注意 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 错误信息包含 `402 Insufficient Balance`
• 通常出现在 LLM 深度健康检查

修复方法

1. 补充供应商余额或切换到可用 provider key。
2. 如果有网关池，确认路由没有固定落到已欠费的单个 key。
3. 补款后手动触发一次深度检查，确认不再返回 402。

企微 WebSocket 未连接

机器人推送通道断开，依赖企微消息的告警和交互会直接失效。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 错误信息包含“企微 WebSocket 未连接”
• 健康检查里 websocket_bot 子项为 unhealthy

修复方法

1. 确认 WebSocket 服务端地址、bot_id、secret 是否正确加载到运行环境。
2. 检查出网网络和 DNS，确认当前机器能建立到企微机器人 WebSocket。
3. 恢复后再做一次实际消息收发验证，不要只看 TCP 连接恢复。

企微 WebSocket 已连接但未订阅

机器人连上了 WebSocket，但订阅阶段失败，通常是 bot_id/secret 不匹配或订阅流程异常。

注意 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 错误信息包含“未订阅”
• 日志里出现 bot_id、secret 或 subscribe 相关错误

修复方法

1. 核对 bot_id 与 secret 是否来自同一个机器人实例。
2. 检查连接成功后的订阅请求和返回体，确认没有被限频或权限拒绝。
3. 必要时重启机器人进程并观察首次订阅日志。

企微 disconnected_event 被误当成断线

企微会通过 WebSocket 推送业务事件 disconnected_event，客户端不应因此主动关闭连接。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 日志反复出现 `disconnected_event` 后紧跟 `WebSocket closed` 和 `Reconnecting in ...`
• 服务在已 connected/subscribed 后仍频繁重连，健康检查间歇性 503

修复方法

1. 检查 WebSocket 客户端事件处理逻辑，`aibot_event_callback` 里的 `disconnected_event` 只应记录为业务事件。
2. 不要在收到 `disconnected_event` 时主动执行 `ws.close()`。
3. 修复后重启业务服务，并观察日志中是否只剩事件记录、不再紧跟重连。

企微 API 频控或并发限制

客户端重试过快或重复连接会触发企微限频，后续订阅、回复或发消息可能失败。

注意 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 日志包含 `45009 api freq out of limit`
• 日志包含 `45033 api concurrent out of limit`
• 短时间内大量重连、订阅或发送消息

修复方法

1. 先停止重连风暴，确认没有多个进程使用同一个 bot_id/secret。
2. 对 WebSocket 重连增加指数退避，例如 1s、2s、4s，最高 60s。
3. 等待企微限频窗口恢复后，再验证订阅和实际消息收发。

监控运行目录与日志目录漂移

源码、dist 产物或 PM2 cwd 不一致时，health-monitor 和 dashboard 可能读写不同的日志目录。

注意 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• `logs/health.jsonl` 和 `dist/logs/health.jsonl` 同时存在
• 服务已恢复，但 dashboard 仍显示旧的 lastCheck 或旧错误
• PM2 实际运行 `dist/*.js`，源码改动未编译进运行产物

修复方法

1. 统一 `MONITOR_LOG_DIR` 和 `MONITOR_STATE_DIR`，避免根目录与 dist 目录各写一份。
2. 确认 PM2 运行的脚本路径，再执行 build 并重启对应进程。
3. 用 `stat` 和 `tail` 验证 dashboard 读取的日志文件确实在持续更新。

持久化状态文件损坏

Bot 的本地状态 JSON 损坏会导致 response_url、最近会话等恢复失败，影响告警或消息回复。

注意 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 日志包含 `Failed to load persisted state`
• 日志包含 `Unexpected non-whitespace character after JSON`
• 重启后 Bot 丢失最近 response_url 或会话目标

修复方法

1. 先备份损坏的状态文件，再用 JSON 校验工具确认具体损坏位置。
2. 如果状态只缓存 response_url/会话目标，可清空该状态文件让服务重新生成。
3. 确认写状态文件使用临时文件加原子 rename，避免并发写入产生半截 JSON。

Node 原生模块 ABI 不匹配

PM2 使用的 Node 版本与原生依赖编译版本不一致时，服务可能在线但业务接口卡死或启动失败。

阻塞 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 日志包含 `NODE_MODULE_VERSION`
• 日志包含 `better-sqlite3.node`、`ERR_DLOPEN_FAILED` 或 `Module did not self-register`
• PM2 显示在线，但 `/health` 超时或内部依赖异常

修复方法

1. 先执行 `pm2 describe <service>`，确认实际 interpreter 和 Node.js version。
2. 如果项目依赖已按 Node 22 编译，就把 PM2 interpreter 固定到 `/usr/bin/node`；如果决定用 Node 24，则用同一 Node 版本重新安装或 rebuild 原生依赖。
3. 修复后验证 `/health` 延迟，并执行 `pm2 save` 固化 PM2 运行态。

监控数据长时间未刷新

面板展示的可能是旧快照，不能代表当前真实状态。

注意 命中 0 次

最近时间：- · 涉及服务：—

常见表现

• 最近检查时间明显滞后当前时间数小时以上
• health-monitor 进程存在，但日志文件不再追加

修复方法

1. 检查 `health-monitor` 进程是否真的在跑，以及对应日志是否持续更新。
2. 确认定时调度是否还在执行，必要时重启监控进程并观察新日志写入。
3. 如果 dashboard 读的是错误目录，修正 `MONITOR_LOG_DIR` 和 `MONITOR_STATE_DIR`。