Linuxへの導入 mihomoコア：コマンドライン実行、systemdでの常駐化、デスクトップクライアントの設定

導入方法：バックグラウンドサービスかデスクトップクライアント

mihomoはClash Metaから派生したプロキシコアです。設定を読み込み、プロキシ接続を確立してルールに基づく通信の振り分けを行います。コア単体にはデスクトップ画面がなく、プロセスを起動しただけですべてのLinuxアプリがプロキシ経由になるわけではありません。アプリ側でローカルのプロキシポートを指定するか、設定済みのTUNで通信を処理する必要があります。

サーバーやGUIのない環境、起動後も継続して動かすマシンには、バイナリとsystemdの組み合わせが適しています。日常的にデスクトップで使う場合や、ノードの切り替え・サブスクリプションの更新を頻繁に行う場合は、Clash Verge RevやFlClashsなどのGUIクライアントが便利です。2つの方法を個別に試すことはできますが、2つのコアで同じポートを同時にリッスンさせないでください。

バイナリの準備：アーキテクチャ、権限、作業ディレクトリ

システムのアーキテクチャとinitシステムを確認する

uname -m
ps -p 1 -o comm=
systemctl --version

x86_64は通常amd64ビルド、aarch64はarm64ビルドに対応します。32ビットARMの場合はビルド要件も確認してください。デバイスのブランドだけでファイルを選ぶことはできません。2つ目のコマンドでsystemdと表示されることを確認します。コンテナやWSL、その他のinitシステムでは、別の起動方法が必要になる場合があります。

信頼できるプロジェクトのリリース元から、使用するアーキテクチャに合ったmihomoバイナリを入手します。展開後、ファイル名をmihomoにして現在のディレクトリに置いてください。圧縮ファイルはそのまま実行できません。Exec format errorが出た場合は、実行権限を何度も付け直すのではなく、アーキテクチャとファイルの展開状態を確認します。

chmod +x ./mihomo
./mihomo -v
sudo install -m 0755 ./mihomo /usr/local/bin/mihomo

-vで実際のコアバージョンを確認できます。設定項目がサポートされているか調べる際は、この出力を基準にしてください。デスクトップクライアントのバージョンで代用することはできません。

プログラム、設定、実行データを分けて管理する

ここでは保存先を3か所に分けます。プログラムは/usr/local/bin/mihomo、設定は/etc/mihomo/config.yaml、実行データは/var/lib/mihomoに配置します。ルールセットやデータベースのダウンロード、キャッシュの保存には、コアが書き込めるデータディレクトリが必要です。設定ファイルは読み取り専用にできます。

sudo useradd --system --home-dir /var/lib/mihomo --shell /usr/sbin/nologin mihomo
sudo install -d -m 0750 -o root -g mihomo /etc/mihomo
sudo install -d -m 0750 -o mihomo -g mihomo /var/lib/mihomo

専用ユーザーがすでに存在する場合はuseraddを実行せず、id mihomoで確認してください。ディストリビューションによってnologinのパスが異なる場合は、command -v nologinで確認できます。ディレクトリの権限対策として、設定ディレクトリ全体を書き込み可能にしないでください。

設定ファイル：まずローカルポートを確認し、その後サブスクリプションを設定

最小構成で実行環境を確認する

まず現在のディレクトリにconfig.yamlを作成し、以下の内容を記述します。この設定はDIRECTルールのみで、プログラム、ポート、権限が正常に動作するかを確認するためのものです。プロキシノードは含まれておらず、プロバイダーが提供する完全な設定の代わりにはなりません。

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
ipv6: false

rules:
  - MATCH,DIRECT

mixed-port: 7890は、同じTCPポートでHTTPプロキシとSOCKS5のリクエストを受け付けます。allow-lan: falseとループバックアドレスを組み合わせることで、ローカルマシンだけで使う構成になります。external-controllerは設定していないため、この例ではコントロールAPIを公開しません。

sudo install -m 0640 -o root -g mihomo ./config.yaml /etc/mihomo/config.yaml
sudo -u mihomo /usr/local/bin/mihomo -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml
sudo -u mihomo /usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml

-tで設定ファイルを読み込めるか確認し、-dで実行データのディレクトリ、-fで設定ファイルのパスを指定します。フォアグラウンドで起動してエラー出力を確認しながら、別のターミナルでポートを調べます。

ss -lntp 'sport = :7890'
curl -I --connect-timeout 10 --max-time 20 --proxy http://127.0.0.1:7890 https://example.com/

