AI 网关虚拟密钥（Virtual Key）
虚拟密钥（Virtual Key）是 AI 网关签发的、用于访问网关代理端点的凭证。你把虚拟密钥下发给应用和 AI 工具，而真实的供应商 API Key 只保存在网关一侧。这样既避免了真实密钥四处散落，又能对每个虚拟密钥单独限权、限速、轮换和吊销。本文介绍虚拟密钥的完整生命周期管理。
为什么用虚拟密钥
- 保护真实密钥 — 应用与工具只接触虚拟密钥，供应商真实 Key 不外泄。
- 按用途细分权限 — 可为不同项目 / 工具创建不同虚拟密钥，各自限制可用模型、可用渠道与速率。
- 可随时收回 — 某个密钥泄露或不再使用时，直接吊销或轮换，不影响其它密钥。
前提条件
- 已登录 ServBay 账号。
- 已在 渠道 页至少添加一个可用渠道。
创建虚拟密钥
进入 AI 网关 → 密钥（Keys） 页，点击 创建（Create）：
- 名称 — 用于识别该密钥的用途（如
claude-code、my-app-dev）。 - 描述（可选） — 补充说明。
- 过期时间 — 可设为永不过期或指定日期。
- 允许的渠道（可选） — 以标签多选限定该密钥只能路由到指定渠道；留空表示不限制。
- 允许的模型（可选） — 限定该密钥只能调用指定模型；留空表示不限制。
- 速率限制（可选）：
- RPM / TPM — 每分钟请求数 / Token 数上限。
- RPD / TPD — 每天请求数 / Token 数上限。
明文只显示一次
密钥创建成功后，网关会一次性显示明文密钥（形如 servbay-sk-xxxxxxxx...），请立即复制保存。关闭后网关只保留前缀用于识别，无法再次查看完整明文。若遗失，只能通过「轮换」重新生成。
密钥列表
密钥列表展示每个虚拟密钥的：
- 前缀 — 如
servbay-sk-abcd...，用于识别。 - 状态 — 有效（active）、已吊销（revoked）、已过期（expired）。
- 创建时间 / 最后使用时间。
- 权限标签 — 允许的模型 / 渠道、速率限制。
管理密钥
在密钥列表中，对每个密钥可执行以下操作：
| 操作 | 说明 | 影响 |
|---|---|---|
| 编辑（Edit） | 修改名称、描述、允许的模型 / 渠道、速率限制 | 立即生效，密钥本身不变 |
| 轮换（Renew） | 重新生成明文，旧明文立即失效，新明文一次性显示 | 需更新所有使用该密钥的应用与工具 |
| 吊销（Revoke） | 立即停用密钥，但保留审计记录 | 不可恢复；用该密钥的请求将被拒绝 |
| 删除（Delete） | 彻底删除密钥 | 不可恢复 |
轮换 vs 吊销
- 轮换（Renew）：密钥本身仍在，只是换了新明文——适合怀疑密钥泄露、但仍要继续使用同一密钥配置的场景，记得同步更新使用方。
- 吊销（Revoke）：让密钥永久失效但保留记录，便于审计——适合确认某密钥不再需要的场景。 轮换与吊销都会要求二次确认。
与一键接管的关系
使用 一键接管 把某个 AI 工具指向网关时，网关会自动为该工具创建一个专属虚拟密钥并写入工具配置。你也可以在密钥页手动管理这些自动创建的密钥。
常见问题（FAQ）
- Q：我忘记复制明文密钥了怎么办？
- A：明文无法再次查看，请对该密钥执行「轮换」，用新生成的明文替换应用中的旧值。
- Q：吊销和删除有什么区别？
- A：吊销会保留密钥记录（便于审计），删除则彻底清除。两者都会让密钥立即失效。
- Q：限制了「允许的模型」后，应用请求其它模型会怎样？
- A：网关会拒绝该密钥权限外的模型请求。请确保应用使用的模型在允许列表内，或放开限制。
- Q：速率限制被触发会怎样？
- A：超过 RPM/TPM/RPD/TPD 的请求会被网关限流。可在 统计 页观察实际用量后调整上限。
总结
虚拟密钥让你以最小权限、可撤销的方式把 AI 能力下发给应用和工具。配合允许模型 / 渠道限制与速率限制，你可以为每个使用场景量身定制凭证，并在需要时随时轮换或吊销，而无需触碰真实的供应商 API Key。
