Docker Hub の Pull 失敗を TUN の問題として切り分ける
Docker Hub Pull できない、docker pull タイムアウト、TLS handshake timeout、lookup registry-1.docker.io: no such hostといったエラーは、イメージそのものの問題とは限りません。Docker Desktop や Linux の Docker デーモンは、ブラウザとは別のプロセスとして通信するため、Clash のシステムプロキシ設定がブラウザにだけ適用され、dockerd の通信は直接接続になっているケースがあります。
特に、Docker Hub からの Pull は一つのドメインだけで完結しません。最初に認証用エンドポイントへアクセスし、その後に Registry、Manifest、Blob、CDN など複数のホストへ HTTPS 接続を張ります。そのため hub.docker.com だけをプロキシへ送っても、実際のレイヤー取得先が DIRECT のままなら、ログインは成功するのにイメージだけ取得できないという非対称な症状になります。
本稿では、Clash TUN を使ってホスト側の通信を取り込み、Docker デーモンの経路、DNS 解決、Docker Hub 関連ルールを順番に確認します。対象は Docker Desktop と、Linux 上で systemd 管理される Docker Engine の両方です。構成を一度に複雑にするのではなく、ログに現れたホスト名とエラーを根拠に、必要な範囲だけをプロキシへ振り分けるのが基本方針です。
docker version、docker info、Clash の接続ログ、そして対象イメージの名前を記録してください。同じ Pull を二回実行し、毎回同じホストで止まるかを確認すると切り分けが速くなります。Clash TUN を有効にする前の確認事項
Clash TUN は、アプリケーションが HTTP プロキシを明示的に指定していなくても、OS の仮想ネットワークインターフェースを通じて通信を Clash コアへ渡す仕組みです。Docker のように独自のネットワーク名前空間やバックグラウンドデーモンを利用するソフトウェアでは、単なる「システムプロキシをオン」にするより TUN のほうが適用範囲を広げやすくなります。
ただし、TUN は有効にすれば必ず解決する万能スイッチではありません。管理者権限、仮想インターフェース、DNS の受け口、既存 VPN との競合、Docker の内部ネットワークがそれぞれ影響します。まず他の VPN クライアントや透過型ファイアウォールを一時停止し、Clash だけを有効にした状態で確認してください。複数のソフトウェアが同じ経路や DNS ポートを奪い合うと、症状がランダムに変化します。
- プロファイルを確認する:Clash で実際に有効化されているプロファイルを開き、プロキシグループに利用可能なノードがあることを確認します。購読更新直後はグループが空になっている場合もあります。
- TUN をオンにする:設定画面で TUN モードを有効化し、必要なら Service Mode や管理者権限によるサービスをインストールします。インターフェースが作成されたことを確認してから Docker を再試行します。
- スタックを選ぶ:Windows では
mixedまたはgvisorを試し、問題が出た場合は一方へ固定します。環境によって適性が異なるため、速度だけでなく Pull の完了率で判断します。 - 接続ログを開く:Pull 実行中に
registry-1.docker.io、auth.docker.io、production.cloudflare.docker.comなどの名前が表示されるかを確認します。
TUN を有効にしたあと、ブラウザで一般サイトを開くだけでは検証として不十分です。Docker デーモンが実際に Clash へ到達しているかを確認するには、docker pull hello-worldのような小さなイメージを使います。Clash のログに新しい接続がまったく出ない場合、ルール以前に TUN のルーティング、Docker Desktop の VM 境界、または Linux のネットワーク名前空間を疑うべきです。
Docker デーモンと DNS 名前解決を整える
Docker DNS エラーは、プロキシ設定と同じくらい頻繁に Pull を止めます。ホストのブラウザが名前解決できても、Docker コンテナや Docker デーモンが使用する DNS は別経路です。Docker の内部リゾルバー、ホスト OS の DNS、Clash の DNS モジュールが異なる回答を返すと、名前は存在するのに接続先が不正になる、IPv6 だけ失敗する、または一時的な server misbehaving が発生します。
Clash 側では DNS 機能を有効にし、TUN の DNS hijack が利用できる構成にします。Mihomo 系の設定例は次のようになります。実際のフィールド名や利用可能なモードはクライアントとコアのバージョンで異なるため、既存プロファイルの仕様を優先してください。
dns:
enable: true
listen: 0.0.0.0:1053
enhanced-mode: fake-ip
nameserver:
- https://1.1.1.1/dns-query
- https://dns.google/dns-query
fallback:
- https://1.0.0.1/dns-query
fake-ip-filter:
- '*.lan'
- '*.local'
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53
fake-ip は、クライアントが名前解決を行ったあとも Clash が元のドメイン情報を保持し、ドメインルールを適用しやすくする方式です。一方、Docker や社内ネットワークでローカル名を多用する環境では、*.lan、*.local、社内ドメインを fake-ip の対象外にする必要があります。ここを無視すると、Docker の内部サービス名や社内レジストリが解決できなくなることがあります。
Linux では、次のコマンドをホスト側で実行し、名前解決の状態を比較します。
getent hosts registry-1.docker.io
resolvectl query registry-1.docker.io
docker run --rm busybox nslookup registry-1.docker.io
docker info
ホストだけ成功し、コンテナ内の nslookup が失敗するなら、Docker の DNS 設定を確認します。必要に応じて /etc/docker/daemon.json に DNS サーバーを指定し、Docker サービスを再起動します。ただし、Clash の TUN が DNS を引き受ける構成で、コンテナへパブリック DNS を直接指定すると、DNS だけがプロキシ外へ漏れることがあります。名前解決の一貫性と到達性を同時に確認してください。
{
"dns": [
"192.168.1.1",
"1.1.1.1"
]
}
systemctl restart docker を実行する前に、SSH 接続やローカル管理経路が失われないか確認してください。Docker Hub 向け Clash ルールを安全に組み立てる
Docker Hub のルールは、最初から広い DOMAIN-KEYWORD,docker,PROXY を書くより、ログで確認したホストを明示するほうが安全です。キーワード指定は、社内の Docker 関連ホストやローカル開発サービスまで誤ってプロキシへ送る可能性があります。まずは認証、Registry、Blob 配送という役割ごとに候補を整理します。
| 役割 | ログに現れる候補 | 確認ポイント |
|---|---|---|
| 認証 | auth.docker.io |
トークン取得が成功するか |
| Registry | registry-1.docker.io |
Manifest とタグ情報を取得できるか |
| レイヤー配送 | production.cloudflare.docker.com など |
Blob のダウンロードが最後まで続くか |
| 関連サービス | hub.docker.com |
検索やログイン画面だけで判断しない |
プロキシグループ名を PROXY とした場合の最小構成は次のようになります。実際に使用するグループ名が異なるなら、プロファイル内の名前に合わせて置き換えてください。ルールは上から評価されるため、Docker Hub の明示ルールを広域ルールより前に置きます。
rules:
- DOMAIN,auth.docker.io,PROXY
- DOMAIN,registry-1.docker.io,PROXY
- DOMAIN,hub.docker.com,PROXY
- DOMAIN-SUFFIX,docker.com,PROXY
- DOMAIN-SUFFIX,docker.io,PROXY
- DOMAIN-SUFFIX,cloudflare.docker.com,PROXY
- GEOIP,LAN,DIRECT
- MATCH,Final
DOMAIN-SUFFIX,docker.io は便利ですが、対象範囲が広くなるため、社内ミラーや自分で運用しているレジストリが同じ名前空間にないかを確認します。また、実際の Blob 配送先が Docker Hub のドメインではない場合、上記だけでは足りません。Pull 中のログに出た完全なホスト名を一時的にメモし、その名前に対して DOMAIN または適切な DOMAIN-SUFFIX を追加します。
Docker Desktop と Linux Engine のプロキシ設定
TUN で取り込める環境でも、Docker 自身のプロキシ設定を補助的に用意すると再現性が高まります。ただし、TUN と明示的な HTTP プロキシを無計画に重ねると、二重プロキシ、認証ヘッダーの不整合、内部レジストリへの誤送信が起きることがあります。どちらを主経路にするかを決め、変更前の設定を保存してください。
Docker Desktop では、アプリの設定にある Resources や Proxies の項目から、Docker Engine が外部へ接続する際の HTTP/HTTPS プロキシを指定できる版があります。Clash の混合ポートがローカルで 7890 だとすると、概念上は次のような値になります。ただし Docker Desktop は内部 VM を経由するため、127.0.0.1 がホストを指すとは限りません。GUI の説明に従い、Docker Desktop が案内するホストアドレスを使用してください。
"proxies": {
"http-proxy": "http://host.docker.internal:7890",
"https-proxy": "http://host.docker.internal:7890",
"no-proxy": "localhost,127.0.0.1,.local"
}
Linux の systemd 管理下にある Docker デーモンでは、環境変数を drop-in 設定で渡す方法が一般的です。
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf <<'EOF'
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,.local,registry.lan"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl show --property=Environment docker
この方法で設定するプロキシは、コンテナ内のアプリケーションへ自動的に渡るものではありません。主に Docker デーモンが Registry へアクセスする経路を対象にします。ビルド中に apt、npm、pip などが外部へ接続する場合は、BuildKit のネットワークやビルド引数、イメージ内の証明書設定を別途確認する必要があります。
TLS エラーと Pull 失敗をログから診断する
設定を変更したら、いきなり大きなイメージを取得するのではなく、問題を再現しやすい小さなタグで試します。次の表のように、エラーメッセージを段階へ分けると、修正対象を絞れます。
| 症状 | 疑う場所 | 最初に行う確認 |
|---|---|---|
no such host |
DNS、fake-ip、Docker DNS | ホストとコンテナの名前解決を比較 |
i/o timeout |
経路、ノード、FW | Clash ログに対象接続が出るか確認 |
TLS handshake timeout |
ノード品質、時刻、MTU | 時刻同期と別ノードでの再試行 |
connection reset |
出口、プロキシ競合、IPv6 | IPv4/IPv6 の差と直接接続の有無を比較 |
unauthorized |
認証トークン、レジストリ設定 | ログイン先とイメージ名を確認 |
unauthorized は通信経路が直ったあとに現れることもあります。つまり、以前は Registry まで到達できずタイムアウトしていたものが、TUN とルール修正によって認証処理まで進んだ結果です。この場合は失敗が悪化したのではなく、次の段階へ切り分けが進んだと考えられます。Docker Hub のレート制限、非公開リポジトリの権限、誤ったイメージタグも確認してください。
- 小さなイメージで再現する:
docker pull hello-world:latestを実行し、Clash の接続ログを同時に記録します。 - 認証と配送を分ける:
auth.docker.ioが成功したあと、どのホストで停止したかを確認します。 - ノードを一つだけ変更する:複数項目を同時に変更せず、ノード変更、DNS 変更、ルール変更を一つずつ試します。
- 直接接続と比較する:許可された検証環境で DIRECT と PROXY の結果を比較し、問題が経路依存かサービス依存かを判断します。
- 設定を整理する:解決後は一時的なキーワードルールや広すぎる例外を削除し、必要なホストだけを残します。
Docker Hub と Clash TUN に関する FAQ
ブラウザで Docker Hub を開けるのに、docker pull だけ失敗するのはなぜですか?
ブラウザはシステムプロキシを利用していても、Docker デーモンはその設定を参照しないことがあります。また、Docker Hub の画面、認証 API、Registry、Blob CDN は別ホストへ分かれているため、ブラウザでトップページを開けたことはイメージ取得の成功を保証しません。Clash TUN のログに Docker 関連ホストが現れるかを確認し、必要なら Docker デーモンへ明示的なプロキシを設定します。
TUN を有効にすれば Docker のプロキシ設定は不要ですか?
環境によります。ホスト上の Docker Engine が TUN のルートを正しく利用できるなら、TUN だけで動作することがあります。しかし Docker Desktop の内部 VM、Linux のネットワーク名前空間、企業ネットワークのポリシーによっては、デーモンへ明示的なプロキシを指定したほうが安定します。二つの経路を重ねる場合は、どちらが実際の出口かをログで確認してください。
DNS を 8.8.8.8 に固定すれば名前解決エラーは直りますか?
必ずしも直りません。Docker がその DNS へ直接問い合わせれば、Clash の分流や DNS 保護を迂回する可能性があります。まず Clash DNS、TUN の DNS hijack、Docker 内部リゾルバーの関係を整理し、ホストとコンテナの両方で同じ名前が期待どおり解決されるかを確認してください。
Docker Hub 以外の社内レジストリも TUN 経由になりますか?
TUN の対象範囲に含まれていれば取り込まれますが、社内レジストリは通常 DIRECT にするほうが適切です。NO_PROXY と Clash の DOMAIN-SUFFIX、LAN/社内 CIDR のルールが矛盾しないようにし、証明書や認証方式を変更しないまま接続できることを確認してください。
一部の VPN クライアントや単純なプロキシアプリは、ブラウザや対応アプリの通信だけを扱い、Docker デーモンの Registry/CDN 通信、DNS の取り込み、ホスト名ごとのログ確認まで一つの画面で管理できないことがあります。従来型の設定では、認証は通るのにレイヤー取得だけ失敗した際、原因をノード・DNS・ルールのどこへ戻すべきか分かりにくい場合もあります。Clash は TUN による透過的な通信取り込み、Mihomo の細かなドメインルール、DNS モードの選択、接続ログによる段階別の検証を組み合わせられるため、Docker Desktop と Linux Engine の両方で同じ考え方を適用しやすい点が強みです。Docker Hub Pull の経路を自分で確認できる構成を整えたい場合は、ダウンロードページから利用環境に合うクライアントを選び、まずは小さなイメージで安全に検証してみてください。