VMess・VLESS・Trojan・Shadowsocksの違いと選び方｜用途別プロキシプロトコル比較

gRPC APIでできることと、設定ファイルとの違い

XrayのAPIは、コアの起動後に管理機能を呼び出すためのgRPCインターフェースです。通常の利用ではJSON設定を読み込んでコアを起動し、その後の接続先変更には設定ファイルを書き換えて再起動する方法が使われます。APIを有効にすると、対応するサービスを通じて稼働中のコアへ操作を依頼でき、プロセス全体を再起動せずにoutboundを追加・削除したり、統計値を問い合わせたりできます。

ここでいう「動的」は、実行中のプロセスに対する変更です。API経由で追加したoutboundが元のJSONファイルに自動保存されるわけではありません。コアを再起動すると、起動時に読み込む設定に存在しないoutboundは失われます。そのため、管理側では「現在の実行状態」と「次回起動時の設定」を分けて管理してください。変更内容を永続化したい場合は、検証済みの構成を設定ファイルや構成管理システムにも反映します。

APIはサーバー管理機能なので、v2rayNやv2rayNGでノードを選ぶ一般的な操作とは役割が異なります。クライアントの画面にノードが表示されることと、XrayのAPIにoutboundが登録されることは同じではありません。自動化する前に、対象がXrayコアであること、実際に使うコアのバージョンが必要なAPIサービスを提供することを確認しましょう。

API用inboundとサービスを設定する

XrayのAPI通信自体もinbound経由でコアに入ります。管理用inboundはループバックアドレスにバインドし、API用のタグを付けます。さらに、routingルールでそのinboundから入った通信をAPI outboundへ送る構成にします。次の例は設定の要点を示すJSON断片です。既存設定に統合するときは、同名キーを二重に作らず、それぞれの配列やオブジェクトへ必要な項目を追加してください。

{
  "inbounds": [
    {
      "tag": "api",
      "listen": "127.0.0.1",
      "port": 10085,
      "protocol": " dokodemo-door",
      "settings": {
        "address": "127.0.0.1"
      }
    }
  ],
  "api": {
    "tag": "api",
    "services": [
      "HandlerService",
      "StatsService"
    ]
  },
  "routing": {
    "rules": [
      {
        "type": "field",
        "inboundTag": ["api"],
        "outboundTag": "api"
      }
    ]
  }
}

上の断片を実際の設定へ転記する際、protocolの値はdokodemo-doorです。コード例中の値に誤記が混じらないよう、読み込み前に確認してください。設定全体を検証する場合は、利用中のXray実行ファイルで設定テストを行い、エラーがないことを確かめてからサービスを再起動します。API inboundのポートを他のサービスが使っていないことも確認してください。

統計を取得するには、トップレベルに空のstatsオブジェクトを置き、policy.systemで対象の統計を有効にします。outboundごとの上り・下りを記録する代表的な指定は次のとおりです。統計ポリシーは利用する設定形式やコアのバージョンに合わせて統合してください。

{
  "stats": {},
  "policy": {
    "system": {
      "statsOutboundUplink": true,
      "statsOutboundDownlink": true
    }
  }
}

HandlerServiceはハンドラー操作、StatsServiceは統計の問い合わせに関係します。APIのサービスを追加しただけでは、通信量のカウンターが必ず記録されるとは限りません。サービスの有効化、統計ポリシー、実際に通信が通るoutboundの三点をそろえてください。管理用ポートを外部ネットワークへ公開すると、意図しない設定変更や情報取得につながるおそれがあります。ローカル利用を基本にし、リモート管理が必要なら、到達範囲を制限した安全な管理経路を別途用意します。

• 待受：127.0.0.1:10085のようにループバックへ限定し、不要な外部接続を受け付けない。
• ルーティング：API用inboundのタグとAPI outboundへのルールが一致しているか確認する。
• 統計：statsOutboundUplinkとstatsOutboundDownlinkを有効にし、統計対象となる通信を発生させる。
• 設定検証：再起動前にJSONの構文とコアの設定読み込み結果を確認する。

outboundを追加・削除する仕組み

動的な追加には、Xray APIのHandlerServiceが提供するAddOutboundを使います。APIクライアントは追加したいoutboundの型と設定を、Xrayが受け取るprotobuf形式のメッセージとして送信します。JSONで書いたoutbound断片を、gRPCへそのままHTTP本文として投げればよいという意味ではありません。使用する言語の生成済みprotobuf型や、対応するJSON変換手段を介して、APIが要求するメッセージを構成します。

