密钥掩码与安全显示

一份你能从屏幕上读出来的凭据是一份你能泄露的凭据。一旦你复制了 一个新密钥，你几乎再也不需要它的明文——你需要的是认出它： 这是哪个密钥、在哪个环境、它是不是那个故障智能体所用的那个。 OrcaRouter 的控制台在不重新打印一份可用密钥的前提下回答这一点： 每个密钥都以一种掩码形式呈现，保留刚好足以识别它的字符， 并隐藏其余部分。 本页涵盖掩码形式看起来如何、明文何时显示与不显示，以及如何在 你自己的日志和工具中安全地掩码 api 密钥值。

​

1. 为什么在显示时掩码 api 密钥值

完整的密钥是一份持有者凭据：任何读到它的人都能以你的身份调用 网关，直到那个密钥的限制。控制台视图不断被复制进截图、屏幕 共享、支持工单和缺陷报告——所以在一个密钥列表中显示活的密钥 会把这其中的每一个都变成一次凭据泄露。 掩码通过分离两个通常被混为一谈的需求来解决这一点：

• 识别 —— 这是哪个密钥？由一个你能一眼读出的稳定掩码 指纹来回答。
• 使用 —— 密钥是什么？ 恰好在创建时回答一次，此后则在一个 刻意的、角色门控的揭示之后回答。

控制台处处满足第一个需求并门控第二个，因此默认表层——你整天 盯着的密钥列表——永远不携带一份可用的密钥。

​

2. 掩码形式看起来如何

控制台显示密钥的品牌前缀，然后一段固定的星号，然后最后四个 字符——足以区分两个密钥，不足以重构其中任何一个。 第一段保留 sk-orca- 前缀和几个开头字符；最后四个字符是你在 交叉引用一个日志行或一个错误时会认出的尾巴。两者之间的一切都 被折叠为一个固定掩码——星号那一段是一个常量，因此它的宽度 永远不会泄露密钥的真实长度。

​

3. 明文何时显示——以及何时不显示

完整密钥只有一个时刻归你复制，以及一条单一的门控路径再次取回它。

​

4. 一个具体的例子：识别泄露的密钥

假设一个告警触发——一个密钥正从一个意外的 IP 发起调用——而 日志行携带掩码尾巴 …7Qm4。你不需要明文就能行动：

1. 打开控制台 Keys 列表（/console/token）。每一行都显示它的 掩码指纹——sk-orca-9f3****7Qm4 及其 environment 标签。
2. 把 …7Qm4 尾巴（和 prod 标签）匹配到那个违规行。掩码形式 恰好是你在这里需要的标识符——列表、告警或你对它的截图中都 没有暴露任何密钥。
3. 禁用那个密钥以暂停它，或删除它以彻底吊销——两者都是 掩码安全的操作，永远不打印明文。参见 管理密钥 和 泄露密钥响应。

整个分诊都基于掩码指纹运行。明文留在你的密钥管理器里， 属于它该在的地方。

​

5. 在你自己的日志和工具中掩码

网关掩码它自己的表层；你掌控你这一侧。同样的原则适用于一个 密钥可能落入你技术栈的任何地方：

• 永远不要记录 Authorization 头或原始的 sk-orca-… 值。 如果你必须记录哪个密钥发起了一次调用，记录控制台所用的 同一形状——前缀和最后四个字符——而非完整密钥。
• 只在一个密钥管理器中存储明文，永远不要在源代码控制、CI 日志，或一个被签入仓库的配置文件中。密钥在控制台中被掩码 恰恰是为了让你自己的系统成为活的密钥所在的唯一地方。
• 狭窄地限定密钥范围，使即便一份泄露凭据也有一个有界的 影响半径——一个模型、一个 IP 范围、一个花费上限。参见 最小权限检查清单。

​

6. 它如何契合其余的密钥卫生

掩码是凭据纵深防御姿态的一层： 关于密钥、策略和工作区如何嵌套以给每个智能体最狭窄身份的全景， 参见 范围与密钥。 规则很简单：控制台向你显示足以认出一个密钥、却永远不足以泄露 一个的内容。把明文留在你的密钥管理器里，在其他任何地方都依靠 掩码指纹，并在一个密钥的身份存疑的那一刻就轮换。