API — 端口池

从代理列表打开一个端口池。

curl -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"tiktok-pool","target":100,"port_lo":20000,"port_hi":30000,
        "protocol":"socks5",
        "source":{"kind":"file","location":"C:/proxies.txt"},
        "up_policy":{"mode":"requests","n":1},
        "fp_policy":{"mode":"requests","n":10},
        "connect_timeout_seconds":5,"request_timeout_seconds":30}' \
  http://127.0.0.1:8891/api/v1/scraper/tasks

{
  "id": "pool-7f3a",
  "export_token": "3b91c0d4e5f6",
  "warnings": null
}

🔴 id 与 export_token 来自此处：id 用于 /scraper/tasks/{id}/…，export_token 用于导出地址 /export/{token}/proxies.txt。除 GET /api/v1/scraper/tasks 外没有其他地方可以看到它们。warnings 只包含一条提示——当实际打开的端口少于请求的 target 时的“opened N of M ports (range LO-HI too small or ports busy)”；若全部打开，该字段返回 null。它不会报告代理源的任何情况：既不会给出未能解析的条目数，也不会告知源根本没有读取成功（URL 返回 404 或超时、文件缺失）。此时池仍会启动——出口列表为空——并返回 200，只能通过流量失败才能察觉。请事先使用单独的 POST /api/v1/scraper/probe 检查源：它会返回 total（可用条目数）与 bad（损坏条目数）。

在 Lite 套餐上返回 403 “the scraper port pool requires a Pro license (single-thread Lite cannot open a port pool)”；若该构建未接入端口池，返回 503 “scraper manager not configured”；若配置不自洽（port_lo 大于 port_hi、target 小于 1，或 profile_source、up_policy.mode、fp_policy.mode、vdns_mode 取值未知，或 device 与 device_os 未知/互不兼容），返回 400 并附说明。🔴 端口区间不足以容纳 target 并不是拒绝：端口池会打开能放下的端口——若全部被占用则一个也不打开——仍返回 200，并在 warnings 中给出形如 “opened 11 of 100 ports (range 20000-20010 too small or ports busy)” 的说明。因此不要只看状态码，请检查 warnings。

有两个默认值是在创建时应用的，而不是保存在配置里：未设置时 protocol 变为 socks5（以便 UDP 与 HTTP/3 可用），vdns_mode 变为 forced——目标名称在出口侧解析，不会泄漏到您所在网络的 DNS。显式设置的 "off" 仍表示关闭。

所有端口池的快照：已打开多少端口、具体是哪些端口，以及它们所在的端口范围。

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/scraper/tasks

[
  {
    "id": "pool-7f3a",
    "name": "catalogue-pool",
    "target": 100,
    "ports_up": 98,
    "ports": [20000, 20001, 20002],
    "export_token": "3b91c0d4e5f6",
    "port_lo": 20000,
    "port_hi": 30000
  }
]

• 空数组表示当前没有任何端口池——这不是错误。若该构建未接入端口池，返回 503 “scraper manager not configured”。
• 响应中不含源代理数量，也不含轮换状态：源中有多少条目由 POST /api/v1/scraper/probe 给出（total 字段），配置了何种轮换由 GET /api/v1/scraper/tasks/{id}/config 给出（up_policy 与 fp_policy）。ports_up 是已开启端口的数量，ports 则是这些端口的编号。

停止端口池并关闭其全部端口。经由它们的流量会被切断。

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/scraper/tasks/pool-7f3a

{
  "ok": true
}

• 若不存在该 id 的端口池，返回 404 并附管理器文本。

在端口池的某个运行端口上执行完整的端口测试——与 POST /api/v1/port/{port}/test 相同——并返回被测试的端口。

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/scraper/tasks/pool-7f3a/test

{
  "port": 20134,
  "report": { "leak": { "…": "…" }, "fingerprint": { "match": true },
                "udp": { "supported": true }, "ok": true }
}

• 在端口池尚未启动任何端口时返回 409 “scraper task has no open ports yet”；端口已不再工作时返回 409 “scraper task ports are not live”。若端口池不存在，返回 404。

以 POST /api/v1/scraper/tasks 所接受的完全相同形态返回端口池的已保存配置：修改的方式是先停止再重新启动。

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/scraper/tasks/pool-7f3a/config

{
  "id": "pool-7f3a",
  "name": "catalogue-pool",
  "port_lo": 20000,
  "port_hi": 30000,
  "target": 100,
  "protocol": "socks5",
  "source": { "kind": "file", "location": "C:/proxies.txt" },
  "up_policy": { "mode": "requests", "n": 1 },
  "fp_policy": { "mode": "requests", "n": 10 },
  "vdns_mode": "forced",
  "export_token": "3b91c0d4e5f6"
}

• 404 “task not found”。该配置还包含打开表中未列出的高级字段：cache_mode、leak_guard、js_solver、keep_sessions、captcha_action 以及端口的三个超时。

列出可用于构建端口池的浏览器与操作系统组合。

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/scraper/device_matrix

{
  "chrome": ["windows", "macos", "linux", "android", "ios"],
  "edge": ["windows", "macos", "linux", "android", "ios"],
  "firefox": ["windows", "macos", "linux", "android", "ios"],
  "safari": ["macos", "ios"]
}

• 此处的取值用于打开端口池时的 device 与 device_os 字段。
• 唯一不可能的组合是非 Apple 设备上的 Safari。该表描述的是显式指定时校验器所接受的范围；device: random 取自更窄的集合——Chrome、Firefox、Edge 不含 iOS，Firefox、Edge 不含 Android——这些组合只能显式指定。

下载并解析代理源，但不启动端口池：可用条目数、损坏条目数、出现了哪些协议，以及供您自行测试连通性的随机样本。

{ "source": { "kind": "url", "location": "https://example.com/proxies.txt" } }

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"source":{"kind":"url","location":"https://example.com/proxies.txt"}}' \
  http://127.0.0.1:8891/api/v1/scraper/probe

{
  "total": 13045,
  "bad": 210,
  "by_scheme": { "socks5": 12835, "http": 210 },
  "sample": ["socks5://203.0.113.10:1080", "socks5://203.0.113.11:1080"]
}

• 若源无法下载或解析，返回 400 并附说明。请求体上限为 32 MiB——即整份粘贴列表的大小；探测上限为 35 秒。
• 许可未激活时返回 403：与其他出口检查一样，该接口位于许可之后。

将端口池的端口下载为纯文本代理列表。访问权限由 URL 中的令牌授予，因此无需 API 密钥。

curl http://127.0.0.1:8891/export/TASK_TOKEN/proxies.txt