健康检查

AISIX AI 网关暴露多个健康和状态端点，每个端点回答不同的运维问题。使用存活检查判断是否应重启进程，使用就绪检查判断实例是否应接收流量，使用模型状态排查服务提供方路由状态。

下表帮助你为检查需求选择最窄的信号：

问题	端点	监听器	身份认证
AISIX 进程是否正在运行且未在关闭？	`GET /livez`	代理；自托管模式下也可使用 Admin	无
此实例是否应接收代理流量？	`GET /readyz`	代理；自托管模式下也可使用 Admin	无
此实例是否已应用过有效配置？	`GET /status/ready`	指标/状态	无
最新配置是否完整加载，AISIX 当前正在使用什么配置？	`GET /status/config`	指标/状态	无
模型是否失败，配置快照是否新鲜？	`GET /admin/v1/health`	自托管模式下的 Admin	Admin Key
直接模型是否健康、处于冷却状态或被后台检查排除？	`GET /admin/v1/models/status` 或 `GET /status/models`	Admin 或指标/状态	Admin 路由使用 Admin Key；状态路由无认证

代理存活检查

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

检查代理监听器：

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 监听器，因此请在托管模式下探测代理监听器。

# 代理监听器（所有模式）：
curl -i "http://127.0.0.1:3000/readyz"
# Admin 监听器（仅自托管模式）：
curl -i "http://127.0.0.1:3001/readyz"

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

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

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

配置加载状态

启用 Prometheus 指标时，指标/状态监听器会提供两个针对配置的检查。与 /readyz 不同，这些路由只报告配置加载情况，不包含进程关闭或配置 watch 陈旧检查。

使用 /status/ready 作为首个有效配置的简单门禁：

curl -i "http://127.0.0.1:9090/status/ready"

在 AISIX 应用首个有效配置之前，该路由返回 503 Service Unavailable，响应体为 no configuration available。之后返回 200 OK，响应体为 ok；即使后续重新加载失败、AISIX 正在使用最后已知的有效配置，也会如此。

使用 /status/config 排查 AISIX 从已配置来源中观察到、应用或拒绝的内容：

curl -sS "http://127.0.0.1:9090/status/config"

成功的文件来源响应结构如下：

{
  "state": "synced",
  "source": {
    "type": "file",
    "source_hash": "sha256-hash",
    "observed_at": "2026-07-20T10:00:00Z"
  },
  "applied": {
    "config_hash": "sha256-hash",
    "apply_seq": 1,
    "applied_at": "2026-07-20T10:00:00Z",
    "resource_counts": {
      "api_keys": 1,
      "models": 2,
      "provider_keys": 2
    }
  },
  "last_reload": {
    "successful": true,
    "at": "2026-07-20T10:00:00Z"
  },
  "last_failure": null,
  "rejected": []
}

顶层 state 概括最新观察到的配置与 AISIX 当前使用的配置之间的关系：

状态	含义
`synced`	已应用配置与最新观察结果一致，且没有被拒绝的资源。
`degraded`	AISIX 应用了最新观察结果的一部分，但拒绝了一个或多个资源。
`out_of_sync`	AISIX 拒绝了整个最新观察结果，并在存在时继续使用最后已知的有效配置。
`empty`	AISIX 应用了不含资源的有效配置。
`never_loaded`	AISIX 启动后尚未应用有效配置。

对于 etcd 来源，source 还会报告连接状态和观察到的修订版本，applied 则报告已应用的修订版本。使用 rejected 查看各资源的验证详情，使用 last_failure 查看最近一次加载失败。这些路由不需要身份认证，因此请保持指标/状态监听器私有。

按模型健康检查

在自托管部署中，当存活检查正常但需要了解已配置模型或配置新鲜度的更多细节时，请使用 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 停滞或配置传播延迟。当快照新鲜度不可用时，该块会被省略。当新鲜度跟踪可用但尚无时长值时，snapshot_age_seconds 可以为 null。

模型运行时状态

Admin 健康响应的聚合结果报告连续上游失败次数。如果要查看直接模型当前是否符合路由条件、是否处于冷却状态，或是否被后台健康检查排除，请改为请求模型运行时状态。

在自托管模式下，需要认证的 Admin 路由可通过 Admin 监听器访问：

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

启用 Prometheus 指标时，指标/状态监听器会在无需应用身份认证的情况下提供相同响应：

curl -sS "http://127.0.0.1:9090/status/models"

/status/models 路由用于私有运维监控。它会暴露模型 ID、显示名称、种类和运行时状态，因此请在网络层限制指标/状态监听器。

两个路由返回相同的模型状态视图。响应可以包含直接模型以及向它们分发请求的虚拟模型：

[
  {
    "id": "m-uuid-1",
    "display_name": "gpt-4o-primary",
    "kind": "direct",
    "status": "cooldown",
    "cooldown_until": {
      "secs_since_epoch": 1784543400,
      "nanos_since_epoch": 0
    },
    "status_reason": "upstream_rate_limited"
  },
  {
    "id": "m-uuid-2",
    "display_name": "chat-prod",
    "kind": "routing",
    "status": "not_applicable"
  }
]

根据模型种类和当前运行时状态解读 status：

healthy：直接模型符合路由条件。
cooldown：最近配置的失败状态暂时将直接模型移出路由。使用 cooldown_until 和 status_reason 查看上下文。
unhealthy：后台模型检查已将直接模型移出路由。
not_applicable：该条目是路由、语义或合议模型。请检查实际调用服务提供方的直接目标模型。

当 AISIX 记录了相应运行时事件时，会出现 last_checked_at、last_check_status 和 status_reason 等可选字段。此视图表示运维路由状态，不能替代 /admin/v1/health 提供的失败次数与配置新鲜度视图。

解读结果

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

如果代理存活检查失败，请检查进程状态、代理监听器绑定和监听器 TLS。
如果自托管模式下 Admin 存活检查失败，请检查 Admin 绑定、私有网络位置和 Admin 监听器 TLS。
如果 /status/ready 返回 503，请检查初始配置加载。使用 /status/config 区分来源不可用和配置内容被拒绝。
如果 /status/config 报告 degraded 或 out_of_sync，请先检查 rejected 和 last_failure，再更改最后已知的有效配置。
如果 snapshot_age_seconds 持续增长，请重点检查 etcd 连接和配置 watch 新鲜度。
如果配置新鲜度健康，但 Admin 健康检查报告模型降级或不可用，请检查上游服务提供方凭证、上游网络路径和服务提供方可用性。
如果请求没有符合条件的路由目标，请检查模型运行时状态中处于 cooldown 或 unhealthy 状态的目标。

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

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

下一步

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

代理存活检查​

Admin 存活检查​

就绪检查​

配置加载状态​

按模型健康检查​

模型运行时状态​

解读结果​

下一步​