たとえば、追加するoutboundの設定断片は次のような形です。これは構成のイメージであり、単独で動作する完全なクライアント設定でも、APIに直接送れるリクエスト本文でもありません。実環境ではプロトコルに必要なサーバー情報、認証情報、ポート、TLSやREALITYなどの通信設定を正しく指定し、送信時には使用中のXray APIスキーマに合う型へ変換します。

{
  "tag": "pool-a",
  "protocol": "freedom",
  "settings": {}
}

削除時はHandlerServiceのRemoveOutboundを呼び、追加時に付けたタグを指定します。タグは設定内で一意にし、削除対象の確認にも使える安定した名前を選んでください。タグが重複すると、ルーティングルールや統計名を見たときに意図した接続先を判断しにくくなります。すでにそのoutboundを使う通信がある場合の扱いも、API呼び出しだけで期待どおりになると決めつけず、テスト環境で接続中の通信への影響を確認してください。

動作確認をしながら追加と統計取得を試す

以下はローカルで管理するXrayを対象にした手順です。APIの仕様や生成されるprotobuf型は、コアのバージョンと利用する言語のAPIバインディングに左右されます。サンプルコードをそのまま本番へ投入するのではなく、まずテスト用のコアと、外部から到達できない管理ポートで確認してください。APIクライアントにはタイムアウトを設け、追加・削除の結果をログに残します。

1. 設定を検証する

   API inbound、api.services、inboundタグのroutingルール、outbound統計ポリシーを確認します。JSONの構文だけでなく、利用するXrayコアが設定を読み込めることをテストしてから起動します。

2. 待受を確認する

   コアの起動ログとOSの待受状態を確認し、APIが127.0.0.1:10085だけで待ち受けていることを確かめます。接続先をローカルのAPIアドレスに限定し、ルーターやファイアウォールで外部へポート転送しないでください。

3. テストoutboundを追加

   一意なタグを付けた最小構成のoutboundを準備し、HandlerService.AddOutbound用のprotobufリクエストへ変換して送信します。応答が成功したことを確認し、必要ならテスト用routingルールからそのタグへ通信を送ります。

4. 統計を問い合わせる

   StatsServiceのQueryStatsを利用し、対象タグの統計名を指定して問い合わせます。一般にoutbound統計名はoutbound>>>タグ>>>traffic>>>uplinkまたはdownlinkの形式です。タグに応じて対象名を組み立て、返却された値を確認します。

5. 削除と再起動を試す

   テスト通信を止めてからRemoveOutboundでタグを指定し、削除後に同じ統計やルーティングがどう変わるか確認します。その後コアを再起動し、APIで追加しただけのoutboundが消えること、永続化した設定がある場合は想定どおり復元されることを確認します。

通信量は累積値として扱い、必要に応じて一定間隔で取得して差分を計算します。取得間隔を短くし過ぎるとAPI呼び出しとログが増える一方、間隔を長くすると瞬間的な状況を把握しにくくなります。監視用途なら、たとえば数十秒から数分程度の間隔で始め、対象数や負荷に応じて調整します。カウンターをリセットする機能を使う場合は、集計側で差分を取る方式と混在させないようにしてください。

通信量統計の読み方と運用上の注意

統計APIが返す数値は、コアが観測した通信カウンターです。outboundの上り・下りは、それぞれのoutboundを通過するデータ量の指標として利用できますが、通信経路上のすべての装置で測った値と一致するとは限りません。アプリケーションのデータ、プロトコルのヘッダー、再送、暗号化などの扱いが計測点によって異なるため、請求用の正確な転送量と同じ意味だと見なさないでください。

よくある統計名は、対象outboundのタグを含みます。たとえばpool-aの上りであれば、outbound>>>pool-a>>>traffic>>>uplinkを問い合わせる形です。タグを変更した場合、以前の統計名を監視し続けると値が見つからなくなります。自動化側でタグ一覧を管理し、問い合わせ対象が存在しない場合と、値がゼロの場合を区別して記録してください。

APIサーバーに認証があると考えて、管理ポートをインターネットへ公開してはいけません。ローカル待受に限定し、プロセス権限も必要最小限にします。リモートから操作する場合は、管理ネットワークやトンネルなどを利用して接続元を絞り、通信経路を保護してください。APIリクエストやログにノードの認証情報を含める場合は、保存先と閲覧権限にも注意が必要です。

よくある質問