API Key 轮换

定期轮换 API Key 可以降低密钥泄露的影响范围，并满足许多安全合规要求。ARouter 的密钥管理 API 支持零停机轮换。

轮换策略

最安全的轮换模式是先创建后删除：

创建一个与旧密钥具有相同权限的新密钥
将新密钥部署到您的应用程序
验证新密钥是否正常工作
删除旧密钥

这样可以确保零停机——在确认新密钥正常工作之前，流量继续使用旧密钥。

第一步：创建新密钥

使用密钥管理 API 创建替换密钥：

cURL
Python
TypeScript

curl -X POST https://api.arouter.ai/v1/keys \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-v2",
    "allowed_providers": ["openai", "anthropic", "google"],
    "spending_limit": 500.00
  }'

import requests

response = requests.post(
    "https://api.arouter.ai/v1/keys",
    headers={"Authorization": "Bearer lr_live_xxxx"},
    json={
        "name": "production-v2",
        "allowed_providers": ["openai", "anthropic", "google"],
        "spending_limit": 500.00,
    },
)
new_key = response.json()["key"]
print(f"New key created: {new_key[:8]}...")

const response = await fetch("https://api.arouter.ai/v1/keys", {
  method: "POST",
  headers: {
    Authorization: "Bearer lr_live_xxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "production-v2",
    allowed_providers: ["openai", "anthropic", "google"],
    spending_limit: 500.0,
  }),
});

const { key } = await response.json();
console.log(`New key: ${key.substring(0, 8)}...`);

请立即保存返回的密钥值 — ARouter 仅在创建时返回完整密钥一次。

第二步：更新您的应用程序

在部署环境中更新 AROUTER_API_KEY 环境变量（或对应的 Secret）：

# 使用 .env 文件示例
AROUTER_API_KEY=lr_live_new_key_here

# 更新 Kubernetes secret 示例
kubectl create secret generic arouter-credentials \
  --from-literal=api-key=lr_live_new_key_here \
  --dry-run=client -o yaml | kubectl apply -f -

重新部署或重启应用程序以使新密钥生效。

第三步：验证新密钥

在删除旧密钥之前，确认新密钥正常工作：

cURL
Python

curl https://api.arouter.ai/v1/models \
  -H "Authorization: Bearer lr_live_new_key_here"

from openai import OpenAI

# 使用新密钥测试
client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_new_key_here",
)

response = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=5,
)
print("New key verified:", response.choices[0].message.content)

检查 ARouter 控制台，确认请求已出现在新密钥下。

第四步：删除旧密钥

确认新密钥正常工作后，使用旧密钥 ID 将其删除：

cURL
Python

curl -X DELETE https://api.arouter.ai/v1/keys/key_oldid \
  -H "Authorization: Bearer lr_live_new_key_here"

import requests

requests.delete(
    "https://api.arouter.ai/v1/keys/key_oldid",
    headers={"Authorization": "Bearer lr_live_new_key_here"},
)
print("Old key deleted")

自动轮换

对于高安全性环境，可以使用 CI/CD 系统或密钥管理器按计划自动轮换：

GitHub Actions 示例

name: Rotate ARouter Key

on:
  schedule:
    - cron: '0 0 1 * *'  # 每月执行

jobs:
  rotate:
    runs-on: ubuntu-latest
    steps:
      - name: Create new key
        id: create
        run: |
          NEW_KEY=$(curl -s -X POST https://api.arouter.ai/v1/keys \
            -H "Authorization: Bearer ${{ secrets.AROUTER_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"name": "production-auto-rotated"}' \
            | jq -r .key)
          echo "new_key=$NEW_KEY" >> $GITHUB_OUTPUT

      - name: Update secret
        uses: gliech/create-github-secret-action@v1
        with:
          name: AROUTER_API_KEY
          value: ${{ steps.create.outputs.new_key }}
          token: ${{ secrets.GH_TOKEN }}

列出活跃密钥

列出所有活跃密钥以审计当前使用情况：

curl https://api.arouter.ai/v1/keys \
  -H "Authorization: Bearer lr_live_xxxx"

响应：

{
  "data": [
    {
      "id": "key_abc123",
      "name": "production-v2",
      "created_at": "2025-01-15T10:00:00Z",
      "last_used_at": "2025-04-01T08:30:00Z",
      "spending_limit": 500.00
    },
    {
      "id": "key_def456",
      "name": "staging",
      "created_at": "2025-03-01T09:00:00Z",
      "last_used_at": "2025-04-01T07:15:00Z",
      "spending_limit": 50.00
    }
  ]
}

最佳实践

定期轮换 — 对大多数应用程序而言，每月轮换是一个良好的基准
疑似泄露后立即轮换 — 不要等到下次计划轮换
使用描述性名称 — 在密钥名称中包含版本或日期（如 production-2025-04、production-v3）
设置消费限额 — 始终为生产密钥配置 spending_limit 以控制风险敞口
不同环境使用独立密钥 — 生产环境与预发布环境绝不共用同一密钥
定期审计 — 每月检查密钥列表，删除不再使用的密钥
将密钥存储在密钥管理器中 — 使用 AWS Secrets Manager、HashiCorp Vault 或同类工具，而非版本控制中的 .env 文件

完整密钥管理指南请参阅密钥管理，完整 API 参考请参阅密钥管理 API。

快速开始

核心概念

路由

功能特性

使用指南

隐私

管理

最佳实践

框架与集成

供应商接入

帮助

轮换策略

第一步：创建新密钥

第二步：更新您的应用程序

第三步：验证新密钥

第四步：删除旧密钥

自动轮换

GitHub Actions 示例

列出活跃密钥

最佳实践

​轮换策略

​第一步：创建新密钥

​第二步：更新您的应用程序

​第三步：验证新密钥

​第四步：删除旧密钥

​自动轮换

​GitHub Actions 示例

​列出活跃密钥

​最佳实践

轮换策略

第一步：创建新密钥

第二步：更新您的应用程序

第三步：验证新密钥

第四步：删除旧密钥

自动轮换

GitHub Actions 示例

列出活跃密钥

最佳实践