Skip to main content
IP 白名单是增强 API 调用安全性的可选机制。配置后，只有白名单内的 IP 地址可以调用 OpenAPI 接口。
为什么需要 IP 白名单？ 即使 RSA 私钥意外泄露，攻击者也无法从非白名单 IP 发起请求，相当于给 API 加了第二把锁。

​
配置方式

登录商户门户，进入「开发者设置 → 安全设置」：
  1. 找到「IP 白名单」配置项
  2. 输入允许调用 API 的服务器出口 IP 地址
  3. 多个 IP 用英文逗号分隔
  4. 保存
示例配置： 
192.0.2.1, 198.51.100.42, 203.0.113.10

​
配置规则

  • 仅支持精确匹配单个 IP（IPv4 格式）
  • 多个 IP 使用逗号分隔
  • 留空表示不限制任何 IP
  • 暂不支持 CIDR 网段格式
沙盒测试期间可暂不配置（留空），但生产环境强烈建议配置。建议设置为商户服务端所有可能的出口 IP。

​
校验流程

  1. 读取请求头中的 X-Merchant-Id
  2. 查询该商户配置的白名单 IP 列表
  3. 若白名单为空，直接放行
  4. 获取客户端真实 IP（优先从 X-Forwarded-For 等代理头获取）
  5. 判断 IP 是否在白名单集合中
  6. 在集合中则放行，否则拒绝请求

​
如何获取服务器出口 IP

# Linux/Mac 终端执行
curl -s https://ifconfig.me
# 或
curl -s https://api.ipify.org
如果使用云服务器（如 AWS、阿里云），注意：
  • 弹性 IP 可能会变化
  • 多台服务器可能有多个出口 IP
  • 使用负载均衡/NAT 网关时，出口 IP 为网关 IP

​
错误处理

当请求 IP 不在白名单时，API 返回错误： 
{
  "code": 1001038,
  "msg": "ip.not.in.whitelist",
  "data": null
}

​
最佳实践

  1. 开发阶段：暂不配置白名单，方便本地调试
  2. 沙盒测试：配置测试服务器的出口 IP
  3. 生产上线：配置所有生产服务器的出口 IP
  4. 变更管理：服务器迁移时，提前更新白名单
  5. 定期审查：定期检查白名单列表，移除不再使用的 IP