Clash Meta を Docker Compose でデプロイ：構成、イメージ更新、購読の永続化
すでに VPS・自宅サーバー・NAS で Docker を使っているなら、Clash Meta（mihomo） も コンテナ に載せ、Docker Compose でバージョンとディレクトリを固定するのが再現性の高い選択です。本記事では イメージの選び方、設定と購読キャッシュのボリューム設計、ポート公開とネットワークモード、pull からの更新とロールバックまでを一通りまとめます。Linux にバイナリ直置きして systemd 常駐する手順とは別ルートであり、どちらもヘッドレス運用として併記すると運用チーム内の認識が揃いやすいです。
なぜ Docker か：systemd 直運用との棲み分け
バイナリとユニットファイルだけで回す方式は軽量で、カーネルに近いところから挙動を追いやすい利点があります。一方で、複数ホストで同じレイアウトを再現したい、NAS やアプライアンス上でパッケージ管理を触りたくない、CI から compose を流したい、といった場面では Docker が独立した検索意図として立ちます。コンテナは「隔離」と「宣言的な再作成」を強く意識するため、イメージタグの固定とホスト側ディレクトリのマウントが設計の中心になります。デスクトップ向け GUI クライアントではなく、サーバー用途の headless 前提で読み進めてください。
- Compose：サービス名・再起動ポリシー・環境変数を一ファイルに集約し、git で差分管理しやすい。
- ボリューム：
config.yamlと provider が書き込むキャッシュをホストに残し、コンテナを捨てても状態を継承できる。 - 更新：
docker compose pullとup -dでロールフォワード。不具合時は前タグへ戻すだけ、という運用に寄せられる。
前提：ホストと権限
Linux 系ホストを想定します。Docker Engine と Compose プラグイン（docker compose サブコマンド）が使えること、ファイアウォールで公開ポートを制御できることが望ましいです。ルートレス Docker やユーザー名前空間を有効にしている環境では、バインドマウント先の UID/GID がコンテナ内ユーザーと一致しないと、購読ファイルの書き込みで失敗します。NAS 製品ごとの「共有フォルダ権限」とコンテナ実行 UIDをあらかじめ突き合わせてください。TUN モードをコンテナ内で使う構成は、cap_add や /dev/net/tun の扱い、場合によっては network_mode: host が絡み、単純なブリッジ公開よりトラブルが増えやすいです。まずはHTTP/SOCKS の mixed-port を LAN またはローカルにだけ出す形から始め、必要になったら TUN を検討するのが安全です。
イメージの選び方とバージョン固定
コミュニティ製の Clash Meta / mihomo 系イメージは複数あり、メンテ状況とタグ規則が異なります。運用では latest 任せにせず、セマンティックバージョン付きタグか、より厳密に digest（image@sha256:...）で固定するのがおすすめです。digest はレジストリのマニフェストを指すため、同じ文字列ならビット一致で再現できます。README にアーキテクチャ別タグ（amd64 / arm64）がある場合は、自機に合わせて明示してください。イメージ内のデフォルト作業ディレクトリやエントリポイントは製品ごとに違うため、必ず説明に沿って command や volumes の左右を確認します。
運用のコツ
本番では compose.yaml をリポジトリ化し、イメージ行にコメントでリリースノート URL を残す。セキュリティパッチのたびに digest を差し替え、変更履歴を追えるようにします。
ディレクトリ構成とボリューム
典型的にはホストに ./clash/config を用意し、そこへ config.yaml（または指定名）と、ルールファイル・証明書などを置きます。proxy-providers がローカルパスへキャッシュを書く場合、その親ディレクトリもマウント対象に含め、コンテナ再起動後も購読の永続化が切れないようにします。空のディレクトリを初回だけ作成し、所有者をコンテナの実行ユーザーに合わせると権限トラブルを減らせます。データだけ別 SSD に置きたい NAS では、共有フォルダの実パスをそのままバインドし、バックアップジョブの対象に含めやすくするのも現実的です。
docker-compose の例
以下は概念実演です。イメージ名・タグ・デフォルトパスは利用する配布に置き換えてください。ポート番号は環境に合わせ、公開範囲はセキュリティグループとセットで絞ります。
# Example — replace image, paths, and command with your distribution's docs
services:
clash-meta:
image: example/mihomo:1.19.0
container_name: clash-meta
restart: unless-stopped
volumes:
- ./config:/root/.config/mihomo
ports:
- "127.0.0.1:7890:7890"
- "127.0.0.1:7891:7891"
# environment:
# - TZ=Asia/Tokyo
127.0.0.1 に限定すると、同じホスト上の他コンテナやプロセスからはホストのループバック経由で届きます。LAN 内の別マシンに SOCKS を出したい場合は mixed-port と allow-lan の記事とあわせ、bind-address とファイアウォールを設計してください。external-controller を有効にするなら、必ずシークレットとアクセス元を制限し、インターネットに晒さないことです。
ネットワークモードの考え方
デフォルトのブリッジはポートマッピングで十分なことが多いです。network_mode: host はホストのネットワークスタックをそのまま使うため、ポート衝突の切り分けは楽になる一方、複数インスタンスや他サービスとの待受競合に注意が必要です。Docker Desktop for Mac のような環境では挙動が Linux と異なるため、本番相当の検証は Linux ホストで行ってください。IPv6 や複雑なルーティングテーブルを絡める場合、まずホスト単体で期待どおりに疎通してからコンテナに移すと原因特定が早いです。
| 方式 | 向く場面 | 注意 |
|---|---|---|
| bridge + ports | 一般的なプロキシ公開 | マッピング漏れとバインドアドレス |
| host | ポート転送を省きたい | ホストとポートの衝突 |
| macvlan（上級） | LAN に独立 IP を取りたい | スイッチ・DHCP 設計が必要 |
購読の永続化と proxy-providers
設定ファイル内で proxy-providers の path をマウント先以下に置けば、取得したノード一覧はホスト側ファイルとして残ります。interval による定期更新はプロセス内で処理されるため、コンテナを再起動しても、キャッシュがボリューム上にあればコールドスタートの負荷を抑えられます。URL にトークンが含まれる購読は、リポジトリにそのままコミットしない運用を徹底し、環境変数やホストのみが読めるファイルに分離します。DNS や fake-ip の話題は 接続表示はあるのに繋がらないの記事と通じます。コンテナでも名前解決の向き先がズレると同様の症状が出ます。
イメージ更新・ロールバック・再作成
更新の基本は docker compose pull のあと docker compose up -d です。設定変更だけならコンテナ再作成を伴わず、ホスト上の YAML を書き換えて API リロードや再起動で足りることもあります。不具合が出たら compose ファイルのイメージ行を一つ前のタグまたは digestに戻し、同じコマンドで再適用すればロールバックになります。運用ログに「どの digest がいつまで本番だったか」を残すと、インシデント後の再発防止がしやすいです。自動更新を watchtower 等に任せる場合は、メジャーアップグレードで破壊的変更が入りやすい点に留意し、ステージングを挟むか手動承認に切り替えてください。
バックアップ
ボリューム内の config.yaml と provider キャッシュを、イメージ更新の前後でスナップショットしておくと、設定ミスとイメージ不具合を切り分けやすくなります。
NAS・ホームサーバー向けの補足
一部の NAS UI は再起動ポリシーやログローテーションを独自にラップします。公式の Compose 互換機能を使う場合でも、生成物が隠しディレクトリにマウントされていないか確認してください。USB 外付けドライブに設定だけ置く構成は、デバイス名が変わるとマウントに失敗するため、ラベルや UUID 固定の fstab を検討します。電源断に弱い環境では、restart: unless-stopped に加え、ホスト側の Docker デーモン自動起動も有効にしておくと無人復旧しやすいです。
よくある質問
TUN はコンテナで簡単に使えるか
ディストリビューションとカーネル設定に依存し、privileged やデバイスマウントが必要になることがあります。まずは mixed-port とルールモードで十分か検証し、どうしても必要ならドキュメント豊富なイメージを選び、ステージングで検証してください。
provider キャッシュが書けない
ホスト側ディレクトリの所有者とパーミッションを、コンテナ内の実行 UID/GID に合わせます。NAS では共有フォルダの「ユーザー権限」とコンテナのユーザー指定（user: キー）を一致させるのが近道です。
pull 後に起動しない
docker compose logs でエントリポイントのエラーを確認します。設定パスがイメージの期待とズレている、あるいは新バージョンで必須キーが増えているケースが多いです。一つ前のイメージに戻して差分を読み比べてください。
チェックリスト
- イメージはタグまたは digest で固定し、変更履歴を残す。
- 設定ディレクトリと provider キャッシュをホストにマウントし、権限を揃える。
- 公開ポートは listen アドレスと FW で最小化する。
- 更新は pull → up、問題時はイメージ行を戻してロールバック。
- DNS・fake-ip の問題は別記事の手順でホストとコンテナ双方を確認する。
まとめとクライアント
Docker は「同じ手順を別ホストへ複製する」強みがあります。サーバー側を Compose で固めつつ、クライアント PC では GUI 版の方がルール編集が楽な場合も多いです。統合ビルドを試す場合は ダウンロードページ から入手できます。