配置状态
AISIX 网关通过状态端点和 Prometheus 指标报告配置是否生效，并在未生效时说明原因。这些界面共同回答运维人员的核心问题：“网关 是否正在使用我预期的配置提供服务？”它们覆盖所有资源来源：resources.yaml 文件、自行管理的 etcd 配置存储或控制面。
这些端点与 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。这与加载后的运行时资源构建不同。已启用并挂载的安全护栏若无法构建，例如 custom 脚本语法错误，运行时索引重建后会将该条目记入 rejected；仍有可用资源时可能报告 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 Enterprise 或 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 时间戳。 |
未知资源类型本身不会使重新加载失败。下例假设最新应用的配置包含至少一条已接受的资源，且 rejected 为空，因此 state 为 synced。若本次加载只有未知资源类型、没有已接受的资源且没有其他错误，state 为 empty，重新加载仍报告成功。请把下面的 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 Enterprise 或 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: "An 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."