配置状态

AISIX AI 网关通过状态端点和一组 Prometheus 指标报告配置是否生效，并在未生效时说明原因。无论配置来自 resources.yaml 文件、自管理配置存储还是 AISIX Cloud 控制面，它们共同回答运维人员的核心问题：“网关是否正在使用我预期的配置提供服务？”

这些端点与 GET /metrics 一起由专用指标监听器 observability.metrics.prometheus.addr（默认 0.0.0.0:9090）提供。与指标端点一样，它们按设计不需要身份认证；请确保该监听器仅对监控网络开放。

端点	用途
GET /status/config	完整配置加载状态：派生状态、来源与已应用哈希、资源数量、重新加载结果及被拒绝的条目。
GET /status/ready	就绪门禁：应用第一个有效配置前返回 503，之后返回 200 ok。
GET /status/models	按模型统计的运行时健康状态：每个已配置模型一行，并包含其路由状态。

GET /status/config

返回描述最近一次观察到和最近一次应用配置的 JSON 文档：

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

{
  "state": "synced",
  "source": {
    "type": "file",
    "source_hash": "1dc0ee8d06edcde3ecbf23672858622a83f266910846f514ccb909cf41046653",
    "observed_at": "2026-07-16T07:14:30Z"
  },
  "applied": {
    "config_hash": "1dc0ee8d06edcde3ecbf23672858622a83f266910846f514ccb909cf41046653",
    "apply_seq": 1,
    "applied_at": "2026-07-16T07:14:30Z",
    "resource_counts": {
      "api_keys": 1,
      "models": 1,
      "provider_keys": 1
    }
  },
  "last_reload": {
    "successful": true,
    "at": "2026-07-16T07:14:30Z"
  },
  "last_failure": null,
  "rejected": []
}

配置状态

state 由网关根据最近一次观察到和已应用的快照派生：

状态	含义
synced	已应用配置与来源中观察到的最新快照一致，并且没有资源被拒绝。
degraded	网关仍在提供服务，但最新快照中有部分条目被拒绝。已接受的子集会被应用；rejected 数组会列出被丢弃的内容。
out_of_sync	最近一次观察到的快照被整体拒绝。网关会继续使用最后一个有效配置提供服务。
empty	已应用有效配置，但其中不包含资源。
never_loaded	进程启动后尚未应用任何有效配置。

从资源文件加载配置的网关会以全有或全无的方式应用文件，因此文件重新加载失败时会报告 out_of_sync，而不是 degraded。当来源逐个投递资源且仅部分资源无效时，会出现 degraded。

响应字段

顶层字段：

字段	类型	说明
state	string	派生的配置状态，为 synced、degraded、out_of_sync、empty 或 never_loaded。
source	object	从配置来源观察到的最新快照。
applied	object	最近一次实际应用并用于提供服务的配置。state 为 never_loaded 时省略。
last_reload	object	最近一次加载的结果。首次加载完成前省略。
last_failure	object 或 null	进程启动后最近一次加载失败。该字段具有粘性：后续重新加载成功后仍保留，直到进程重启。
rejected	array	网关从最新快照中拒绝的条目。所有内容均加载成功时为空。

source 字段：

字段	类型	说明
type	string	配置读取位置：file 或 etcd。
connected	boolean	配置存储是否可达。仅当 type 为 etcd 时存在。
observed_revision	number	最近一次观察到的快照对应的存储修订版本。仅当 type 为 etcd 时存在。
source_hash	string	最近一次观察到的快照的 SHA-256 哈希。对于文件来源，这是原始文件字节的哈希。
observed_at	string	最近一次观察的 RFC 3339 UTC 时间戳。

applied 字段：

字段	类型	说明
applied_revision	number	已应用配置反映的存储修订版本。仅当 source.type 为 etcd 时存在。
config_hash	string	已接受并用于提供服务的配置的 SHA-256 哈希。没有资源被拒绝时等于 source_hash。
apply_seq	number	每次已应用配置发生变化时递增的计数器。内容未变化时不会递增。
applied_at	string	最近一次应用变更的 RFC 3339 UTC 时间戳。
resource_counts	object	按资源类型统计的服务中资源数量，例如 {"models": 2}。

last_reload 和 last_failure 字段：

字段	类型	说明
last_reload.successful	boolean	最近一次加载是否在没有拒绝资源的情况下完成。
last_reload.at	string	最近一次加载的 RFC 3339 UTC 时间戳。
last_failure.at	string	最近一次失败发生的时间。
last_failure.last_error_kind	string	最近一次失败的故障类型。
last_failure.last_error	string	最近一次失败的可读消息。

rejected 中的每个条目：

字段	类型	说明
resource_kind	string	复数形式的资源类型，例如 models 或 provider_keys。无法确定来源条目类型时为空。
resource_id	string	资源 ID。来源条目无法解析到足以识别资源时为空。
last_error_kind	string	故障类型：bad_key、non_json、schema_failed、parse_failed 或 unknown_kind。
last_error	string	可读错误消息。Schema 消息会遮蔽凭证值。
first_seen_at	string	进程启动后首次观察到此拒绝的时间。重复加载同一无效条目时保持稳定。
last_seen_at	string	最近一次观察到此拒绝的时间。

