mihomo 上級設定

プロキシグループの種類と使い方

ルールの宛先と実際の出口を区別する

ルールは接続の振り分け先を決め、プロキシグループはその宛先から実際に使う出口を選びます。ルールに記述する名前は、プロキシ、プロキシグループ、内蔵ポリシーのいずれかと完全に一致させてください。大文字・小文字やスペースも名前の一部です。まず変更の少ないグループ名を決め、サブスクリプションの更新ではグループ内のメンバーだけが変わる構成にするとよいでしょう。プロキシの構成が変わってもルールは同じグループを参照でき、すべてのルールを書き換える必要がありません。

selectは出口を手動で選ぶ場合に適しています。メンバーが一時的に使えなくなっても、自動で別のメンバーに切り替わることはありません。クライアントのパネルで選んだ内容は通常保存できますが、保持されるかどうかは設定名やクライアントの実装にもよります。トラブル時はグループ名だけでなく、展開して実際のプロキシと選択中のメンバーを確認し、新しい接続で使われているポリシーの全経路を調べてください。既存の長時間接続は、すぐには切り替わらないことがあります。

接続先に応じて自動選択する

url-testは、接続テストの結果に基づいてメンバーを選択します。出口が変わっても問題のない通信に適しています。測定結果は指定したURLへの接続状況を示すもので、すべてのサイトやプロトコルでの使い勝手を保証するものではありません。テスト先への接続が良好でも、特定のサービスでは制限されることがあります。toleranceを設定すると小さな差による頻繁な切り替えを抑えられますが、出口を固定できるわけではありません。セッションを維持したいサービスには、専用の手動選択グループを使ってください。

fallbackはメンバーの順序を重視し、ヘルスチェックで利用可能と判定されたメンバーのうち、先頭の出口を優先します。応答時間の最小化ではなく、メインと予備の優先順位を明確にしたい場合に適しています。load-balanceは複数のメンバーに接続を振り分ける機能です。1つのダウンロード接続で複数の出口の帯域を合算するものではありません。ログイン、決済、接続元IPに制約のあるサービスには、安易に切り替え方式を適用しないでください。

手動選択と自動テストを2層に分ける

実用的な構成は、外側に手動選択グループ、内側に自動選択グループを置く方法です。外側には自動選択、固定プロキシ、DIRECTなどの入口を用意し、内側にはテスト対象のプロキシだけを入れます。外側のグループを内側に戻すと循環参照になるため避けてください。階層を増やしすぎず、ルールの宛先から2～3段階で実際の出口を確認できる構成にすると、追跡や保守が容易です。

以下の例では、内蔵のDIRECTのみを参照しています。グループ間の参照を理解するためのもので、リモートのプロキシ出口が設定済みという意味ではありません。実際に使う場合は、自動選択グループのメンバーに、現在の設定に存在するプロキシ名を追加し、必要に応じてDIRECTの選択肢を残すか削除してください。テスト先にはHTTPSを指定し、テスト間隔の単位は秒です。テスト先自体に接続できるかどうかも、ヘルスチェックの結果に影響します。

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - AUTO
      - DIRECT
  - name: AUTO
    type: url-test
    proxies:
      - DIRECT
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

rules:
  - DOMAIN-SUFFIX,github.com,PROXY
  - MATCH,DIRECT

プロキシがproxy-providersから提供されている場合、プロキシグループのuseでプロバイダーを参照すると、メンバー名を大量にコピーせずに済みます。まずプロバイダーが正常に読み込まれていることを確認し、次にグループに想定したメンバーが含まれているか調べてください。フィルター式は、条件を少しずつ厳しくしていきます。条件が狭すぎると、サブスクリプションの更新に成功してもグループに利用可能なメンバーが残らないことがあります。その場合、テスト設定を調整してもメンバー不足は解消しません。

プロキシグループを検証するときは、まずパネルでグループの種類、候補メンバー、現在の選択を確認し、新しい接続を開始します。ログにテスト成功と表示されても、ヘルスチェックが動作していることを示すだけで、実際のサービスへの接続確認にはなりません。グループを切り替えてもページに変化がない場合は、すべてのネットワークサービスを再起動する前に、対象アプリの既存接続を閉じるか、アプリを再起動して試してください。モードの基本的な違いはプロキシモードの説明をご覧ください。

ルールセットのサブスクリプション管理

ルールは順序、ルールセットは条件を管理する

rulesはルールの適用順を定義し、rule-providersは再利用可能なマッチ条件を定義します。大量のドメインをルールセットに移した場合も、メイン設定のRULE-SETから参照し、マッチ後のポリシーを指定する必要があります。ルールセットを定義しただけでは、通信の振り分けには使われません。通常、ルールは上から順に評価され、最初に一致した項目が適用されます。そのため、ファイルを何個に分けるかよりも、ローカルの例外、用途別ルール、最後のフォールバックの順序が重要です。

