Xray APIでノード自動切替：実運用向け高度設定ガイド

Xray APIで自動切替を行う理由

Xray のノードを手動で切り替える運用は、少数の端末や短時間の利用なら十分です。しかし、常時稼働するサーバー、複数の出口を持つ検証環境、あるいは回線品質が時間帯で変わる環境では、手作業だけで安定性を保つのは難しくなります。接続が遅くなったときに管理者が画面を開き、ノードを選び直すまでの数分間も、アプリケーションから見れば障害時間です。

Xray APIを使うと、稼働中の Xray プロセスに対して、統計情報の取得、プロキシグループの選択、ルーティング状態の確認などを外部プログラムから実行できます。重要なのは、APIがノードそのものを作り出す仕組みではなく、現在読み込まれている設定と稼働状態を操作する管理インターフェースだという点です。したがって、最初に有効なノードを設定ファイルへ登録し、そのうえで監視と切替のロジックを組み立てます。

実運用では「速いノードを毎秒探して即座に切り替える」設計は避けた方がよいでしょう。短い瞬断や一時的な遅延で切替が連続すると、接続が安定する前に別ノードへ移動するフラッピングが起こります。監視間隔、失敗回数、クールダウン時間、復旧判定を決め、切替を制御された状態機械として扱うことが安定運用の基本です。

自動切替に必要な設定要素

まず、API用のインバウンドを設定します。Xray の設定では、APIを受け付ける内部ポートと、APIへ接続するための管理用サービスを分けて考えます。既存のプロキシ受け付けポートと同じ番号を使うのではなく、ローカルホストからだけ利用できる専用ポートを割り当てるのが安全です。たとえば API の待受を 127.0.0.1:10085 に限定すれば、外部ネットワークから直接管理ポートへ到達できません。

次に、切替対象を明確にします。複数のノードを outbounds に登録し、利用者が選ぶ出口をひとつのタグで識別します。自動選択を行う場合は、選択対象のタグを固定し、各ノードには重複しない tag を付けます。タグ名を表示名と兼用すると、後から名称を変更したときにスクリプトが壊れやすいため、node-jp-01 や node-us-02 のような機械的で安定した識別子を使うとよいでしょう。

APIの有効化だけで自動切替が完成するわけではありません。統計を取得するための設定、APIサービスの登録、ルーティングでどのトラフィックを対象にするかも確認が必要です。設定を変更したら、いきなり本番へ反映せず、まず設定ファイルの構文を検証し、Xrayを再起動した後にローカルAPIへ接続できるかを確認します。ポートが開いているだけでなく、期待するサービスが応答していることまで確認してください。

API待受は外部公開せず、原則として 127.0.0.1 に限定する
ノードのタグは重複させず、表示名と内部識別子を分ける
監視用の出口と通常利用の出口を、ルーティング上でも区別する
設定変更前にバックアップを取り、失敗時に元へ戻せるようにする

監視指標と切替判定を設計する

ノード監視では、単純な「応答したかどうか」だけでは情報が足りません。TCP接続が成功しても、DNS解決、TLSハンドシェイク、実際のHTTP応答のどこかで止まることがあります。逆に、一度だけタイムアウトしたからといってノード全体を無効と判断するのも危険です。監視は複数段階に分け、異常の種類を記録できるようにします。

最低限の指標として、接続成功率、応答時間、連続失敗回数、直近の切替時刻を持たせます。たとえば30秒ごとに検査し、5回中3回以上失敗した場合に候補から外す、平均応答時間が一定値を超えた状態が数分続いた場合だけ切り替える、といった条件です。しきい値は回線や用途によって異なるため、最初から厳しく設定せず、通常時の値を数時間から数日観測してから決めます。

監視先も一つに固定しない方がよいでしょう。特定ドメインだけが一時的に遅い場合、そのドメインの障害をノード障害と誤認する可能性があります。自分が管理する軽量なHTTPSエンドポイント、複数の安定した宛先、そして必要ならDNS解決の確認を組み合わせます。ただし、短時間に大量のリクエストを送ると監視自体が負荷になるため、間隔とタイムアウトを適切に設定します。

切替後は、すぐに元のノードを候補へ戻さないことが重要です。切替先で一定時間の成功を確認し、障害ノードにはクールダウン期間を設けます。クールダウン終了後に少数回の試験を行い、すべて成功した場合のみ候補へ復帰させる方式なら、断続的な障害による往復切替を抑えられます。

APIを使った動作確認の手順

ここからは、スクリプトを書く前に確認すべき順番です。実際のAPIメソッド名や利用可能なサービスは、使用している Xray-core のバージョンと設定に左右されます。ドキュメントの例をそのまま貼り付けるのではなく、自分のバージョンで公開されているサービス名とメッセージ形式を確認してください。

現在の設定ファイルを別名で保存し、元に戻せるバックアップを作成する
APIの待受アドレスが 127.0.0.1 になっていることを確認する
Xrayを再起動し、ログに設定エラーやポート競合がないことを確認する
ローカルからAPIへ接続し、利用可能なサービスが応答することを確認する
まず読み取り操作だけを行い、統計や現在の選択状態を取得する
テスト用のノードグループで手動切替を実行し、通信が継続するか確認する
最後に監視、失敗判定、切替、復旧判定を小さなスクリプトへ分けて実装する

