IP 白名单与免密端口
白名单的准确规则、和提取接口的关系，以及免密接入到底免的是哪一段的密。
白名单在这个平台上有一个具体用途：提取接口 的授权 + 免密端口的接入凭证。它不是"给 58971 端口开免密"的开关。
白名单能做什么
白名单的规则
只接受公开、全局单播的 IPv4 地址。
被拒绝的：IPv6、私网地址、环回、链路本地、文档用地址、CGNAT 段。
不支持 CIDR，只能一条一个 IPv4 字符串。想覆盖一个网段就得逐个加，或者收敛出口 IP。
每个代理子账号 10 条。不是每个用户 10 条——多个子账号各有自己的 10 条额度。
连续 10 天未使用的白名单条目会被维护任务自动删除，相关的端口绑定也一起清掉。
加白名单
先确认自己当前的出口 IP。控制台有 /api/v1/client-ip 接口，或者直接：
curl -s https://api.ipify.org
然后在控制台的白名单页添加，或走 API：
POST
/api/v1/proxy/ip-whitelistcurl -X POST 'https://api.example.com/api/v1/proxy/ip-whitelist' \
-H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN' \
-H 'Origin: https://console.example.com' \
-H 'Content-Type: application/json' \
-d '{"accountId":"YOUR_ACCOUNT_ID","ipAddress":"203.0.113.10"}'
查询和删除：
GET
/api/v1/proxy/ip-whitelistDELETE
/api/v1/proxy/ip-whitelist/:id超过上限会怎样
加第 11 条时返回 HTTP 409，错误码 proxy_api_limit_reached。需要先删掉不用的条目。
免密端口是怎么工作的
这是白名单最有价值的用法。流程是：
把出口 IP 加进白名单
免密端口靠"来源 IP + 端口"这个组合来识别你，所以来源 IP 必须先登记。
调用提取接口拿一批端口
curl 'https://api.example.com/api/v1/proxy/extract?apikey=YOUR_KEY&num=5&country=US&session=sticky&time=10'
返回：
1.2.3.4:20001
1.2.3.4:20002
1.2.3.4:20003
1.2.3.4:20004
1.2.3.4:20005
直接用，不带用户名密码
curl -x http://1.2.3.4:20001 https://api.ipify.org
每个端口在控制面已经绑定好了你的账号和这次提取时指定的地区、会话配置。
免密端口什么时候会失效
- API Key 被撤销
- 对应的白名单条目被删除
- 白名单条目因连续 10 天未使用被自动清理
- 提供该端口的网关节点不健康 —— 下次提取时旧绑定会被删除并重新分配
- 代理账号或 API Key 记录被删除
两种接入方式怎么选
账号密码接 58971 | 免密端口 | |
|---|---|---|
| 需要白名单 | 不需要 | 需要 |
| 出口 IP 变化 | 不影响 | 全部失效 |
| 地区/会话配置 | 每个请求可变（拼用户名） | 提取时固定 |
| 支持 ASN 定位 | 支持 | 不支持 |
| 适合 | 大部分场景 | 出口 IP 固定、配置不常变的服务端 |
端口范围
免密端口的范围由每个网关节点自己注册，不是固定常量。注册时的约束：
- 起始端口不低于
1024 - 结束端口不超过
65535 - 单个节点的端口跨度最多
4096
所以不要在防火墙里写死某个端口段，按提取接口实际返回的值来。