配置传播

AISIX 将配置更新与代理请求处理分离。无论动态资源来自哪里，每个网关都使用其最新应用的快照处理请求。

因此，资源更新已接受与代理已就绪并不是同一个状态。请通过应用使用的同一条调用方路径验证重要变更。

更新如何到达网关

更新触发方式取决于所配置的资源来源：

资源来源	更新如何到达 AISIX
声明式 `resources.yaml` 文件	网关在启动时加载该文件，并在收到 `SIGHUP` 后重新读取。
etcd	网关监听所配置键空间中的资源变更。
AISIX Cloud	控制面将环境资源投射到已连接的网关。

每种来源都进入相同的快照应用路径：

AISIX 在成功应用配置后，以原子方式替换已加载配置。新请求使用当前快照；替换之前开始的请求可以继续使用先前的快照。

无效更新不会悄然替换有效快照。根据资源来源和故障类型，AISIX 会应用已接受的子集并报告被拒绝的资源，或继续使用最后已知的有效配置。

重新加载资源文件

开源 AISIX 网关不会监视 resources.yaml 的变更。发送 SIGHUP 前，请先验证编辑后的文件，再确认网关已应用新快照。

以下命令使用开源 AISIX 网关快速入门中的容器名称和资源路径。如果网关使用其他容器名称或路径，请相应调整。

编辑挂载到正在运行的容器中的资源文件。快速入门提供了一个完整示例：添加第二个模型，并授予现有调用方 API Key 对该模型的访问权限。

添加新的环境变量

正在运行的容器无法继承之后才在主机上导出的环境变量。如果编辑后的资源文件引入了新的 ${VAR} 引用，请先在短生命周期容器中使用所有必需变量验证该文件：

docker run --rm \
  -v "$(pwd):/etc/aisix:ro" \
  -e OPENAI_API_KEY \
  -e CALLER_API_KEY \
  -e PROVIDER_VARIABLE_1 \
  -e PROVIDER_VARIABLE_2 \
  --entrypoint /usr/local/bin/aisix \
  ghcr.io/api7/aisix:latest \
  validate --resources /etc/aisix/resources.yaml

请将服务提供方变量名替换为资源文件实际使用的名称。如果服务提供方只需要一个凭证变量，请从两条命令中删除 -e PROVIDER_VARIABLE_2。如果当前 shell 中没有 OPENAI_API_KEY 和 CALLER_API_KEY，请先重新导出它们。

验证成功后，使用相同的变量重新创建快速入门容器：

docker rm -f aisix-quickstart

docker run -d --name aisix-quickstart \
  -v "$(pwd):/etc/aisix:ro" \
  -e OPENAI_API_KEY \
  -e CALLER_API_KEY \
  -e PROVIDER_VARIABLE_1 \
  -e PROVIDER_VARIABLE_2 \
  -p 3000:3000 -p 9090:9090 \
  ghcr.io/api7/aisix:latest

挂载的工作目录会在旧容器删除后保留 resources.yaml。替换后的容器会在启动时加载已验证的文件，因此无需发送 SIGHUP，可直接继续确认已应用的配置。

使用现有环境变量重新加载

如果编辑后的文件没有引入新的环境变量，请在正在运行的容器中验证它：

docker exec aisix-quickstart \
  /usr/local/bin/aisix validate --resources /etc/aisix/resources.yaml

此命令会复用正在运行的容器及其环境。验证过程与启动和重新加载使用相同的文件加载流水线，包括环境变量插值、名称引用解析和 schema 验证。无效文件会以非零状态退出并输出完整错误报告。

验证成功时会报告文件已加载，并显示其中的资源数量：

OK: /etc/aisix/resources.yaml loaded <number> resource(s)

发送 SIGHUP 重新加载文件：

docker kill --signal=HUP aisix-quickstart

确认已应用的配置

确认新配置已应用：

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

成功应用时会报告 "state": "synced"，且资源计数应反映本次编辑。通过 SIGHUP 重新加载后，apply_seq 应大于此前的值。如果重新加载失败，网关会继续使用最后一个有效配置提供服务，同时报告 out_of_sync 并标识被拒绝的条目。

动态资源之间可能存在依赖关系。模型可以引用模型服务提供方密钥，调用方 API Key 可以允许使用该模型。当资源来源逐个交付资源时，在包含多个资源的变更期间，一个已接受的资源可能先于另一个资源可见。

请按依赖顺序应用相关资源：

创建或更新模型服务提供方密钥。
创建或更新引用该密钥的模型。
创建或更新可以使用该模型的调用方 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'

自动化流程需要等待变更时，请轮询预期的模型别名，不要固定休眠一段时间。别名出现后，通过行为发生变更的确切端点和模型发送请求。

调用方路径探测不仅能确认配置已被接受，还能验证为应用提供服务的网关已加载资源关系，并能解析调用方的访问权限。

检查延迟的变更

如果预期行为没有出现，请检查受影响网关的配置状态：

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

使用结果定位延迟：

source 显示最新观察到的配置；适用时还会显示存储连接状态。
applied 显示 AISIX 当前提供服务的快照。
rejected 标识验证失败的资源。
last_failure 记录最近一次加载错误。

degraded 状态表示 AISIX 正在使用已接受的子集，同时报告被拒绝的资源。out_of_sync 状态表示最新观察结果被整体拒绝；如果存在最后一个有效配置，AISIX 会继续使用它。

有关完整响应 schema、状态含义、指标和告警，请参阅配置状态。

区分传播问题与请求失败

根据故障发生的位置排查，避免重复提交已经传播的更新：

如果 /status/config 报告资源被拒绝，请修正被拒绝的资源或源文件。
如果预期 etcd 变更期间来源修订版本没有前进，请检查存储连接和监听的前缀。
如果 GET /v1/models 中缺少模型，请检查其别名、类型、调用方访问权限、环境和已应用快照。
如果模型已经出现，但模型服务提供方请求失败，请排查该提供方的凭证、端点、配额或网络路径。
如果某个网关与其他网关不同，请比较各实例的资源来源和已应用快照。

重复同一写入无法修复收不到配置的网关。再次更改资源前，请先确定故障发生在资源来源、应用步骤、资源关系还是请求路径。

下一步

继续阅读健康检查，为进程、流量、配置和模型健康选择合适的探针。

更新如何到达网关​

重新加载资源文件​

添加新的环境变量​

使用现有环境变量重新加载​

确认已应用的配置​

按顺序应用相关资源​

验证配置变更​

检查延迟的变更​

区分传播问题与请求失败​

下一步​