Xray API 節點自動切換：進階設定與自動化實戰

Xray API 自動切換的基本概念

Xray 的節點自動切換，實際上不是讓核心「猜測哪條線路比較好」，而是由外部控制程式定期發送測試請求，根據回應時間、錯誤率或連線狀態，再透過 API 調整目前使用的出站標籤。這種做法把「流量轉送」和「健康檢查、決策、切換」分成兩層，既方便維護，也比較容易追蹤故障原因。

在一個典型架構裡，Xray 會保留多個實際節點，例如 node-hk、node-jp 和 node-sg，另外建立一個供路由使用的選擇器，例如 proxy-auto。瀏覽器或其他應用程式的流量只需要送往 proxy-auto，自動化程式則負責觀察各節點並更新選擇器。這樣做比直接修改每條路由規則更穩定，因為應用程式不需要知道目前實際使用的是哪個節點。

需要先釐清的是，API 自動切換解決的是「目前節點失效或表現惡化」問題，不會改善服務商本身的頻寬、節點品質或上游路由。如果所有節點都無法連線，腳本再完整也只能保留最後一個可用狀態。因此正式部署前，應先確認每個節點能在 v2rayN、v2rayNG 或直接使用 Xray 核心的環境中單獨連通。

API 服務與權限設定

Xray API 通常透過本機 gRPC 服務提供控制能力。常見做法是在 inbounds 中建立一個只監聽本機回環位址的 API 入站，例如監聽 127.0.0.1:10085，再在 routing 裡將對應流量送到名為 api 的出站。API 入站不應直接綁定到公網網卡，否則任何能接觸該連接埠的主機都可能嘗試控制你的 Xray 程序。

最小化設定可以包含以下幾個重點：api 服務名稱、只供本機使用的監聽位址，以及允許呼叫的服務類型。若腳本需要查詢出站狀態，應啟用 HandlerService；若要取得統計資料，則需要 StatsService。不同 Xray 版本對服務方法的支援可能略有差異，實際部署前應用目前版本的 API 定義或命令列工具確認。

控制面與資料面最好分開。健康檢查請求可以直接由腳本發出，也可以經由 Xray 代理送往測試網址，但 API 控制連線本身應留在本機。防火牆不應為了方便而開放 API 連接埠；若自動化程式放在另一台監控主機，建議改用受限的 SSH 通道、內網防火牆規則或專用管理網段，並額外限制來源位址。

設定完成後，先重啟 Xray 並查看日誌，確認 API 入站成功監聽。若看到連接埠被占用、服務未註冊或權限不足，應先解決這些問題，再開始寫切換邏輯。直接讓腳本不斷重試，只會製造大量無效日誌，卻無法修好底層設定。

節點分組與路由設計

自動切換能否穩定運作，關鍵在於節點標籤和路由分工是否清楚。建議給每個實際出站使用固定且容易辨識的標籤，例如 proxy-hk-01、proxy-jp-01、proxy-sg-01，不要直接使用一大串伺服器名稱或訂閱匯入後難以閱讀的隨機標籤。標籤一旦被腳本、路由和監控系統引用，就應避免頻繁修改。

可以將節點分成三類：實際代理節點、選擇器或負載平衡組，以及特殊用途的直連和阻斷出站。實際節點負責建立遠端連線；選擇器負責承接一般代理流量；直連則用於本地服務、測試例外或不需要代理的網域。不要把 API 出站、DNS 出站和一般代理出站混成同一組，否則健康檢查結果可能受到控制流量本身的影響。

如果使用 Xray 的負載平衡功能，應先確認版本支援的選擇策略和 API 行為。部分環境適合由 Xray 根據觀察結果選擇節點，部分環境則需要外部腳本保留明確的「目前主節點」。後者更容易做審計，因為每次切換都能記錄舊標籤、新標籤、觸發原因和測試數值。