まずは、開発サービス、LAN内アドレス、専用の出口が必要なサービスなど、意味の明確なルールセットを少数作るのがおすすめです。分類を網羅しようとして、同じドメインを複数のセットで重複管理しないようにしてください。重複を避けられない場合は、メインルールで優先順位を明確にし、その理由も記録します。例外ルールを追加するときは、「何に一致するか」「どのポリシーに渡すか」「なぜこの位置に置くか」を説明できるようにしてください。説明が曖昧だと、後から削除してよいか判断しにくくなります。

behaviorとファイル内容を一致させる

behavior: domainはドメインの一覧、ipcidrはIPアドレスの範囲、classicalはルールタイプを含む従来形式のルールに使います。これらは自由に置き換えられるラベルではありません。ドメインセットにDOMAIN-SUFFIX形式のルールを記述したり、classical形式のセットにドメイン名だけを書いたりすると、読み込みに失敗したり、想定外のマッチ結果になったりすることがあります。ファイルの形式を確認してからbehaviorを選び、ファイル名だけで判断しないでください。

formatも実際のデータ形式に合わせる必要があります。YAML形式のルールセットでは通常payload配列を使います。テキスト形式は行単位で読み込み、バイナリ形式には専用の生成手順があります。拡張子を変更するだけでは形式を変換できません。同じドメインリストが複数の形式で提供されている場合は、カーネルが明示的に対応している形式を選び、パスの拡張子も実際の内容に合わせてください。ダウンロードURLをブラウザーで開けるかどうかより、読み込みログの解析エラーを確認するほうが確実です。

# メイン設定に統合する。rules の位置は既存のルールに合わせて調整
rule-providers:
  development:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/development.yaml

rules:
  - RULE-SET,development,PROXY
  - MATCH,DIRECT

# カーネルの設定作業ディレクトリに rules/development.yaml として保存
payload:
  - '+.github.com'
  - '+.githubusercontent.com'

ローカルでの検証からリモート更新へ

上の例では、PROXYという名前のポリシーがすでにあることを前提としています。相対パスの基準は通常カーネルの作業ディレクトリであり、エディターで開いているファイルの場所とは限りません。まずローカルファイルでbehaviorとマッチ条件を確認してからリモートサブスクリプションに切り替えると、形式の問題とネットワークの問題を切り分けられます。テストでは、ルールセット内のドメインに新しい接続を行い、同じ出口を使うフォールバックルールではなく、該当のルールセットにマッチしていることを接続詳細で確認してください。

リモートのルールセットではtype: httpを指定し、配布元のURL、キャッシュパス、更新間隔を設定します。URLはメンテナーが実際に提供するものを使い、ルールファイルそのものではなく紹介ページを指定しないでください。更新頻度は配布元の更新ペースに合わせます。数日おきにしか変わらないリストを頻繁に取得すると、リクエストとトラブルシューティングのノイズが増えるだけです。アカウント情報を含むURLはローカル設定にのみ保存し、公開スクリーンショット、共有リポジトリ、問い合わせ本文には載せないでください。

ルールの更新に失敗したら、まずダウンロード、内容の解析、参照のどこで失敗したかを切り分けます。ダウンロードできない場合は、配布元への接続可否とダウンロード時の出口を確認します。解析エラーの場合は、応答がWebページやエラーメッセージ、別形式のデータに変わっていないか確認してください。参照エラーの場合は、プロバイダー名とRULE-SETに指定した名前が一致しているか確認します。キャッシュにより通信が一時的に続いていても、更新が正常とは限りません。最終更新時刻と読み込みログも確認してください。

ドメインルールは、対象アドレスの名前解決が必要な地理・IP範囲のルールより前に配置するのが基本です。追加の名前解決を避けたいアドレスルールでは、構文に従ってno-resolveを指定できますが、すべてのルールに付ける汎用のオプションではありません。実際のIPアドレスを持つ接続はアドレス判定の対象になりますが、ドメイン名しかなく実際の解決結果がない接続では、該当する判定がスキップされることがあります。設定を変更する前に、どの名前解決を省きたいのかを確認してください。

運用時は、検証済みのローカル例外ルールセットを残し、サブスクリプションの内容は外部からの入力として扱い、個人用ルールをすべて置き換える唯一の情報源にしないでください。更新後は、代表的な接続をいくつかテストしてから対象を広げます。誤った振り分けが起きた場合は、マッチしたルールと適用先のポリシーを記録し、セットを修正するか順序を調整するか判断してください。MATCHの出口を別のものに変えると、問題を覆い隠せる一方で、正常だった多くの接続まで変わる可能性があります。

