BlankTrail Proxy
登录 立即开始

API — 端口与流量

打开、关闭、列出和配置代理端口，并在正式使用前测试上游代理。这些是集成 BlankTrail Proxy 时最常用的接口。

打开端口

POST /api/v1/ports/open 需要鉴权

使用给定配置打开一个新的代理端口，并返回它将呈现的身份。

参数类型必填说明
portint是要打开的本地 TCP 端口。
protocolstring否"socks5" 或 "http"（默认 "http"）。
modestring否身份的选取方式："random"、"db"、"auto" 或 "specific"。
browserstring否浏览器筛选，例如 "chrome"、"firefox"、"safari"、"edge"（可附带版本号）。
osstring否操作系统筛选："windows"、"macos"、"linux" 或 "ios"。
upstreamstring否上游代理，例如 "socks5://user:pass@host:1080"。留空则直连。
upstream_gatewaystring否要路由经过的已保存网关名称，替代原始上游代理。
spoof_headersbool否是否将出站 HTTP 请求头规范化以匹配身份。
请求体
{
  "port": 20134,
  "protocol": "socks5",
  "mode": "random",
  "browser": "chrome",
  "os": "windows"
}
示例 (curl)
curl -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"port":20134,"protocol":"socks5","mode":"random","browser":"chrome"}' \
  http://127.0.0.1:8891/api/v1/ports/open
响应
{
  "port": 20134,
  "protocol": "socks5",
  "status": "opened",
  "current_profile": {
    "name": "Chrome_145_Windows_10",
    "browser": "chrome",
    "os": "windows",
    "user_agent": "Mozilla/5.0 ..."
  }
}

关闭端口

POST /api/v1/ports/close 需要鉴权

关闭一个已打开的端口并释放它。

参数类型必填说明
portint是要关闭的端口。
请求体
{ "port": 20134 }
示例 (curl)
curl -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"port":20134}' http://127.0.0.1:8891/api/v1/ports/close

列出已打开的端口

GET /api/v1/ports 需要鉴权

返回每个已打开端口及其状态，以及你的端口总数和最大端口数。

示例 (curl)
curl -H "X-API-Key: YOUR_API_KEY" http://127.0.0.1:8891/api/v1/ports
响应
{
  "ports": [
    { "port": 20134, "protocol": "socks5", "status": "open" }
  ],
  "total_open": 1,
  "max_ports": 10000
}

建议一个空闲端口

GET /api/v1/ports/suggest 需要鉴权

返回一个你可以打开的可用端口号。

示例 (curl)
curl -H "X-API-Key: YOUR_API_KEY" http://127.0.0.1:8891/api/v1/ports/suggest
响应
{ "port": 20123 }

测试上游代理

POST /api/v1/upstream/test 需要鉴权

在打开端口之前，对上游链路进行预检：可达性、SOCKS5 UDP 支持，以及 DNS/IPv6 泄漏。

参数类型必填说明
checksstring[]是"http"、"udp"、"leak" 中的任意组合。
protocolstring否"socks5" 或 "http"。
upstreamstring否要测试的上游代理（留空则测试直连）。
chain_proxystring否上游代理之前可选的第一跳。
请求体
{
  "checks": ["http", "leak"],
  "protocol": "socks5",
  "upstream": "socks5://user:pass@host:1080"
}
响应
{
  "http": { "ok": true, "detail": "200 in 45ms" },
  "leak": { "ok": true, "detail": "no DNS/IPv6 leak — exit 203.0.113.45" }
}

获取端口的配置

GET /api/v1/port/{port}/status 需要鉴权

返回单个端口的完整配置快照。

示例 (curl)
curl -H "X-API-Key: YOUR_API_KEY" http://127.0.0.1:8891/api/v1/port/20134/status

修改单个端口的设置

每项端口设置在 /api/v1/port/{port}/… 下都有对应的 GET/PUT 接口。将值放在请求体中发送。例如，设置上游代理或切换请求头伪装：

PUT /api/v1/port/{port}/upstream 需要鉴权

为某个端口设置上游代理。

请求体
{ "upstream": "socks5://user:pass@host:1080" }
示例 (curl)
curl -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -X PUT \
  -d '{"upstream":"socks5://user:pass@host:1080"}' \
  http://127.0.0.1:8891/api/v1/port/20134/upstream

其他单端口设置遵循相同的模式，包括：mode、browser、os、chain_proxy、spoof_user_agent、spoof_headers、h2_spoofing 和 idle。