この例ではリクエストがローカルのmihomoを経由した後、宛先へ直接接続します。HTTPレスポンスが返っても、この接続経路が使えることを確認できるだけで、リモートプロキシが使われている証明にはなりません。確認後は、コアを実行しているターミナルでCtrl+Cを押してフォアグラウンドプロセスを停止してください。systemdの起動時にポートが競合するのを防げます。

利用可能なサブスクリプション設定に置き換える

1. プロバイダーがClashまたはmihomo向けに明示的に提供しているYAML設定を入手してください。ノード共有リンク、Web上のサブスクリプション案内、他のクライアント用フォーマットは、そのままYAMLとして使えません。
2. 手元で使えるコピーを残したうえで、新しいファイルを/etc/mihomo/config.yamlに配置します。権限は0640、所有者はroot:mihomoのままにしてください。
3. リッスンポート、proxy-groups、rulesと、ルールが参照するポリシー名が一致しているか確認します。
4. もう一度-tを実行し、問題がなければサービスを起動します。リモートのルールセットやデータベースを使う場合は、ネットワークへの接続とデータディレクトリへの書き込み権限も確認してください。

systemdで常駐化：自動起動、ログ、設定更新

/etc/systemd/system/mihomo.serviceを作成し、以下の内容を記述します。このサービスは通常のローカルプロキシのみを提供し、TUNに必要な権限設定は含みません。

[Unit]
Description=mihomo local proxy service
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/var/lib/mihomo
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=5
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/mihomo

[Install]
WantedBy=multi-user.target

Restart=on-failureは、プロセスが異常終了したときに再起動を試みる設定です。無効な設定ファイルを修復するものではありません。ProtectSystem=strictはファイルシステムへの書き込みを制限し、データディレクトリだけを書き込み可能にします。設定が別のパスを参照する場合は、実行ユーザーに読み取り権限があること、またダウンロード先が書き込みを許可された場所であることを確認してください。

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
sudo journalctl -u mihomo -b -n 80 --no-pager

enable --nowを実行すると、自動起動を有効にしてサービスをすぐに起動します。network-online.targetは起動順序を指定するもので、ネットワークを実際に待つかどうかは、システム上のwait-onlineサービスによって異なります。インターネットへの接続が必ず確立するという意味ではありません。サブスクリプション、ルールセット、ノードへの接続は別途確認してください。

設定を変更した後の手順

sudo cp -p /etc/mihomo/config.yaml /etc/mihomo/config.yaml.bak
sudoedit /etc/mihomo/config.yaml
sudo -u mihomo /usr/local/bin/mihomo -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml
sudo systemctl restart mihomo
sudo journalctl -u mihomo -n 40 --no-pager

設定チェックに成功した場合のみ再起動してください。serviceファイルを変更した場合は、先にdaemon-reloadが必要です。YAMLだけを変更した場合は不要です。ここでは設定を反映するためにサービスを再起動します。ExecReloadは定義していないため、systemctl reload mihomoで反映されるとは限りません。再起動すると既存のプロキシ接続が切れるため、ダウンロードやリモートセッションは事前に調整してください。

Linuxのプロキシ環境変数：ターミナル、Git、APT

コアがリッスンを開始しても、ターミナルのプログラムにプロキシの接続先を知らせる必要があります。以下の変数が適用されるのは現在のシェルと、そのシェルから起動する子プロセスのみです。すでに起動しているブラウザーや別のターミナル、システムサービスには適用されません。

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5h://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1

curl -I --connect-timeout 10 --max-time 20 https://example.com/

https_proxyの値にhttp://を指定しても、HTTPプロキシのCONNECTトンネル経由でHTTPSの宛先にアクセスするという意味です。宛先との接続が平文に変わるわけではありません。socks5hは、SOCKSプロキシ側で宛先ドメインを名前解決する指定です。ローカルのコアがその後どのように名前解決するかは、DNS設定によって異なります。

• 環境変数への対応はプログラムによって異なります。curlはセキュリティ上の理由から大文字のHTTP_PROXYを受け付けません。上記の小文字表記を使ってください。
• 対話型ターミナルを開くたびに適用したい場合は、使用しているシェルに応じて~/.bashrcまたは~/.zshrcに変数を記述します。サービスを停止したら、これらの変数も無効にしてください。
• sudoはプロキシ環境変数を削除することがよくあります。systemdサービスもユーザーのシェル起動ファイルを自動的には読み込まないため、環境変数は個別に設定する必要があります。
• コンテナ内の127.0.0.1はコンテナ自身を指し、ホストマシンではありません。コンテナとの接続を解決するために、LAN全体にプロキシを公開しないでください。

