版本：1.10.0

服务提供方密钥轮换

轮换服务提供方密钥会替换 AISIX 访问上游服务提供方时使用的凭证。调用方无需修改调用方 API Key 或模型别名。

如果所有依赖模型和透传路由都可以同时切换到新凭证，请原地轮换服务提供方密钥。如果希望逐步迁移这些资源，并保留旧凭证用于回滚，请创建替代服务提供方密钥。

前置条件

开始前请准备：

替代上游凭证。
使用该服务提供方密钥的全部模型与服务提供方透传路由清单。原地修改会影响所有这些依赖资源。
对于 AISIX Enterprise 或 AISIX Cloud，需要管理服务提供方密钥和模型的权限；如果使用替代密钥迁移透传路由，还需要更新受影响路由的权限。
对于开源 AISIX 网关，需要访问网关进程环境和声明式资源文件。
如果替换凭证的同时还会更改上游端点或协议，请查看服务提供方兼容性。

选择轮换策略

策略	影响	适用场景
原地轮换	保留服务提供方密钥引用，并同时切换所有依赖模型和透传路由。	可以快速验证替代凭证，并接受一次协调切换。
替代服务提供方密钥	在模型和透传路由迁移到新密钥期间保留两套凭证。	需要渐进发布、逐资源验证或简单直接的回滚路径。

在 AISIX Enterprise 或 AISIX Cloud 中轮换服务提供方密钥

控制面将服务提供方凭证作为只写密钥存储。读取操作绝不会返回已存储凭证。更新现有服务提供方密钥的密钥会保留其 ID，因此依赖模型和透传路由无需更改。

调用方无需获得新的调用方 API Key，应用可以继续使用相同的模型别名和透传路径。

原地轮换

在控制台中：

打开 服务商密钥，并在目标密钥上选择编辑。
在 上游 API 密钥 中输入替代值。该字段为空，因为控制面不会返回已存储密钥；留空会保留当前值。对于包含多个凭证字段的服务提供方，请提供所有必填字段，并在存在替代方案时选择一种凭证方式。凭证会整体替换，而不是逐字段替换。
选择保存。控制面会加密替代凭证，并将其下发到允许使用该密钥的每个环境。关于保存的配置如何成为有效网关配置，参见资源下发。
通过每个受影响模型和服务提供方透传路由发送请求，确认上游接受新凭证。

要自动执行相同操作，请使用具有写入权限的 Admin Token。完整请求和响应 Schema 参见 AISIX Enterprise / Cloud Admin API 参考。

导出控制面连接信息：

# AISIX_CP 是 Admin API 基础 URL；请包含 /api，且不要以斜杠结尾。
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

通过 api_key 发送替代明文密钥：

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

省略 api_key 会保留已存储密钥，空值会被拒绝。

对于包含多个凭证字段的服务提供方，请在 config 中发送完整替代凭证。以下示例轮换 Amazon Bedrock 凭证：

curl -sS -X PATCH "$AISIX_CP/provider_keys/$PROVIDER_KEY_ID" \
  -H "Authorization: Bearer $AISIX_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 中二选一。

警告

原地轮换会让所有依赖模型和透传路由切换到替代凭证。如果凭证无效，这些资源会持续失败，直到提供可用凭证。需要在验证期间保留旧凭证时，请使用替代服务提供方密钥。

使用替代服务提供方密钥轮换

在控制台中：

使用与旧密钥相同的服务提供方和端点设置创建新的服务提供方密钥，但提供替代凭证。对于自定义上游，请选择相同的适配器。
允许替代密钥在所有受影响环境中使用。
编辑每个受影响模型并选择替代服务提供方密钥。下拉列表只显示目标环境允许使用的服务提供方密钥。如果没有显示替代密钥，请先更新其允许环境。
将每条受影响的服务提供方透传路由重新绑定到替代密钥。配置下发到网关后，通过迁移后的模型和路由发送实际请求。如果保存的变更尚未到达网关，请参见资源下发。
只有在所有依赖模型和透传路由完成迁移并验证替代凭证后，才删除旧服务提供方密钥。

以下 API 示例迁移一个环境中的模型。如果旧服务提供方密钥跨环境共享，请在所有受影响环境中允许替代密钥，并在删除旧密钥前迁移所有依赖模型和透传路由。除直接模型外，还要包含语义路由使用的 Embedding 模型。

导出控制面连接信息和受影响资源 ID：

# AISIX_CP 是 Admin API 基础 URL；请包含 /api，且不要以斜杠结尾。
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_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/provider_keys" \
  -H "Authorization: Bearer $AISIX_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

