Skip to main content
首頁博客指南如何設定及輪替貨件追蹤 API 金鑰而不影響您的整合

如何設定及輪替貨件追蹤 API 金鑰而不影響您的整合

17TRACK

要安全地設定及輪換貨件追蹤 API 金鑰,請將憑證保存在伺服器端的秘密管理器中,識別每個使用這些憑證的應用程式,並在停用舊金鑰前測試替換金鑰。如果你的供應商支援憑證重疊,請逐步遷移使用者,並只在驗證完成後撤銷舊金鑰。如果替換操作會立即使現有金鑰失效,請使用持久佇列及復原檢查規劃協調一致的切換,而不要假設可以做到零停機。

如何設定及輪換貨件追蹤 API 金鑰而不影響服務

本指南適用於在電子商務平台、訂單管理系統、倉庫軟件及客戶通知服務中維護追蹤整合的開發人員及營運團隊。目標不只是發出經身份驗證的請求,而是在變更期間保留貨件註冊、追蹤更新及下游處理。

確認供應商如何處理憑證

在變更生產環境設定前,先了解供應商的憑證生命週期。控制面板中標示為「重新產生」的操作,行為可能與「建立另一個金鑰」不同。不要根據按鈕標籤推斷其行為。

  • 身份驗證格式:確認所需的標頭或其他身份驗證機制、端點版本及帳戶關聯。
  • 重疊:兩個憑證能否同時保持有效?產生替換憑證是否會立即撤銷之前的憑證?
  • 權限:確定金鑰是否有獨立範圍、環境限制或存取控制。若有這些控制,請加以使用;不要假設它們一定存在。
  • 撤銷:確認如何停用憑證,以及是否需要考慮任何傳播行為。
  • 營運影響:確定配額、已註冊貨件及 webhook 設定是屬於帳戶、應用程式,還是個別金鑰。

對於 17TRACK 整合,請先查看官方 Tracking API 文件及Tracking API 產品頁面。使用文件確認整合所需的身份驗證合約,並在安排輪換前透過帳戶控制項或支援服務確認憑證生命週期行為。以下程序是營運操作手冊,並不代表 17TRACK 提供特定的雙金鑰或重新產生流程。

決策規則:只有在確認憑證可同時有效時,才使用重疊金鑰推出方式。否則,應將輪換視為協調一致的憑證替換。部署策略無法創造供應商不支援的重疊時間窗口。

一次設定金鑰,避免在系統中散播

將身份驗證保留在伺服器端

將生產憑證儲存在受管理的秘密儲存區或同等的受控系統中。讓應用程式透過其工作負載身份、部署平台或其他獲批准的機制取得憑證。限制需要使用憑證的工作負載及操作人員的讀取權限。

不要將金鑰嵌入瀏覽器 JavaScript、流動應用程式套件、原始碼、容器映像檔或共享設定範例中。面向客戶的追蹤頁面應呼叫你的後端,由後端向追蹤供應商進行身份驗證,而不暴露供應商憑證。

OWASP 的 Secrets Management Cheat Sheet 支援集中式秘密管理、受控存取、審計及生命週期管理。其 REST Security Cheat Sheet 亦建議不要將 API 金鑰放入 URL,因為記錄及其他處理可能會暴露金鑰。遵循供應商記錄的身份驗證方法,並從請求記錄及診斷匯出中移除身份驗證值。

分隔環境並識別已部署版本

在供應商支援的情況下,使用獨立的開發、測試及生產憑證。如果無法使用獨立憑證或帳戶,請記錄此限制,並防止非生產工作執行不受控的生產寫入操作。

為秘密設定邏輯配置參考,例如 SHIPMENT_TRACKING_API_KEY。另行記錄秘密管理器版本或非秘密部署標籤。該標籤讓操作人員可以回答「此工作程序使用的是哪個版本?」而無需檢查或記錄憑證本身。

明確決定應用程式如何接收更新。啟動時讀取環境變數的程序,通常需要重新啟動或重新部署,才能取得變更後的值。掛載的秘密檔案或執行時查詢則有不同的更新行為。更新秘密儲存區並不代表每個正在執行的程序都已採用替換值。

在輪換前讓請求可復原

