跳轉到主要內容

API 密鑰能放在前端嗎:為什麼支付接口密鑰必須留在服務器上

把 API 密鑰放進前端 JavaScript 安全嗎?為什麼支付接口密鑰必須留在服務器上、瀏覽器不用密鑰如何付款,以及密鑰泄露後該怎麼辦。

發佈於 約 3 分鐘閲讀

手繪插畫:一個瀏覽器窗口裏的 kuko_live_ 密鑰被打叉,箭頭指向一台保管密鑰並調用 API 的服務器,旁邊一個人正指着它
本文目錄
  1. 為什麼前端代碼藏不住 API 密鑰
  2. 瀏覽器不用密鑰如何收款
  3. 密鑰在服務器上應該放在哪裏
  4. API 密鑰泄露後該怎麼辦
  5. 總結

把 API 密鑰放進前端代碼——瀏覽器 JavaScript、移動 App、桌面應用——就等於把它交給了每一個使用這段代碼的人。任何發到設備上的東西都可以被讀出來:在瀏覽器開發者工具裏、在網絡面板裏、在打包後的源碼裏、在 App 安裝包裏。對支付接口密鑰來説,這不是理論上的風險:這把密鑰能創建訂單、發起退款、讀取你的餘額,誰拿到它,誰就能以你的服務器的身份行事。

這篇文章説明為什麼 KukoPay 的 API 密鑰必須留在服務器上、瀏覽器或移動 App 不用密鑰如何收款、密鑰應該放在哪裏,以及密鑰已經泄露時該怎麼辦。

為什麼前端代碼藏不住 API 密鑰

  • 壓縮或混淆沒有用。 代碼要用到密鑰,密鑰就必須以可用的形式存在於代碼裏。
  • 前端構建時的環境變量沒有用。 打包工具注入 process.env.X 時,會把值直接寫進編譯後的 JavaScript。
  • 移動 App 也沒有用。 安裝包可以被解開,流量也可以在攻擊者自己的設備上被抓取。
  • "只有我的網站會調用"不算防護。 任何人都可以從網絡面板裏複製一個請求,再用腳本重放。

有些支付服務商會另外簽發一種可公開的密鑰,它本來就設計成公開的,只能做少數幾件無害的事。KukoPay 沒有這種密鑰:每一把 KukoPay API 密鑰都是服務端密鑰,對所屬應用擁有完整的接口權限——所以文檔説得很直接:不要把它寫進瀏覽器 JavaScript、移動應用或公開倉庫。

瀏覽器不用密鑰如何收款

瀏覽器裏根本不需要密鑰,因為買家是在 KukoPay 的託管收銀台上付款的:

  1. 瀏覽器請求你的服務器開始結賬——你自己的接口,用你自己的會話或登錄。
  2. 你的服務器創建訂單,用環境變量裏的 API 密鑰調用 POST /v1/orders。
  3. 你的服務器返回 checkout_url,瀏覽器跳轉過去。
  4. 買家在託管頁面上付款,這個頁面帶有只對這一筆訂單有效的短期簽名令牌。
  5. 你的服務器從 Webhook 得知結果,見 return_url 和 notify_url 的區別。
// 服務端(Express)——密鑰只存在於這裏
app.post("/checkout", requireLogin, async (req, res) => {
  const order = await fetch("https://api.kukopay.com/v1/orders", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.KUKOPAY_API_KEY,
    },
    body: JSON.stringify({ out_trade_no: req.body.cartId, amount: priceFor(req.body.cartId), currency: "USD" }),
  }).then((r) => r.json())
  res.json({ checkout_url: order.data.checkout_url })
})

注意 priceFor(...):金額由服務器決定。由瀏覽器傳價格,它就可以傳任何價格。移動 App 也是同樣的模式:App 調用你的後端,後端創建訂單,App 打開 checkout_url。見 託管支付頁面是什麼。

密鑰在服務器上應該放在哪裏

  • 放在服務器的密鑰管理或環境變量裏,永遠不要放進代碼倉庫。把存放密鑰的文件加入 .gitignore,並確認它沒有被打進容器鏡像的某一層。
  • 每台服務器或每種用途一把密鑰。 一個應用可以同時持有多把正式密鑰,各自命名,這樣你能分辨是哪個系統發起的調用,也能只吊銷其中一把而不影響其他的。
  • 限制使用來源。 IP 白名單讓泄露的密鑰在別處無法使用,見 API IP 白名單。
  • 測試和正式分開。 kuko_test_ 密鑰只能產生沙箱數據;kuko_live_ 密鑰會動真錢。不要在開發環境用正式密鑰,見 沙箱與正式環境的區別。
  • 不要寫進日誌。 KukoPay 的 API 日誌在入庫前就會脱敏密鑰類字段;請確認你自己的日誌和錯誤追蹤工具也這樣做。

API 密鑰泄露後該怎麼辦

吊銷或輪換密鑰

輪換會立即簽發一把新密鑰,舊密鑰保留到過期時間;吊銷則立即停用。密鑰已經泄露時,請吊銷,見 如何輪換 API 密鑰。

查看它被用來做了什麼

API 日誌記錄了每次調用的來源 IP、路徑和狀態——找出不是你發起的下單、退款或端點變更。

檢查 Webhook 端點和退款

密鑰可以創建 Webhook 端點和退款。刪除你不認識的端點,並核查最近的退款。

從泄露的地方移除密鑰

把它從前端打包產物或倉庫歷史中清除,並按上文把調用移到服務器上。

總結

  • 前端代碼裏的 API 密鑰,任何加載它的人都能讀到——壓縮、構建時變量和移動 App 打包都藏不住它;
  • 每一把 KukoPay API 密鑰都是服務端密鑰;沒有可公開的密鑰,也不需要;
  • 瀏覽器請求你的服務器,服務器創建訂單並返回 checkout_url,買家在託管收銀台付款;
  • 金額由服務器決定,密鑰放在密鑰管理裏,每個系統一把,並配置 IP 白名單;
  • 密鑰泄露時,吊銷它、查看 API 日誌,並檢查 Webhook 端點和退款。

在沙箱裏把它跑通

註冊商戶後即可申請測試密鑰,不需要等待資質審核。