金鑰遮罩與安全顯示

一張你能從螢幕上讀出來的憑證，是一張你能洩漏的憑證。一旦 你複製了一把新金鑰，你幾乎再也不需要它的明文——你 需要的是辨識它：這是哪把金鑰、在哪個環境、是不是 那個失敗代理所用的那把。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. 這如何契合金鑰衛生的其餘部分

遮罩是憑證縱深防禦姿態的一層： 要了解金鑰、政策與工作區如何巢狀以給每個代理 最狹窄身份的更大圖景，參見 範圍與金鑰。 規則很簡單：主控台顯示給你足以辨識一把金鑰、卻 永遠不足以洩漏一把的東西。把明文留在你的密鑰管理器中、 在其他每個地方仰賴遮罩指紋，並在一把金鑰的身份有疑慮時 立即輪替。