Skip to main content

API Key 防泄露最佳實務

從縮短憑證暴露時間、收窄許可權範圍、配置預警與止損三個層面預防 API Key 泄露,涵蓋臨時 API Key、定期輪換、IP 白名單、私網連接、預算告警與模型監控警示。

概述

API Key 是調用阿里雲百鍊模型服務的憑證。一旦泄露,任何持有者都可以用它調用該 Key 授權範圍內的模型並消耗額度。泄露造成的影響可拆解為四個因子:泄露機率、暴露時間、單次調用的許可權範圍、異常持續時長。泄露機率由貫穿全文的基礎實踐壓縮,其餘三個因子分別由以下三個層面壓縮:

層面

壓縮的因子

關鍵手段

縮短暴露時間

暴露時間

用戶端使用臨時 API Key、一次性展示加受控保存、定期輪換與離崗回收

收窄許可權範圍

單次調用的許可權範圍

一業務一 Key、業務空間隔離、IP 白名單與模型範圍、私網連接

預警與止損

異常持續時長

預算告警與達預算即停、模型監控警示、平台風險檢測

貫穿三個層面的基礎實踐:
  • 應用從環境變數或密鑰管理服務讀取憑證,不在程式碼中硬編碼;CI/CD 配置敏感資訊掃描(可使用 gitleaks 等憑證掃描工具),覆蓋 API Key 形態。
  • 維護密鑰台帳:從一張記錄 Key ID、用途、負責人與最近輪換時間的基礎表格開始,逐步補齊地區、業務空間、許可權範圍、預算等欄位;台帳不保存完整 Key。
  • 將 Key 的管理許可權(建立、查看、編輯、刪除)限制在必要的管理員範圍內。

縮短憑證暴露時間

妥善保管長期 API Key

新建 API Key 僅在建立時完整顯示一次,關閉對話方塊後無法再查看或複製完整明文;若未保存,只能重設或重新建立,參見擷取 API Key。 建立成功後,將完整 Key 直接存入受控憑證儲存(密鑰管理服務或部署平台的 Secret 管理),不要經截圖、郵件、聊天工具或普通文件中轉;清單中的脫敏值僅用於比對識別。 不要將長期 API Key 放入以下位置:
  • 瀏覽器指令碼、前端建置產物、移動 App 安裝包
  • 公開或共享的程式碼存放庫(僅添加 .gitignore 不能消除歷史提交中的憑證)
  • Notebook 輸出、範例程式碼
  • 截圖、螢幕錄製
  • 工單、群聊、線上文件
  • Prompt、知識庫、Agent 上下文
  • 請求 URL 與查詢參數
  • 存取日誌與異常堆疊
  • 第三方外掛程式與模型中轉服務
  • 共享環境、對外暴露的設定檔、鏡像與備份
本地調試時建議透過隱藏輸入設定環境變數,避免明文進入命令歷程記錄:
read -r -s -p "Enter API key: " DASHSCOPE_API_KEY
printf '\n'
export DASHSCOPE_API_KEY
該範例適用於 Linux/macOS 環境。
環境變數可以避免硬編碼,但不是加密儲存:憑證仍可能經程序診斷資訊、容器配置、當機傾印或維運匯出等途徑泄露,調試時避免使用 set -x 等會輸出敏感變數的選項。生產環境請使用密鑰管理服務或部署平台的 Secret 注入。
若曾將 API Key 提供給不可信的模型中轉服務或第三方外掛程式,建議停止向其交付新 Key,改用官方介面或可信服務端整合,並輪換已交付的 Key。

用戶端情境使用臨時 API Key

瀏覽器、移動 App、小程式等環境無法可靠保密憑證。這類情境請由已鑒權的後端簽發臨時 API Key,供前端直連使用:
  1. 長期 API Key 僅保存在您自己的伺服器上,不下發到任何用戶端。
  2. 前端需要調用模型時,先向您的後端申請臨時 Key。
  3. 後端調用產生臨時 API Key 介面,簽發短有效期間的 st- Key 回傳給前端。
  4. 前端使用 st- Key 直連百鍊調用模型。
