跳到主要内容

服务提供方密钥轮换

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

当上游服务提供方向你签发替换 Secret 时，可原地轮换服务提供方密钥。引用该密钥的每个模型都会使用新凭证，因此无需修改模型或调用方配置。

若要逐个迁移模型，并保留旧凭证作为回退，请改用创建替换密钥的方式轮换。

准备工作​

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

轮换如何工作​

托管控制面会将服务提供方密钥 Secret 作为只写凭证材料保存。它永远不会返回已保存的 Secret，因此轮换时需要提供新值，而不会暴露现有值。

模型按 ID 引用服务提供方密钥，并在请求时解析其凭证。因此，替换密钥上的 Secret 会作用于每个依赖模型，而无需更新这些模型。

调用方不需要新的调用方 API Key；只要模型别名保持不变，应用也不需要更改 model 值。

原地轮换服务提供方密钥​

在控制台中操作​

  1. 打开 Provider keys，在要轮换的密钥上选择 Edit。
  2. 在 Upstream API key 中输入新 Secret。该字段为空是因为托管控制面不会返回已保存的 Secret；留空会保留当前密钥。对于 Amazon Bedrock 或 Google Vertex AI 等凭证包含多个字段的服务提供方，请填写所有必填字段，并在存在替代方案时选择一种凭证方式。凭证会整体替换，而不是逐字段替换。
  3. 选择 Save。托管控制面会重新加密凭证，并将其投射到允许使用该密钥的每个环境。资源投射说明了已保存配置如何变成正在服务的网关配置。
  4. 通过托管网关端点向受影响模型发送请求，并确认新凭证可用。参见验证轮换。

使用 API​

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

设置示例所需变量：

# 请替换为实际值
export AISIX_CP_API="https://<your-cp-api-host>/api"
export AISIX_ADMIN_TOKEN="YOUR_ADMIN_TOKEN"
export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

在 api_key 中发送新 Secret：

curl -sS -X PATCH "${AISIX_CP_API}/provider_keys/${PROVIDER_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_NEW_UPSTREAM_API_KEY"
  }'

省略 api_key 会保留已保存的 Secret，因此更新其他字段时无需重新发送凭证。空的 api_key 会被拒绝，而不会被视为清除密钥。

如果服务提供方凭证包含多个字段，请改为在 config 中发送完整凭证。以下示例轮换 Amazon Bedrock 凭证：

curl -sS -X PATCH "${AISIX_CP_API}/provider_keys/${PROVIDER_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "access_key_id": "YOUR_NEW_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_NEW_SECRET_ACCESS_KEY",
      "region": "us-west-2"
    }
  }'

请包含服务提供方要求的所有字段，而不只是发生变化的字段。例如，Google Vertex AI 要求提供 project、region，并且必须且只能提供 access_token 或 service_account_json 之一。

警告

原地轮换会同时切换该密钥上的所有模型。如果新凭证错误，受影响的模型会持续失败，直到发送可用凭证。若要在验证期间保留回退，请改用替换密钥。

使用替换密钥逐步轮换​

当你希望逐个将模型迁移到新凭证、逐一验证并保留旧凭证以便切回时，请使用此方式。对于被多个模型依赖的服务提供方密钥，这是更安全的选择。

请按以下顺序轮换：创建替换密钥、更新每个受影响模型、确认实时流量，然后再删除旧密钥。

在控制台中操作​

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

使用 API​

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

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

设置示例所需变量：

# 请替换为实际值
export AISIX_CP_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_CP_API}/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "provider": "openai",
    "display_name": "OpenAI replacement",
    "api_key": "YOUR_NEW_UPSTREAM_API_KEY",
    "allowed_environments": ["${ENV_ID}"]
  }
EOF

对于自定义上游，请包含该服务提供方密钥类型要求的端点和适配器字段。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_CP_API}/environments/${ENV_ID}/models/${MODEL_ID}" \
    -H "Authorization: Bearer ${AISIX_ADMIN_TOKEN}" \
    -H "Content-Type: application/json" \
    --data-binary @- <<EOF
    {
      "provider_key_id": "${REPLACEMENT_PROVIDER_KEY_ID}"
    }
EOF
done

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

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

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

验证轮换​

验证新凭证是否正在处理流量：

  1. 通过托管网关端点向每个受影响模型发送请求，并确认成功。
  2. 检查请求日志，确认新请求已成功。
  3. 如果使用替换密钥轮换，请在 Models 页面确认每个受影响模型都显示替换服务提供方密钥，然后移除旧密钥。

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

下一步​

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