虚拟密钥 (Virtual Keys) 隔离与分发体系

在大模型技术深入企业各个业务系统的过程中，如何安全、可控地向数十个微服务、业务线以及研发团队分发大模型调用凭据，是企业级平台建设的核心命题。传统模式下，若将公有云厂商或本地算力的真实物理 API Key 直接下发给业务团队或配置在业务代码中，极易发生密钥泄密；且一旦真实凭据发生轮换，往往需要所有业务线同步修改配置并重启服务，造成极大的运维风险与协调负担。

OmniCortex 提供了虚拟密钥（Virtual Keys）隔离与受控分发体系。网关将上游各云厂商与私有模型的真实物理凭据安全加密托管在网关内部，对外仅向业务系统分发由网关颁发的虚拟凭据。系统支持按团队、人员或全局多维实体绑定，支持继承标准化访问策略集（Access Profiles），并提供时效自动过期（TTL）、即时启停开关、单凭据即时安全轮换与周期用量监控等全生命周期管控能力，构筑零信任的大模型访问防护底座。

---

核心机制与业务场景

1. 物理凭证与虚拟凭证解耦 (Zero-Trust Decoupling)

• 真实物理凭证安全托管：上游数十家模型供应商（如 OpenAI、Anthropic、DeepSeek、私有开源集群）的物理真实 API Key 统一保存在网关加密保险库中，对外永不外泄；
• 业务端仅持有虚拟凭据：向业务端分发的均为系统签发的虚拟凭据（格式为统一的标准凭证如 sk-xxxxxxxx...），业务客户端完全无感知上游物理凭据的存在；
• 无感轮换与故障隔离：当上游云厂商的物理 Key 发生泄密或需要轮换时，管理员只需在网关后台更新供应商凭证池，下游所有业务系统无需改动任何一行代码或配置文件。

2. 多维主体归属与用量归集

每个虚拟密钥均需明确其在企业中的归属主体，告别“凭据满天飞、不知谁在用”的混乱现状：

• 团队业务密钥 (team)：绑定具体的部门或业务线（如“智能客服组”、“搜索推荐组”）。该密钥产生的所有调用请求与 Token 消耗自动归集到该部门名下，支撑精细化的部门用量分析；
• 个人开发者密钥 (user)：绑定具体的研发人员，作为其在沙箱演练场或本地研发环境的专属测试凭据。人员调岗或离职时，管理员可一键定位并注销其名下凭证；
• 全局系统密钥 (global)：用于跨部门通用系统、基础设施底座或集中式任务调度中间件。

3. 策略集继承与独立灵活调优

在配置虚拟密钥的访问范围时，系统提供两种灵活模式：

• 策略集受管模式（推荐）：一键关联已创建的模型访问策略（Access Profile），直接继承其预设的模型白名单、渠道覆盖、分流权重及 RPM/TPM 速率限制；当管理员在策略集中更新规则并执行广播时，该密钥自动秒级对齐最新基线；
• 独立灵活覆写：支持在继承策略集的基础上，针对特定重要业务单独放行专用模型或调整限流阈值；也可完全脱离策略集，为该密钥自主配置独立的供应商通道与防护门限。

4. 凭据全生命周期安全闭环

• 时效自动过期 (TTL)：创建密钥时可设定有效期限（如 7 天、30 天、90 天或自定义日期时间）。到期后密钥自动失效，从源头杜绝临时测试或外包项目遗留的“僵尸凭据”；
• 即时断流保护：控制台提供秒级启用/停用开关，当发现某个业务凭据出现异常流量或安全风险时，管理员一键即可关闭该凭据，实时阻断调用；
• 单凭据即时轮换 (Single Rotation)：在控制台表格操作列或详情抽屉中，点击「轮换凭据」，系统弹出二次确认框，确认后网关立即为该密钥重新生成随机凭据字符串，旧凭据即刻失效作废，实现凭证无缝刷新。

5. 虚拟凭证分发与鉴权全景拓扑

🔑

物理凭证脱敏与虚拟密钥受控分发拓扑