DNS設定の最適化

問い合わせの種類ごとに経路を分ける

DNSを最適化するには、誰が何を問い合わせ、どこからリクエストを送るのかを分けて考えます。アプリはシステムのリゾルバーを使うことも、独自に暗号化DNSを使うこともあります。カーネルはプロキシサーバーのドメイン名も解決する必要があります。すべて同じ上流に問い合わせていても、処理経路が同じとは限りません。トラブル時は、アプリからカーネル、カーネルからDNS上流、カーネルからプロキシサーバーへの経路を整理してから設定を変更すると、起動時の名前解決と通常の名前解決を混同せずに済みます。

default-nameserverは主にDNS上流自身のドメイン名を解決し、暗号化DNSの起点を確保するために使います。nameserverは通常の問い合わせ先となる上流DNSです。proxy-server-nameserverでは、プロキシサーバーのドメイン名を解決するDNSを指定できます。プロキシがまだ起動していない段階での依存関係を解決する際に特に有効です。プロキシのドメイン名を解決するリクエストも同じプロキシを経由しなければならない構成では、循環が発生し、設定の読み込み後も出口を確立できないことがあります。

まず説明しやすい最小限のDNS設定から始める

以下の設定例は、ローカルで待ち受け、Fake-IPを使う基本構成です。通常のUDP上流とHTTPS上流ではネットワーク経路が異なり、前者は通信を暗号化しません。ここでは起動時の名前解決と通常の問い合わせの役割を示しており、すべてのネットワークに適した固定設定ではありません。まず選んだDNSサーバーに現在のネットワークから接続できることを確認してから、暗号化方式、ルーティング、予備の仕組みを検討してください。上流を増やしても、必ず安定するわけではありません。

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query
  fake-ip-filter:
    - '*.lan'
    - '*.local'

DNSを127.0.0.1:1053で待ち受ける設定は、カーネルがローカルのDNSサービスを提供することを示すだけで、システムが自動的にそのサービスを使うわけではありません。通常のシステムDNS設定では任意のポートを指定できないため、クライアントによるDNS制御、TUNによるリダイレクトなど、明確な転送経路が必要です。システムが従来のリゾルバーを使い続けている場合、nameserverを変えても結果に反映されないのは不自然ではありません。まず問い合わせがカーネルに届いていることを確かめてから、上流の応答を比較してください。

ドメインごとにDNSサーバーを選び、フォールバックの追加は慎重に

nameserver-policyでは、ドメインなどの条件に応じてDNSサーバーを指定できます。社内ドメイン、家庭内機器のドメイン、個別の名前解決が必要なサービスなどに適しています。内部ドメインは、内部アドレスを返せるリゾルバーに送信し、パブリックDNSには送らないでください。ドメインポリシーが決めるのは使用するDNSサーバーであり、最終的な接続の出口ではありません。正しいアドレスが得られた後も、接続はルールとプロキシグループを通ります。2つの段階をそれぞれ検証してください。

fallbackは、プライマリDNSがタイムアウトしたときだけ使われる予備のアドレス、と単純に考えることはできません。fallback-filterとともに応答を判定するため、問い合わせが追加されることがあります。現在のネットワークに合わないフィルター条件を設定すると、利用可能な応答が別の不適切な応答に置き換わる可能性があります。どの応答を置き換える必要があるのか説明できる場合にのみ、この設定を追加してください。そうでなければ、信頼できる上流を少数使って基準を作るほうが、原因を特定しやすくなります。

respect-rulesを有効にすると、DNS上流への接続にもルーティングルールを適用できます。その際は、プロキシサーバーの名前解決など、起動時の依存関係も解決してください。まだ利用できないプロキシグループに、すべてのDNSリクエストを無理に向けないでください。テストでは、DNS上流への接続と通常の通信で出口を分けて記録します。出口は異なっていてもよく、異なるほうが適切な場合もあります。この項目とフォールバックDNSの詳しい解説は、DNS設定項目の解説をご覧ください。

暗号化DNSの障害は、症状に応じて切り分けてください。名前解決エラーが出る場合は、まず起動時の名前解決を確認します。アドレスは取得できてもハンドシェイクに失敗する場合は、システム時刻、証明書の信頼性、接続経路を調べます。上流への接続は成功するのに応答が異常な場合は、ドメインポリシーとサービスの応答を確認してください。ネットワークや時刻の問題を隠すために証明書検証を無効にしたり、根拠なく複数の上流を次々に入れ替えたりしないでください。再現可能な問い合わせ対象を記録し、変更する変数は一度に一つにします。