路由規則中，應讓需要自動切換的流量統一指向同一個出站標籤。例如規則的目標出站可以固定寫成 proxy-auto，腳本只修改選擇器目前指向的成員。這個抽象層很重要：如果腳本每次切換都要改寫整份 JSON 設定、重啟核心，切換期間可能中斷現有連線，也容易因格式錯誤造成服務無法啟動。

健康檢查指標與判斷條件

健康檢查不要只看一次請求是否成功。單次測試可能受到瞬時丟包、DNS 延遲、測試站點限流或遠端伺服器繁忙影響。較穩妥的方式是對每個節點連續測試數次，記錄成功次數、平均延遲、最大延遲與連續失敗次數，再用多項條件判定節點是否需要退出。

一個容易落地的規則是：每 30 秒測試一次，每個節點發送三次請求；若三次全部失敗，累積一次失敗週期；連續兩個週期失敗才標記為不健康。若目前節點的平均延遲高於 1500 毫秒，且候選節點低於 500 毫秒，也可以觸發切換。不過數值不應照搬到所有網路，應先觀察正常時段的基線，再設定合理門檻。

測試網址最好準備兩個以上，並選擇回應穩定、內容簡單的 HTTPS 端點。不要只測試某一個與業務完全無關、可能隨時變更或限制請求頻率的網站。若你的實際需求是存取特定 API 或企業服務，應在合法合規的前提下加入與業務路徑接近的測試，但要控制請求頻率，不要把健康檢查變成額外負載。

恢復判斷也要設計冷卻時間。節點剛剛恢復一次，不代表已經穩定。可以要求連續三次成功才重新加入候選清單，並在切回後觀察一段時間。對頻繁抖動的節點設定冷卻時間，例如 5 分鐘內不允許再次切換，通常比單純降低延遲門檻更有效。

動手建立自動切換流程

以下流程適合先在測試環境驗證，再放到長時間運作的主機。假設目前選擇器是 proxy-auto，候選節點是 proxy-hk-01、proxy-jp-01 和 proxy-sg-01。實際名稱可以依你的設定調整，但不要在腳本裡混用訂閱顯示名稱與路由標籤。

  1. 建立一份節點清單，為每個節點保存標籤、測試網址、最近成功時間、失敗次數和冷卻截止時間。
  2. 由健康檢查程序逐一測試候選節點，收集 TCP 連線、TLS 握手、HTTP 回應與總耗時等資料。
  3. 將測試結果與門檻比較，先排除連續失敗或仍在冷卻期的節點，再按照穩定性和延遲排序。
  4. 讀取目前選擇器狀態。若目前節點仍健康，且新候選只快一點點，不要急著切換，以免產生頻繁抖動。
  5. 只有在目前節點不健康，或候選節點明顯優於目前節點時，才呼叫 API 更新選擇器。
  6. 切換成功後記錄時間、舊節點、新節點、觸發原因和測試摘要，並為新節點啟動觀察期。
  7. 若所有候選節點都失敗，保留目前設定並發出告警，不要在沒有可用目標時將選擇器寫成空值。

在 JSON 設定中，節點、API 入站和路由規則應各自保持清晰。概念上可以使用 api 入站提供本機管理介面，使用 proxy-auto 作為路由目標，再由控制程式透過 gRPC 呼叫選擇器服務。完整欄位名稱會依你採用的 Xray 版本和服務模型而不同，因此不要直接把網路上針對舊版核心的範例原封不動貼進正式環境；先用目前版本的設定檢查功能驗證 JSON，再啟動服務。

如果你使用腳本語言實作，建議把「測試節點」和「執行切換」寫成兩個獨立函式。前者只回傳結構化結果，例如成功與否、耗時和錯誤類型；後者只接受經過排序和門檻判斷的節點標籤。這種分離可以避免一次測試失敗就直接改寫生產設定，也方便日後將測試結果送到 Prometheus、Zabbix 或其他監控平台。

切換安全性與容錯處理

