配置传播
AISIX AI 网关会将配置写入与代理请求处理分离。在自托管部署中，写入通常来自 Admin API；在托管部署中，写入来自托管控制面。两种情况下，网关都会基于已加载快照处理代理请求。
这种分离可以保持请求处理快速，但也意味着写入被接受和代理已就绪不是同一个状态。
配置变更遵循以下路径：
新的代理请求会读取网关已应用的最新快照。
配置传播的工作方式
传播是异步的。写入响应成功表示资源已被接受并存储，但不保证每个代理请求都能立即使用新资源。
配置监听会将变更应用到原子快照。每个新代理请求都会加载当前快照，因此在更新应用前启动的请求仍可能使用旧配置，而之后的请求会使用更新后的配置。
当资源之间存在依赖时，这一点尤其重要。例如，模型可以引用服务提供方密钥，调用方 API Key 可以允许该模型。在传播过程中，一个已接受资源可能先于另一个资源可见。请按依赖顺序创建资源，然后在发送生产流量前验证最终面向 调用方的路径。
验证配置传播
配置写入成功只确认资源已被接受，并不确认传播完成。请通过应用使用的同一面向调用方路径观察预期结果，以确认传播完成。
对于模型访问变更，请使用应用将要使用的同一个调用方 API Key 检查面向调用方的模型列表：
AISIX_API_KEY="YOUR_CALLER_API_KEY"
curl -sS "http://127.0.0.1:3000/v1/models" \
-H "Authorization: Bearer ${AISIX_API_KEY}" \
| jq -r '.data[].id'
自动化流程需要等待变更生效时，请轮询预期的代理可见状态，而不是依赖固定等待时间。当一次变更包含多个资源时，请按以下顺序操作：
- 按依赖顺序创建或更新资源，例如服务提供方密钥、模型和调用方 API Key。
- 当变更应让模型别名可见时，使用应用的调用方 API Key 轮询
GET /v1/models。 - 当变更应影响代理行为时，通过应用将使用的确切端点和模型发送请求。
面向调用方的正向探测比假设固定传播时间更可靠。在自托管模式下，Admin 健康检查可提供快照辅助信息，但代理路径才是确认特定变更已可承载流量的依据。
检查配置加载
启用 Prometheus 指标时，可以查询指标/状态监听器，查看 AISIX 是否接受了最新观察到的配置：
curl -sS "http://127.0.0.1:9090/status/config"
响应会区分来源中最新观察到的内容与 AISIX 实际应用的配置。如果来源更新没有产生预期代理行为，请使用以下字段排查：
| 字段 | 含义 |
|---|---|
state | 已应用配置是否处于 synced、degraded、out_of_sync、empty 或 never_loaded 状态。 |
source | 来源类型、最新观察时间和哈希；适用时还包含 etcd 连接和修订版本详情。 |
applied | 配置哈希、应用序号、应用时间、各资源数量；适用时还包含 etcd 修订版本。 |
rejected | 因解析、schema、引用或键验证失败的资源。 |
last_failure | 启动后记录的最近一次配置加载错误。 |
如果 state 为 degraded，AISIX 正在使用已接受的子集，rejected 会指出未应用的内容。如果状态为 out_of_sync，AISIX 拒绝了整个最新观察结果，并在存在时继续使用最后已知的有效配置。
配套的 GET /status/ready 路由会在首个有效配置应用后返回 200，此前返回 503。两个状态路由都不需要身份认证，因此请保持指标/状态监听器私有。有关响应示例和所有状态含义，请参阅健康检查。
检查快照新鲜度
在自托管模式下，GET /admin/v1/health 可以包含报告配置快照新鲜度的 config 块。当写入成功但代理仍表现为使用旧配置时，可以使用它排查。
使用 Admin Key 请求 Admin 健康检查：
AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
curl -sS "http://127.0.0.1:3001/admin/v1/health" \
-H "Authorization: Bearer ${AISIX_ADMIN_KEY}"
响应可能包含快照新鲜度字段：
{
"status": "ok",
"models": [
{
"id": "m-uuid",
"name": "gpt-4o-mini",
"health": 0
}
],
"config": {
"snapshot_revision": 1234567,
"snapshot_age_seconds": 5
}
}
使用 snapshot_revision 查看已加载快照反映的最高 etcd 修订版本。使用 snapshot_age_seconds 查看距离网关上次应用配置事件已过去多久。
快照时长并不表示监听是否已连接。配置空闲时该值也会增长，因此数值很大本身不能证明监听已停滞。
请在预期变更正在进行时解释该值。如果新写入已被接受但修订版本没有前进，网关可能没有收到或应用这些更新。
当快照新鲜度不可用时，config 块会被省略。如果新鲜度跟踪可用但尚未应用任何快照，snapshot_age_seconds 可以为 null。
排查传播问题
当写入成功但代理请求仍失败时，请根据观察范围区分资源问题和传播问题：
| 观察结果 | 检查项 | 后续操作 |
|---|---|---|
/status/config 报告被拒绝的资源。 | 受影响网关实例上的 state、rejected 和 last_failure。 | 修正被拒绝的资源或来源文档，再确认下一次加载状态为 synced。 |
新模型返回 404，且未出现在 GET /v1/models 中。 | 模型别名、模型类型、调用方 API Key 访问权限和最新快照修订版本。 | 修正资源关系或等待预期修订版本，然后再次查询模型发现。 |
| 模型已出现在发现结果中，但服务提供方请求失败。 | 服务提供方密钥、上游模型 ID、服务提供方端点和出站连接。 | 排查服务提供方路径，不要重复配置写入。 |
| 一个网关实例与其他实例不同。 | 每个自托管实例的启动配置、etcd 前缀和快照修订版本。 | 恢复异常实例的配置连接，然后验证面向调用方的路径。 |
| 新写入成功，但所有实例仍使用旧状态。 | 预期修订版本在变更期间是否前进。 | 重试写入前，先检查 etcd 可达性和配置监听。 |
重复同一写入通常无法修复没有收到配置更新的网关。请先判断资源关系是否错误，或预期修订版本是否未到达受影响实例。
下一步
你已经了解配置写入如何从配置存储进入代理请求链路。接下来阅读生产部署了解生产就绪检查；需要检查健康端点和快照新鲜度时， 请阅读健康检查。