キャッシュの影響で、変更結果がすぐに反映されないことがあります。システム、ブラウザー、カーネルが名前解決結果を保存するほか、アプリが古い接続を再利用する場合もあります。検証前に対象アプリの既存接続を終了し、クライアントが提供する手順で関連キャッシュを消去してから再度問い合わせてください。コマンドラインからローカルのDNS待ち受け先に問い合わせる場合と、ブラウザーでWebページを開く場合では、確認している経路が異なります。結果が一致しない場合は、カーネル設定が無効と判断する前に、ブラウザー独自の名前解決が有効か確認してください。

最後にアドレスファミリーを確認します。DNS応答でIPv6を無効にしても、システム全体のIPv6通信が停止するわけではありません。アプリがキャッシュ済みのアドレスを使ったり、独自に名前解決したりする場合があります。逆にIPv6アドレスを返す設定でも、実際のネットワークに利用可能な経路が必要です。一部のサイトが時間をおいてから開く場合は、IPv4とIPv6の接続結果を分けて確認し、調整するレイヤーを決めてください。DNS設定の目的は、項目をできるだけ埋めることではなく、現在の経路に適した応答を得ることです。

TUNによる通信制御とFake-IPマッピング

Fake-IPはドメインとの対応付けを行う。リモートの出口ではない

Fake-IPモードでは、カーネルがアプリにマッピング用アドレスを返し、そのアドレスとドメインの対応を保存できます。アプリがマッピング用アドレスに接続すると、カーネルがドメインを復元し、ルーティングと出力処理を行います。マッピング用アドレスは接続先サーバーのグローバルIPでも、プロキシサーバーのアドレスでもありません。198.18.0.0/16の範囲が表示されても、ただちに名前解決エラーと判断しないでください。接続がカーネルで処理され、想定したドメインが復元されているかを確認します。

Fake-IPとTUNは異なる機能です。Fake-IPは名前解決とドメインの対応付けを行い、TUNは仮想ネットワークインターフェースで通信を受け取ります。併用されることは多いものの、互いに代替できる機能ではありません。Fake-IPだけを有効にしても、すべてのアプリが自動的にプロキシを経由するわけではありません。TUNだけを有効にしても、各接続のドメイン情報が必ず得られるとは限りません。特定のスイッチを通信制御全体の設定と考えず、名前解決、仮想インターフェース、ルール処理をつないで検証してください。

権限・ルート・名前解決の順にTUNを有効化する

TUNの利用には、管理者権限、サービスコンポーネント、またはシステムの許可が必要になることがあります。Clash Plus、Clash Verge Rev、FlClashなどでは、設定画面や権限の扱いが異なります。まず使用中のクライアントの説明に従い、必要なコンポーネントをインストールしてください。設定ファイルのenable: trueはカーネルへの要求にすぎず、システムがインターフェースの作成やルート追加を拒否すると通信を制御できません。スイッチを何度も押すより、ログでインターフェースとルートの作成結果を確認しましょう。

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
    - tcp://any:53

この設定例は、有効になっているdns設定と組み合わせて使います。auto-routeはカーネルに関連ルートの設定を要求し、auto-detect-interfaceは出力インターフェースの検出を支援します。dns-hijackは対象となる通常のDNS通信をカーネルに渡しますが、HTTPSを使った暗号化DNSをすべて自動的に制御する機能ではありません。アプリ内蔵の暗号化DNSは別途確認してください。実際の対応状況はプラットフォームやネットワークスタックによって異なるため、実行ログと使用中のカーネルのドキュメントを確認してください。

system、gvisor、mixedはネットワークスタックの選択肢であり、性能の順位ではありません。プロトコル処理、システムとの連携、互換性にそれぞれ異なる特徴があります。特定のアプリで問題が起きたら、ほかの設定を維持したままスタックを切り替えて比較できます。ただし、DNS、ルート、MTUを同時に変更しないでください。変更を一つに絞れば、改善がスタックによるものか、ほかの設定によるものか判断できます。

LAN、VPN、マッピングの例外を設定する

プリンター、画面共有機器、社内管理画面など、LAN内の機器には実際のアドレスで直接アクセスする必要があることが多いです。fake-ip-filterを設定しても、対象のドメインにマッピング用アドレスが割り当てられなくなるだけで、接続が自動的にDIRECTになるわけではありません。正しい内部アドレスを返せるDNSを用意し、ルールで適切な出口を指定する必要があります。内部DNSを正しく設定せずフィルターだけ追加すると、マッピング用アドレスは消えても機器にアクセスできないことがあります。

