API 密鑰輪換：如何不停機輪換支付 API Key，密鑰泄露時該怎麼辦

API 密鑰輪換是按計劃或在出事之後，用一把新密鑰替換舊密鑰，讓可能已被複製的密鑰失效。對支付 API 來説，這件事的風險很高：一把正式密鑰可以在你的賬戶上創建訂單和退款。所以輪換必須是例行操作，而且必須不停機：你的服務器永遠不能拿着一把已經失效的密鑰。

這篇文章講清楚如何不停機地輪換支付 API Key、密鑰泄露後最初幾分鐘該做什麼、如何證明舊密鑰已經沒人使用，以及從源頭上防止密鑰泄露的習慣。

輪換和吊銷有什麼區別？

經驗法則：情況在你掌控之中就輪換，不在掌控之中就吊銷。 泄露的密鑰比部署新密鑰期間的幾次失敗調用危險得多。

如何不停機輪換 API 密鑰

在 KukoPay，打開 開發者 → API 密鑰，找到這把密鑰，點擊 輪換。你可以選擇 舊 Key 保留時長：

然後：

1. 立刻複製新密鑰。 正式密鑰只在簽發時完整顯示一次，之後後台只顯示前綴和末四位。把它存到你的密鑰管理工具或服務端配置裏，不要寫進代碼。
2. 部署到每一個調用 API 的服務。
3. 觀察舊密鑰的流量。 每把密鑰都顯示 最近使用 時間；舊密鑰的這個時間不再變化，就説明已經沒有服務依賴它了。
4. 讓它在保留期結束時失效，或者確認無誤後再輪換一次並選擇 立即失效。

因為保留期內兩把密鑰都能用，所以不存在任何一個請求因為切換而失敗的時刻。

API 密鑰泄露了怎麼辦？

被推送到公開倉庫、貼進工單、打印在日誌裏或打包進移動 App 的密鑰，都應該視為已經泄露。

1. 立即吊銷。 吊銷 會讓密鑰立刻失效。不要等部署完成，泄露的正式密鑰幾分鐘內就可能被利用。
2. 簽發替代密鑰：點擊 簽發新 Key 並部署。在更新完成之前，仍在使用舊密鑰的地方會收到 401，這是堵住漏洞的代價。
3. 查看它做過什麼。 API 請求日誌記錄了每一次調用使用的 key_id，保留 30 天，可以據此查看泄露的密鑰調用過什麼，見 API 調用日誌。留意你不認識的訂單、退款或 Webhook 端點。
4. 從泄露的地方刪除它：改寫提交記錄、刪除日誌、重新打包 App，並查明它是怎麼泄露的。

正式密鑰的簽發、輪換和吊銷都會郵件通知賬戶的所有者和管理員，所以賬戶上發生了意外的變更也不會被忽略。

如何確認舊密鑰已經沒人使用

• 每把密鑰的 最近使用 顯示它最後一次通過認證的時間（最多每分鐘更新一次）。
• API 請求日誌 記錄了每次調用的 key_id，可以看出哪些服務還在用舊密鑰。
• 簽發時給密鑰起名字，比如「生產服務器」「賬單任務」，這樣舊密鑰還有流量時，你知道該去找誰。

一個服務一把密鑰

每個應用在每個環境下最多可以持有 5 把長期有效的密鑰。好好利用它們：

• 每台服務器或每個服務一把，並以它命名。這樣一旦泄露，只需要輪換一把，而不是所有服務一起換；最近使用 也能準確告訴你是哪個服務在用這把密鑰。
• 每個接入一個應用。 密鑰屬於應用，只能看到該應用的訂單、退款和 Webhook，查詢其他應用的對象會返回 404，所以從一個邊緣項目泄露的密鑰碰不到你主站的數據。

支付 API 密鑰的最佳實踐

• 只放在服務端。 支付 API Key 等同於你賬戶的服務端操作權限。永遠不要把它放進瀏覽器 JavaScript、移動 App、前端構建變量或公開倉庫；瀏覽器只應該和你自己的後端通信。
• 用密鑰區分環境。 kuko_test_ 密鑰只能訪問沙箱，kuko_live_ 密鑰只能訪問正式環境；沒有任何請求字段可以切換環境，所以測試代碼永遠動不了真實資金。把測試和正式密鑰放在不同的配置裏。
• 把密鑰鎖定在你的服務器上。 應用的 IP 白名單（單個 IPv4、IPv4 CIDR 或精確的 IPv6 地址）讓被複制的密鑰在其他地方毫無用處，白名單外的調用返回 403 ip_not_allowed。沒有固定出口 IP 的雲函數平台不建議啓用。
• 定期輪換，有權限的人員離職時也要輪換，而不是只在出事後才換。
• 不要把密鑰寫進日誌。 在你自己的請求日誌和錯誤報告裏遮蓋 X-Api-Key 請求頭。KukoPay 自己的 API 日誌在入庫前會對密鑰類字段脱敏。

Webhook 簽名密鑰也要輪換

給 Webhook 簽名的密鑰同樣是憑證。輪換 Webhook 端點的密鑰時，舊密鑰會和新密鑰一起簽名 24 小時，每次投遞都帶兩個簽名，你可以在這段時間內任意時刻切換。只要任意一個 v1= 簽名匹配就接受投遞，只保留一個簽名的坑見 收不到支付 Webhook 回調怎麼辦。

相關指南

• 超時後如何安全重試：冪等鍵是什麼
• 如何處理 429 響應：API 調用頻率限制與 429 Too Many Requests
• 如何驗簽並去重 Webhook：Webhook 重複通知怎麼辦

總結

• API 密鑰輪換是按你的計劃更換密鑰；吊銷是讓泄露的密鑰立即失效；
• 在 KukoPay，輪換 會簽發新密鑰，並讓舊密鑰在你選擇的時長內（從立即到 7 天）繼續可用，所以輪換不會造成停機；
• 密鑰泄露：先吊銷，再替換，然後在請求日誌裏按 key_id 查看它的調用；
• 最近使用 和日誌裏的 key_id 能告訴你舊密鑰是否真的已經沒人用；
• 每個服務一把有名字的密鑰，密鑰只放在服務端，能用 IP 白名單就用，並定期輪換。