Xray APIで実現するノード自動選択とJSON設定の実践ガイド

Xray APIで自動選択を実現する仕組み

XrayのAPIは、ノードの状態を確認したり、統計情報を取得したり、実行中のインバウンドやアウトバウンドを操作したりするための管理インターフェースです。APIを設定しただけで、すべてのノードから最速の接続先が自動的に選ばれるわけではありません。実際の自動選択では、Xrayが通信を処理し、別のスクリプトまたは監視プロセスがAPIから情報を取得し、判定結果に応じて利用ノードを変更するという3つの役割を組み合わせます。

遅延を測定する方法は大きく2種類あります。1つ目は、Xrayの observatory または burstObservatory を利用して、設定したプロキシグループの状態をXray自身に検査させる方法です。2つ目は、管理スクリプトから各ノードへHTTPリクエストを送り、実際の応答時間、接続成功率、直近の失敗回数を記録する方法です。APIのStatsServiceが返すアップロード量・ダウンロード量は通信の利用状況を示す値であり、ネットワーク遅延そのものではありません。この違いを理解しないまま、転送量だけで最速ノードを判断しないことが重要です。

自動選択で最も大きな問題は、短時間の一時的な遅延だけでノードを頻繁に切り替えるフラッピングです。たとえばAノードが1回だけ120msになり、次の測定で60msへ戻った場合、即座にBへ変更すると接続中の通信が切れる可能性があります。そのため、最低スコアのノードを選ぶだけでなく、連続して2回以上悪化した場合だけ切り替える、現在のノードより一定割合以上改善した場合だけ変更する、といった安定化条件を入れます。

最小構成のJSON設定を作る

まずAPIを外部ネットワークへ公開しない構成から始めます。API用のインバウンドは 127.0.0.1:10085 で待ち受け、APIタグを持つ通信だけをXray内部の api アウトバウンドへ送ります。管理プロセスが同じサーバー上で動くなら、LANアドレスや 0.0.0.0 で待ち受ける必要はありません。APIポートを外部公開すると、設定変更や統計情報の取得を第三者に許す危険があります。

{
  "log": {
    "loglevel": "info"
  },
  "api": {
    "tag": "api",
    "services": [
      "HandlerService",
      "StatsService",
      "RoutingService"
    ]
  },
  "inbounds": [
    {
      "tag": "api-in",
      "listen": "127.0.0.1",
      "port": 10085,
      "protocol": "dokodemo-door",
      "settings": {
        "address": "127.0.0.1"
      },
      "streamSettings": {
        "network": "tcp"
      }
    }
  ],
  "routing": {
    "rules": [
      {
        "type": "field",
        "inboundTag": [
          "api-in"
        ],
        "outboundTag": "api"
      }
    ],
    "balancers": [
      {
        "tag": "auto-proxy",
        "selector": [
          "proxy-"
        ]
      }
    ]
  },
  "stats": {},
  "policy": {
    "levels": {
      "0": {
        "statsUserUplink": true,
        "statsUserDownlink": true
      }
    },
    "system": {
      "statsInboundUplink": true,
      "statsInboundDownlink": true,
      "statsOutboundUplink": true,
      "statsOutboundDownlink": true
    }
  }
}

この例では、api タグのアウトバウンド本体と、実際に利用する proxy-asia、proxy-eu などのアウトバウンド定義を省略しています。実運用では、サブスクリプションから生成した各ノードを個別のタグに割り当て、タグの先頭を proxy- に統一します。タグ名はJSON内で一文字でも異なると一致しないため、ハイフン、大文字、小文字を含めて統一してください。

RoutingService を有効にする場合は、XrayのバージョンとAPIクライアントが対応していることを確認します。不要なら最初は HandlerService と StatsService だけに絞り、読み取りと簡単な管理操作から検証するほうが安全です。設定変更後は xray -test -config config.json 相当の構文チェックを実行し、JSONの末尾カンマ、重複タグ、存在しないサービス名を確認してから再起動します。

遅延を測定し、ノードのスコアを計算する

StatsServiceから取得できる値は、アウトバウンドごとのアップロード量とダウンロード量、ユーザー単位の統計値です。値が増えていることは、そのノードが通信に使われたことを示しますが、応答速度が良いことを意味しません。遅延ランキングを作る場合は、StatsServiceを利用量の確認と異常検知に使い、接続時間は別のプローブで測定します。

候補ノードを比較するときは、同じURL、同じHTTPメソッド、同じタイムアウト、同じ測定回数を使います。たとえば各ノードに対して10秒のタイムアウトで3回測定し、最小値ではなく中央値を採用します。1回目だけDNSキャッシュの影響を受ける場合があるため、測定結果をそのまま平均するより、中央値と失敗回数を組み合わせるほうが安定します。

スコアの計算例は、遅延を基準化して latencyScore = min(100, medianMs / 5)、成功率を failureScore = (1 - successRate) * 100 とし、次のように減点する方法です。数値は環境ごとに調整してください。