企業VPN、仮想マシン、コンテナー、ほかのプロキシソフトは、ルートを追加することがあります。併用する前に各ネットワークの範囲を記録し、特にFake-IPのアドレス範囲と重複していないか確認してください。複数のネットワークインターフェースがあると、自動検出で不適切な出口が選ばれることもあります。その場合は実際のインターフェースとルートに基づいて調整し、ほかの端末のインターフェース名をそのままコピーしないでください。社内ネットワークを変更する場合は、機器の管理ルールに従い、既存のアクセス制限を損なわないようにしてください。

一部のプログラムは、名前解決したアドレスをプロトコル検証、LAN内の機器検索、アドレス表示などに使うため、マッピング用アドレスに対応できない場合があります。互換性の問題は対象を絞って対応してください。まず問題のあるドメインを特定し、必要なフィルターを追加してから、ほかのドメインが引き続き想定どおりマッピングされるか確認します。すべてのドメインをフィルターに登録すると簡単に見えますが、ドメインの復元方法全体が変わり、以前はドメインで判定できた接続が実アドレスやスニッフィング頼みになる可能性があります。

次の順序で検証するのがおすすめです。まずTUNを使わずにシステムプロキシが動作することを確認し、次にTUNを有効にしてインターフェースとルートを調べます。その後、DNSリクエストがカーネルに届くことを確認し、最後にシステムプロキシを使わないアプリをテストしてください。障害が発生したら逆の順で元に戻します。ブラウザーはシステムプロキシを使っている可能性があるため、ブラウザーでアクセスできてもシステム全体が制御されているとは限りません。マッピング用アドレスの検索結果だけで、すべての通信がカーネルに届いたと判断することもできません。

ドメインスニッフィングでルール判定を補う

スニッフィングは情報を補う機能であり、DNSの代わりではない

接続がカーネルに届いた時点で、宛先アドレスしかなく、利用可能なドメイン情報がない場合があります。アプリ独自のDNSを使っている場合、透過的な通信制御から接続している場合、プログラムがキャッシュ済みのアドレスを直接使う場合などです。ドメインスニッフィングは、一部プロトコルの初期データからホスト情報を取得し、ドメインルールを適用できるようにします。不足情報を補う機能ですが、あらゆる通信からドメインを特定できるわけではなく、暗号化された接続の内容をすべて読み取る機能でもありません。

HTTPにはホスト情報が含まれ、条件がそろえばTLSのハンドシェイクからサーバー名を取得できる場合があります。QUICでは、カーネルが関連するハンドシェイク情報を解析する必要があります。クライアントがサーバー名を隠している場合、カーネルが対応していないプロトコルを使っている場合、識別に必要なデータが不足している場合は、スニッフィングできないことがあります。その場合は、アドレスルールやフォールバックに戻れるようにしてください。スニッフィングの失敗は、プロキシの出口が利用できないことを意味しません。プロトコルが公開していない情報は、対象ポートを増やしても取得できません。

対象ポートを絞って始める

以下の例では、HTTP、TLS、QUICの一般的なポートでスニッフィングを有効にし、取得したドメインに基づいて宛先アドレスを書き換える動作を無効にしています。まず識別結果を確認し、宛先の名前解決まで制御する必要があるか判断する場合に適しています。設定を統合するときは、クライアントがすでにsnifferを生成していないか確認し、同じトップレベルキーを重複させないでください。まず明確なWebリクエストを1～2件だけテストし、ログでドメイン情報の取得元が変化したことを確認してから対象アプリを増やします。

sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true
  override-destination: false
  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
    TLS:
      ports:
        - 443
        - 8443
    QUIC:
      ports:
        - 443

parse-pure-ipを有効にすると、IPアドレスだけの接続も解析できます。ドメインとの対応がない一部の通信に役立ちますが、識別できるとは限りません。force-dns-mappingは、該当するDNSマッピングの状況でスニッフィングを続けて試みるための設定であり、DNSの待ち受けや転送設定の代わりにはなりません。項目名だけから、すべてのアプリにカーネルのDNSを強制する機能だと判断しないでください。リクエストが名前解決モジュールに届くかどうかは、実際のネットワーク経路によって決まります。

override-destinationを有効にするかどうかは、個別に検討してください。有効にすると、スニッフィングで取得したドメインに基づき、その後の宛先処理を変更することがあります。マッチ情報を補うだけの設定ではありません。独自の名前解決、固定アドレス、特定の入口に依存するアプリでは、従来の接続経路が変わる可能性があります。変更要素を減らすため、まずは無効のままにしてください。サービス上の必要性と再解決・ルーティングへの影響を理解してから、対象ドメインやプロトコルを絞って慎重に調整します。

ドメインの取得元を確認し、本当にスニッフィングが必要か判断する

