BYOK (Store Keys)

Bring your own keys (BYOK) 是 Cloudflare AI Gateway 中的一项功能，允许你直接在 Cloudflare 仪表板中安全存储 AI 提供商 API 密钥。无需在每个 AI 模型请求中包含 API 密钥，你可以在仪表板中配置一次，并在 gateway 配置中引用它们。

密钥通过 Secrets Store 安全存储，并提供以下优势：

• 安全存储并限制暴露
• 更轻松的密钥轮换
• 通过 Dynamic Routes 实现速率限制、预算限制和其他限制

• 确保你的 gateway 已认证。
• 确保你拥有在 Secrets Store 上创建和部署密钥的适当权限。

你可以从仪表板或使用 API 配置 BYOK。

从仪表板添加提供商密钥时，AI Gateway 会自动创建并命名 Secrets Store 密钥。

1. 登录 Cloudflare 仪表板 ↗并选择你的账户。
2. 前往 AI > AI Gateway。
3. 选择你的 gateway 或创建新的 gateway。
4. 前往 Provider Keys（提供商密钥） 部分。
5. 点击 Add API Key（添加 API 密钥）。
6. 从下拉菜单中选择 AI 提供商。
7. 输入 API 密钥，并可选择提供描述。
8. 点击 Save（保存）。

如果使用 API 配置 BYOK，请在创建提供商配置之前创建 Secrets Store 密钥。使用以下格式命名密钥：

{gateway_id}_{provider_slug}_{alias}

例如，对于 gateway my-gateway、提供商 anthropic 和别名 default，创建 Secrets Store 密钥为：

my-gateway_anthropic_default

然后使用相同的 provider_slug 和 alias 值创建提供商配置。

Secrets Store 返回的 secret_id 不被 AI Gateway 用于运行时查找，因此通过 API 创建的密钥必须遵循命名约定。

在仪表板中配置 API 密钥后：

1. 从代码中移除 API 密钥：删除任何硬编码的 API 密钥或环境变量。
2. 更新请求标头：从请求中移除提供商授权标头。请注意，你仍需要传递 cf-aig-authorization。
3. 测试集成：验证不包含 API 密钥时请求是否正常工作。

启用 BYOK 后，你的工作流程从以下变为：

1. 传统方式：在每个请求标头中包含 API 密钥

   curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
     -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
     -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model": "gpt-4", "messages": [...]}'

2. BYOK 方式：在仪表板中配置一次密钥，发送请求时不暴露密钥

   curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
     -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
     -H "Content-Type: application/json" \
     -d '{"model": "gpt-4", "messages": [...]}'

在 AI Gateway 仪表板中，你可以：

• 按提供商查看所有已配置的 API 密钥
• 查看每个密钥上次使用时间
• 检查每个密钥的状态（active、expired、invalid）

要轮换 API 密钥：

1. 从 AI 提供商生成新的 API 密钥
2. 在 Cloudflare 仪表板中，编辑现有密钥条目
3. 用新密钥替换旧密钥
4. 保存更改

应用将立即开始使用新密钥，无需任何代码更改或停机。

要移除 API 密钥：

1. 在 AI Gateway 仪表板中，找到要移除的密钥
2. 点击 Delete（删除） 按钮
3. 确认删除

AI Gateway 支持为同一提供商存储多个 API 密钥。这允许你：

• 为不同用例使用不同密钥（例如，开发 vs 生产）
• 在轮换期间逐步在密钥之间迁移

每个 API 密钥可以分配别名以标识它。添加密钥时，你可以指定自定义别名，或系统将使用 default 作为别名。

发送请求时，AI Gateway 默认使用别名为 default 的密钥。要使用不同密钥，请包含 cf-aig-byok-alias 标头及要使用的密钥别名。

如果你配置了具有不同别名（例如 default、production 和 testing）的多个 OpenAI 密钥，可以指定使用哪一个：

# 使用别名为 "default" 的密钥（无需标头）
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [...]}'

# 使用别名为 "production" 的密钥
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
  -H 'cf-aig-byok-alias: production' \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [...]}'

# 使用别名为 "testing" 的密钥
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
  -H 'cf-aig-byok-alias: testing' \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [...]}'