Xray API 節點自動選優：JSON 設定與腳本實戰

本篇專為熟悉 Xray 設定檔的開發者與網路管理員撰寫，示範如何透過 Xray API 讀取流量統計、搭配節點健康檢查與腳本排程，建立可控的自動選線機制。內容以 Linux 上的 Xray-core 1.8.x～1.9.x 常見配置為例，涵蓋 API 入站、JSON 結構、候選節點比較、切換策略、權限限制，以及長時間執行時的記錄與排錯方法。

先釐清 Xray API 能做什麼

Xray API 是以 gRPC 提供的管理介面，不是另一條代理協定，也不會自動替你測試所有節點。API 必須先在設定檔中啟用對應服務，外部程式再透過 gRPC 送出查詢或管理要求。常見服務包括 StatsService、HandlerService、RoutingService 與 LoggerService。

自動選優通常包含三個獨立環節：第一是取得數據，例如上行、下行、連線錯誤或探測延遲；第二是按照門檻排除不健康節點；第三是讓流量真正改用新節點。前兩步可以透過 API 完成，但第三步不一定等同於呼叫一個「切換目前節點」按鈕。若使用 balancer，Xray 會在多個出站之間選擇；若由腳本修改 JSON，則通常需要透過管理服務重建出站，或讓 systemd 重新載入設定。

建立安全的 API JSON 設定

以下是可嵌入主設定檔的基本結構。API 入站使用 dokodemo-door 接收本機管理連線，並以 api 標籤識別。StatsService 需要配合 policy 開啟統計，否則執行查詢時可能只得到空結果。

{
  "log": {
    "loglevel": "warning",
    "error": "/var/log/xray/error.log",
    "access": "/var/log/xray/access.log"
  },
  "api": {
    "tag": "api",
    "services": [
      "HandlerService",
      "LoggerService",
      "StatsService",
      "RoutingService"
    ]
  },
  "stats": {},
  "policy": {
    "levels": {
      "0": {
        "statsUserUplink": true,
        "statsUserDownlink": true
      }
    },
    "system": {
      "statsInboundUplink": true,
      "statsInboundDownlink": true,
      "statsOutboundUplink": true,
      "statsOutboundDownlink": true
    }
  },
  "inbounds": [
    {
      "tag": "api-in",
      "listen": "127.0.0.1",
      "port": 10085,
      "protocol": "dokodemo-door",
      "settings": {
        "address": "127.0.0.1"
      }
    }
  ],
  "routing": {
    "rules": [
      {
        "type": "field",
        "inboundTag": ["api-in"],
        "outboundTag": "api"
      }
    ]
  }
}

這段設定的重點不是固定使用 10085，而是讓腳本與 Xray 共享一個明確、固定且只供本機使用的管理端點。若伺服器上已有其他服務使用 10085，可以改成 10086，但必須同步修改腳本、監控工具與防火牆規則。API 不應監聽 0.0.0.0，也不應直接暴露至公網；Xray API 本身並非以帳號密碼作為通用的安全邊界。

完成設定後先執行設定檢查，再重新啟動服務。常見命令如下，實際執行檔位置應以發行版安裝方式為準。

sudo xray run -test -config /etc/xray/config.json
sudo systemctl restart xray
sudo systemctl status xray --no-pager
ss -lntp | grep 10085

比較 balancer 與外部腳本兩種方案

如果節點格式穩定，而且需求是依探測結果在多個出站中選擇，優先考慮 Xray 原生的 balancer 與 observatory。這種方式讓核心維持節點清單，路由規則將指定流量送入 balancer，再由策略選擇可用出站。若需求包含自訂評分、每日報表、失敗冷卻、跨多個 Xray 程序或根據業務時段切換，外部腳本會更容易維護。

不要只用單次延遲作為唯一標準。延遲低的節點可能有高封包遺失率，或在實際下載時吞吐量很差。較穩妥的分數可以由多項指標組成，例如延遲占 40%、近 5 分鐘成功率占 40%、錯誤懲罰占 20%。分數計算只是篩選工具，仍應設定硬性淘汰門檻：連續 3 次連線失敗、延遲超過 800 毫秒，或最近 5 分鐘錯誤率高於 20% 時，暫時移出候選集合。