テストでは対象アプリの既存接続を終了してから新しい接続を行い、接続詳細に表示されるドメイン、宛先アドレス、適用ルールを確認してください。スニッフィングを有効にしても、既存接続でハンドシェイクがやり直されることはありません。Fake-IPによってすでにドメインが復元されている接続では、有効化の前後で適用ルールが変わらないことがあります。その場合、追加でスニッフィングするメリットは小さい可能性があります。設定項目を埋めるためだけに、すべてのオプションを有効にする必要はありません。

有効化後に特定のサービスで問題が起きたら、まずDNS設定全体を変更するのではなく、そのサービスに対してスニッフィングを無効にした場合と比較してください。カーネルが対応しているドメインの除外設定などを使い、対象を絞ることもできます。ただし、実際に確認できたドメインに基づいて例外を設定し、ほかの設定から一式をコピーしないでください。強制対象が広すぎると、より多くの通信がプロトコル判定を待つことになります。除外対象が広すぎると、ドメインルールが必要な接続がアドレスベースの振り分けに戻ることがあります。

ポート番号だけでプロトコルを特定することはできません。一般的なWebポートで独自プロトコルを使うアプリもあれば、標準外ポートでTLSを提供するサービスもあります。ポートを限定すると処理範囲を絞れますが、その範囲内の接続をすべて識別できるわけではありません。独自サービスを対象にする場合は、実際のプロトコルを確認してから設定してください。すべてのポートを追加すると調査範囲が広がるだけで、ハンドシェイク情報が隠されている問題や、未対応プロトコルの問題は解決しません。

QUICはUDPを利用することが多く、条件によってはTCPにフォールバックするアプリもあります。Webページが開けるかだけを確認すると、プロトコルが切り替わったことを見落とす場合があります。接続ログで使用中のトランスポートを確認し、スニッフィング結果と適用ルールを比較してください。ログを整えるためにUDPをすべて遮断しないでください。音声通話、リアルタイム通信、一部のアプリはUDPに依存しています。ログの見た目ではなく、対象サービスに応じて対応を決めましょう。

スニッフィング結果を扱う際は、プライバシーとデバッグの範囲にも注意してください。取得したドメインが接続記録やデバッグログに残る場合があります。スクリーンショットや問い合わせを共有する前に、社内サービス名などが含まれていないか確認しましょう。一般的なトラブルで必要なのは、通常、ルールタイプ、ポリシーの経路、匿名化した接続先の特徴であり、アクセス履歴全体をアップロードする必要はありません。ログを増やせば自動的に問題を特定しやすくなるわけではありません。有効化の前後で何が変わったかを記録するほうが役立ちます。

ローカル設定の上書きと複数サブスクリプションの統合

最終的な実行設定を基準にする

GUIクライアントでは、サブスクリプション、全体設定、ローカルの上書き設定を統合してカーネルに渡すことがよくあります。編集画面に表示されるのは入力内容であり、実行設定が最終結果です。同じDNS項目がサブスクリプションとクライアント設定の両方にある場合、どちらが使われるかは統合の順序で決まります。トラブルを調べる前に、クライアントの実行設定プレビューやエクスポート機能で、カーネルが実際に受け取った内容を確認してください。後から上書きされるファイルを繰り返し編集するのは避けましょう。

役割ごとに設定を分けるのがおすすめです。サブスクリプションにはプロキシと必要なプロバイダー情報を含め、業務用グループ、ルールの優先順位、DNS、端末固有の設定はローカルで管理します。端末固有の項目には、待ち受けアドレス、ポート、TUN、コントローラーなどがあります。異なるOS間で同じ設定をそのまま同期するには適しません。同期前に、再利用できる運用ルールと端末固有の環境設定を分けてください。ファイルを読み込めても、別の端末でルーティングや権限が同じように動作するとは限りません。

すべての統合ツールが同じルールで動くとは限らない

マッピング、配列、スカラー値の統合方法は、クライアントによって異なることがあります。マッピングは階層ごとに統合される場合も、全体が置き換えられる場合もあります。配列は追加、先頭への挿入、上書きなどの動作が考えられます。カーネルがクライアント間の差を統一するわけではありません。特にrules配列でローカルの例外が既存設定のMATCHの後ろに追加されると、適用されなくなります。画面に保存済みと表示されるだけで判断せず、最終的なルール順を確認してください。

以下は、上書き機能に渡す設定内容の一例です。ローカルの待ち受けを固定し、ルールモードを選択し、選択状態を保存するよう指定しています。すべてのクライアントで共通の上書きファイル形式ではありません。使用中のクライアントが対応するYAML統合用の入口に配置してください。スクリプトや専用形式が求められる場合は、その仕様に従い、YAMLをスクリプトエディターに貼り付けないでください。profileの効果は、再起動後の状態でも確認します。

