监控与状态检查 - AgentBook Docs

监控与状态检查

AgentBook 会自检哪些依赖、哪些是它做不到的，以及如何接入外部的可用性监控。

先说清楚它做不到什么#

AgentBook 会检查自身的各项依赖，但它无法监控自己的可用性——任何跑在应用内部的检查都做不到这件事：如果应用挂了，做检查的那部分也一起挂了，而那份沉默看起来和"一切正常"完全一样。

所以这件事分成两半，只有其中一半在应用里。

AgentBook 会自检什么#

GET /api/health/deep 会逐项检查依赖，并把结果一并返回：

检查项	是否关键	失败意味着什么
`database`	是	应用完全连不上 Postgres。
`database_schema`	是	能连上 Postgres，却读不到真实的表——连接池在迁移过程中仍然会正常回答 `SELECT 1`，在存活检查看来一切健康，而实际查询全部失败。
`llm`	是	没有配置任何 LLM 供应商，助手无法回答任何问题。
`blob_storage`	否	收据图片会退回使用原始链接，而这些链接会过期。
`error_tracking`	否	错误不会被记录到任何地方。这类故障天生不可见——DSN 未设置时，每次上报都"成功"了，只是发往了虚空。
`cron_auth`	否	定时任务无法完成自身鉴权。

这个接口公开且无需鉴权，这是刻意的——需要凭据才能访问的监控，迟早会被人关掉。它只返回检查项名称、状态词、耗时，以及一个来自固定集合的简短说明；绝不会返回 URL、主机名、密钥或错误信息。

**返回 503 表示关键依赖已宕机。**仅仅是"未配置"的依赖仍然返回 200，并在响应体里说明：没人启用的功能确实值得关注，但不该成为凌晨三点把人叫醒的理由。

有一个每五分钟运行一次的定时任务会执行同样的检查并保存结果，因此即使当时无人盯着，某项依赖宕机六小时也会留下记录。它只在状态发生变化时通过 Sentry 告警，而不是在持续故障期间反复告警——宕机六小时是两条消息，而不是七十二条；并且某项检查必须连续失败两次才算数，因为冷启动时的一次查询超时并不是故障。

需要你自己接入的那一半#

把外部监控指向这个接口即可。Better Stack、Checkly、Pingdom、UptimeRobot，或者一个 GitHub Actions 定时任务都可以：

URL：     https://agentbook.brainliber.com/api/health/deep
频率：    1–5 分钟
告警条件：HTTP 状态码 ≠ 200

这样你才能获得应用内检查给不了的东西：整个部署消失时的那条告警。

手动检查#

Terminal

$curl -s https://agentbook.brainliber.com/api/health/deep | jq

也可以运行仓库里的配置体检脚本，它会连同其他"会静默失效"的设置一起检查：

Terminal

$./bin/config-doctor.sh

先说清楚它做不到什么#

所以这件事分成两半，只有其中一半在应用里。

AgentBook 会自检什么#

GET /api/health/deep 会逐项检查依赖，并把结果一并返回：

检查项	是否关键	失败意味着什么
`database`	是	应用完全连不上 Postgres。
`database_schema`	是	能连上 Postgres，却读不到真实的表——连接池在迁移过程中仍然会正常回答 `SELECT 1`，在存活检查看来一切健康，而实际查询全部失败。
`llm`	是	没有配置任何 LLM 供应商，助手无法回答任何问题。
`blob_storage`	否	收据图片会退回使用原始链接，而这些链接会过期。
`error_tracking`	否	错误不会被记录到任何地方。这类故障天生不可见——DSN 未设置时，每次上报都"成功"了，只是发往了虚空。
`cron_auth`	否	定时任务无法完成自身鉴权。

需要你自己接入的那一半#

把外部监控指向这个接口即可。Better Stack、Checkly、Pingdom、UptimeRobot，或者一个 GitHub Actions 定时任务都可以：

URL：     https://agentbook.brainliber.com/api/health/deep
频率：    1–5 分钟
告警条件：HTTP 状态码 ≠ 200

这样你才能获得应用内检查给不了的东西：整个部署消失时的那条告警。

手动检查#

Terminal

$curl -s https://agentbook.brainliber.com/api/health/deep | jq

也可以运行仓库里的配置体检脚本，它会连同其他"会静默失效"的设置一起检查：

Terminal

$./bin/config-doctor.sh