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...）。閘道會在本機保存明文，之後仍可在金鑰詳情中取回；僅早期以雜湊方式建立的歷史金鑰沒有可還原的明文（請求取回時會回傳 409）。若懷疑金鑰外洩，請直接「輪換」。
金鑰清單
金鑰清單會顯示每個虛擬金鑰的：
- 前綴 — 如
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。
