WARP 代理池 · 使用文档
一台服务器 = 多个独立出口 IP 的自动维护代理池。面向业务程序提供 SOCKS5 代理提取，免登录、公开可读；文中所有示例命令中的服务器地址均自动替换为当前访问地址，复制即用。
文档权限公开 · 免登录
服务地址正在读取…
API 鉴权IP 白名单
代理模式白名单免密 / 账密
🚀 快速开始（3 步）
# 第 1 步：把调用方 IP 加入白名单（只需一次；服务器本机执行任意一条）
curl -X POST {{API_BASE}}/api/whitelist -H "Content-Type: application/json" -d '{"add":"你的IP"}'
# 第 2 步：提取 5 个代理（txt 格式，每行一个 ip:port，轮换出口）
curl -s "{{API_BASE}}/api/proxies?num=5&type=txt"
# 第 3 步：白名单内的机器直接免密使用（白名单端口 = 实例端口 + 1000）
curl -s --proxy "socks5://{{HOST}}:11010" https://api64.ipify.org
不需要登录：本页无需任何账号/凭据即可阅读；调用 API 也不需要 API Key，只要来源 IP 在白名单内（或服务器本机）即可。未在白名单时调用 API 会返回 401 A0001，响应里附带了加入白名单的命令。
🔑 两种接入方式
| 方式 | 适用对象 | 连接方式 | 调用 API |
|---|
| 白名单免密 |
白名单内的来源 IP |
连白名单端口 = 实例端口 +1000（如 10010 → 11010），不需要账密 |
免任何凭据 |
| 账号密码 |
任意 IP（未加白名单） |
连实例端口（10010 起）：socks5://warpuser:密码@服务器IP:端口 |
需先加入白名单 |
一句话记忆：在白名单里 → 用 +1000 的端口免密；不在白名单 → 用账号密码连原端口。账密模式可随时关闭/开启，密码可在管理台「账密模式」页修改。
🔄 提取代理
每次提取自动轮换一个出口 IP（Round-Robin，IPv6 出口每实例唯一）。选择 ip4 时，批量接口默认按公网 IPv4 去重；由于 IPv4 是共享 NAT 池，实际返回数量可能少于请求数量。
GET/api/pool/acquire原始提取接口，返回结构化 JSON（含出口 IP 详情）
参数（query）：
| 参数 | 说明 | 必选 |
|---|
| session_id | 粘性会话 ID：相同 ID 重复调用返回同一代理 | 否 |
| minutes | 粘性时长（1~1440 分钟，默认 10），别名 sticky_minutes | 否 |
| ip_mode | 出口协议：ip6（默认，独立 IPv6）或 ip4（共享 IPv4 NAT） | 否 |
# 普通提取（默认 IPv6）
curl -s "{{API_BASE}}/api/pool/acquire?ip_mode=ip6"
# IPv4 提取
curl -s "{{API_BASE}}/api/pool/acquire?ip_mode=ip4"
GET/api/proxies商用批量提取（CliProxy 风格），txt / json 两种格式
| 参数 | 说明 | 必选 |
|---|
| num | 提取数量（1~20） | 否（默认 1） |
| type | txt（默认，每行 ip:port）/ json（含账密与出口 IP） | 否 |
| format | txt 行分隔符：n（默认 \n）/ rn（\r\n，方便 Windows） | 否 |
| sid | 粘性会话 ID：相同 sid 总是拿到同一个出口 IP | 否 |
| time | 粘性时长（分钟，1~1440，默认 10） | 否 |
| ip_mode | 出口协议：ip6（默认，独立 IPv6）/ ip4（IPv4 NAT） | 否 |
# 提取 5 个（txt，白名单端口）
curl -s "{{API_BASE}}/api/proxies?num=5&type=txt"
# → {{HOST}}:11010
# → {{HOST}}:11011
# → …
# 提取 5 个 IPv4 代理（JSON，默认去重）
curl -s "{{API_BASE}}/api/proxies?num=5&type=json&ip_mode=ip4"
# IPv4 按实例提取，允许重复出口 IP
curl -s "{{API_BASE}}/api/proxies?num=5&type=json&ip_mode=ip4&unique_ip=0"
# 提取 5 个 IPv6 代理（TXT）
curl -s "{{API_BASE}}/api/proxies?num=5&type=txt&ip_mode=ip6"
# JSON 中每项包含 ip_mode 与 ipv4 字段
📌 粘性会话（固定出口一段时间）
带 sid 提取后，同一 sid 在有效期内始终拿到同一出口 IP，适合登录态、需要多次请求保持同 IP 的业务。超时未使用自动释放，也可主动释放。
# 提取固定出口（30 分钟内此 sid 始终拿到同一出口）
curl -s "{{API_BASE}}/api/proxies?num=1&type=json&sid=account-001&time=30"
# 用完主动归还（可选，避免占用到超时）
curl -s -X POST {{API_BASE}}/api/pool/release \
-H "Content-Type: application/json" -d '{"session_id":"account-001"}'
POST/api/pool/release释放粘性会话，归还实例
| 参数 | 说明 | 必选 |
|---|
| session_id | 要释放的粘性会话 ID | 是 |
| result | 本次业务实际 HTTP 状态码（如 403），顺带上报用于统计 | 否 |
🏠 长效静态 IP（固定绑定）
把某个实例独占绑定给你：它的 IPv6 出口长期不变，不参与轮换、豁免自动换 IP，直到显式解绑。绑定状态持久化，服务器重启自动恢复。
POST/api/pool/dedicated/bind绑定：自动挑选可用实例，或指定实例，可批量
| 参数 | 说明 | 必选 |
|---|
| name | 指定实例（如 warp-0）；不传则自动挑选空闲健康实例 | 否 |
| count | 自动挑选数量（1~20） | 否 |
| remark | 备注（如业务名） | 否 |
curl -s -X POST {{API_BASE}}/api/pool/dedicated/bind -H "Content-Type: application/json" -d '{"remark":"订单业务"}'
# → data.items[0] 里含 name / ip / proxy_auth / proxy_whitelist，可长期保存使用
# 查看绑定列表 / 修改备注 / 解绑
curl -s {{API_BASE}}/api/pool/dedicated
curl -s -X POST {{API_BASE}}/api/pool/dedicated/remark -H "Content-Type: application/json" -d '{"name":"warp-0","remark":"新备注"}'
curl -s -X POST {{API_BASE}}/api/pool/dedicated/unbind -H "Content-Type: application/json" -d '{"name":"warp-0","force":true}'
# force=true 时解绑后立即换 IP（该 IP 已被独占使用过）
GET/api/pool/dedicated/history绑定/解绑历史记录
注意：固定的是每实例唯一的 IPv6 出口；IPv4 出口是共享 NAT 池动态轮换，无法固定（WARP 架构决定的）。
🔄 换 IP 与状态上报
POST/api/pool/rotate换 IP = 停止进程 → 重新注册账号 → 轮换接入点 → 重启。异步任务，返回 jobId
| 参数（body） | 说明 | 必选 |
|---|
| pool_key | 换指定实例（纯实例索引，如 "0"）；固定绑定实例需 force=true | 否 |
| session_id | 换该会话对应的实例 | 否 |
| （空 body） | 换全部实例（固定绑定实例自动排除） | — |
| force | 对固定绑定实例强制换 IP（换后仍保持绑定） | 否 |
# 换所有实例（常见：想换一批新出口时）
curl -s -X POST {{API_BASE}}/api/pool/rotate
# → {"code":"00000","data":{"jobId":3}} ← 用 jobId 轮询进度
curl -s {{API_BASE}}/api/job/3
# → {"code":"00000","data":{"id":3,"status":"running","current":0,"total":20,"logs":[...]}}
POST/api/pool/report上报业务方真实 HTTP 状态码（SOCKS5 层读不到 HTTPS 状态码，用于 403 统计与自动换 IP）
| 参数（body） | 说明 | 必选 |
|---|
| session_id | 会话 ID | 是 |
| result | 真实 HTTP 状态码（数字，如 403） | 是 |
curl -s -X POST {{API_BASE}}/api/pool/report \
-H "Content-Type: application/json" -d '{"session_id":"account-001","result":403}'
自动换 IP 规则：检测次数 ≥ cf_min_check_count（默认 3）且 403 率 ≥ cf_403_threshold（默认 50%）时自动重新注册账号换出口；健康巡检发现实例异常也会自动重建。固定绑定实例豁免所有自动换 IP。
GET/api/pool/status代理池整体状态：总数 / 可用 / 使用中 / 不健康 / 固定绑定 + 每实例明细
curl -s {{API_BASE}}/api/pool/status
# → data: { total:20, available:20, in_use:0, unhealthy:0, dedicated:0,
# instances:[{ pool_key, port, ip, health, status, proxy, proxy_auth, proxy_whitelist, ... }] }
⚙️ 实例管理（运维）
这些接口用于运维管理，管理台页面已封装，一般接入业务用不到。
| 接口 | 方法 | 参数 | 说明 |
|---|
| /api/containers | GET | - | 全部实例状态（port / ip / endpoint / health / pool_status / ip_risk / dedicated） |
| /api/check | GET | - | 服务与关键依赖检查（sing-box/wgcf 是否存在、池容量、可用数） |
| /api/stats | GET | - | 实例统计汇总 |
| /api/create | POST | {"count":N} | 创建 N 个新实例 |
| /api/delete | POST | {"name"} 或 {"names":[]} | 删除实例（固定绑定需 force=true） |
| /api/rebuild | POST | {"name"} 或 {"names":[]} | 重建实例（重新注册账号 + 轮换接入点） |
| /api/start | POST | {"name"} 或 {"names":[]} | 启动实例 |
| /api/stop | POST | {"name"} 或 {"names":[]} | 停止实例 |
| /api/job/:id | GET | - | 查询创建/重建/换 IP 任务的进度与日志 |
🛡️ 白名单与账密
GET/POST/api/whitelist白名单查询 / 增删（改动后自动热更新全部实例，出口 IP 不变）
# 查询（含每个条目的归属地）
curl -s {{API_BASE}}/api/whitelist
# 添加（可带备注）/ 批量添加 / 删除
curl -s -X POST {{API_BASE}}/api/whitelist -H "Content-Type: application/json" -d '{"add":{"ip":"1.2.3.4","remark":"公司出口"}}'
curl -s -X POST {{API_BASE}}/api/whitelist -H "Content-Type: application/json" -d '{"add":["1.2.3.5","10.0.0.0/24"]}'
curl -s -X POST {{API_BASE}}/api/whitelist -H "Content-Type: application/json" -d '{"remove":"1.2.3.4"}'
本机特权：服务器本机（127.0.0.1/::1）始终放行，即使白名单为空也可调用全部 API。白名单为空时，外部 IP 调用 API 一律返回 401 A0001。
POST/api/creds/set修改全局代理账密（用户名/密码），热更新全部实例，出口 IP 不变
POST/api/creds/reset重置全部账密（随机生成新密码）
curl -s -X POST {{API_BASE}}/api/creds/set \
-H "Content-Type: application/json" -d '{"username":"warpuser","password":"MyNew-Pass-123"}'
# 密码仅允许字母数字/下划线/连字符；改后立即生效，旧密码全部失效
📐 配置管理
GET/POST/api/config查看 / 修改运行配置（team_token 仅显示前 6 位）
# 查看配置
curl -s {{API_BASE}}/api/config
# 修改常用项（保存即生效）
curl -s -X POST {{API_BASE}}/api/config -H "Content-Type: application/json" \
-d '{"resident_count":20, "sticky_minutes":10, "cf_403_threshold":50}'
# 常用白名单字段：resident_count / sticky_minutes / auto_rebuild_on_unhealthy /
# auto_rotate_on_high_403 / cf_403_threshold / cf_min_check_count /
# ip_risk_check / ip_risk_threshold / rate_limit_per_minute / proxy_auth_enabled / team_token 等
🗺️ 服务区配置（出口地区）
出口 IP 的地区由服务器就近接入的 Cloudflare 边缘节点（colo）决定，与实例数、账号数、隧道协议均无关。换服务区 = 换机房部署，无法在服务器内切换地区。
| 项 | 值（当前实测） |
|---|
| 边缘节点 | LAX（洛杉矶） |
| IPv4 出口 | 104.28.195.186/187、104.28.227.186/187（节点 NAT 池，4 个） |
| IPv6 出口 | 2a09:bacx::/29（每实例唯一） |
| 可用 endpoint | 188.114.96.1、188.114.97.1、188.114.96.2、188.114.96.3（UDP 2408） |
工作原理：服务启动时对内置 endpoint 列表做 UDP 连通性探测，剔除不可用项；实例按索引轮询分配 endpoint（idx % 列表长度），换 IP 时轮换到下一个 endpoint，避免同端点换 IP 后出口仍相同。出口位置无法在本机内切换。
| 需求 | 做法 |
|---|
| 保持当前地区 | 无需配置，默认就近接入 |
| 更换出口地区 | 在目标地区的机房部署一台新服务器（不同机房 → 不同边缘节点 → 不同出口地区，且每台额外贡献 4 个 IPv4 出口） |
| 自定义 endpoint 列表 | 修改 server.js 中 WARP_ENDPOINTS 常量后重启（新端点需实测确认能承载流量） |
提示：N 台不同地区服务器 = 4N 个 IPv4 出口 + 20N 个 IPv6 出口，是增加出口地区与 IPv4 数量的唯一途径。
🔢 推荐实例数（按服务器配置）
每个实例是一个独立的 sing-box run 进程，实测内存约 15MB/实例，CPU 空闲占用很低。单机实例数上限 max_instances=200。
| 服务器配置 | 推荐实例数 | 说明 |
|---|
| 1 核 1G | 20 | 最小可用（当前生产即此规模） |
| 2 核 2G | 50 | 常规够用 |
| 2 核 4G | 100 | 中大规模 |
| 4 核 8G | 200 | 系统上限 |
估算依据：实例内存约 15MB/个 + 系统与 sing-box 基础开销，建议为服务器预留 30%~50% 内存余量；CPU 主要消耗在批量创建/重建与高并发转发，日常巡检空闲占用低。
# 常驻实例数（管理台「配置」或 API 修改，保存即生效，自动补齐/缩容）
curl -s -X POST {{API_BASE}}/api/config \
-H "Content-Type: application/json" -d '{"resident_count":50}'
扩缩容注意：批量创建/重建会触发 Cloudflare 注册 API 429 限流（内置退避重试，建议 max_concurrent_create 默认 3 控制并发）；缩容从端口最大的实例开始删除，固定绑定实例自动排除；单机达 200 上限后仍需更多出口，请部署多台服务器。
📊 用量统计
GET/api/usage每日提取/粘性/释放/上报/换IP/绑定次数（数据概览图表的来源）
curl -s "{{API_BASE}}/api/usage?days=30"
# → data: { days:[{ date:"2026-08-18", acquires:0, sticky:0, releases:0,
# reports:0, rotates:0, binds:0, unbinds:0, total:0 }, ...] }
🖥️ 管理台操作
管理台入口为 /，文档入口为 /docs。管理台按功能分为数据概览、流量代理、长效静态 IP、白名单管理和实例管理。
| 页面 | 主要用途 | 常用操作 |
|---|
| 数据概览 | 查看容器、实例、可用数、使用中、不健康、独立 IP、固定绑定和活跃会话 | 查看近 30 天用量；添加白名单或一键添加当前 IP；进入代理提取、静态 IP、白名单管理 |
| API 白名单模式 | 生成批量提取链接 | 选择 txt/json、IPv4/IPv6、轮换/Sticky、数量和换行符；复制链接或直接打开；可切换白名单列表批量删除 |
| 账密模式 | 使用代理账号密码连接实例端口 | 查看/复制账密，修改密码，生成 HTTP(S)/SOCKS5 示例和代理列表（1~200 条） |
| 长效静态 IP | 管理长期固定的 IPv6 出口 | 绑定、搜索、复制、编辑备注、导出、批量解绑；切换使用记录/历史记录；可重置全部账密 |
| 白名单管理 | 管理 API 免 Key 和白名单端口来源 | 支持 IPv4、IPv6、CIDR；搜索、编辑备注、批量删除、查看归属地、一键添加当前 IP |
| 实例管理 | 管理 WARP 实例生命周期 | 调整实例数、粘性时长、403 自动换 IP、账密开关；创建/重建、启停、删除、换 IP、查看任务日志 |
端口规则：实例主端口从 base_port（默认 10010）开始递增；白名单端口 = 主端口 + whitelist_port_offset（默认 1000）。白名单端口仅允许白名单来源且免密，主端口是否需要账密由账密模式开关决定。
🔐 管理台登录与鉴权
管理台页面公开可打开，但管理接口需要登录。点击右上角「登录」，使用配置中的 API Key 换取会话 Token；登录成功后会话默认有效 30 天，浏览器会保存登录状态。
POST/api/loginAPI Key 换取管理台会话 Token
curl -s -X POST {{API_BASE}}/api/login \
-H "Content-Type: application/json" -d '{"key":"你的API Key"}'
# 成功返回 data.token；expires_in 为有效秒数，api_key_hint 仅显示脱敏提示
注意：管理台登录 Token 只用于管理接口，不会替代代理提取接口的来源 IP 白名单。外部调用 API 仍需把调用方 IP 加入白名单；服务器本机 127.0.0.1 / ::1 始终放行。
登录保护：API Key 连续输错 5 次会锁定当前来源 60 秒。不要把 API Key 写入前端代码、公开脚本或代理列表。
🧰 高级配置与自动维护
常用配置
| 配置 | 默认值 | 说明 |
|---|
| resident_count | 5 | 常驻实例数；保存后自动补齐或缩容 |
| max_instances | 200 | 单机实例上限 |
| min_available | 5 | 可用实例不足时触发补充 |
| max_concurrent_create | 3 | 创建/重建并发数，降低 Cloudflare 429 风险 |
| health_check_interval | 600 秒 | 健康巡检间隔；配合自动重建使用 |
| auto_rebuild_on_unhealthy | true | 实例异常时自动重建；最多由 max_rebuild_attempts 控制 |
| auto_rotate_on_high_403 | true | 403 统计达到阈值后自动换 IP |
| cf_403_threshold / cf_min_check_count | 50 / 3 | 403 比例阈值与最少统计次数 |
| ip_risk_check / ip_risk_threshold | true / 70 | 使用 Scamalytics 风控检测，达到阈值自动换 IP |
| rate_limit_per_minute | 60 | 代理池及管理操作的接口限流 |
| proxy_auth_enabled | true | 主端口是否启用用户名密码；切换会热更新实例且不改变出口 IP |
WireGuard 与 MASQUE
warp_transport 默认为 wireguard；设置为 masque 时使用 usque 引擎，通过本机独立 SOCKS 端口承载 WARP 流量，适合服务器 UDP/WireGuard 受限的网络。masque_http2 可启用 HTTP/2 传输；修改后需重建或重启相关实例。
Teams Token
在 team_token 中填写 WARP Teams Token 后，新注册账号会按 Teams 方式创建（用于团队/无限流量场景）。GET 配置接口只返回 Token 前 6 位；不要在文档、日志或截图中暴露完整 Token。
固定绑定影响：长效静态 IP 实例会从普通代理池中排除，并豁免自动换 IP和自动重建；如需更换其出口，必须显式传 force=true，换 IP 后仍保留绑定关系。
⚠️ 统一响应格式与错误码
所有 JSON 接口统一返回 { "code": "00000", "msg": "", "data": {} }，code 为 5 位错误码，00000 代表成功。
| code | 含义（HTTP） | 怎么办 |
|---|
| 00000 | 成功 | — |
| A0001 | 来源 IP 不在白名单（401） | 按响应中的 hint 命令把 IP 加入白名单 |
| A0002 | 请求过于频繁（429） | 稍后再试（默认限 60 次/分钟，可调） |
| P0001 | 无可用代理 | 实例可能都在恢复/被绑定，稍等或到管理台查看 |
| S0001 | 会话不存在或已过期 | 重新提取一次 |
| D0001 | 实例被固定绑定保护 | 确认要操作就传 force=true |
| I0001 / I0002 | 参数错误 / 资源不存在 | 检查参数拼写与数值范围 |
| R0001 | 实例操作失败 | 查看任务日志（/api/job/:id）定位原因 |
| 99999 | 系统内部异常 | 查看服务端日志 |
💻 代码示例
Python（requests + pysocks）：
import requests
# 1) 提取代理（普通轮换：每次调用换出口）
r = requests.get("http://SERVER:4433/api/pool/acquire", timeout=10)
proxy = r.json()["data"]["proxy"] # 如 socks5://IP:10010
print("出口代理:", proxy)
# 2) 走 SOCKS5 发起业务请求
resp = requests.get(
"https://api64.ipify.org",
proxies={"http": proxy, "https": proxy}, # 需要 pip install pysocks
timeout=15,
)
print("出口 IP:", resp.text)
# 3) 粘性会话：多次请求同一出口 IP
sess = requests.get("http://SERVER:4433/api/proxies?num=1&type=json&sid=task-01&time=30", timeout=10)
p = sess.json()["data"]["proxies"][0]
proxies = {"http": p["proxy"], "https": p["proxy"]}
for i in range(3):
ip = requests.get("https://api64.ipify.org", proxies=proxies, timeout=15).text
print(f"第{i+1}次出口: {ip}") # 3 次都是同一个 IP
命令行批量提取后逐个使用：
# 提取 10 个 txt，然后循环使用
curl -s "{{API_BASE}}/api/proxies?num=10&type=txt&format=n" > proxies.txt
while IFS= read -r line; do
curl -s --max-time 15 --proxy "socks5h://$line" "https://api64.ipify.org"
echo " <- $line"
done < proxies.txt
❓ 常见问题
Q：调用 API 提示 401 / A0001 怎么办？
来源 IP 不在白名单。SSH 到服务器执行响应信息里给出的 curl 命令添加，或让白名单内的人帮你在管理台「白名单管理」页添加（会自动识别归属地）。
Q：文档需要登录吗？
不需要。本页是公开页面，任何人都能直接打开阅读；文中示例已自动替换成当前访问的服务器地址，复制即可用。
Q：账号密码在哪里看？
管理台 → 账密模式。一套账密（默认用户名 warpuser）适用于所有端口，密码可修改或重置，改后立即生效。
Q：怎么让某个业务一直用同一个 IP？
短期（分钟级）用粘性会话 sid；长期用「长效静态 IP」绑定，IPv6 出口固定到解绑为止。
Q：粘性会话和长效静态 IP 有什么区别？
粘性会话是临时固定（默认 10 分钟、最长 1440 分钟，超时自动释放）；长效静态 IP 是独占绑定、长期不变，直到手动解绑。前者适合短任务，后者适合长期固定出口。
Q：能选国家/地区吗？
不能。出口位置由服务器就近的 Cloudflare 节点决定（当前为 LAX 洛杉矶）。换地区需要在不同机房部署新服务器，每台还能额外增加 4 个 IPv4 出口。
Q：IPv4 和 IPv6 出口有什么区别？
每个实例有唯一的 IPv6 出口（对外按 IP 轮换就是靠它）；IPv4 出口是边缘节点共享的 NAT 池，同一服务器固定 4 个、动态轮换，无法作为大量唯一 IP 使用。目标站支持 IPv6 时优先走唯一 IPv6 出口。
Q：能过 OpenAI 网页/注册吗？
不能。WARP 出口是数据中心 IP（AS13335），会被 Cloudflare 质询拦截（403）。但 api.openai.com、Grok、Anthropic、DeepSeek、OpenRouter 等大模型 API 全部可用——已注册 Key 的 API 调用不受影响。
Q：提取后出口 IP 偶尔相同？
Round-Robin 按实例轮换，20 个实例就有 20 个唯一 IPv6 出口，正常情况下连续提取不相同；若部分实例正在恢复/重建，可用池变小，循环一圈后可能重复，稍后再提取即可。