自動化最怕的不是「沒有切換」，而是「錯誤切換」。腳本啟動時應先取得目前狀態，確認 API 回應正常、選擇器存在、候選節點標籤都能在本機設定中找到。若發現設定版本不一致，應停止變更並發出告警，而不是嘗試自行建立未知出站。

每次切換都應加入鎖定機制。當上一個檢查週期尚未完成時，下一個週期不能再次寫入；API 呼叫逾時後也不能立刻並行發起大量重試。可以設定單次呼叫的逾時時間、最大重試次數和指數退避，並在每次重試之間保留短暫間隔。這些細節能避免 API 暫時變慢時，腳本反而把核心壓垮。

日誌至少要包含事件時間、目前節點、候選節點、測試結果、切換原因、API 回應和執行程序版本。不要在日誌中記錄 UUID、私鑰、訂閱完整網址或其他敏感資訊。若需要把事件送到集中式監控平台，先對節點名稱與錯誤資訊做適當遮罩。

還要考慮核心重啟、主機斷電和腳本升級後的狀態恢復。失敗計數可以保存於簡單的本機資料檔，但檔案寫入要採用暫存檔加重新命名，避免程序中斷後留下半份 JSON。啟動時若找不到狀態檔，應採取保守的初始狀態，先完成幾輪健康檢查，再決定是否切換。

常見問題與排查方向

為什麼 API 連得上，但節點沒有切換？ 先確認腳本呼叫的服務類型與目前 Xray 版本相符，再確認選擇器名稱、候選節點標籤和路由實際使用的標籤完全一致。很多「切換無效」不是 API 沒有動作，而是流量根本沒有經過腳本正在控制的出站。

健康檢查成功，實際應用程式卻仍然無法連線，原因是什麼？ 測試網址成功只能證明某條測試路徑可用，不能代表所有網域、DNS 查詢和傳輸協定都正常。應檢查應用程式是否遵循系統代理、路由規則是否命中、DNS 是否走了預期的出站，以及是否有 TUN、VPN 或其他代理工具造成衝突。

節點為什麼在兩個選項之間反覆跳轉？ 通常是門檻太敏感、測試樣本太少或沒有冷卻時間。增加連續成功與連續失敗的要求，加入最小切換間隔，並設定「改善幅度」門檻，通常可以有效抑制抖動。節點只快幾十毫秒時，沒有必要為了理論上的最佳值中斷現有連線。

是否應該每次切換都重啟 Xray？ 一般不建議。若 API 已能修改選擇器狀態，重啟只會增加中斷時間和設定損壞風險。只有在設定結構變更、API 無法完成必要操作，或核心本身出現無法恢復的錯誤時，才應把重啟納入受控的故障處理流程，而且要先備份設定並限制重啟次數。

維運建議與總結

Xray API 節點自動切換的核心，不是寫一支會呼叫 API 的腳本，而是建立一套可觀察、可回復、可限制風險的流程。先用固定標籤整理節點，再讓路由統一指向選擇器；接著以多次測試、連續失敗、冷卻時間和恢復確認降低誤判，最後用日誌和告警把每次決策留下來。這樣即使自動切換沒有解決問題，也能快速知道問題發生在測試、路由、API 還是上游節點。

建議先在一台測試主機上只放兩個候選節點，手動模擬逾時、拒絕連線和 API 不可用等情況，確認腳本不會清空選擇器、不會無限重試，也不會因單次失敗就切換。驗證完成後，再逐步增加節點數量和監控指標。若你主要使用 v2rayN，還要確認桌面端的系統代理或 TUN 模式確實把流量送進 Xray；Android 上的 v2rayNG 和 v2flyNG 則要另外檢查 VPN 權限與分應用規則。

最後，請把設定檔、腳本、版本資訊和回復步驟納入同一套維運文件。任何自動化控制都應保留手動接管方式，例如暫停排程、固定到已知可用節點，或回復上一個設定版本。自動化的價值不是完全取代人工，而是在故障發生時先完成一致、可追蹤的處置，讓管理員有時間處理真正需要判斷的問題。