使用 config_hash 确认特定变更已落地：该哈希是确定性的，因此知道所发布内容的部署流水线可以比较哈希，无需对资源执行差异比较。对于文件来源，source_hash 是文件字节的 SHA-256（sha256sum resources.yaml）。

GET /status/ready

仅针对配置来源的就绪门禁：

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

条件	状态	响应体
尚未应用有效配置	503 Service Unavailable	no configuration available
已应用有效配置	200 OK	ok

将其用作启动或就绪探针，可避免网关在能够提供已配置路由前接收流量。应用第一个配置后，该端点会保持返回 200；后续重新加载失败且网关使用最后一个有效配置提供服务时也是如此。代理监听器上的 /livez 和 /readyz 保持进程级语义；请参阅故障排除。

GET /status/models

按模型统计的运行时健康视图，每个已配置模型对应一行：

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

[
  {
    "id": "9a3f2c67-52b8-4b1e-9f4e-1f2f3a4b5c6d",
    "display_name": "gpt-4o-prod",
    "kind": "direct",
    "status": "healthy"
  },
  {
    "id": "5b17e9d2-8a44-4c05-b7a1-0c9d8e7f6a5b",
    "display_name": "claude-prod",
    "kind": "direct",
    "status": "cooldown",
    "status_reason": "upstream_auth_failure",
    "cooldown_until": { "secs_since_epoch": 1784708130, "nanos_since_epoch": 0 }
  }
]

状态	含义
healthy	模型处于路由轮转中。
cooldown	最近的上游失败使模型退出路由，直到 cooldown_until；status_reason 指出故障类别，例如 upstream_auth_failure 或 upstream_rate_limited。
unhealthy	最近的后台模型检查失败，路由会避开该模型。last_check_status 包含最近一次检查的 HTTP 状态。
not_applicable	该行是多目标或其他虚拟模型；其可用性由目标模型的对应行决定。

时间戳（cooldown_until，以及经过后台检查的模型上的 last_checked_at）是如上所示的秒/纳秒 Epoch 对象，而不是 RFC 3339 字符串。与其他状态端点一样，/status/models 无需身份认证并反映已应用配置，因此适用于所有网关部署。

配置加载指标

同一监听器上的 GET /metrics 端点会以 Prometheus 序列暴露配置加载状态。这些值在抓取时从支持 GET /status/config 的同一状态刷新。

指标	类型	标签	说明
aisix_config_last_reload_successful	gauge	无	最近一次加载没有拒绝资源时为 1，否则为 0。
aisix_config_last_reload_success_timestamp_seconds	gauge	无	最近一次成功加载的 Unix 时间戳。
aisix_config_reloads_total	counter	无	进程启动后的配置加载次数，包括启动加载、文件重新加载和来自配置存储的完整同步。
aisix_config_reload_failures_total	counter	reason	未完全成功的加载次数，按 reason 分类：fetch（来源不可达或不可读）、parse（无法解析来源内容）或 validate（资源 schema、形状或引用验证失败）。
aisix_config_rejected_resources	gauge	kind	当前按资源类型统计的被拒绝条目数。修复有问题的条目后为 0。
aisix_config_hash_info	gauge	hash	Info 风格序列：只有一个值为 1 的活动样本，其 hash 标签为已应用的 config_hash。
aisix_config_observed_revision	gauge	无	最近一次观察到的快照对应的存储修订版本。仅为 etcd 来源发出。
aisix_config_applied_revision	gauge	无	已应用配置对应的存储修订版本。仅为 etcd 来源发出。
aisix_config_source_connected	gauge	无	配置存储可达时为 1。仅为 etcd 来源发出。

完整指标目录请参阅指标参考。

告警示例

网关拒绝任何已配置资源时发出告警。网关会继续提供服务，但运维人员写入的部分内容没有生效：

- alert: AisixConfigRejectedResources
  expr: sum by (instance) (aisix_config_rejected_resources) > 0
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "AISIX gateway is rejecting configured resources"
    description: "Check GET /status/config on {{ $labels.instance }}: the rejected array names each entry and its error."

配置持续重新加载失败时发出告警。网关正使用最后一个有效配置运行，新变更没有生效：

- alert: AisixConfigReloadFailing
  expr: aisix_config_last_reload_successful == 0
  for: 10m
  labels:
    severity: warning
  annotations:
    summary: "AISIX gateway configuration reloads are failing"
    description: "The last configuration load on {{ $labels.instance }} did not fully succeed. Check last_failure and rejected in GET /status/config."

下一步

• 在配置传播中了解已接受的变更如何到达代理请求。
• 按照开源 AISIX 网关快速入门重新加载使用文件配置的网关并检查结果。