跳到主要内容

配置传播

AISIX AI 网关会将配置写入与代理请求处理分离。在自托管部署中，写入通常来自 Admin API；在托管部署中，写入来自托管控制面。两种情况下，网关都会基于已加载快照处理代理请求。

这种分离可以保持请求处理快速，但也意味着写入被接受和代理已就绪不是同一个状态。

配置变更遵循以下路径：

新的代理请求会读取网关已应用的最新快照。

配置传播的工作方式​

传播是异步的。写入响应成功表示资源已被接受并存储，但不保证每个代理请求都能立即使用新资源。

配置 watch 会将变更应用到原子快照。每个新代理请求都会加载当前快照，因此在更新应用前启动的请求仍可能使用旧配置，而之后的请求会使用更新后的配置。

当资源之间存在依赖时，这一点尤其重要。例如，模型可以引用服务提供方密钥，调用方 API Key 可以允许该模型。在传播过程中，一个已接受资源可能先于另一个资源可见。请按依赖顺序创建资源，然后在发送生产流量前验证最终面向调用方的路径。

验证代理就绪状态​

请将配置写入成功视为资源被接受，将代理可见结果视为就绪。

对于模型访问变更，请使用应用将要使用的同一个调用方 API Key 检查面向调用方的模型列表：

curl -sS "http://127.0.0.1:3000/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  | jq -r '.data[].id'

当自动化流程需要等待变更生效时，请轮询预期的代理可见状态，而不是依赖固定等待时间。正向探测比假设某个固定传播时间更可靠。

可以使用以下面向调用方的探测方式：

  • 当变更应该让某个模型别名对调用方 API Key 可见时，调用 GET /v1/models。
  • 当变更应该让请求成功时，调用应用实际使用的精确代理端点。

使用 Admin 健康检查检测过期或卡住的配置 watch。使用代理端点，并携带应用实际使用的同一个调用方 API Key，确认特定变更已可承载流量。

检查快照新鲜度​

在自托管模式下，GET /admin/v1/health 可以包含报告配置快照新鲜度的 config 块。当写入成功但代理仍表现为使用旧配置时，可以使用它排查。

使用 Admin Key 请求 Admin 健康检查：

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 revision。使用 snapshot_age_seconds 查看距离网关上次应用配置已过去多久。持续增长的 age，尤其是在活跃配置变更期间增长超过数分钟，可能表示 watch 停滞或网关无法访问配置存储。

当快照新鲜度不可用时，config 块会被省略。如果新鲜度跟踪可用但尚未应用任何快照，snapshot_age_seconds 可以为 null。

查看传播过程​

当写入成功但代理请求仍失败时，请先确认依赖资源存在并正确互相引用，然后检查代理可见状态是否已经跟上。

如果新创建模型返回 404，请检查该模型别名是否出现在该调用方 API Key 的 GET /v1/models 结果中。如果没有出现，请先检查调用方 API Key 访问列表和配置 watch 新鲜度，再考虑重试同一写入。

如果某个网关实例与其它实例行为不同，请比较这些实例的快照新鲜度和部署配置。重复同一写入通常无法修复没有收到配置更新的网关。

下一步​

你已经了解配置写入如何从配置存储进入代理请求链路。接下来阅读生产部署了解生产就绪检查；需要检查健康端点和快照新鲜度时，请阅读健康检查。