配置状态

AISIX 网关通过状态端点和 Prometheus 指标报告配置是否生效，并在未生效时说明原因。这些界面共同回答运维人员的核心问题：“网关是否正在使用我预期的配置提供服务？”它们覆盖所有资源来源：resources.yaml 文件、自行管理的 etcd 配置存储或 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": "YYYY-MM-DDTHH:MM:SSZ"
  },
  "applied": {
    "config_hash": "1dc0ee8d06edcde3ecbf23672858622a83f266910846f514ccb909cf41046653",
    "apply_seq": 1,
    "applied_at": "YYYY-MM-DDTHH:MM:SSZ",
    "resource_counts": {
      "api_keys": 1,
      "models": 1,
      "provider_keys": 1
    }
  },
  "last_reload": {
    "successful": true,
    "at": "YYYY-MM-DDTHH:MM:SSZ"
  },
  "last_failure": null,
  "rejected": [],
  "unknown_kinds": [],
  "partially_compatible": []
}

配置状态

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

状态	含义
synced	当前有非空配置在提供服务，且 rejected 中没有活动条目。归类到 unknown_kinds 的条目不会改变该状态，即使 last_error 指出其放置位置有问题。未知类型键也可能导致 source_hash 与 config_hash 不同。请检查 unknown_kinds 和 partially_compatible 了解兼容性详情。
degraded	网关仍在提供服务，但最新快照中有部分条目被拒绝。已接受的资源和最后一个已知良好值仍会提供服务；rejected 数组会说明每个被拒绝的条目。
out_of_sync	最近一次观察到的快照被整体拒绝。网关会继续使用最后一个有效配置提供服务。
empty	已应用有效配置，但其中不包含资源。
never_loaded	进程启动后尚未应用任何有效配置。

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

从 etcd 读取配置具有向前兼容性。如果文档包含无法识别的字段，网关会使用可识别的字段提供服务，并在 partially_compatible 中报告被忽略的字段。仅出现这种情况不会使 state 从 synced 变为其他状态。资源文件验证仍然严格，因此资源文件中的未知字段会导致整个重新加载被拒绝。

向前兼容同样覆盖资源类型本身。如果 etcd 键使用当前网关版本不认识的资源类型，它会被报告在 unknown_kinds 而不是 rejected 中：它不会改变 state 或 last_reload.successful，并由 aisix_config_unknown_kind_resources 统计，而不是 aisix_config_rejected_resources。通常这表示控制面正在投影网关发布后才引入的资源类型；升级到支持该类型的网关即可消除报告。

当已知资源类型写在共享定价目录前缀下时，etcd 加载器也使用同一分类；该前缀只接受 pricing。此时 last_error 会说明该类型不允许出现在全局前缀下，应从源头修正键名，升级网关无法修正它。1.3.0 及更早版本不会区分这两种情况：它会把键报告在 rejected 中，last_error_kind 为 unknown_kind，并在键存在期间将 aisix_config_last_reload_successful 保持为 0。

对于使用 etcd 或 AISIX Cloud 的网关，never_loaded 是它首次连接配置来源期间所处的状态。处于该状态时它不会绑定代理监听器，因此该端点和 GET /status/ready 就是观察它的地方，参见启动与第一个配置。如果来源可以连上但其中没有资源，网关会应用一份空配置并报告 empty，而不是 never_loaded。

响应字段

顶层字段：

字段	类型	说明
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	网关拒绝的活动条目。没有活动拒绝时为空；请单独检查 unknown_kinds。
unknown_kinds	array	被归类为 unknown_kind 的 Etcd 键。通常表示网关版本之后引入的资源类型，也可能表示已知类型放在共享定价目录前缀下。它们与 rejected 分开报告；没有键被归入此类时为空。
partially_compatible	array	包含当前网关版本无法识别字段、但仍在提供服务的 etcd 资源，按资源类型和字段聚合。所有用于提供服务的文档均符合网关 Schema 时为空。

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。被拒绝的条目或 unknown_kinds 中未用于提供服务的条目都会使两者不同。
apply_seq	number	每次已应用配置发生变化时递增的计数器。内容未变化时不会递增。
applied_at	string	最近一次应用变更的 RFC 3339 UTC 时间戳。
resource_counts	object	按资源类型统计的服务中资源数量，例如 {"models": 2}。

last_reload 和 last_failure 字段：