• 最小樣本：每個節點至少保留 3 次成功探測結果，避免一次偶發超時造成誤切換。
• 滯後區間：新節點分數必須比目前節點高出至少 15%，才執行切換。
• 冷卻時間：切換後至少等待 180 秒，不要在兩個節點之間來回震盪。
• 失敗回退：新節點啟用後連續 2 次業務請求失敗，立即回到上一個健康節點。
• 持久化：將目前節點、切換時間與原因寫入狀態檔，重啟後不要遺失冷卻狀態。

動手製作 API 查詢與切換腳本

以下流程先完成「讀取統計與評估」，再決定是否修改設定。若只需要查詢 Xray 的統計資料，可以使用隨 Xray 提供的 API 命令列工具；不同核心版本的命令參數可能略有差異，請先執行 xray api statsquery --help 確認。查詢時可先列出目前可用的統計項目，再指定某個 outbound 或 user 的計數器。

1. 準備候選清單

   在設定中為每個代理出站設定唯一的 tag，例如 node-hk-01、node-sg-01 與 node-jp-01，不要使用會隨訂閱更新而改變的顯示名稱。

2. 測試 API 連線

   在本機執行 xray api statsquery --server=127.0.0.1:10085，若得到統計項目清單，表示 API 入站、路由與服務名稱基本正常。

3. 記錄健康數據

   腳本每 60 秒執行一次，保存時間戳、節點標籤、探測延遲、成功率與最近錯誤，不要只覆寫一個無法追溯原因的數字。

4. 套用滯後門檻

   新候選分數至少高於目前節點 15%，且目前不在 180 秒冷卻期內，才進入切換流程。

5. 驗證新出站

   更新後先檢查 systemctl is-active xray、監聽連接埠與核心錯誤記錄，再以固定測試目標發出一次實際請求。

#!/usr/bin/env bash
set -euo pipefail

API="127.0.0.1:10085"
STATE="/var/lib/xray/selector.state"
LOG="/var/log/xray/selector.log"

now=$(date +%s)
stats=$(xray api statsquery --server="$API" 2>/dev/null) || {
  printf '%s api_unreachable\n' "$(date -Is)" >> "$LOG"
  exit 1
}

printf '%s stats_received bytes=%s\n' \
  "$(date -Is)" "${#stats}" >> "$LOG"

# 實際專案中於此解析節點指標、計算分數與冷卻時間。
# 只有通過滯後門檻，才更新模板並執行受控重載。
printf '%s\n' "$now" > "$STATE"

這段 shell 只示範 API 可達性與狀態保存，沒有假裝用文字搜尋就能可靠解析所有 protobuf 回應。正式環境應使用 Xray 對應版本的 gRPC client，例如以 Python、Go 或其他支援 gRPC 的程式讀取結構化結果。若採用 JSON 模板重建方式，先產生暫存檔，再執行 xray run -test -config /etc/xray/config.next.json；測試成功後以原子方式替換正式設定，最後才執行 reload 或 restart。

tmp="/etc/xray/config.next.json"
sudo xray run -test -config "$tmp"
sudo install -o root -g root -m 0644 "$tmp" /etc/xray/config.json
sudo systemctl restart xray
sudo systemctl is-active --quiet xray

Linux 長時間執行與排錯

腳本不應以互動式終端機啟動後就放著不管。建議建立專用系統使用者、限制設定檔與狀態檔權限，並使用 systemd timer 或 service 管理週期。腳本需要讀取 Xray API，但不應擁有修改整個系統的多餘權限；若確實需要重啟服務，可透過限制命令的 sudoers 規則處理，而不是給予完整 root 權限。

[Unit]
Description=Xray node selector
After=xray.service
Requires=xray.service

[Service]
Type=oneshot
User=xray-selector
ExecStart=/usr/local/sbin/xray-node-selector

[Install]
WantedBy=multi-user.target

[Unit]
Description=Run Xray node selector every minute

[Timer]
OnBootSec=2min
OnUnitActiveSec=60s
Persistent=true

[Install]
WantedBy=timers.target

啟用後可使用 systemctl list-timers 確認排程，使用 journalctl -u xray-node-selector.service -n 50 --no-pager 查看最近執行結果。Xray 本身則查看 journalctl -u xray -n 100 --no-pager，並將 API 查詢失敗、候選數量為零、切換原因與重啟結果分開記錄。記錄中不要寫入完整 VLESS UUID、VMess 使用者識別或訂閱網址，避免日誌變成憑證外洩來源。