mixed-port: 7890
allow-lan: false
mode: rule

profile:
  store-selected: true
  store-fake-ip: true

同じYAMLマッピング内に重複キーがある場合は、解消すべき問題です。解析エラーになるパーサーもあれば、後から書かれた値を採用するパーサーもあるため、この違いを上書きの手段として利用しないでください。インデントにはスペースを使い、特殊な構文として解釈される可能性のある文字列は引用符で囲みます。変更後はまず構文をテストし、その後に実行環境へ読み込んでください。YAMLとして解析できても、ポリシー参照、ファイルパス、ルールの動作は別途検証する必要があります。

複数サブスクリプションは配布元を分けてから、名前と参照を整理する

複数の配布元から同名のプロキシ、プロキシグループ、プロバイダーが届くことがあります。そのまま結合すると競合したり、ルールが意図しない項目を参照したりする可能性があります。配布元ごとに明確なプロバイダーの名前空間を設け、ローカルのプロキシグループからuseで必要なメンバーを選ぶ方法が安全です。プロキシ名を変更する場合は、すべての参照先も更新してください。リストの表示名だけを変え、グループ内の参照を更新しないと、起動エラーやメンバー不足につながります。

複数の配布元を統合する場合も、DNSやルール一式を何度も複製する必要はありません。どの設定を最終的な判断元にするかを決め、ほかの配布元はプロキシ情報の供給元として扱ってください。サブスクリプションに残す必要がある専用ルールがある場合は、個別に確認して明確な位置に配置し、ローカルのポリシー全体を上書きさせないでください。配布元が増えるほど、無効化や削除の手順も明確にする必要があります。プロバイダーを無効にした後も、それを参照するグループが動作するか事前に判断できる状態にしましょう。

ターミナル環境では、デプロイ前にカーネルの設定テスト機能を利用できます。コマンドに指定するディレクトリは、実際の設定作業ディレクトリに置き換えてください。以下のコマンドは、設定ファイルと依存ファイルが現在のディレクトリにある場合に使えます。テストだけで実際のネットワーク接続を確認することはできませんが、項目、参照、ファイル読み込みなどの問題を事前に検出できます。GUIクライアントに設定チェック機能がある場合も、リロード前に検査してください。未検証の設定をそのまま起動時の既定値にするのは避けましょう。

mihomo -t -d . -f ./config.yaml

サブスクリプションが自動更新されたら、最終的な設定の待ち受けポート、先頭付近のルール、最後のフォールバック、重要なグループのメンバーを抜き取り確認してください。こうした箇所には、統合方法の変化が表れやすい傾向があります。更新後に問題が出たら、まず直前の正常な入力に戻してから生成結果を比較してください。自動更新をすぐに完全停止して放置するのは避けましょう。追加したドメイン例外や変更したグループのメンバー元など、説明可能な変更記録を残すと、その後の調査に役立ちます。

複数端末で同期する場合は、必要なファイルだけを対象にし、ログ、キャッシュ、端末が生成した一時設定を除外してください。サブスクリプションのURLやプロキシの認証情報は機密情報であり、公開リポジトリには置かないでください。詳しい手順は複数端末間の設定同期をご覧ください。ポートの競合が起きた場合は、ローカルの上書き設定だけでなく、システムプロキシとアプリの設定も変更する必要があります。具体的な調査方法はポート競合のトラブルシューティングをご覧ください。

外部コントローラーと検証手順

コントローラーポートとプロキシポートを区別する

external-controllerはカーネルの管理APIを提供し、パネルから状態の確認、プロキシグループの切り替え、管理操作などを行うための設定です。通常のプロキシ通信を受け付けるmixed-portの代わりにはなりません。ブラウザーのプロキシ設定にはプロキシの待ち受けポートを指定し、パネルの接続設定にはコントローラーのアドレスを指定します。2つのポートを混同すると、ブラウザーで通信できない、またはパネルが接続エラーになることがありますが、カーネル自体は動作している場合があります。

管理APIは実際のネットワーク動作に影響するため、待ち受け先はローカルのループバックアドレスに制限するのが基本です。以下の設定例は、ローカルの管理エンドポイントとパネルのディレクトリを指定する、ローカル利用向けの基本構成です。パネルのファイルはカーネルの作業ディレクトリ内にあるuiディレクトリへ事前に配置してください。このパスを指定しただけで、カーネルがWebページを自動生成するわけではありません。クライアントにコントローラーとパネルの管理機能が内蔵されている場合は、重複した待ち受けを手動で作らず、内蔵機能を優先してください。