totalScore =
  latencyScore * 0.50 +
  failureScore * 0.30 +
  usagePenalty * 0.10 +
  consecutiveFailurePenalty * 0.10

切り替え条件：
現在のスコア - 新候補のスコア >= 15
かつ新候補の測定成功回数 >= 2
かつ前回の切り替えから30秒以上経過

APIを使った切り替え処理を実装する手順

動作確認では、いきなり全ノードを自動変更しないでください。まずAPIへ接続できること、StatsServiceから数値を取得できること、測定スクリプトが候補ごとに結果を保存できることを順番に確認します。切り替え処理は最後に有効化し、最初の数時間はログだけを出すドライランにします。

1. APIを構文検査

   設定ファイルを保存し、XrayのテストモードでJSONを検査します。APIインバウンド、APIタグ、ルーティングの3つが同時に存在することを確認します。

2. 統計取得を確認

   同じサーバー上で xray api statsquery --server=127.0.0.1:10085 --pattern= を実行し、応答が返るか確認します。転送が発生していない場合に値が0でも、API接続成功とは分けて記録します。

3. 候補を測定

   proxy- で始まるアウトバウンドを候補として読み込み、同一URLへ3回ずつプローブします。結果には時刻、タグ、応答時間、成功または失敗、エラー内容を保存します。

4. ドライランする

   最良候補を表示するだけにし、実際の切り替えAPIは呼び出しません。30秒間隔で10回以上実行し、スコアの変動と候補の入れ替わりを確認します。

5. 変更条件を有効化

   改善幅15点、成功測定2回、クールダウン30秒などの条件を満たした場合だけ切り替えます。切り替え前後のタグと理由を必ずログへ出力します。

6. 復旧経路を残す

   API操作に失敗した場合は現在のノードを維持し、すべての候補を無効にしない設計にします。固定ノードへ戻すコマンドと、最後に正常だった設定のバックアップを用意します。

切り替え方法は、使用するXrayのAPI機能と構成によって異なります。既存のバランサーや観測機能を利用する場合は、その機能が参照するタグとセレクターを変更します。アウトバウンドを動的に追加・削除する方法では、HandlerServiceの対象メソッド、認証経路、設定の永続化方法を事前に確認してください。実行中のメモリ上の設定を変更しても、Xrayを再起動した際に元のJSONへ戻ることがあります。

ドライランのログ例：
2026-08-29T10:00:00Z candidate=proxy-asia median=62ms success=10/10 score=18
2026-08-29T10:00:00Z candidate=proxy-eu median=48ms success=8/10 score=34
2026-08-29T10:00:00Z current=proxy-asia best=proxy-asia action=keep reason=improvement<15

切り替えを許可する例：
2026-08-29T10:01:00Z current=proxy-asia best=proxy-eu
2026-08-29T10:01:00Z action=switch reason=score_gap=21 cooldown=expired

ノード切り替え時に既存のTCP接続が新しいノードへ移動するわけではありません。すでに確立した接続は旧アウトバウンドに残り、新しく作られた接続から新しい候補が使われる構成もあります。ブラウザーの複数接続、長時間のダウンロード、WebSocketなどでは、切り替え直後も旧経路が残っているように見えることがあります。判定ログだけでなく、新規接続を使った実通信で結果を確認してください。

運用時の安全対策とトラブル対処

API自動化は便利ですが、誤判定を短時間に繰り返すと、ノードの切り替え自体が障害になります。監視スクリプトが停止した場合は現在のノードをそのまま維持し、判定結果が空の場合も全ノードを無効にしないでください。API応答が遅い、測定URLが一時的にエラーを返す、DNSだけが失敗するといったケースを、ノード全体の障害と同一視しないことが大切です。

導入前に確認するチェックリスト

完成した構成では、Xray本体がプロキシ通信を担当し、APIが管理情報を返し、測定スクリプトが候補の状態を比較し、切り替え処理が十分な差がある場合だけ経路を変更します。この役割分担を崩さなければ、Xrayの設定を大きく書き換えずに自動選択を段階的に導入できます。

• APIの待受が 127.0.0.1:10085 などのローカルアドレスに限定されている。
• api-in から api へのルーティング規則があり、タグの表記が完全に一致している。
• StatsServiceが取得でき、StatsServiceの値を遅延値と誤認していない。
• 候補ノードごとに同じURL、同じタイムアウト、同じ回数で測定している。
• 連続失敗、最低成功回数、改善幅、クールダウンの条件が設定されている。
• ドライランで判定を確認し、切り替え前後のタグと理由をログへ残している。
• API変更が再起動後も必要な場合、元のJSONと起動時処理を同期している。
• 候補がすべて失敗した場合に、固定のフォールバックノードを残している。

Xray APIによるノード自動選択は、「APIを有効にして最小遅延のノードへ自動接続する」単純な機能ではありません。統計情報、実測遅延、成功率、切り替え条件、復旧経路を個別に設計し、まず観測、次に評価、最後に変更という順番で有効化することで、予期しない接続断や頻繁なノード変更を避けられます。