Files
usdt/docs/app-ip-whitelist.md
T
2026-11-16 10:30:21 -05:00

31 lines
2.2 KiB
Markdown

# 支付与租赁应用 IP 白名单
`apps.ip_whitelist` 和 `rent_app.ip_whitelist` 使用 `VARCHAR(2048) NOT NULL DEFAULT ''`。
支付应用 JSON 字段为 `ipWhitelist`,租赁工作台 JSON 字段为 `ip_whitelist`。
## 规则
- 空值或空白:拒绝此应用全部外部 API 请求。不会影响后台 JWT 管理页面,仍可登录修改白名单。
- 精确 IPv4 / IPv6:例如 `203.0.113.10`、`2001:db8::1`。
- IPv4 完整地址段通配:例如 `192.168.*.*`、`10.*.1.*`。`*` 不能匹配半个地址段,不支持 CIDR、主机名或 URL。
- 独立 `*`:显式允许所有来源,签名及原有鉴权仍必须通过。
- 多条使用换行、逗号、分号或空白分隔;保存时去重,最多2048字符。
支付覆盖所有调用 `ApiSecurityService` 的创建订单、查询、代付和钱包开放接口。
租赁覆盖 `/api/rental/v1/{operation}` 和 `/api/rental/v1/address-onchain/{operation}`。
供应节点 Agent、后台管理、链上扫描和平台接收回调不属于应用商户调用,不套用本规则。
拒绝响应为原 JSON 协议的 `code=403`,签名、密钥及抗重放逻辑继续保留。
## 真实来源与反向代理
默认取 Servlet `request.getRemoteAddr()`,不直接使用 `X-Forwarded-For`、`X-Real-IP` 或 `Forwarded`,防止调用者伪造来源。
直接部署填写客户端实际 IP。反向代理部署须由运维在可信代理/容器层配置来源地址恢复,并且只信任确定的代理地址、限制直连后端和覆盖外部转发头;未配置时服务看到的是代理 IP。
不要仅把所有用户共用的反向代理地址加入名单后将其当作按客户端隔离。
## 部署
1. 先在业务库执行 `sql/app_ip_whitelist_upgrade.sql`,可重复执行,不重建、不删除已有表。新租赁库的 `rent_init.sql` 已包含该列。
2. 按每个应用配置实际来源 IP;旧记录默认空白,新版上线后会拒绝其 API 请求,必须提前配置。
3. 编译部署前后端并重启服务。支付应用在创建/编辑对话框维护;租赁商户在应用详情保存,运营在应用列表的“IP 白名单”操作维护。
4. 使用名单内、名单外和伪造转发头的请求验证。测试不广播任何链上交易。