在將追蹤工作傳送至供應商前先予以持久化。對於貨件註冊,保留內部操作識別碼、貨件參考、處理狀態及重試歷史。將業務資料與身份驗證分開,以便佇列工作在執行時使用有效憑證。

不要將 API 金鑰序列化到佇列訊息中。這樣會使延遲工作綁定於過時憑證,並將秘密散播到佇列儲存區、死信佇列及除錯工具中。

對於寫入操作,在啟用重試前先確定供應商的重複處理規則。逾時並不代表註冊失敗:供應商可能在連線中斷前已接受請求。如果存在有文件記載的冪等機制,請使用該機制;否則在重新提交前先核對貨件狀態。

建立使用者清單及監控基線

最容易遺漏的使用者通常不是主應用程式。請清點排程匯入、佇列工作程序、無伺服器函數、管理員指令碼、支援工具、災難復原部署,以及目前縮減至零個執行個體的服務。

對每個使用者記錄其負責人、環境、秘密參考、更新機制、執行排程及部署方法。識別可能將憑證保留在記憶體中的長時間執行工作。亦請檢查可重用的 HTTP 客戶端,它們可能在設定變更後仍保留舊的身份驗證標頭。

在切換前,為以下項目建立基線:

  • 按服務、環境、端點及部署版本分組的身份驗證失敗。
  • 供應商回應延遲、逾時、速率限制回應及伺服器錯誤。
  • 佇列深度、最舊待處理工作的時間及死信數量。
  • 成功的貨件註冊及尚未解決的註冊嘗試。
  • Webhook 接收及處理狀況(若 webhook 是整合的一部分)。

將整合健康狀況與貨件流動分開。一件沒有新承運商事件的包裹,不一定代表 API 失效。在輪換期間,成功的身份驗證請求及健康的處理佇列,比配送狀態發生變化的貨件數量更能直接反映狀況。

在支援的情況下使用重疊金鑰進行輪換

  1. 建立替換金鑰,但不要撤銷有效金鑰。確認舊憑證仍然有效。將新憑證儲存為獨立的秘密版本,並適當限制存取權限。
  2. 隔離驗證替換金鑰。對目標環境執行有文件記載且影響較低的操作。檢查 HTTP 結果及回應本文中的應用程式層級結果。
  3. 測試具代表性的工作流程。驗證應用程式實際需要的操作,而不只是基本連線檢查。如果需要註冊,請使用獲授權的測試貨件,並考慮可能產生的配額或計費影響。
  4. 部署至小型使用者群組。將一個工作程序群組或應用程式執行個體切換至替換金鑰,然後檢查身份驗證、處理結果及佇列行為。
  5. 推展至所有其餘使用者。每個服務重新載入或重新啟動時更新清單。包括排程工作、休眠工作負載及復原設定。
  6. 觀察適當的驗證窗口。涵蓋相關工作程序生命週期、設定快取行為、重試延遲及工作排程。沒有普遍適用的等待時間可以證明所有使用者都已採用新金鑰。
  7. 撤銷舊金鑰並再次驗證。留意過時使用者,然後根據保留及事故回應要求淘汰舊秘密參考。

如果無法取得供應商端的金鑰使用報告,請使用部署記錄及應用程式報告的秘密版本標籤來驗證採用情況。這提供了營運證據,但不能取代完整的使用者清單。

將立即替換作為協調一致的切換處理

如果發出替換金鑰會立即使舊金鑰失效,則無法透過滾動部署保證身份驗證不中斷。設計過渡方案,讓工作可以安全延遲而不是遺失。

  1. 在替換憑證前準備好應用程式部署、秘密參考、操作人員存取權限及復原指令。
  2. 在受控邊界暫停向外發出的追蹤請求,同時在可行的情況下繼續將工作接收到持久儲存區。
  3. 排空或處理正在執行的請求。對結果不明確的寫入操作標記以供核對,而不是自動視為失敗。
  4. 替換供應商憑證、更新秘密儲存區,並重新整理每個使用者。
  5. 在釋放完整積壓工作前執行身份驗證及工作流程檢查。
  6. 逐步恢復處理,遵守供應商速率限制,並檢查重複註冊。

如果整合無法暫停、保留工作或可靠地更新憑證,請在例行輪換前修正這些弱點。不過,如懷疑憑證已遭入侵,即使會造成短暫中斷,遏制措施仍可能需要立即撤銷。

