资源投射
AISIX Cloud 会将已保存的资源变更发布到连接该环境的网关。每个网关都会验证新修订版本，并将接受的配置应用于新请求。发布是异步的，因此各网关实例可能会暂时报告不同的修订版本。
控制台或 API 返回成功，只能确认控制面接受了变更。要验证变更已生效，请依次追踪控制面修订版本、网关快照和实时请求。
资源作用域
资源所有权决定哪些环境会接收资源。资源的挂载、引用或条件进一步决定哪些请求会使用它。
| 资源类别 | 所有权与投射 | 请求作用域 |
|---|---|---|
| 模型和调用方 API Key | 属于一个环境，投射到连接该环境的所有网关。 | 请求的模型和解析 出的调用方 API Key 决定适用条目。 |
| 模型服务提供方密钥 | 属于组织，仅投射到允许使用它们的环境。 | 模型引用模型服务提供方密钥；透传路由注入上游凭证时也会引用它。 |
| MCP 服务器和基于 OpenAPI 的服务器 | 属于组织。已批准的服务器仅投射到允许使用它们的环境；基于 OpenAPI 的服务器是 type: openapi 的 MCP 服务器。 | 调用方工具授权和适用的安全护栏挂载控制访问与检查。 |
| A2A Agent | 属于组织，仅投射到允许使用它们的环境。 | 调用方 API Key 必须具有该 Agent 的访问权限。 |
| 安全护栏及其挂载 | 属于一个环境，一起投射。未挂载的安全护栏不会执行。 | 挂载将安全护栏的作用域限定为环境、模型、调用方 API Key、团队、MCP 服务器或透传路由。 |
| 缓存策略 | 属于一个环境，投射到该环境的网关。 | 策略可以覆盖整个环境、某个模型别名或某个调用方 API Key。 |
| 限流策略 | 属于一个环境，投射到该环境的网关。 | 条件可以按团队、成员、调用方 API Key、模型、模型名称或服务提供方选择流量。 |
| OIDC 提供方与声明映射 | 属于一个环境，投射到该环境的网关。 | 对 JWT 调用方进行认证，并将符合条件的声明解析为调用方 API Key。 |
| 透传路由 | 属于一个环境，投射到该环境的网关。 | 路由匹配和调用方 API Key 的路由授权决定访问权限。 |
| 可观测性导出器 | 属于一个环境，投射到该环境的网关。 | 每个已启用的导出器会根据自身类型和内容设置接收符合条件的网关遥测数据。 |
| MCP 环境访问与认证设置 | 属于一个环境，投射到该环 境的网关。 | 环境策略定义默认的工具访问层。认证设置定义 /mcp 的 API Key、OAuth 或匿名访问行为。 |
| MCP 团队访问策略 | 通过团队归属于组织，投射到该组织的所有环境。 | 团队策略适用于绑定该团队的调用方 API Key，并与环境级和密钥级访问层取交集。 |
| 预算 | 保留在 AISIX Cloud 控制面中，不进入投射快照。 | 网关为解析出的调用方 API Key 请求预算决策，并可在中断期间临时使用缓存决策。参见预算。 |
修改组织级资源允许使用的环境，会从相应快照中添加或移除该资源。写入成功只能确认控制面接受了资源及其目标环境，不能确认所有网关都已接收。
验证投射的变更
按顺序检查控制面、网关和实时请求。
1. 比较已发布和已应用的修订版本
设置控制面 API URL、具有 read 权限范围的 Admin Token 和环境 ID：
# AISIX_CP 包含 /api，末尾不带斜杠
# 本地 On-Premises 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
比较 store_revision 与各节点的 applied_revision：
curl -sS "${AISIX_CP}/environments/${ENV_ID}/dp_nodes" \
-H "Authorization: Bearer ${AISIX_TOKEN}" \
| jq '{
store_revision,
nodes: [
.data[] |
{
hostname,
dp_version,
last_heartbeat_at,
applied_revision,
config_hash,
partially_compatible_resources
}
]
}'
当节点的 applied_revision 大于或等于 store_revision 时，该节点即为最新状态。config_hash 相同表示各网关实例接受了相同的配置。
partially_compatible_resources 会列出节点在提供服务时忽略了自身无法识别字段的资源。如果要求每个字段都必须生效，请确保该列表为空或未返回。
控制台也会显示相同的网关上报信息。环境概览会区分被忽略的字段和整个资源被拒绝的情况，Data planes 则显示各节点的兼容性状态与详情。即使最初保存配置时没有返 回警告，也要检查这些运行时信号，因为之后可能有网关注册或回滚。
当修订跟踪不可用，或网关尚未上报相关字段时，控制面可能会省略 store_revision、applied_revision 或 config_hash。此时，请使用下一步中的网关状态端点。心跳按周期上报，因此网关的直接状态也可能比控制面视图更新。
如果网关没有最新心跳，请先排查其管理连接，再检查资源投射。请参阅连接 AISIX 网关。
2. 检查网关快照
查询正在处理流量的网关实例上的指标和状态监听器：
# AISIX_STATUS_URL 是指标与状态监听器的源地址，不含末尾斜杠或端点路径
# 开源快速入门使用 http://127.0.0.1:9090
export AISIX_STATUS_URL="YOUR_AISIX_STATUS_LISTENER_URL"
curl -sS "${AISIX_STATUS_URL}/status/config" \
| jq '{
state,
source,
applied,
rejected,
partially_compatible,
last_failure
}'
当 state 为 synced、source.connected 为 true、applied.applied_revision 反映预期修订版本且 rejected 与 partially_compatible 均为空时，变更即已完全应用。
如果 source.connected 为 false，请恢复配置连接。中断期间，网关可以继续使用最近一次接受的快照提供服务，但无法接收新变更。请参阅离线韧性。
如果 state 为 degraded 或 out_of_sync，请使用 rejected 和 last_failure 识别无效资源。如果 partially_compatible 不为空，表示该资源仍在提供服务，但其中列出的字段在此网关上不会生效。有关状态定义、完整响应和 Prometheus 指标，请参阅配置状态。
状态监听器不需要身份认证。请确保端口 9090 仅对监控网络开放。
3. 验证调用方可见行为
网关应用变更后，请通过应用实际使用的同一个网关端点和调用方身份进行验证。
对于模型或调用方访问权限变更，先查询模型发现端点：
# AISIX_PROXY 是网关源地址，不含末尾斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
curl -sS "${AISIX_PROXY}/v1/models" \
-H "Authorization: Bearer ${AISIX_API_KEY}" \
| jq -r '.data[].id'
确认预期的模型别名已出现，然后按照相应模型服务提供方或功能指南发送请求。
如果修订版本匹配后结果仍不符合预期，请先确认请求到达了所检查的网关，再检查环境、模型别名、调用方 API Key、模型服务提供方密钥的环境访问权限和策略作用域。
下一步
如果尚未发送实时流量，请选择模型服务提供方上游，并按照相应的设置指南操作。在将多个网关实例置于生产负载均衡器之前，请阅读高可用。