跳到主要内容

健康检查

AISIX AI 网关针对不同运维问题暴露健康端点。当你需要确认监听器是否启动时，请先看存活检查。在自托管部署中，如果需要通过本地 Admin 监听器查看模型状态和配置新鲜度，请使用需要认证的 Admin 健康检查。

代理存活检查确认代理监听器能够响应且进程未在关闭。就绪检查独立于存活检查，报告某个实例是否应该接收流量。Admin 存活检查确认自托管模式下私有管理监听器是否可达。当你需要比存活状态更多的细节时，Admin 健康检查会增加模型健康和快照新鲜度信息。

代理存活检查​

代理存活检查适合负载均衡器和编排探针使用。它确认代理监听器可以响应，且进程未在关闭。

检查代理监听器：

curl -i "http://127.0.0.1:3000/livez"

健康响应应返回 200 OK，响应体为 ok。

在优雅关闭期间，AISIX 会将存活状态标记为失败。该路由返回 503 Service Unavailable，响应体以 livez check failed 结尾。优雅关闭是预期的排空过程，而不是内部错误，因此状态码是 503 而非 500。存活检查决定 Kubernetes 是否重启容器；要停止向正在排空的实例发送流量，请使用就绪检查，Kubernetes 会将其映射到 Service 端点成员关系。

追加 ?verbose=1 可以获得适合手动 curl 检查的多行响应体。自动化探针不要依赖 verbose 响应体。

代理存活检查刻意保持较窄范围，不暴露快照详情、服务提供方适配器清单、服务提供方凭证或模型健康状态。

Admin 存活检查​

自托管模式下，Admin 监听器会暴露同样的 /livez 路由。可以用它确认私有管理监听器是否可达。

检查 Admin 监听器：

curl -i "http://127.0.0.1:3001/livez"

代理和 Admin 监听器是不同 socket。代理监听器健康并不证明 Admin 监听器可达；Admin 监听器健康也不证明面向调用方的流量可以到达代理。

就绪检查​

存活检查回答容器是否应该被重启。就绪检查回答实例是否应该接收流量。请将 Kubernetes 存活探针指向 /livez，就绪探针指向 /readyz。

/readyz 路由在代理监听器上提供服务；在自托管模式下，Admin 监听器上也提供该路由。托管模式下不存在 Admin 监听器，因此请在托管模式下探测代理监听器。

# Proxy listener (all modes):
curl -i "http://127.0.0.1:3000/readyz"
# Admin listener (self-hosted mode only):
curl -i "http://127.0.0.1:3001/readyz"

当实例可以处理流量时，返回 200 OK，响应体为 ok；当实例应该被移出轮转时，返回 503 Service Unavailable：

  • 在优雅关闭期间，实例正在排空时。
  • 在网关应用第一个配置快照之前，实例仍在启动时。
  • 当配置 watch 陈旧、大约最近五分钟内没有应用时，这可能表示 watch 卡死。

追加 ?verbose=1 可以获得多行响应体，指明哪个就绪检查失败。与存活检查一样，自动化探针不要依赖 verbose 响应体。

按模型健康检查​

在自托管部署中，当存活检查正常但需要了解已配置模型或配置新鲜度的更多细节时，请使用 Admin 健康检查。该端点需要 Admin Key Bearer Token，并返回 Admin 存储中已知的模型。

使用 Admin Key 请求 Admin 健康检查：

curl -sS "http://127.0.0.1:3001/admin/v1/health" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

该端点会返回类似下面的响应：

{
  "status": "degraded",
  "models": [
    {
      "id": "m-uuid-1",
      "name": "gpt-4o-prod",
      "health": 0
    },
    {
      "id": "m-uuid-2",
      "name": "claude-prod",
      "health": 1
    }
  ],
  "config": {
    "snapshot_revision": 1234567,
    "snapshot_age_seconds": 5
  }
}

顶层 status 聚合了模型健康和配置新鲜度：

  • ok：当每个模型都健康且配置新鲜时。
  • degraded：当某个模型降级，或快照陈旧或尚未应用时。
  • unhealthy：当某个模型不可用时。

请使用每个模型的 health 值和 config 块获取各维度的详细信息：

  • 0：健康，近期没有连续上游失败
  • 1：降级，出现 4 到 7 次连续上游失败
  • 2：不可用，出现 8 次或更多连续上游失败

可选的 config 块报告快照新鲜度。持续增长的 snapshot_age_seconds 可能表示 watch 停滞或配置传播延迟。当快照新鲜度不可用时，该块会被省略。当新鲜度跟踪可用但尚无 age 时，snapshot_age_seconds 可以为 null。

解读结果​

请使用能够回答当前问题的最小信号。

  • 如果代理存活检查失败，请检查进程状态、代理监听器绑定和监听器 TLS。
  • 如果自托管模式下 Admin 存活检查失败，请检查 Admin 绑定、私有网络位置和 Admin 监听器 TLS。
  • 如果 snapshot_age_seconds 持续增长，请重点检查 etcd 连接和配置 watch 新鲜度。
  • 如果配置新鲜度健康，但模型报告降级或不可用，请检查上游服务提供方凭证、上游网络路径和服务提供方可用性。

存活检查不能证明模型别名存在、服务提供方密钥有效或上游服务提供方可达。请使用面向调用方的模型列表，或向应用实际使用的端点发送真实请求来确认这些条件。

Admin 健康检查也不能替代真实请求链路检查。模型可能出现在健康检查中，但调用方访问权限、服务提供方凭证或上游行为仍可能导致代理请求失败。

下一步​

你已经了解哪些健康端点可以回答哪些就绪问题。接下来阅读指标与日志，将健康信号与运行时遥测关联起来。