文件 控制器 API

控制器 API 文件

Clash / Mihomo 核心暴露了一套本地 RESTful 介面（外部控制器），面板、腳本都是靠它拿資料和下指令。約 30 個介面，按功能分組列出請求方式和回傳欄位。

請求範例

面板/腳本發給核心的每一條請求都要帶上驗證標頭，格式統一如下：

curl Shell
curl -H 'Authorization: Bearer ${secret}' http://${controller-api}/configs?force=true \
  -d '{"path": "", "payload": ""}' -X PUT
  • ${secret} 是設定檔裡設定的 secret 金鑰
  • ${controller-api} 是設定檔裡設定的 external-controller 監聽位址
  • ?force=true 是查詢參數，部分介面需要攜帶
  • '{"path": "", "payload": ""}' 是要更新的資源資料

如果請求裡要傳檔案路徑，而路徑又不在 mihomo 工作目錄下，需要手動設定 SAFE_PATHS 環境變數把它加入安全路徑，語法與作業系統的 PATH 變數一致（Windows 用分號分隔，其他系統用冒號分隔）。

日誌

GETWS/logs

取得即時日誌。

  • 可選參數 ?level=log_level，log_level 可選 info/warning/error/debug
  • 可選參數 ?format=structured，攜帶後輸出結構化日誌（含 time/level/message/fields）
  • 標準模式每行推送一個 JSON：type 日誌級別、payload 日誌內容
  • 結構化模式：time（HH:MM:SS）、level、message、fields（附加欄位陣列）

流量資訊

GETWS/traffic

取得即時流量，up/down 單位是位元組/秒，upTotal/downTotal 單位是位元組，每秒推送一次。

  • up 目前上傳速率　down 目前下載速率
  • upTotal 累計上傳位元組數　downTotal 累計下載位元組數

記憶體資訊

GETWS/memory

取得即時記憶體佔用（位元組），每秒推送一次。

  • inuse 目前記憶體使用量　oslimit 系統記憶體限制（固定為 0）

版本資訊

GET/version

取得核心版本資訊。

  • meta 是否為 Meta 版本　version 版本號字串

快取

POST/cache/fakeip/flush

清除 fakeip 快取，回傳 HTTP 204。

POST/cache/dns/flush

清除 DNS 快取，回傳 HTTP 204。

執行設定

GET/configs

取得目前執行設定，回傳一個 JSON 物件，包含 port、socks-port、mixed-port、mode、log-level、allow-lan、ipv6、tun 等欄位。

PUT/configs

重新載入基本設定，攜帶參數 ?force=true，回傳 HTTP 204。

PATCH/configs

局部更新基本設定，例如 '{"mixed-port": 7890}'，回傳 HTTP 204。

POST/configs/geo

更新 GEO 資料庫，攜帶 '{"path": "", "payload": ""}'，回傳 HTTP 204。

POST/restart

重新啟動核心，攜帶 '{"path": "", "payload": ""}'，回傳 HTTP 204。

更新

POST/upgrade

更新核心，可選 ?channel=xxx 指定更新通道、?force=true 強制更新，回傳 {"status": "ok"}。

POST/upgrade/ui

更新面板（須先在設定裡設定 external-ui），回傳 {"status": "ok"}。

POST/upgrade/geo

更新 GEO 資料庫，回傳 HTTP 204。

策略組

GET/group

取得全部策略組資訊，回傳 proxies 陣列，每項格式同 /proxies/{name}。

GET/group/{group_name}

取得指定策略組資訊，格式同 /proxies/{name}。

GET/group/{group_name}/delay

對策略組內全部節點測速，回傳新的延遲資料，並清除該自動策略組目前的 fixed 固定選擇。

  • 攜帶參數 ?url=xxx&timeout=5000
  • 可選 ?expected=xxx，期望的 HTTP 回應狀態碼，支援範圍寫法如 200/204、200-299
  • 回傳以節點名為鍵、延遲毫秒數為值的物件，如 {"節點A": 120, "節點B": 350}

代理

GET/proxies

取得全部代理/策略組資訊，回傳以名稱為鍵的 proxies 物件，每條公共欄位包括：

  • name/type（如 Shadowsocks、VMess、DIRECT、Selector、URLTest 等）
  • udp/uot/xudp/tfo/mptcp/smux 能力旗標
  • alive 目前是否存活，history 延遲歷史（time+delay），extra 按測速 URL 分組的額外歷史
  • interface/routing-mark/provider-name/dialer-proxy
  • 策略組額外含：now 目前選中（LoadBalance 無此欄位）、all 成員列表、testUrl、hidden、icon、emptyFallback、expectedStatus（Selector 無）、fixed（僅 URLTest/Fallback）
