本页由英文页面机器翻译而来。内容以英文页面为准。 阅读英文页面
从外部监控服务器
如何让正常运行时间监控服务指向服务器、如何避免监控推高运行成本,以及如何区分维护模式(维护)和故障。探测路径见运行指南中的健康检查一节。
下文中关于第三方的事实都附有确认日期和来源。各服务会更改其方案和界面;在依赖某项限制之前,请查看链接的页面。
监控哪个 URL
Section titled “监控哪个 URL”| 路径 | 用途 | 是否访问数据库 | 在维护模式下 |
|---|---|---|---|
GET /api/v1/instance/health |
可用性监控、状态页面、Web 客户端 | 每个进程每 60 秒最多一次 | 503,带有 Retry-After 和 {"status":"maintenance"} |
GET /healthz、GET /health/live |
平台的存活探测 | 从不 | 200 {"status":"maintenance"} |
GET /readyz、GET /health/ready |
负载均衡器或 Kubernetes 的就绪探测 | 每个请求都会访问(并发请求共用一次检查) | 200 {"status":"maintenance"} |
请让外部监控指向 /api/v1/instance/health,而不是 /readyz(/health/ready):后者每个请求都会查询数据库,
因此间隔很短的监控会让缩容到零的数据库一直保持唤醒。这些探测是留给你的平台用的。
monitoring 部分在 Google Cloud(mycroblog-gcp)上检查 /health/live,在 AWS(mycroblog-aws)上检查 /readyz,都由平台自带的监控以较长的间隔执行:它的 uptime_period 就是这要花费的成本,因为每次检查都会唤醒一个实例。
服务器自己的指标、追踪和错误报告送往哪里,由这些模块中同一份配置的 observability 部分决定,monitoring 会读取它。默认情况下,它把每一项都送往平台:在 Google Cloud 上,指标送往 Cloud Monitoring,请求追踪送往 Cloud Trace,错误报告送往 Error Reporting,这三者都来自 Cloud Run 发送给它们的内容,并会启用它们的 API;在 AWS 上,指标以 Embedded Metric Format 送往 CloudWatch,错误报告送往 CloudWatch Logs,追踪则通过每个任务中与服务器并排运行的采集器送往 X-Ray(AWS ECS 上的追踪)。monitoring 需要那里有指标:它拒绝 observability.metrics = "settings",因为这会把 metrics_exporter 交给 settings 输入。
/api/v1/instance/health 的响应(无需认证,Cache-Control: no-store):
| 状态 | HTTP | 正文 |
|---|---|---|
| 健康 | 200 |
{"status":"ok","checked_at":"<RFC 3339>"} |
| 不可用(数据库无法访问,或未应用 schema) | 503 |
{"status":"unavailable","checked_at":"<RFC 3339>"} |
| 维护模式 | 503,带有 Retry-After |
{"status":"maintenance"} |
健康时,/healthz 和 /readyz 返回 200 和 {"status":"ok"},而当数据库尚未就绪时,/readyz 返回带有问题文档的 503。/health/live 和 /health/ready 是同样的检查,只是名称不同。
在 Cloud Run 上,请调用不以 z 结尾的路径。 Cloud Run 保留了一些以 z 结尾的路径,会在请求到达容器之前用它自己的 404 响应:/healthz 就是其中之一,也没有任何保证说 /readyz 会一直有响应。从 Cloud Run 部署的外部(可用性监控、curl)请使用 /health/live、/health/ready 或 /api/v1/instance/health。容器自己的探测不受影响。
响应正文从不包含原因、主机名或版本。原因在服务器日志中。
checked_at 是该响应所依据的检查的时间。服务器每个进程每分钟最多运行一次数据库检查并重用结果,
因此轮询频率高于每 60 秒一次的监控只会看到相同的 checked_at,没有任何好处。有多个进程时,每个进程运行自己的检查。
设置了 origin_secret 时,这三个路径在没有该请求头的情况下仍会响应,因此它们不能说明 CDN 丢失了该请求头。如果监控是你发现问题的第一个信号,也请监控一个经过 CDN 的页面,例如 https://<host>/about。
让监控保持低成本
Section titled “让监控保持低成本”- 缩容到零的数据库。 如果监控的间隔短于数据库停止前等待的时间,数据库就永远不会停止。Neon 在 5 分钟没有活动之后挂起计算资源;Free 套餐无法关闭这一点(2026-10-25 确认,Neon: Scale to zero)。作为经验法则,5 分钟或更长的间隔能让空闲的数据库在两次检查之间停止,而每次检查会把它唤醒,持续时间为检查时间加上空闲时间。参与联邦的服务器全天候都会收到其他服务器的投递,所以它的数据库一天中大部分时间本来就是唤醒的;额外的成本仅限于安静的时段。
- 如果空闲成本最重要,请选择更便宜的拆分方式。 以较短的间隔监控
/health/live(它从不访问数据库),以较长的间隔(15 分钟或更久)监控依赖数据库的/api/v1/instance/health。/health/live在维护模式下也返回200,因此请匹配正文中的"status":"ok"。 - 请求本身很小。 每 5 分钟检查一次,每月约 8,640 个请求,每分钟一次则约 43,200 个。这在 Cloud Run 的免费额度之内(每月 200 万个请求、180,000 vCPU 秒和 360,000 GiB 秒;时间向上取整到 100 毫秒;2026-10-23 确认,Cloud Run 定价)。
区分维护模式和故障
Section titled “区分维护模式和故障”在维护模式(维护指南)期间,健康检查端点回答 503,大多数监控会把它当作故障。仅凭状态码无法区分两者,因此请根据正文判断:
- 把正文中有
"status":"ok"视为健康,其他任何情况都视为宕机。关键字监控或 JSON 值监控可以做到这一点。 - 为了避免计划维护期间的告警,如果服务提供维护窗口,就设置监控的维护窗口(见下表),或者在开始前手动暂停监控。
- UptimeRobot 的 Free 方案没有维护窗口:请暂停监控,或者接受告警。
以下服务检查的都是同一件事:当 GET https://<your-host>/api/v1/instance/health 的响应为 200 且正文包含 "status":"ok" 时即为健康。
| 服务 | 监控类型 | 健康条件 | 维护窗口 | 确认 |
|---|---|---|---|---|
| UptimeRobot | Keyword | 正文包含 "status":"ok" |
Free 方案没有(Solo 及以上) | 2026-10-25,pricing |
| Better Stack | HTTP status 或 Keyword | 2xx,或正文包含 "status":"ok" |
未验证 | 2026-10-25 |
| Gatus | Endpoint conditions | [STATUS] == 200 且 [BODY].status == ok |
配置中的 maintenance |
2026-10-25,README |
| Uptime Kuma | HTTP(s) - Keyword 或 JSON Query | 正文包含 "status":"ok",或 status 为 ok |
内置 | 2026-10-23,README |
| Upptime | .upptimerc.yml 中的 sites |
200 且正文包含 "status":"ok" |
无 | 2026-10-25,Configuration |
UptimeRobot
Section titled “UptimeRobot”创建一个类型为 Keyword 的监控:URL 为 https://<your-host>/api/v1/instance/health,关键字为 "status":"ok",在关键字不存在时告警。Free 方案允许 50 个监控,间隔为 5 分钟,包含关键字监控。“Custom headers & statuses”和维护窗口从 Solo 方案(付费,间隔 60 秒)开始提供(2026-10-25 确认,pricing)。由于检查针对的是正文,这里用关键字监控就足够了。
Better Stack
Section titled “Better Stack”两种方式都可以(2026-10-25 确认,Uptime monitor、Keyword monitor):
- HTTP status 监控:它把
2xx响应视为正常,因此200为正常,503(不可用或维护)会触发事件。 - Keyword 监控:“Alert us when”设为“URL doesn’t contain keyword”,关键字为
"status":"ok"。匹配不区分大小写。
Free 方案的检查频率和维护窗口尚未验证:官方页面没有针对 Free 方案说明这些内容。免费额度的数量(监控和心跳合计 10 个,一个状态页面)来自价格页面,2026-10-23 确认。
在 config.yaml 中(默认间隔为 60s;2026-10-25 确认,README):
endpoints: - name: my url: "https://<your-host>/api/v1/instance/health" interval: 5m conditions: - "[STATUS] == 200" - "[BODY].status == ok"Gatus 有一个顶层的 maintenance 部分(start 为 hh:mm 格式,duration,timezone 默认为 UTC,every 为星期几的列表,为空表示每天),用于计划内的工作。README 只说明它用于在维护窗口期间避免告警;请在你使用的版本上确认其行为。
Uptime Kuma
Section titled “Uptime Kuma”添加一个类型为 HTTP(s) - Keyword、关键字为 "status":"ok" 的监控,或者类型为 HTTP(s) - Json Query、查询为 status、期望值为 ok 的监控。接受的状态码默认为 200-299,因此维护时的 503 和故障时的 503 都会被视为宕机。Uptime Kuma 有一个用于设置监控窗口的维护功能(wiki 列出了它;其细节未经验证)。这些监控类型已于 2026-10-23 在源代码中确认(monitor.js、EditMonitor.vue)。
Upptime
Section titled “Upptime”在 .upptimerc.yml 中(2026-10-25 确认,Configuration):
sites: - name: My server url: https://<your-host>/api/v1/instance/health __dangerous__body_down_if_text_missing: '"status":"ok"'默认情况下,20x 和 30x 都算正常;设置 expectedStatusCodes: [200] 可以只接受 200。检查通过 GitHub Actions 按为所有站点统一设置的计划运行(workflowSchedule.uptime,默认每 5 分钟一次,这也是 GitHub Actions 允许的最短间隔)。该选项的名称表明不推荐使用它,但这是检查正文的方法。
把 status_page_url(MY_STATUS_PAGE_URL,一个 https: URL;参见配置参考)设为你的监控服务的公开页面。服务器会在 GET /api/v1/instance、它渲染的登录页面和错误页面、Web 客户端(包括服务器无响应时)以及维护页面中显示这个链接,这样无法访问服务器的用户也能了解原因。它从配置中读取,而不是从数据库读取,因此在数据库宕机时也能工作。修改在重启后生效。
页面本身的选择(本服务器不会导入状态页面的状态,因此也请以全服务器通知的形式发布公告):
- 你所选监控服务的托管状态页面(UptimeRobot 的 Free 方案有一个不可自定义的状态页面;Better Stack 的免费额度有一个)、Gatus 和 Uptime Kuma 自己提供的页面,或者部署在 GitHub Pages 上的 Upptime 静态站点。
- Atlassian Statuspage,它是一个发布状态的地方,而不是监控服务。一个组件有五种状态之一:Operational、Under maintenance、Degraded performance、Partial outage、Major outage(API 取值为
operational、under_maintenance、degraded_performance、partial_outage、major_outage;2026-10-23 确认,What is a component?、Statuspage API)。如何根据监控的告警自动更改组件的状态尚未验证(这需要在实际账号上设置针对各服务的集成)。
供 LLM 和编程智能体使用:llms.txt,llms-full.txt, llms-small.txt