文件與 API

用程式碼操控 WhaleProxy。

一套本機控制平面：8091 埠上的 REST、走具名管道的 JSON-RPC，以及一個 CLI——都是 GUI 底層那套指令。

總覽

此 API 是路由引擎的機器對機器介面。預設基底 URL 為 http://127.0.0.1:8091/v1，輸入輸出皆為 JSON。在 Settings 分頁啟用它。

預設只監聽本機回送位址（127.0.0.1）。你可以把它綁定到某個網路 IP 以進行遠端控制——請務必放在 TLS 與防火牆之後，因為引擎以提升後的權限執行，並掌控機器上所有的網路流量。

亮點：WhaleProxy 能切換執行中程序的代理——這是其他逐程序代理工具都做不到的。

驗證

每個請求（/v1/healthz 除外）都需要 API 金鑰，並透過標頭傳送。金鑰以 CSPRNG 產生；在 Settings → Generate 建立或輪替。金鑰以固定時間比對。

http

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清除重新路由，還原為規則

POST /v1/reroute

{ "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 即可輸出機器可讀的格式。引擎執行時即可使用。

cmd

$ 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，任何語言都能呼叫。下方範例會把一個程序移到另一個代理。

python

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}

用腳本自動化

用腳本重新路由整批程序

下載 WhaleProxy，在 Settings 啟用 API，開始用程式碼操控它。

下載 WhaleProxy 探索功能

用程式碼 操控 WhaleProxy。

總覽

驗證