对于自定义上游，请包含该服务提供方密钥类型所需的端点和适配器。

导出替代 ID，然后更新每个受影响模型：

export REPLACEMENT_PROVIDER_KEY_ID="YOUR_REPLACEMENT_PROVIDER_KEY_ID"

for MODEL_ID in $MODEL_IDS; do
  curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/models/$MODEL_ID" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @- <<EOF
{
  "provider_key_id": "${REPLACEMENT_PROVIDER_KEY_ID}"
}
EOF
done

上面的模型更新不会迁移透传路由。请通过服务提供方透传配置更新所有依赖路由，并在移除旧密钥前验证每个受影响模型和路由的实际请求：

curl -sS -X DELETE "$AISIX_CP/provider_keys/$OLD_PROVIDER_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN"

只要仍有模型或透传路由引用旧密钥，Admin API 就会以 409 CREDENTIAL_IN_USE 拒绝删除，旧密钥仍会保留。删除前请重新绑定或移除每个依赖资源。

在开源 AISIX 网关中轮换服务提供方密钥

资源文件通过 display_name 引用服务提供方密钥。网关加载文件时解析环境变量，因此只修改 Shell 中的变量不会更新已运行的网关进程。

原地轮换

检查现有模型服务提供方 Key 条目并保持其不变。轮换通过替换该条目引用的环境变量值完成：

resources.yaml（模型服务提供方 Key）
provider_keys:
  - display_name: openai-prod
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY}
    api_base: https://api.openai.com/v1

在启动网关使用的环境中替换 OPENAI_API_KEY，然后重启或重新创建网关，使进程获得新值。由于服务提供方密钥名称仍是 openai-prod，模型和透传路由的引用无需更改。

使用替代服务提供方密钥轮换

让网关进程可以访问两套凭证。将 openai-replacement 添加到 provider_keys，然后替换 gpt-4o-prod 模型条目。保持 openai-prod 和其他资源不变：

resources.yaml（替代模型服务提供方 Key 与模型）
provider_keys:
  - display_name: openai-replacement
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY_NEW}
    api_base: https://api.openai.com/v1

models:
  - display_name: gpt-4o-prod
    provider: openai
    model_name: gpt-4o
    provider_key: openai-replacement

替代项是独立的服务提供方密钥。复制旧条目中所有适用的非密钥字段，包括 provider、adapter、api_base、strip_headers、telemetry_tags、request 和 response。除非有意修改其他设置，否则只更改 display_name 和凭证引用。

如果替代环境变量此前对网关进程不可用，请重启或重新创建网关。要分阶段迁移模型，请在文件中同时保留两个服务提供方密钥，将选定模型的引用改为 openai-replacement，并在每批迁移后验证和重新加载文件。还要更新使用旧密钥的每条 passthrough_routes[].provider_key。只有在没有模型或透传路由引用 openai-prod，且所有迁移资源的实际请求均成功后，才删除它。

验证轮换

用于验证模型的网关请求与其管理方式无关。对每个受影响模型：

使用已授权的调用方 API Key，通过面向调用方的别名发送代表性实际请求。
使用模型正常提供服务的端点和请求格式。例如，应通过 /v1/embeddings 验证 Embedding 模型，而不是使用 Chat Completions 端点。
确认上游接受替代凭证并返回预期响应。

对每条受影响的透传路由，按其配置的身份认证方式向对应路径发送代表性请求，确认上游接受替代凭证。

使用替代服务提供方密钥时，请在删除旧密钥前确认每个受影响模型和透传路由都已引用新密钥。在 AISIX Enterprise 和 AISIX Cloud 中，可以通过请求日志检查验证请求；如果保存的变更尚未到达网关，请查看资源下发。对于开源网关，重新加载资源文件后请检查配置状态。

后续步骤

现在，你已经在不改变调用方访问方式的情况下轮换了服务提供方凭证。将模型迁移到其他上游前，请继续阅读服务提供方兼容性，比较支持的请求路径和适配器行为。

前置条件​

选择轮换策略​

在 AISIX Enterprise 或 AISIX Cloud 中轮换服务提供方密钥​

原地轮换​

使用替代服务提供方密钥轮换​

在开源 AISIX 网关中轮换服务提供方密钥​

原地轮换​

使用替代服务提供方密钥轮换​

验证轮换​

后续步骤​

前置条件

选择轮换策略

在 AISIX Enterprise 或 AISIX Cloud 中轮换服务提供方密钥

原地轮换

使用替代服务提供方密钥轮换

在开源 AISIX 网关中轮换服务提供方密钥

原地轮换

使用替代服务提供方密钥轮换

验证轮换

后续步骤