API IP 白名單:如何把支付接口密鑰限制在自己的服務器上使用
支付接口的 IP 白名單如何工作:找到服務器的出口 IP,IPv4、CIDR 與 IPv6 條目,ip_not_allowed 錯誤,以及什麼時候不該啓用。
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 表示密鑰是有效的,但請求來自一個不在該應用白名單上的地址。它不是臨時錯誤:從同一台服務器重試,結果還是一樣。
- 找到這次請求實際的來源地址——就是 API 日誌中這次調用的
ip。 - 如果是你自己的,把它(或它所在的網段)加入白名單。
- 如果不是,就當作密鑰已經泄露:輪換密鑰,並查清它是怎麼泄露出去的。見 如何輪換 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 的安全靠簽名而不是白名單。
在沙箱裏把它跑通
註冊商戶後即可申請測試密鑰,不需要等待資質審核。