健康与就绪协议

Health listener 与客户端 API listener 分离，不要求 API key。生产环境应只允许本机探针、私网负载均衡器或 DNS controller 访问。

方法与路径

方法	路径	响应
`GET` / `HEAD`	`/healthz`	存活时 200
`GET` / `HEAD`	`/readyz`	就绪时 200，否则 503

其他方法返回 405，未知路径返回 404。Query 不影响路径匹配。HEAD 返回与 GET 相同状态和 Content-Length，但没有 body。

响应 schema

{
  "service": "scootgate",
  "instance_id": "gate-a",
  "version": "0.1.0",
  "status": "ready",
  "ready": true,
  "auth_snapshot_version": 7,
  "routing_snapshot_version": 41,
  "usage_outbox": {
    "pending_events": 0,
    "pending_bytes": 0,
    "dropped_events": 0,
    "oldest_event_age_secs": null
  }
}

字段	类型	说明
`service`	string	固定 `scootgate`
`instance_id`	string	节点配置 ID
`version`	string	二进制版本
`status`	string	`alive`、`starting`、`ready` 或 `draining`
`ready`	bool	当前能否接收新流量
`auth_snapshot_version`	u64	当前授权版本；0 表示未加载
`routing_snapshot_version`	u64	snapshot 路由版本；static 模式为 0
`usage_outbox.pending_events`	u64	未确认事件数
`usage_outbox.pending_bytes`	u64	未确认 payload 字节
`usage_outbox.dropped_events`	u64	进程生命周期累计丢弃数
`usage_outbox.oldest_event_age_secs`	u64/null	最老积压事件年龄

`/healthz`

只要进程和 health listener 能响应就返回 200。status 固定为 alive，但 ready 仍反映真实就绪状态，因此调用方可以在一次请求中同时观察存活与就绪。

不要用 /healthz 决定是否接入 Provider 流量。

`/readyz`

只有以下条件全部成立才返回 200：

auth_snapshot_version > 0；
路由表可用；
snapshot 路由最近一次成功同步未超过 max_stale_secs；
节点未进入 draining。

否则返回 503 和相同 JSON schema。

状态解释

`status`	`/readyz`	含义
`starting`	503	缺授权／路由，或 snapshot 路由过期
`ready`	200	可接新流量
`draining`	503	收到停机信号，正在等待在途请求

Static 路由不会因控制面 staleness 变为 unready；授权快照目前只要求已加载有效版本，不设置 staleness readiness 窗口。

探针建议

liveness：GET /healthz；
readiness：GET /readyz；
周期应明显短于路由 max_stale_secs；
连续 readiness 失败后从入口摘除，但不要立刻杀死进程；
draining 立即停止分配新请求；
对 pending_bytes、oldest_event_age_secs 与 dropped_events 单独告警。

示例：

curl --fail --silent http://127.0.0.1:9091/healthz
curl --fail --silent http://127.0.0.1:9091/readyz

Keyboard shortcuts

ScootGate