検証中は、ブラウザでページを開けたという結果だけで判断しないでください。Xrayのログ、スクリプトの標準出力、切替前後の応答時間を同じ時刻で記録すると、問題の所在が見えやすくなります。API接続は成功しているのに通信が変わらない場合は、切替対象のタグと実際にルーティングされている出口が一致しているかを確認します。別のルールが先に適用されていれば、API操作が成功しても利用中の通信には影響しません。

スクリプト化するときの実運用設計

自動切替スクリプトは、一つの長い処理にせず、監視、評価、切替、記録の四つに分けると保守しやすくなります。監視部分は対象ノードごとに結果を返し、評価部分は成功率や遅延から候補順位を計算します。切替部分は現在のノードと次のノードが同じなら何もしないようにし、必要な場合だけAPIの変更操作を呼び出します。記録部分には時刻、対象ノード、判定理由、APIの結果を残します。

候補順位を決めるときは、応答時間だけを使わない方が安全です。低遅延でも失敗率が高いノードは、平均値だけを見ると優秀に見えることがあります。たとえば「成功率を最優先し、同じ水準なら遅延を比較する」という二段階評価にすると、極端に不安定なノードを選びにくくなります。業務通信と動画視聴など用途が異なる場合は、用途別に候補グループを用意し、すべての通信を一つの基準で評価しないことも有効です。

多重起動への対策も必須です。cron、systemd timer、タスクスケジューラ、コンテナの再起動などが重なると、二つのスクリプトが同時にノードを変更する可能性があります。ロックファイル、プロセスロック、または単一の常駐プロセスを使い、同時実行を防いでください。APIの応答が遅いときにタイムアウトせず待ち続ける設計も危険です。API呼び出しには明確なタイムアウトを設け、失敗時は現在のノードを維持する方が、無効な値へ切り替えるより安全です。

ログにはサブスクリプションの内容や認証情報を出力しないでください。ノードの共有リンク、UUID、パスワード、秘密鍵、APIの認証情報がログへ残ると、ログを閲覧できるユーザーが通信設定を再利用できてしまいます。監視ログは必要な情報だけを残し、保存期間とアクセス権限も決めます。外部APIへ管理機能を公開する設計は、どうしても必要な場合を除いて避け、リモート管理が必要ならVPNや安全なトンネルなど別の認証境界を設けます。

障害時の復旧とロールバック

自動切替は、切り替える機能よりも、切替に失敗したときの振る舞いが重要です。候補ノードがすべて失敗した場合、無効なノードを繰り返し選ばず、最後に成功したノードを保持する、または明示的な停止状態にするなど、フェイルセーフの方針を決めます。管理者が状況を把握できるよう、一定回数以上の全滅が続いたらログへ警告を出し、必要に応じて通知を送ります。

APIが停止している場合と、プロキシ通信だけが停止している場合も分けて扱います。API接続失敗を理由にXray全体を再起動すると、正常な通信まで切断する可能性があります。まずAPIのポート、Xrayプロセス、設定ファイルの状態を確認し、再起動は明確な条件を満たした場合だけに限定します。設定ファイルを直接書き換えて再起動する方式を採用するなら、一時ファイルへ書き出して構文検証を行い、検証成功後に置き換える手順にしてください。

ロールバック用の設定は、現在の設定と同じ場所に上書きせず、世代管理できる形で保存します。変更前のファイル、変更時刻、変更理由を残しておけば、切替スクリプトの不具合を追跡できます。自動化の導入直後は、切替操作を実行せず「切り替えるならどのノードか」だけをログに出すドライラン期間を設けると安心です。判定結果が期待どおりになってから、実際のAPI変更を有効にします。

よくある質問

APIポートをインターネットへ公開してもよいですか？
原則として避けてください。APIは管理操作を受け付けるため、通常のプロキシポートよりも慎重な保護が必要です。ローカルホスト限定を基本とし、外部から操作する場合も、ファイアウォール、認証、暗号化された管理経路を組み合わせます。

応答時間が最も短いノードへ毎回切り替えるべきですか？
おすすめしません。一回の測定値は揺れます。成功率、複数回の平均値、連続失敗、クールダウン期間を組み合わせ、一定時間安定した候補だけを選ぶ方が実用的です。

APIで切り替えたのに通信先が変わりません。なぜですか？
切替対象のタグが実際のルーティングで使われていない、別のルールが先に適用されている、既存接続が維持されている、といった原因があります。ログとルーティング設定を確認し、新規接続で前後を比較してください。

v2rayNからも同じ運用ができますか？
v2rayNはデスクトップ向けの管理画面として便利ですが、内部コアのAPI公開や設定項目は導入方法とバージョンによって異なります。まず Xray-core 単体でAPI操作を検証し、その後に v2rayN の管理方法へ合わせると、クライアント画面とコア設定の混同を減らせます。

Xray APIによるノード自動切替は、APIを呼び出すだけの小技ではありません。安全な待受、安定したタグ設計、複数回の監視、フラッピング防止、同時実行制御、障害時の保持とロールバックを一つの運用設計として考える必要があります。小さな検証環境で読み取りと手動切替から始め、ドライラン、限定的な自動化、監視付きの本番運用という順に段階を踏めば、設定ミスによる停止を抑えながら実用的な仕組みへ育てられます。