跳轉到主要內容

API IP 白名單:如何把支付接口密鑰限制在自己的服務器上使用

支付接口的 IP 白名單如何工作:找到服務器的出口 IP,IPv4、CIDR 與 IPv6 條目,ip_not_allowed 錯誤,以及什麼時候不該啓用。

發佈於 約 4 分鐘閲讀

手繪插畫:兩台服務器向一道 API 閘門發送請求,一個 IP 被放行打勾,另一個被 403 ip_not_allowed 拒絕,旁邊一個人雙手插兜
本文目錄
  1. KukoPay 的 API IP 白名單如何工作
  2. 白名單應該填哪些 IP 地址
  3. 支持的格式
  4. ip_not_allowed 是什麼意思?
  5. 什麼時候不該使用 IP 白名單
  6. IP 白名單管不到的地方
  7. 總結

API IP 白名單限制的是一把密鑰可以從哪裏使用。你列出自己服務器的 IP 地址,接口就會拒絕任何來自名單之外的請求——即使它帶着有效的密鑰。密鑰如果通過日誌文件、代碼倉庫或筆記本電腦泄露出去,在其他地方也用不了。IP 白名單不能代替保管好密鑰,它是第一把鎖後面的第二把鎖。

這篇文章説明 KukoPay 的 API IP 白名單如何工作、如何找到應該填的地址、支持哪些格式、ip_not_allowed 是什麼意思,以及什麼情況下白名單帶來的麻煩比它防住的更多。

KukoPay 的 API IP 白名單如何工作

  • 按應用配置。 每個應用都可以選配自己的白名單,在應用切換器中選中該應用後,於 開發者 → API 密鑰 頁面設置。它同時約束這個應用的 API 密鑰和它的易支付商戶 ID(pid)。
  • 沙箱和正式環境都生效。 白名單屬於應用,而不屬於環境:一旦設置,用這個應用的 kuko_test_ 密鑰發起的沙箱調用也必須來自名單上的地址。
  • 為空即關閉。 沒有任何條目時,接受來自任何地方的請求。保存第一個條目後立即開始生效。
  • 先驗密鑰,再驗來源。 先校驗密鑰,再檢查來源地址;來自名單外地址的請求返回 403 ip_not_allowed。

白名單應該填哪些 IP 地址

填你的服務器對外發起請求時使用的公網出口地址——也就是 KukoPay 看到的地址,而不是服務器網卡上的地址。

  • 在 NAT 網關或代理後面,填網關的公網地址。
  • 多台服務器或多個地域,全部列出,包括會切換過去的備用機器。
  • 不要填你的筆記本或辦公室地址,除非你真的從那裏調用正式接口。

最可靠的辦法是看 KukoPay 記錄下的地址:每次 API 調用都會連同來源 IP 一起記錄。調用一次,然後打開 開發者 → API 日誌 或查詢 GET /v1/logs,讀取 ip 字段——日誌的用法見 支付接口錯誤處理。

支持的格式

條目示例匹配
單個 IPv4 地址203.0.113.24僅這個地址
IPv4 CIDR 網段203.0.113.0/28網段內的 16 個地址
IPv6 地址2001:db8::25僅這個地址——不支持 IPv6 網段

多個條目用逗號或空格分隔。保存時會校驗格式,所以寫錯的條目會被直接拒絕,不會在你不知情的情況下把你鎖在外面。

ip_not_allowed 是什麼意思?

403 ip_not_allowed 表示密鑰是有效的,但請求來自一個不在該應用白名單上的地址。它不是臨時錯誤:從同一台服務器重試,結果還是一樣。

  1. 找到這次請求實際的來源地址——就是 API 日誌中這次調用的 ip。
  2. 如果是你自己的,把它(或它所在的網段)加入白名單。
  3. 如果不是,就當作密鑰已經泄露:輪換密鑰,並查清它是怎麼泄露出去的。見 如何輪換 API 密鑰。

完整的錯誤碼列表以及哪些值得重試,見 支付接口錯誤處理。

什麼時候不該使用 IP 白名單

只有出口地址穩定時,白名單才有用。

  • 雲函數和自動擴縮容的容器,出口地址經常變化。如果沒有固定出口(例如帶靜態地址的 NAT 網關),不要開啓——否則下一次發佈就會變成一次故障。
  • 開發人員在筆記本上共用的沙箱應用。 由於白名單對測試密鑰同樣生效,請給本地開發單獨建一個不設白名單的應用,白名單只放在生產應用上。應用的用法見 多個網站如何接入收款。

IP 白名單管不到的地方

  • 買家的瀏覽器。 收銀台和易支付的 submit.php 由買家從任何地方打開,所以永遠不受限制。白名單管的是服務器之間的調用:API,以及易支付的 mapi.php 和 api.php,見 易支付接入指南。
  • 發給你的 Webhook。 它們的方向相反;保護你的接收端靠驗證簽名,而不是看來源地址。見 Webhook 驗簽怎麼做。
  • 你的後台登錄。 那由密碼和兩步驗證保護,見 商戶賬戶安全。

總結

  • API IP 白名單讓密鑰只能從你列出的地址使用,泄露的密鑰到了別處就沒用;
  • 在 KukoPay,白名單按應用配置,對應用的測試和正式密鑰以及易支付 pid 都生效,為空時關閉;
  • 填服務器的公網出口地址——API 日誌會顯示每次調用來自哪個 ip;
  • 支持單個 IPv4、IPv4 CIDR 和精確的 IPv6 地址;名單外的來源返回 403 ip_not_allowed;
  • 沒有固定出口地址時不要啓用,Webhook 的安全靠簽名而不是白名單。

在沙箱裏把它跑通

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