external-controller: 127.0.0.1:9090
external-ui: ./ui

ループバックアドレスで待ち受けても、すべてのセキュリティ対策が完了するわけではありません。ローカルの別プロセスからはポートに接続できます。クライアントが対応する方法でコントローラー専用のsecretを設定し、パネルの接続設定にも同じ値を入力してください。実際の秘密情報を公開ファイルやサンプルに記載せず、認証情報を含むパネルのURLを共有しないでください。プロキシのアカウントパスワードをコントローラーの認証情報に流用するのも避けてください。変更後にパネルへ接続し、古い認証情報が使えなくなったことを確認します。

まずAPIを確認し、その後ブラウザーのパネルを確認する

パネルが開かない場合は、まずカーネルが動作しているか、コントロールポートで待ち受けているかを確認し、その後に静的Webファイルのディレクトリを調べます。認証を設定していないローカル環境では、以下のコマンドで管理APIの応答を確認できます。認証を有効にしている場合は、クライアントの対応する接続方法を使うか、ローカルからのリクエストに認証情報を付けてください。テストのためにコントローラーをすべてのネットワークインターフェースへ公開しないでください。接続拒否とポートに接続できない状態は、異なる原因として切り分ける必要があります。

curl --noproxy '*' http://127.0.0.1:9090/configs

APIには接続できるのにパネルが使えない場合は、パネルに保存されたコントローラーのアドレス、認証情報、ブラウザーのエラーを確認します。HTTPSで開いたページからローカルのHTTP APIに接続すると、混在コンテンツやブラウザーによるローカルネットワークへのアクセス制限が発生する場合があります。異なるオリジンからの接続では、コントローラーのオリジン設定も関係します。汎用的な修正としてすべてのオリジンを許可するのではなく、クライアント内蔵のパネルや同一オリジンのローカルページを優先し、必要な接続元だけを許可してください。

リモート管理では、待ち受けアドレスをすべてのインターフェースに変更するだけで設定を終えてはいけません。認証、ネットワークのアクセス範囲、暗号化通信、ファイアウォールルールをあわせて設計する必要があります。管理されたローカル転送や管理用ネットワークを利用できるなら、管理APIを公共のネットワークに直接公開する必要は通常ありません。パネルページが開けても、管理用接続が保護されているとは限りません。ページとAPIで異なるアドレスや通信方式が使われることがあるため、それぞれ確認してください。

接続ログで検証を完結させる

パネルでは、新しい接続がどのように処理されたかを追跡できます。送信元アプリ、宛先のドメインやアドレス、適用ルール、ポリシー経路、最終出口を確認してください。検証する際は明確な宛先を一つ選び、新しいリクエストを1回発生させます。多数の同時接続を印象だけで判断しないでください。グループ名が表示されても、それが最終出口とは限りません。グループを展開して実際の選択先を確認します。ルールの判定が正しいのに接続できない場合は、ルール順をさらに変更するのではなく、実際のプロキシと名前解決を調べてください。

パネルで選択されているポリシーと、設定ファイルの既定メンバーが異なる場合があります。選択状態の保存が有効だと、設定を再読み込みした際に以前の選択が復元されることがあります。グループ内の順序を変えても、現在の出口が変わるとは限りません。トラブル時はパネルの実際の状態を記録してから、手動で切り替えてください。設定を再読み込みしても、既存の接続がすべて終了するわけではありません。検証には新しい接続を使います。継続中の処理があるアプリでは、接続を強制終了する前に作業への影響を確認してください。

次の順序で一通り確認するのがおすすめです。設定の構文と参照先がテストに通ること、プロキシ用ポートとコントロールポートが正常に待ち受けていること、通常モードで接続できること、DNS問い合わせが想定したモジュールに届くこと、ルールが正しく適用されること、プロキシグループから実際の出口を確認できることを順に検証します。その後必要に応じてTUNとスニッフィングを有効にします。モジュールを追加するたびに結果を記録しておけば、問題が再発した際に直近の正常な状態まで戻せます。すべての設定を一度にやり直す必要はありません。

トラブルの記録には、OS、クライアント名、TUNの使用有無、問題が起きる接続先の種類、適用ルール、重要なエラーメッセージを簡潔に記載します。サブスクリプション全体、認証情報、すべてのアクセス履歴は公開しないでください。基本的な疑問はよくある質問をご覧ください。接続済みなのにWebページが開かない場合は、原因を順に確認するチェックリストを使い、システムプロキシからDNS、ファイアウォールまで調べてください。設定を保守しやすくするには、接続がそのように処理される理由を説明でき、失敗時にどこまで戻すか明確にできることが重要です。