臨時 API Key 預設有效期間 60 秒,可透過 expire_in_seconds 設定 1~1800 秒(按任務所需的最短時長設定,不要無條件使用最大值),到期自動失效,不支援提前刪除;它繼承簽發它的長期 API Key 的全部許可權,需要更小許可權時應先收窄用於簽發的長期 Key。簽發介面透過 OpenAPI 以長期 Key 發起調用,應校驗調用許可權並限制簽發頻率,避免成為公開的憑證發放入口。介面詳情參見產生臨時API Key。

定期輪換與離崗回收

長期有效的 Key 配置在程式碼或 Agent 中,暴露面會隨時間累積,應定期輪換:
  1. 建立新 Key,按當前需求重新配置許可權與預算。
  2. 更新業務側的憑證引用。
  3. 驗證新 Key 調用正常。
  4. 刪除舊 Key,並確認舊 Key 無法發起新調用。
  5. 更新密鑰台帳。
新 Key 不會自動繼承舊 Key 的許可權與預算配置,需重新設定。人員離崗或業務下線時,必須單獨清點並刪除或輪換其名下的 Key:2026 年 3 月 25 日及之後建立的 API Key 不會因刪除歸屬 RAM 使用者而級聯刪除,仍可繼續使用(該規則僅在 Key 歸屬 RAM 子帳號時相關),因此不能僅憑 RAM 使用者已刪除就認定憑證已回收,參見時效性與限制。 若多個 Key 保存在同一台疑似遭入侵的伺服器、公開配置、程式碼存放庫或第三方環境中,應一併輪換可能受影響的憑證並修復環境:既不必無差別更換全部 Key,也不要只處置單個 Key 而忽略共同暴露的環境。 進階做法:將 Key 明文託管在密鑰管理服務(KMS)中,由應用按憑證名稱取用,並利用 KMS 的密鑰輪換能力定期更新。

收窄憑證許可權範圍

一業務一 Key 與業務空間隔離

為不同應用和不同環境(生產、測試、個人調試)分配獨立的 API Key:既縮小單個 Key 泄露的影響面,也便於按 Key 定位問題與單獨輪換。需要許可權隔離、精細化模型存取控制或獨立成本核算時,為業務分配非預設業務空間(業務空間是百鍊中隔離許可權與成本的容器,帳號預設已有預設業務空間),Key 的基礎調用範圍受歸屬業務空間約束,參見許可權管理。 同時將 Key 的管理許可權限制在必要的管理員範圍內;可登入控制台管理憑證的帳號應採用最小許可權並按組織要求啟用多重要素驗證。

配置 IP 白名單與模型範圍

在 API Key 的建立或編輯面板中將許可權設為自訂後,可進一步收窄 Key 的調用範圍:
  • IP 白名單:僅放通業務實際使用的公網出口 IP 或網段,最多 20 個(可透過 curl ifconfig.me 等方式查詢公網出口)。預設放通全部 IPv4 位址,僅建立 Key 不等於已啟用來源限制。經 NAT、代理或閘道調用時,請填寫百鍊實際看到的公網出口位址,而非伺服器內網位址。
  • 存取模型範圍:開啟後該 Key 僅能調用已勾選的模型(最多 30 個,受業務空間已授權模型約束),防止泄露後被用於高成本模型。
配置後建議驗證收窄是否生效:僅允許的網路與模型可調用、未授權的不可調用;驗證時不要輸出完整 Key。操作入口與完整規則參見如何管理 API Key 的許可權。
IP 白名單不能替代憑證保密:能從同一出口網路發起調用的人員或遭入侵的主機,仍可能濫用泄露的 Key。

透過私網連接調用