物理凭据脱敏托管 ➔ 虚拟密钥多维绑定 ➔ 准入鉴权 ➔ 算力调度

物理脱敏 · 权责闭环

1. 业务端持虚拟凭证发起调用 (Authorization: Bearer sk-xxxxxx)

智能客服 / 业务微服务 / 开发者本地环境 ➔ 携带标准虚拟密钥请求网关

↓

2. 网关鉴权与多维规则校验

校验密钥状态与 TTL 有效期 ➔ 校验模型白名单 ➔ 执行 RPM/TPM 速率与用量配额门禁

↓

3. 上游物理凭据解耦注入与路由派发

网关从安全凭据池提取对应的上游物理真实 Key ➔ 派发至 OpenAI / Claude / 内部开源算力集群

---

企业控制台配置导览

管理入口：「模型与治理」➔「虚拟密钥」（路由路径：/governance/virtual-keys）。

1. 虚拟密钥全景看板与多维检索

进入虚拟密钥管理页面后，系统提供企业级密钥的统一管理看板：

• 组合搜索与筛选：支持按密钥名称模糊搜索、按所属团队架构树下拉筛选、按所属用户筛选，支持按创建时间或状态排序；
• 列表信息覆盖：展示密钥名称与主体归属徽标、凭据 Token 掩码（支持点击复制与查看明文）、周期用量条、速率限制标签、启用状态 Switch 开关及快捷操作栏。

📸 截图替换指引（图 1：虚拟密钥管理看板与多维筛选）

• 需截图内容：登录控制台，点击左侧导航栏「模型与治理」➔「虚拟密钥」（/governance/virtual-keys），展示密钥数据表格与筛选工具栏。
• 关键画面要素：
  1. 顶部 Hero 标题栏包含「虚拟密钥」与 Gateway Hub 徽标、以及「新建密钥」操作按钮；
  2. 搜索过滤栏包含关键字输入框、所属团队架构树下拉、所属用户下拉与刷新按钮；
  3. 表格列展示：密钥名称与归属主体徽标（团队/个人/全局）、脱敏凭据单元格（带复制小图标）、周期用量进度条、限流规则标签、启用状态 Switch 开关及操作列（编辑、轮换、删除）。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/virtual-keys/zh/virtual-keys-overview.png
  • 英文版：Documentation/docs/public/images/virtual-keys/en/virtual-keys-overview.png

---

2. 新建虚拟密钥（抽屉实操详解）

点击右上角「新建密钥」或在列表中点击「编辑」，系统右侧滑出配置抽屉：

📸 截图替换指引（图 2：新建虚拟密钥配置抽屉）

• 需截图内容：点击右上角「新建密钥」展开的完整配置抽屉。
• 关键画面要素：
  1. 抽屉标题显示「新建虚拟密钥」；
  2. 基础信息区展示密钥名称、有效期快捷选项（7d/30d/90d/never/custom）；
  3. 主体归属选择器（全局 / 团队 / 个人单选标签组）；
  4. 策略集选择面板（Access Profile 连接器）或展开的供应商模型路由卡片；
  5. 底部包含取消与创建提交按钮。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/virtual-keys/zh/virtual-key-form-drawer.png
  • 英文版：Documentation/docs/public/images/virtual-keys/en/virtual-key-form-drawer.png

核心配置项说明

配置项	界面项	填写方式	是否必填	配置说明
密钥名称	凭据名称	文本输入（1 ~ 128 字符）	是	区分业务用途的名称（如“智能问答微服务生产 Key”）。
有效期限	有效期	快捷标签（7天/30天/90天/永不过期/自定义）	是	设定密钥的生存周期（TTL），到期后系统自动拒绝该凭证的访问。
主体归属	实体类型	单选标签（全局 / 团队 / 个人）	是	决定该凭据关联的业务主体；选择团队或个人后需在下拉中指定对应实体。
策略绑定	访问策略集	策略模板选择器	否	关联 Access Profile，快速继承其预设的模型白名单与流控规则。
速率门禁	RPM / TPM	数字步进器	否	限制每分钟最大请求次数与 Token 吞吐，可覆盖策略集默认值。