特定のコマンドにプロキシを明示的に指定する

git -c http.proxy=http://127.0.0.1:7890 ls-remote https://github.com/MetaCubeX/mihomo.git HEAD

sudo apt \
  -o Acquire::http::Proxy="http://127.0.0.1:7890" \
  -o Acquire::https::Proxy="http://127.0.0.1:7890" \
  update

これらの設定が適用されるのは実行中のコマンドだけです。動作確認には便利ですが、GitやAPTの設定は継続的に変更されません。現在のシェルからプロキシ環境変数を削除するには、次のコマンドを使います。

unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY

アプリがプロキシ環境変数を読み込まず、独自のプロキシ設定もない場合、通常のmixed-portでは通信を自動的に処理できません。こうした場合にTUNを検討します。環境変数を何度も設定して解決する問題ではありません。

デスクトップクライアントの設定：インポート、システムプロキシ、TUN

GUI環境で使う場合は、ダウンロードページからLinuxクライアントを選んでください。DebianやUbuntuでは通常DEBパッケージ、FedoraなどRPM系のディストリビューションではRPMパッケージを選び、CPUアーキテクチャも確認します。以下のコマンドでは、ダウンロード済みのインストーラーパッケージをローカルでリネームしたものとして扱います。

# Debian / Ubuntu
sudo apt install ./client.deb

# Fedora
sudo dnf install ./client.rpm

クライアントの画面やメニュー名はバージョンによって異なります。操作する際は「設定のインポート」「プロキシの選択」「ネットワークの制御」にあたる機能を探してください。アプリのバージョンとコアのバージョンを混同しないようにしましょう。

1. 設定をインポート：設定またはサブスクリプションの画面でURLを追加するか、ローカルのYAMLファイルをインポートします。ダウンロードが完了し、対象の設定が選択されていることを確認してください。リストに表示されただけでは有効になっていません。
2. ポリシーを選択：プロキシグループの画面を開き、ルールが参照しているポリシーグループで利用可能なノードを選びます。ルールモードでは、すべてのリクエストが選んだノードを通るわけではありません。DIRECTに一致した通信は直接接続されます。
3. ポートを確認：設定内のネットワークまたはポートの項目で、混合ポートを確認します。デスクトップクライアントでは7897など別のポートが使われる場合があるため、本文の7890をそのまま使わないでください。
4. システムプロキシを有効化：主にデスクトップ環境のプロキシ設定を行います。適用範囲は、各アプリがシステム設定に従うかどうかによって異なります。ブラウザーを確認した後、ターミナルのプログラムも個別に確認してください。
5. 必要に応じてTUNを有効化：クライアントが用意するサービスのインストールと権限付与の手順に従い、その後、仮想ネットワークインターフェイス、ルート、DNSを確認します。クライアントをrootで常時実行しないでください。

TUNは「速度を上げる」機能ではありません。仮想ネットワークデバイスを使って対象の通信を処理するため、/dev/net/tun、ネットワーク管理権限、ルーティング設定が関係します。有効化後にリモートSSH、LANへのアクセス、コンテナネットワークに問題が起きた場合は、まずTUNを無効にして接続を復旧し、その後ルートの除外設定とDNSを確認してください。低権限で動かす本稿のservice設定は、実際のTUN導入方法に合わせて見直す必要があります。tun.enable: trueを追加するだけで動くと考えないでください。

起動しない・プロキシが効かない場合：原因を段階的に確認

「プロセス、リッスンポート、アプリの接続設定、ルールとポリシー、リモートノード」の順に確認してください。まずcurl --proxyを明示してアプリの設定に問題がないか切り分け、その後ログでルールとポリシーの適用結果を確認します。ノードのタイムアウトとローカル接続の拒否は原因の層が異なるため、どちらも「Linuxでプロキシが効かない」と一括りにしないでください。

導入後は、コアのバージョン、有効な設定ファイルのコピー、serviceファイル、復旧コマンドを保管してください。バイナリを更新する前にサービスを停止し、旧バイナリを残したうえで差し替えて設定をテストします。ルールやDNSについて詳しく知りたい場合は用語集をご覧ください。エラーが続く場合は、トラブル対処の手順に沿って原因を調べてください。