對網路安全要求較高的情境,可在您的 VPC 與百鍊之間建立私網連接(PrivateLink):調用不經公網,即使 Key 泄露,網路不連通的外部攻擊者也無法調用。配置方法參見通過終端節點私網訪問阿里雲百鍊模型或應用 API。

配置預警與止損

預算告警與達預算即停

為帳號、業務空間或單個 API Key 設定月度預算與告警閾值,優先為開發測試、示範、第三方接入等高風險 Key 設定獨立預算。費用達到閾值與預算用盡時會透過站內信、簡訊、郵件或機器人通知;開啟「達到預算後立即停止」後,預算耗盡將限制該維度按量調用並返回 429。配置方法參見預算管理。
「達到預算後立即停止」存在生效延遲,延遲期間費用仍會計收;預置吞吐(PTU)溢出部分與應用產生的調用暫不支援自動停止。生產關鍵業務不建議開啟自動停止,優先預警加受控處置。

模型監控警示

模型監控按業務空間統計調用次數、Token 用量、失敗次數、失敗率等指標,支援按 API Key 篩選,並可基於預設警示範本或自訂範本建立警示規則,通知到聯絡人或聯絡人群組。建議為高風險 Key 配置調用量、調用次數突增類警示:異常在調用發生後分鐘級可見,非工作時段觸發即人工介入。首次設定警示需先在資料投遞中授權雲監控服務角色,設定方法參見警示。

平台風險檢測

平台會週期性掃描公開程式碼存放庫等公網環境,識別泄露的 API Key 並主動告知,具體管道以實際啟用的為準(可能包括簡訊、郵件、站內信等);同時識別非常用 IP 登入、夜間突發流量、費用異常激增等異常行為。 平台風險檢測與告警是平台為提升使用體驗而主動提供的異常檢測與預警能力,不在 SLA 約定的服務範圍內;受風險情境複雜性所限,不承諾絕對的告警覆蓋率,告警的識別與送達也可能存在時延。API Key 等憑證的安全保管與合規使用屬於您的責任範疇,請以自行配置的預算告警、模型監控警示與定期輪換作為主要防線;未收到平台告警不代表沒有泄露風險。發現疑似泄露或收到告警後,請按 API Key 泄露排查定位並處置。

上線前檢查清單

個人開發者或小團隊可先完成最小起步:為 Key 設定預算與告警通知、憑證僅存於環境變數、定期輪換。完整檢查清單如下:
  • 生產、測試及第三方接入不共用同一個 API Key,Key 負責人和用途明確。
  • 歸屬地區、業務空間、模型範圍和請求出口 IP 已核對,許可權僅覆蓋必要範圍。
  • 長期 Key 僅保存在受控後端,不進入用戶端、原始碼、Prompt、共享文件或日誌。
  • Key 未交付不可信的第三方中轉服務或外掛程式環境;如曾交付,已停止交付並輪換。
  • 憑證透過環境變數或 Secret 注入,敏感檔案與建置產物不含明文。
  • 用戶端直連情境由已鑒權後端簽發短期 Key,簽發用的長期 Key 許可權已收窄。
  • 新版 Key 已受控保存;舊版 Key、閒置 Key 和離崗人員相關 Key 已核對。
  • 帳號、業務空間及 Key 級預算與告警已配置,通知管道與責任人明確。
  • 「達到預算後立即停止」的可用性影響與生效延遲已評估。
  • 輪換與泄露處置流程已明確,排查步驟參見 API Key 泄露排查。

常見問題

不小。臨時 API Key 繼承簽發它的長期 API Key 的全部許可權,僅有效期間更短。需要更小許可權時,應先收窄用於簽發的長期 API Key。
需要。IP 白名單只能限制調用來源網路,泄露到同一出口網路內的 Key 仍可能被濫用。請結合最小許可權、預算告警與定期輪換使用。
停止向該服務交付新 Key,輪換已交付的 Key,並改用官方介面或可信服務端整合。已泄露 Key 的處置步驟參見 API Key 泄露排查。