---

3. 凭据资产明细抽屉与即时安全轮换

在虚拟密钥表格中点击任意数据行，系统右侧将滑出「虚拟密钥资产明细抽屉 (VirtualKeyDetailDrawer)」，提供深度审计与快捷操作能力：

• 快捷跨条目导航：抽屉顶部提供前翻/后翻按钮，支持管理员在不关闭抽屉的情况下连续快速检视多把凭据配置；
• 全景状态与多维归属：直观呈现凭据启用状态徽标（已启用/已停用/已过期/配额耗尽）、凭据唯一 ID（一键复制）、所属团队或人员归属卡片及业务描述；
• 周期用量配额监控 (Budgets)：以可视化进度条实时展示当前计费周期的最大配额限制与实际用量，支持查看临时调额（Override）状态；
• 供应商路由与策略详情：完整展示该密钥绑定的策略集、各供应商渠道的模型允许白名单（allowed_models）与熔断黑名单；
• 即时安全轮换与删除：
  • 行内/抽屉安全轮换：支持在表格操作列或抽屉底部点击「轮换密钥」，系统弹出确认提示框后，网关立即为该密钥重新生成全新的凭证字符串，旧凭据即刻失效作废，实现业务零停机安全轮换；
  • 安全删除：针对废弃或存在高危合规风险的密钥，抽屉底部与表格操作列均支持二次确认后彻底注销删除。

📸 截图替换指引（图 3：虚拟密钥资产明细抽屉）

• 需截图内容：在「虚拟密钥」列表点击任意密钥行展开的详情抽屉。
• 关键画面要素：
  1. 抽屉顶部展示跨条目导航箭头、密钥名称、凭据 ID 及「编辑」链接；
  2. 基础卡片展示密钥状态徽标（如绿色「已启用」）与主体归属（如团队名称）；
  3. 周期配额监控区展示用量金额进度条与限额说明；
  4. 绑定的供应商渠道与模型白名单/黑名单标签；
  5. 抽屉底部包含「轮换密钥」警告按钮与「删除」危险按钮。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/virtual-keys/zh/virtual-key-detail-drawer.png
  • 英文版：Documentation/docs/public/images/virtual-keys/en/virtual-key-detail-drawer.png

---

常见问题与排查指南

异常现象 / 错误提示	根本原因排查 (Root Cause)	推荐处理方案
API 调用报 401 认证失败 Invalid or inactive virtual key	1. 客户端请求头中的 Bearer Token 填写错误或包含换行符； 2. 该虚拟密钥在控制台中被置为「停用」状态； 3. 该密钥已达到设定的有效期限（TTL 到期自动失效）。	登录控制台在「虚拟密钥」列表中核实： 1. 点击凭证旁的眼睛图标核对完整 Token 字符串； 2. 检查列表中的启用开关是否处于打开状态； 3. 检查过期时间列，如已过期可点击编辑延长有效期或重新激活。
API 调用报 403 模型访问受限 Model access forbidden by policy	客户端请求的目标模型未包含在该密钥所绑定策略集（或独立配置）的允许模型白名单（allowed_models）中。	点击该密钥的「编辑」按钮，检查关联的策略集或该密钥的供应商渠道配置，将目标模型名称补充至白名单列表中并保存。
API 调用频繁触发 429 速率限制 Rate limit exceeded (RPM/TPM)	业务系统的瞬时调用频次或每分钟 Token 消耗量超过了该密钥设定的 RPM 或 TPM 门限。	根据业务并发峰值需求，在密钥编辑抽屉或其绑定的策略集中适度调大 RPM 或 TPM 限流上限并保存。
轮换凭据后业务调用连续报错	执行密钥轮换后，网关已作废旧凭证并启用了新凭证，但业务系统尚未更新配置。	轮换凭证后，需及时复制新生成的凭证字符串，并更新至业务微服务的环境变量或配置中心中。