GET/proxies/{name}

取得指定代理/策略組資訊，欄位同上（一般代理只有公共欄位）。

PUT/proxies/{name}

切換該策略組目前選中的節點，攜帶 '{"name":"日本"}'，回傳 HTTP 204。

DELETE/proxies/{name}

清除該代理/策略組的 fixed 固定選擇（Selector 類型除外），回傳 HTTP 204。

GET/proxies/{name}/delay

對指定代理測速，攜帶 ?url=xxx&timeout=5000（可選 ?expected=xxx），回傳 {"delay": 120}。

代理集合

GET/providers/proxies

取得全部代理集合資訊，回傳以集合名稱為鍵的 providers 物件，每個集合含元資訊及代理列表。

GET/providers/proxies/{name}

取得指定代理集合資訊，含設定資訊及 proxies 代理列表。

PUT/providers/proxies/{name}

更新該代理集合，回傳 HTTP 204。

GET/providers/proxies/{name}/healthcheck

觸發該代理集合的健康檢查，回傳 HTTP 204。

GET/providers/proxies/{name}/{proxy_name}

取得集合內指定代理的資訊，欄位同 /proxies/{name}。

GET/providers/proxies/{name}/{proxy_name}/healthcheck

對集合內指定代理測速，攜帶 ?url=xxx&timeout=5000，回傳 {"delay": 120}。

規則

GET/rules

取得全部規則，回傳 rules 陣列，每項包含：

  • index 索引（從 0 開始）　type 規則類型　payload 匹配內容　proxy 目標代理/策略組
  • size 規則條目數（僅 GEOIP/GEOSITE 有效，其餘為 -1）
  • 可選 extra：disabled/hitCount/hitAt/missCount/missAt
PATCH/rules/disable

按索引暫時停用/啟用規則（重新啟動後失效），攜帶 '{"0": false,"1": true}'，回傳 HTTP 204。

規則集合

GET/providers/rules

取得全部規則集合資訊，回傳以名稱為鍵的 providers 物件。

PUT/providers/rules/{name}

更新指定規則集合，回傳 HTTP 204。

連線

GETWS/connections

取得活躍連線資訊，可選參數 ?interval=milliseconds（刷新間隔，預設 1000ms）。

  • downloadTotal/uploadTotal 累計流量　memory 目前記憶體佔用
  • connections 活躍連線陣列：id、metadata（來源/目標位址、協議、行程名稱等）、upload/download、start、chains/providerChains 代理鏈路、rule/rulePayload 命中的規則
DELETE/connections

關閉全部連線，回傳 HTTP 204。

DELETE/connections/{id}

關閉指定連線，回傳 HTTP 204。

網域查詢

GET/dns/query

取得指定名稱和類型的 DNS 查詢結果，攜帶 ?name=example.com&type=A。

  • Status DNS 回應碼　Question 查詢問題陣列
  • TC/RD/RA/AD/CD 各類 DNS 旗標
  • 可選 Answer/Authority/Additional：均為記錄陣列，每項含 name/type/TTL/data

儲存

GET/storage/{key}

取得指定 key 的儲存值，不存在時回傳 null。

PUT/storage/{key}

寫入指定 key 的值（須為合法 JSON，最大 1MB），攜帶 '{"foo": "bar"}'，回傳 HTTP 204。

DELETE/storage/{key}

刪除指定 key 的儲存值，回傳 HTTP 204。

DEBUG

/debug 系列介面需要核心啟動時的日誌級別設為 debug。

PUT/debug/gc

觸發一次主動 GC，回傳 HTTP 204。

GET/debug/pprof

瀏覽器開啟 http://${controller-api}/debug/pprof 查看原始 DEBUG 資訊：

  • allocs：每個函式呼叫的記憶體配置情況（堆疊上/堆積上大小與次數），用來排查記憶體洩漏、頻繁申請等問題
  • heap：堆積上記憶體使用詳情，包含配置區塊的大小、數量、位址並按大小排序，用來定位記憶體佔用過高的位置

安裝 Graphviz 後可以看圖形化報告：

Shell pprof
go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/heap
go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/allocs

瀏覽器存取 http://${controller-api}/debug/pprof/heap?raw=true 即可下載報告檔案，遇到問題時可以把它上傳到 issue 裡方便排查。