服务提供方密钥轮换

服务提供方密钥轮换会替换上游凭证，但保持面向调用方的 API Key 和模型别名稳定。调用方继续使用相同的 model 值和相同的调用方 API Key，只有受影响模型资源背后的上游凭证会变化。

AISIX Cloud 会将服务提供方密钥 Secret 作为只写凭证材料保存，因此不能从控制台直接编辑已有服务提供方密钥上的上游 Secret。如需更换凭证，请创建替换服务提供方密钥，并将每个受影响模型指向该新密钥。

准备工作

你是可以在目标环境中管理服务提供方密钥和模型的 Owner 或成员。
你已获得新的上游 Secret（例如刚签发的服务提供方 API Key）。
你知道哪个或哪些模型引用了正在轮换的服务提供方密钥。服务提供方密钥是共享依赖，因此每个引用它的模型都会受到影响。

轮换如何工作

调用方继续使用相同的模型别名。AISIX Cloud 会更新受影响模型上的服务提供方密钥引用，然后将变更投射到托管网关。调用方无需修改配置。

变化的是 AISIX 向上游发送请求时使用的服务提供方密钥。调用方不需要新的调用方 API Key；只要模型别名保持不变，应用也不需要更改 model 值。旧服务提供方密钥可以保留到实时流量确认替换路径正常之后。

轮换服务提供方密钥

请按以下顺序轮换，避免请求被发送到缺失凭证的模型：创建替换密钥、更新每个受影响模型、确认实时流量，然后再删除旧密钥。

在控制台中操作

打开 Provider keys，选择 New provider key，输入与待替换密钥相同的服务提供方和 base URL，并使用新的上游 Secret。对于自定义上游，请重新选择相同协议适配器；目录服务提供方会自动设置适配器。允许该密钥用于正在轮换模型的环境，然后选择 Create provider key。
打开该环境下的 Models，逐个编辑受影响模型，将 Provider key 下拉框切换到替换密钥。下拉框只会列出该环境可用的密钥。如果看不到替换密钥，请先在 Provider keys 页面扩大其允许环境范围。然后保存每个模型。
等待 AISIX Cloud 将更新后的模型投射到托管网关。资源投射说明了已保存配置如何变成正在服务的网关配置。
通过托管网关端点向受影响模型发送请求，并确认请求使用新凭证后成功。参见验证轮换。
只有在实时流量确认后，才删除旧服务提供方密钥。删除仍被模型引用的密钥会破坏这些模型，因此请先更新所有依赖模型。

使用 API

当轮换是自动化流程的一部分时，请使用 API。先使用具有写权限的 Admin Token 认证，然后执行同样的顺序。准确请求和响应 schema 请参见 Cloud Admin API 参考。

下面示例轮换一个环境中的模型。如果旧服务提供方密钥被多个环境共享，请创建允许所有受影响环境使用的替换密钥，然后在每个环境中更新所有受影响模型，最后再删除旧密钥。

将 MODEL_IDS 设置为 ENV_ID 中当前引用旧服务提供方密钥的模型资源，包括语义路由器使用的嵌入模型。单模型轮换时填写一个模型 ID；同一环境中多个模型共享该密钥时，填写空格分隔列表。

设置示例所需变量：

export AISIX_CLOUD_API="https://<your-cp-api-host>/api"
export AISIX_ADMIN_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export MODEL_IDS="YOUR_MODEL_ID_1 YOUR_MODEL_ID_2"
export OLD_PROVIDER_KEY_ID="YOUR_OLD_PROVIDER_KEY_ID"

创建替换服务提供方密钥，并复制返回的服务提供方密钥 ID：

curl -sS -X POST "${AISIX_CLOUD_API}/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "display_name": "OpenAI replacement",
    "api_key": "YOUR_NEW_UPSTREAM_API_KEY",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }'

对于自定义上游，请包含该服务提供方密钥类型要求的端点和适配器字段。Cloud Admin API 参考列出了完整的服务提供方密钥 schema。

从创建响应中设置替换服务提供方密钥 ID：

export REPLACEMENT_PROVIDER_KEY_ID="YOUR_REPLACEMENT_PROVIDER_KEY_ID"

更新每个受影响模型，让它引用替换密钥：

for MODEL_ID in ${MODEL_IDS}; do
  curl -sS -X PATCH "${AISIX_CLOUD_API}/environments/${ENV_ID}/models/${MODEL_ID}" \
    -H "Authorization: Bearer ${AISIX_ADMIN_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "provider_key_id": "'"${REPLACEMENT_PROVIDER_KEY_ID}"'"
    }'
done

当每个受影响模型都已通过替换凭证成功处理实时流量后，删除旧服务提供方密钥：

curl -sS -X DELETE "${AISIX_CLOUD_API}/provider_keys/${OLD_PROVIDER_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_TOKEN}"

不要使用服务提供方密钥 PATCH 端点来轮换上游 Secret。该端点可以更新服务提供方密钥元数据和端点设置，但不会替换只写的 api_key 值。

警告

在通过托管网关发送的实时请求确认替换密钥可用之前，不要删除旧服务提供方密钥。在此之前请保留两组密钥，以便新凭证错误时可以切回旧密钥。

验证轮换

更新受影响模型后，请先验证替换路径，再删除旧服务提供方密钥：

在 Models 页面确认每个受影响模型都显示替换服务提供方密钥。
通过托管网关端点向每个受影响模型发送请求，并确认成功。
检查用量上报或日志与审计，确认新的请求仍然成功。

实时流量确认后，再移除旧服务提供方密钥。

如果实时流量仍然失败，请检查新的上游 Secret、服务提供方专属认证要求，以及受影响模型的服务提供方密钥引用。如果模型已经保存为替换密钥，但网关仍表现为旧行为，请先检查资源投射，不要直接假设新凭证无效。

下一步

你已经了解如何在不改变调用方访问方式的情况下轮换服务提供方凭证。接下来阅读日志与审计，在轮换后检查真实托管网关请求。

准备工作​

轮换如何工作​

轮换服务提供方密钥​

在控制台中操作​

使用 API​

验证轮换​

下一步​