📖 概述
ProxyHub 提供两种代理模式：
🔀
Forward 转发模式
POST：ProxyHub 代你请求，返回完整响应。每次自动换节点。
POST /api/forward
📍
Forward 取址模式
GET：返回代理地址，你自己用。自动切换节点后给你地址。
GET /api/forward
📡
Proxy 取用模式
从外部代理池获取代理 URL（公网代理，非 Clash）。
GET /api/proxy/next
🔀 Forward 转发 API
推荐调用方只需传目标 URL，ProxyHub 内部完成：选 Clash 实例 → 随机选节点 → 切换 → 代理转发 → 返回结果。每次请求自动轮换不同节点。
POST
/api/forward
— 通过 Clash 集群转发请求
请求头
| Header | 说明 |
|---|---|
| Content-Type | application/json |
请求体（JSON）
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| url | string | ✓ | — | 目标请求 URL |
| token | string | ✓ | — | API Token（也支持 query 参数 ?token=） |
| method | string | — | GET | HTTP 方法（GET/POST/PUT/DELETE） |
| headers | object | — | — | 自定义请求头键值对 |
| body | string | — | — | 请求体内容（POST/PUT 时使用） |
| timeout | float | — | 15.0 | 超时时间（秒） |
| max_retries | int | — | 5 | 最多尝试节点数（自动轮换） |
响应体（JSON）
| 字段 | 类型 | 说明 |
|---|---|---|
| status_code | int | 目标网站返回的 HTTP 状态码 |
| headers | object | 目标网站返回的响应头 |
| body | string | 目标网站返回的响应体（文本） |
| clash_instance | string | 使用的 Clash 实例名（如 clash_1） |
| node_used | string | 使用的代理节点名（如 🇯🇵 日本Z01） |
| attempts | int | 尝试次数（1 = 首次成功） |
请求示例
curl -X POST http://proxyhub:8788/api/forward \
-H "Content-Type: application/json" \
-d '{
"url": "http://httpbin.org/ip",
"token": "YOUR_TOKEN",
"timeout": 15
}'
✅ 成功响应
{
"status_code": 200,
"headers": { "content-type": "application/json", ... },
"body": "{ \"origin\": \"103.151.172.70\" }",
"clash_instance": "clash_1",
"node_used": "🇭🇰 香港Z03 | IEPL",
"attempts": 1
}
❌ 错误响应
// HTTP 502 — 所有节点都失败
{
"detail": "all clash nodes failed. last: clash_1/🇰🇷 韩国Z01: timeout"
}
// HTTP 503 — 没有 Clash 实例
{
"detail": "no active clash instance available"
}GET
/api/forward
— 获取代理地址（走 Clash，外部可直接用）
和 /api/proxy/next 类似，但底层走 Clash 集群。每次调用自动切换到随机节点，返回代理地址供外部使用。
Query 参数
| 参数 | 必填 | 默认 | 说明 |
|---|---|---|---|
| token | ✓ | — | API Token |
| switch | — | 1 | 1=自动切换随机节点 / 0=不切换（用当前节点） |
| consumer | — | — | 调用方标识（记录日志） |
| region | — | all | 地区（仅记录，不影响选择） |
响应体（JSON）
| 字段 | 说明 |
|---|---|
| proxy_url | 外部可用的代理地址（http://服务器IP:41001） |
| proxy_url_internal | Docker 内部地址（http://clash_1:7890） |
| clash_instance | Clash 实例名 |
| node_used | 当前使用的节点（已切换） |
| controller_url | Clash 控制器地址（可自行操作切换） |
| region | 节点地区（从节点名提取） |
请求示例
# 1. 获取代理地址
proxy=$(curl -s "https://proxyhub.xqz.uk/api/forward?token=YOUR_TOKEN" \
| python3 -c "import sys,json;print(json.load(sys.stdin)['proxy_url'])")
# 2. 用代理地址请求（节点已自动切换）
curl --proxy $proxy http://ip-api.com/json
响应示例
{
"proxy_url": "http://172.18.0.1:41001",
"proxy_url_internal": "http://clash_1:7890",
"clash_instance": "clash_1",
"node_used": "🇭🇰 香港Z03 | IEPL",
"controller_url": "http://172.18.0.1:42001",
"api_url_internal": "http://clash_1:9090",
"region": "HK",
"port": 41001
}💡 使用场景
- 浏览器/工具配置代理：填入
proxy_url - Python requests：
requests.get(url, proxies={"http": proxy_url}) - SDK 需要代理地址的场景（Selenium、Playwright 等）
- 每次调用换一个节点 → 自然 IP 轮换
GET
/api/forward/health
— 检查 Clash 集群状态
请求示例
curl "https://proxyhub.xqz.uk/api/forward/health?token=YOUR_TOKEN"{
"clash_instances": ["clash_1"],
"count": 1,
"mode": "clash_cluster"
}📡 Proxy 取用 API
获取代理 URL 自己使用。适合需要长连接、自定义控制或 SDK 限制必须自己管代理的场景。
GET
/api/proxy/next
— 获取下一个可用代理
Query 参数
| 参数 | 必填 | 默认 | 说明 |
|---|---|---|---|
| token | ✓ | — | API Token |
| region | — | all | 地区筛选（JP/US/HK/KR/all） |
| network | — | external | external=公网代理 / internal=Clash 本地端口 |
| consumer | — | — | 调用方标识（记录到日志） |
请求示例
curl "https://proxyhub.xqz.uk/api/proxy/next?token=YOUR_TOKEN®ion=JP"
响应
{
"proxy_url": "http://user:pass@host:port",
"region": "JP",
"source": "api",
"latency": 75,
"network": "external",
"id": 42
}GET
/api/proxy/stats
代理池统计
curl ".../api/proxy/stats?token=TOKEN"
{
"total": 50,
"alive": 42,
"by_region": {"JP": 10, "US": 20, ...}
}POST
/api/proxy/report
反馈代理成功/失败（用于自动剔除）
curl -X POST ".../api/proxy/report?token=TOKEN" \
-H "Content-Type: application/json" \
-d '{
"proxy_url": "http://...",
"success": false,
"consumer": "my-app"
}'🔌 集成示例
🐍 Python — Forward 模式
httpx 异步
import httpx
import asyncio
async def fetch_via_proxyhub(url):
async with httpx.AsyncClient(timeout=30) as c:
r = await c.post(
"http://proxyhub:8788/api/forward",
json={
"url": url,
"token": "YOUR_TOKEN",
"timeout": 15,
},
)
data = r.json()
print(f"via {data['node_used']} ({data['clash_instance']})")
return data["body"]
html = asyncio.run(fetch_via_proxyhub("https://example.com"))🐍 Python — Proxy 取用模式
import requests
# 1. 获取代理 URL
r = requests.get("https://proxyhub.xqz.uk/api/proxy/next",
params={"token": "YOUR_TOKEN", "region": "JP"})
proxy_url = r.json()["proxy_url"]
# 2. 使用代理请求
resp = requests.get("https://example.com",
proxies={"http": proxy_url, "https": proxy_url})
# 3. 反馈结果
requests.post("https://proxyhub.xqz.uk/api/proxy/report?token=TOKEN",
json={"proxy_url": proxy_url, "success": resp.ok})💻 cURL — Forward 模式
一行命令
curl -X POST https://proxyhub.xqz.uk/api/forward \
-H "Content-Type: application/json" \
-d '{"url":"http://httpbin.org/ip","token":"YOUR_TOKEN"}' \
| python3 -m json.tool⚙️ 工作原理
调用方 ProxyHub Clash 集群
│ │ │
│ POST /api/forward │ │
│ {url, token, method...} │ │
│ ──────────────────────────────>│ │
│ │ 1. 查活跃 Clash 实例 │
│ │ 2. 获取节点列表 │
│ │ 3. 随机打乱（轮换） │
│ │ 4. 切换到候选节点 │
│ │ ─────────────────────────────>│ clash_1:9090
│ │ │ (PUT /proxies/{group})
│ │ 5. 通过代理端口转发请求 │
│ │ ─────────────────────────────>│ clash_1:7890
│ │ │ ───> 目标网站
│ │ │ <─── 返回响应
│ │ <─────────────────────────────│
│ │ │
│ │ ✅ 成功？返回结果 │
│ │ ❌ 失败？换下一个节点重试 │
│ │ (最多 5 个节点) │
│ HTTP 200 + {body, node...} │ │
│ <──────────────────────────────│ │
│ │ │🎲
随机轮换
每次请求从可用节点随机选，避免固定 IP 被风控
🔄
自动 Fallback
节点失败自动切换下一个，最多尝试 5 个节点
🛡️
隐藏服务器 IP
出口全部是 Clash 节点 IP，服务器 IP 永不暴露