文档 & API
掌控 WhaleProxy 只需代码。
一个本地控制平面:8091 端口上的 REST、通过命名管道的 JSON-RPC,以及一个 CLI——它们与图形界面共用同一套命令。
概览
该 API 是通往路由引擎的机器对机器接口。默认基础 URL 为 http://127.0.0.1:8091/v1,输入输出均为 JSON。在 Settings 标签页中启用它。
默认情况下,它只监听回环地址(127.0.0.1)。你也可以把它绑定到某个网络 IP 以便远程控制——但请务必为其加上 TLS 和防火墙,因为该引擎以提权身份运行,掌控着本机的全部网络流量。
亮点:WhaleProxy 可以更改运行中进程所用的代理——这是其他任何按进程代理工具都做不到的。
身份验证
除 /v1/healthz 外,每个请求都需要一个通过请求头发送的 API 密钥。该密钥由 CSPRNG 生成;可在 Settings → Generate 中创建/轮换。密钥采用恒定时间比较。
X-API-Key: <YOUR_API_KEY>
# hoặc
Authorization: Bearer <YOUR_API_KEY>重新路由——更改运行中进程所用的代理
通过 pids、exe 名称、路径、身份哈希或别名来选择进程——然后把它们指向一个新代理。使用 /preview 可试运行而不实际应用。
POST/v1/reroute重新路由一个运行中的进程
POST/v1/reroute/preview预览哪些 PID 会被匹配
POST/v1/reroute/clear清除重新路由,恢复按规则处理
{ "match": { "nickname": "App 3" }, "proxy": "jp-2" }
→ 200 { "rerouted": 1, "flows_moved": 12 }代理
管理上游代理池(socks5 / http / localnet)。测试会返回延迟和真实的出口 IP。
GET/v1/proxies列出代理及其状态
POST/v1/proxies添加(单个 / 批量)
POST/v1/proxies/{alias}:test测试 → 延迟 + 出口 IP
DELETE/v1/proxies/{alias}删除 + 自动再均衡
规则
持久化的规则,首条匹配优先,适用于当前和未来的进程。
GET/v1/rules列出规则链
POST/v1/rules添加一条规则
POST/v1/rules/reorder调整优先级顺序
POST/v1/config/reload重载配置,实时生效
进程
查看被跟踪的进程、为其设置别名,或将其终止。
GET/v1/processes实时进程列表
GET/v1/processes/{pid}查看单个 PID 的详情
POST/v1/processes/{pid}/nickname设置别名
POST/v1/processes/{pid}/kill终止该进程
统计 & 事件
读取每个进程、每个代理的字节数/数据流/连接数;长轮询进程创建/退出事件。
GET/v1/stats全系统汇总数据
GET/v1/stats/per-proxy按代理统计
GET/v1/events/poll长轮询事件
命令行
CLI 封装了同一套命令;加上 --json 即可获得机器可读的输出。只要引擎在运行就能使用。
$ whaleproxy proxies list --json
$ whaleproxy reroute --name chrome.exe --to jp-2
$ whaleproxy pin --nickname "App 3" --proxy us-1
$ whaleproxy stats --json示例——用 Python 调用
该 API 就是普通的 HTTP,任何语言都能调用。下面的示例把一个进程切换到另一个代理。
import requests
API = "http://127.0.0.1:8091/v1"
H = { "X-API-Key": "YOUR_KEY" }
# Đổi proxy của "App 3" sang jp-2, ngay khi đang chạy
r = requests.post(f"{API}/reroute", headers=H, json={
"match": { "nickname": "App 3" },
"proxy": "jp-2"
})
print(r.json()) # {'rerouted': 1, 'flows_moved': 12}