跳到主要内容

服务提供方密钥轮换

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

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

前置条件​

开始前请准备：

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

选择轮换策略​

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

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

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

只要模型别名保持不变，调用方无需获得新的调用方 API Key，应用也无需修改模型别名。

原地轮换​

在控制台中：

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

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

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；请包含 /api，且不要以斜杠结尾。
# 本地 On-Premises 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_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 中二选一。

警告

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

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

在控制台中：

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

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

导出 AISIX Cloud 连接信息和受影响资源 ID：

# AISIX_CP 是 Admin API 基础 URL；请包含 /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"
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"

如果仍有模型引用该服务提供方密钥，删除它会导致这些模型无法成功分发请求。删除前请重新绑定每个依赖模型。

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

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

原地轮换​

保持服务提供方密钥条目及其环境变量名称不变：

resources.yaml
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，模型引用无需更改。

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

让网关进程可以访问两套凭证，并声明两个服务提供方密钥：

resources.yaml
provider_keys:
  - display_name: openai-prod
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY_OLD}
    api_base: https://api.openai.com/v1
  - 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，并在每批迁移后验证和重新加载文件。只有在没有模型引用 openai-prod，且所有迁移模型的实际请求均成功后，才删除它。

验证轮换​

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

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

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

后续步骤​

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