字段	类型	说明
last_reload.successful	boolean	最近一次加载是否在没有拒绝资源的情况下完成。unknown_kinds 中的条目不算拒绝，不会改变该字段的 true 值。
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。
last_error	string	可读错误消息。Schema 消息会遮蔽凭证值。
first_seen_at	string	进程启动后首次观察到此拒绝的时间。重复加载同一无效条目时保持稳定。
last_seen_at	string	最近一次观察到此拒绝的时间。
serving_stale_since	string	网关从何时起继续使用该资源最后一个已知良好值提供服务的 RFC 3339 时间戳。没有以前的值仍在提供服务时省略。
serving_stale_age_seconds	number	从 serving_stale_since 开始经过的秒数，在读取状态时重新计算。与 serving_stale_since 一同省略。

unknown_kinds 中的每个条目：

字段	类型	说明
resource_kind	string	键名中写明的复数形式资源类型。无法确定类型时为空。
resource_id	string	资源 ID。键名无法解析到足以识别资源时为空。
last_error	string	来自加载路径的可读说明。
first_seen_at	string	进程启动后首次观察到该键的 RFC 3339 UTC 时间戳。重复加载同一个键时保持稳定。
last_seen_at	string	最近一次观察到该键的 RFC 3339 UTC 时间戳。

如果网关的最新快照中只有未知的资源类型而没有被拒绝的资源，它仍然报告 synced 和一次成功的重新加载。请把下面的 NEW_KIND 替换为控制面实际写入的资源类型：

{
  "state": "synced",
  "last_reload": {
    "successful": true,
    "at": "YYYY-MM-DDTHH:MM:SSZ"
  },
  "rejected": [],
  "unknown_kinds": [
    {
      "resource_kind": "NEW_KIND",
      "resource_id": "9a3f2c67-52b8-4b1e-9f4e-1f2f3a4b5c6d",
      "last_error": "unknown kind \"NEW_KIND\"",
      "first_seen_at": "YYYY-MM-DDTHH:MM:SSZ",
      "last_seen_at": "YYYY-MM-DDTHH:MM:SSZ"
    }
  ],
  "partially_compatible": []
}

网关在所有资源类型中最多保留 256 个未知类型键的详情，该限额与真正的拒绝条目分开计算。如果仍有超过 256 个受影响的键，即使完成一次配置全量重新同步，unknown_kinds 和 aisix_config_unknown_kind_resources 也只是下限。发生溢出后，即使总数降到 256 以下，它们仍可能不完整，直到下一次全量重新同步重建保留集合。未知类型键的数量不会挤占 rejected 条目。

partially_compatible 中的每个条目：

字段	类型	说明
resource_kind	string	复数形式的资源类型，例如 api_keys 或 models。
field	string	被忽略的字段路径。数组索引会规范化为 []，例如 routing.targets[].priority。
count	number	包含该被忽略字段且仍在提供服务的此类资源数量。

使用 config_hash 确认特定变更已落地：该哈希是确定性的，因此知道所发布内容的部署流水线可以比较哈希，无需对资源执行差异比较。对于文件来源，source_hash 是文件字节的 SHA-256（sha256sum resources.yaml）。对于 etcd 来源，哈希相同并不表示所有字段都已执行；需要精确 Schema 兼容时，还应要求 partially_compatible 为空。

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 回答的是进程级问题——存活状态和排空状态——而不是重复这一项。对于使用 etcd 或 AISIX Cloud 的网关，该监听器在应用第一个配置之前不会绑定，因此在这个端点返回 503 期间，它们两个都不会有任何响应。请参阅健康检查。

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。只有 cooldown 块中设置了 enabled: true 的模型才会进入该状态。
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。未知的资源类型是例外：它们不会把该值置为 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_partially_compatible_resources	gauge	kind	包含至少一个被忽略字段、但仍在提供服务的资源，按资源类型分组。包含多个被忽略字段的资源只计一次。
aisix_config_stale_served_resources	gauge	kind	来源中的最新值被拒绝、但最后一个已知良好值仍在提供服务的资源，按资源类型分组。
aisix_config_unknown_kind_resources	gauge	kind	被保留且归类为 unknown_kind 的 Etcd 键，按资源类型分组。某类不再有保留键时，其序列返回 0。aisix_config_rejected_resources 不统计这些保留键。受影响的键超过 256 个时，取值为下限；发生溢出后，取值可能一直不完整，直到配置全量重新同步。
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."

该告警不包含归类为未知类型的键，它们由 aisix_config_unknown_kind_resources 统计。运行 1.3.0 或更早版本的网关不做这种区分。网关版本之后引入的资源类型会被计为拒绝，因此该告警会触发，并且 aisix_config_last_reload_successful 会一直保持为 0，直到网关升级。发布说明中 1.3.0 的升级说明描述了会出现这种情况的定价目录场景。

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

- 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."