將 API 身份驗證與 webhook 安全分開

向外發出的 API 金鑰及向內接收的 webhook 驗證秘密用途不同。不要假設輪換其中一項會改變另一項,也不要假設兩者使用相同值。分別遵循供應商記錄的 webhook 身份驗證及傳送行為。

在向外發出的憑證切換期間,除非有其他停止原因,否則應保持 webhook 接收運作。根據供應商規格驗證傳入訊息,在架構允許時先持久接收再確認,並使處理流程能容忍重複傳送。

成功的身份驗證 API 呼叫並不能證明 webhook 傳送或處理正常。分別檢查兩條路徑,除非供應商設計要求,否則避免在同一項維護操作中同時變更兩個憑證。

在不造成重試風暴的情況下排解故障

症狀首先檢查安全回應
部署後出現身份驗證失敗秘密版本、標頭格式、環境、空白字元、已快取的客戶端停止盲目重試;修正設定並驗證一個請求。
只有部分工作程序失敗舊程序、遺漏的部署、延遲工作、過時的秘密快取更新受影響的使用者,並比較版本標籤。
復原期間出現速率限制積壓釋放速率及總體並行數限制復原速度,並遵循有文件記載的重試指引。
註冊逾時供應商是否已接受該操作在重播前先核對狀態或使用有文件記載的冪等機制。

HTTP 401 通常涉及缺少或無效的身份驗證,而 403 表示伺服器拒絕請求。供應商特定的回應本文可能更準確地說明原因。不要將每個 403 都歸類為金鑰已過期,也不要假設每個不成功的操作都會使用 HTTP 錯誤狀態。

對適當的暫時性故障使用具有退避及抖動的有限重試。重複提交無效憑證並不能修復問題。通知操作人員、保留工作,並防止設定錯誤演變成不受控的請求風暴。

在變更前定義回滾及完成條件

對於重疊金鑰輪換,回滾可能意味着在舊憑證仍然有效且可信時,暫時讓使用者恢復使用舊憑證。撤銷後,這個選項便不再存在。如果舊金鑰可能已遭入侵,不要僅為了恢復可用性而還原它;應發出另一個憑證並繼續向前。

只有在所有已清點的使用者都使用替換金鑰、身份驗證錯誤已回到預期基線、佇列工作正在復原、不明確的寫入已完成核對,且 webhook 處理仍然健康時,才完成輪換。記錄負責人、完成時間、已部署的秘密版本及撤銷結果,但不要記錄金鑰值。

為持續的 API 安全,根據組織政策、憑證暴露風險及供應商能力選擇輪換排程。在懷疑發生洩漏或不當存取後,應在該排程以外進行輪換。可重複且經測試的程序,比整合無法安全支援的任意頻率更有用。

常見問題

我可以在不造成停機的情況下輪換追蹤 API 金鑰嗎?

有可能,但前提是供應商支援並行憑證,而且每個使用者都能在撤銷前完成遷移。如果重新產生會立即停用舊金鑰,請計劃受控地中斷向外發出的請求。持久佇列可以在此期間保留工作,但不能令供應商連線持續可用。

佇列中的貨件工作應否包含 API 金鑰?

不應。儲存貨件操作及其處理中繼資料,然後在工作程序執行時解析有效憑證。這可減少秘密暴露,並防止延遲工作重複使用已失效的金鑰。

輪換金鑰會刪除已註冊的貨件嗎?

不要假設任何一種結果。確認已註冊貨件及相關設定是附加到帳戶、應用程式還是憑證。身份驗證成功本身並不能證明替換金鑰可以存取預期的貨件記錄。

如果金鑰出現在儲存庫或記錄中,我應該怎樣做?

將其視為可能已遭入侵。立即撤銷或替換,並在可行的情況下檢查存取及使用記錄,同時遵循事故回應流程。移除可見值並不足夠,因為副本可能仍留在歷史記錄、日誌匯出或其他系統中。

如何知道舊的排程工作是否仍在使用之前的金鑰?

檢查其秘密參考、已部署設定及執行時更新行為。在安全的情況下透過受控執行來測試,或在其下次排程啟動前確認部署。安靜的控制面板並不能證明低頻使用的使用者已完成遷移。

來源