Docker Hubからイメージをpullするときにi/o timeoutやcontext deadline exceededが出ても、Clashのノードだけが原因とは限りません。重要なのは、docker pullを実行するターミナルではなく、イメージ取得を担当するDockerデーモンがプロキシを利用できているかどうかです。ターミナルのブラウザーやcurlは通るのにDockerだけ失敗する場合は、デーモン側のプロキシ設定、Clashのルール、Docker Desktopのネットワーク経路を順番に確認しましょう。

最初にエラーと通信経路を切り分ける

タイムアウトは、Docker Hubへの接続が一定時間内に完了しなかったことを示します。ただし、エラーの発生箇所は一つではありません。Docker Hubのレジストリに接続できない場合だけでなく、認証トークンを取得するサーバー、イメージレイヤーの配信先、DNS解決、プロキシへの接続のどこで止まっても、pull全体が失敗することがあります。

症状確認する場所最初の対応
i/o timeout、接続先へ到達できないデーモンのプロキシ、Clashのポート、ルーティングClashのHTTPポートへ接続できるかテスト
no such hostDNS、TUNモード、DNSルールドメイン解決とClashのDNS設定を確認
unauthorized、認証エラーDocker Hubのログイン状態、認証情報docker loginを実行して認証を確認
429 Too Many RequestsDocker Hubの利用制限ログイン状態とpull頻度を確認し、時間を置いて再試行
一部のレイヤーだけ遅い、途中で止まる配信先ドメイン、回線品質、MTUClashの接続ログで失敗した接続先を特定

まずClashを起動し、現在選択しているプロキシがブラウザーなどで利用できることを確認します。そのうえで、Dockerを実行している同じマシンからClashのHTTPポートへ接続してみてください。以下の例ではポートを7890としています。Clash Verge、Clash Verge Rev、Mihomoなどで実際に設定しているポートが異なる場合は、読み替えてください。

Clash経由の疎通テスト
curl -x http://127.0.0.1:7890 -I https://registry-1.docker.io/v2/
curl -x http://127.0.0.1:7890 -I https://auth.docker.io/

registry-1.docker.io/v2/への応答が401 Unauthorizedでも、ここでは必ずしも失敗ではありません。認証なしのリクエストに対して認証を求める正常な応答です。接続自体が成立しているかを確かめるテストとして扱いましょう。一方、接続拒否やタイムアウトになる場合は、指定したポートがClashのHTTPポートと一致するか、Clashの「LANからの接続を許可」設定が必要な環境では有効になっているかを確認します。

切り分けのポイント:curlのテスト成功は、ターミナルからClashへの経路があることを示します。しかしDockerデーモンが同じプロキシ設定を使っている証明にはなりません。次にデーモン側の設定を確認してください。

Dockerデーモンにプロキシを設定する

Linuxの一般的な構成では、docker pullの通信はDockerデーモンが行います。そのため、シェルでexport HTTP_PROXY=...を設定しただけでは、すでに起動しているデーモンに設定が反映されないことがあります。Clashが同じLinuxマシン上で動作している場合は、systemdのDockerサービスにプロキシ環境変数を渡す方法が実用的です。

次の例では、Clashがローカルの127.0.0.1:7890でHTTPプロキシを提供しているものとします。まずDockerサービス用の設定ディレクトリを作成し、ドロップイン設定を保存します。

Linux systemd向けDockerプロキシ設定
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null <<'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,::1"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

設定後、Dockerサービスが再起動したことを確認し、docker pullを再試行します。サービス再起動は実行中のコンテナに影響する可能性があるため、共有サーバーや本番環境では作業時間を選び、事前に運用上の影響を確認してください。環境変数が反映されているかは、次のコマンドで確認できます。

systemd設定とDocker情報の確認
systemctl show --property=Environment docker
docker info

出力に設定したプロキシが見当たらない場合は、ドロップインのファイル名や書式、Dockerサービス名を確認します。環境によってはサービス名がdocker以外であったり、Dockerをsystemdではなく別の方法で起動していたりします。また、Clashが別のコンテナや別のマシンで動いているなら、Dockerデーモンから見た127.0.0.1はClashのホストではありません。その場合はデーモンから到達できるホスト名またはIPアドレスを指定し、ファイアウォールでも接続を許可する必要があります。

NO_PROXYには、プロキシを経由させないローカルの宛先や社内レジストリを必要に応じて追加します。Docker Hubだけを通したいのに、広すぎる除外条件を設定すると外部通信までプロキシを迂回することがあります。反対に、社内レジストリを使う環境で除外がないと、内部宛ての通信がClashへ送られて接続できなくなる場合があります。

Docker DesktopとOSごとの設定を確認する

Docker Desktopでは、Docker Engineが仮想化環境内で動作する構成があります。この場合、ホストOSの127.0.0.1をエンジン内部から見ても、ホスト上のClashを意味しないことがあります。Linuxのsystemd設定例をそのまま適用するのではなく、Docker Desktopの設定画面にあるプロキシ設定を使い、Docker Engine向けのHTTP・HTTPSプロキシを設定してください。設定項目の名称や場所はDocker Desktopのバージョンによって異なるため、保存後にアプリを再起動し、Docker Engineへ反映されたことを確認します。

WindowsでClash Verge Revなどを使う場合も、ブラウザーのプロキシ設定とDocker Desktopのプロキシ設定は別のものとして考えます。Docker Desktopのエンジンがホスト側のプロキシを自動利用できないときは、Docker Desktopの設定でプロキシを明示します。Clashのポートに接続できるかをPowerShellから調べる際は、PowerShellの別名との混同を避けるためcurl.exeを使うと分かりやすくなります。

Windowsでのプロキシ疎通確認
curl.exe -x http://127.0.0.1:7890 -I https://registry-1.docker.io/v2/
docker info

macOSのDocker Desktopでも、ホストのClashポートとDocker Engine側の到達性を別々に確認してください。環境によっては、デスクトップアプリのプロキシ設定でシステムプロキシを利用する方法が最も簡単です。ただし、OSのシステムプロキシを変更しても、Docker Desktopのエンジン通信に必ず反映されるとは限りません。反映が不明な場合はDocker Desktopのプロキシ設定を明示し、docker infoの表示と実際のpull結果を照合します。

Clashのプロキシポートを0.0.0.0へ公開する場合は、ネットワーク上の他の機器から接続される可能性があります。必要な範囲だけに公開し、ファイアウォールで接続元を制限してください。プロキシ認証情報を設定ファイルや公開リポジトリへ平文で保存するのも避けましょう。

ClashのルールでDocker Hub関連通信を通す

デーモンがClashへ接続できても、ClashのルールがDocker Hub関連ドメインをDIRECTへ振り分けていれば、タイムアウトが続くことがあります。Docker Hubの通信はレジストリへの接続だけでなく、認証やイメージレイヤーの取得にも複数のドメインが関係します。Clashの接続画面またはログを開き、pullを実行した時刻にどのドメインが表示され、どのルールとプロキシグループが選択されたかを確認してください。

該当通信が意図せず直接接続されている場合は、利用中の設定形式と既存ルールの優先順位に合わせて、必要なドメインをプロキシグループへ振り分けます。次はMihomo系設定での概念例です。プロキシグループ名は実際の設定にある名前へ置き換え、同等のルールがすでにある場合は重複させないでください。

Docker Hub向けルールの例
rules:
  - DOMAIN-SUFFIX,docker.io,PROXY
  - DOMAIN-SUFFIX,docker.com,PROXY
  - DOMAIN,auth.docker.io,PROXY
  - MATCH,DIRECT

PROXYは例示用のグループ名です。実際の設定にある名前へ変更してください。ルールは一般に上から評価されるため、これらのルールを広い条件のMATCHより後ろへ追加すると、先に一致したルールが優先されて期待どおりに動きません。ルールを保存した後は設定を再読み込みし、ログで対象通信が指定したグループを通っていることを確かめます。

配信元のホスト名は、イメージやレジストリの構成、サービス側の変更によって異なることがあります。レジストリと認証先だけを許可してもレイヤーの取得が失敗する場合は、ログで実際に失敗したドメインを特定してからルールを調整しましょう。無関係なドメインを一括でプロキシへ送るより、必要な接続先だけを追加する方が、原因の追跡と通信管理が容易になります。

TUN・DNS・接続の安定性を見直す

DockerデーモンにHTTPプロキシを設定できない構成や、プロキシ設定を適用しても特定の接続だけ漏れる構成では、ClashのTUNモードが選択肢になります。TUNはOSのネットワーク経路を利用して通信を取り込む方式ですが、Docker Engineが仮想マシン内で動いている場合などは、ホスト側でTUNを有効にするだけで全通信が必ず捕捉されるとは限りません。まずはClashの接続ログにDocker Hub関連の接続が現れるかを確認し、OSのルーティングや仮想ネットワークの違いを考慮してください。

DNSエラーが出る場合は、ClashのDNS機能、OS側のDNS、Docker Engine側のDNSを区別して調べます。ホストでドメインを解決できても、デーモンやDocker Desktopの仮想環境から同じ名前を解決できるとは限りません。TUNとDNSを同時に変更すると原因が分かりにくくなるため、まず現在の設定を保存し、DNSの疎通、TUNの有効・無効、ルールの順に一つずつ変更してテストします。

接続が確立するもののダウンロードが長時間停止する場合は、選択中のノードの混雑やパケット損失も疑います。別の利用可能なプロキシグループへ切り替えて同じイメージを取得し、結果を比較してください。企業ネットワークやVPNとの併用では、MTUの不一致や経路の重複によって大きな転送だけが不安定になることもあります。設定変更後は、次のように小さなイメージからテストし、問題が解消したかを確認すると切り分けやすくなります。

小さなイメージでの再テスト
docker pull hello-world
docker pull alpine:latest

同じイメージを何度もpullするとき、すでにローカルにあるレイヤーは再利用されるため、テスト結果の比較にならないことがあります。必要に応じて別のタグを使うか、Dockerのpull出力で実際に通信が発生しているかを確認してください。診断のためだけに証明書検証を無効化したり、ファイアウォールを広範囲に停止したりするのは避けます。これらの変更はセキュリティを低下させるうえ、プロキシ経路の原因特定にも直結しません。

よくある質問

curlは成功するのにdocker pullだけ失敗するのはなぜですか?

多くの場合、curlを実行するシェルとDockerデーモンが別々のプロキシ設定を使っているためです。ターミナルで設定した環境変数がデーモンへ自動で渡るとは限りません。LinuxではsystemdのDockerサービス設定を、Docker Desktopではアプリ内のプロキシ設定を確認し、docker infoとClashの接続ログを照合してください。

レジストリの疎通テストで401が返るのは異常ですか?

https://registry-1.docker.io/v2/へ認証なしでアクセスした際の401 Unauthorizedは、認証が必要だと示す応答です。プロキシ経由でその応答を受け取れたなら、少なくともレジストリまでのHTTP接続は成立しています。実際のpullが認証エラーになる場合は、ネットワークタイムアウトと分けてdocker loginや認証情報を確認しましょう。

HTTPプロキシとTUNモードはどちらを使うべきですか?

Dockerデーモンに適切なプロキシ設定を渡せるなら、まずHTTPプロキシを使うと経路を把握しやすくなります。デーモンの構成上プロキシ設定が難しい場合はTUNを検討できますが、Docker Desktopの仮想ネットワークやDNSの影響を受けることがあります。どちらを選ぶ場合も、ClashのログでDocker関連通信を確認することが重要です。

大きなイメージだけタイムアウトするときは何を確認しますか?

小さなイメージは成功し大きなイメージだけ止まるなら、プロキシノードの混雑、パケット損失、VPNとの経路競合、MTUなどを確認します。別ノードでの比較とClashの接続ログを先に行い、DNSやルールの変更は必要な場合に限定してください。

Docker Hubのタイムアウトを解消するには、Clashのノードを切り替えるだけでなく、デーモンが実際にプロキシを利用しているか、接続先が適切なルールへ振り分けられているかを確かめることが近道です。疎通テストから始め、Docker Desktopまたはsystemdの設定、Clashのログ、DNSとTUNの順に切り分ければ、不要な設定変更を避けながら原因へ近づけます。設定を一つずつ見直したあとに小さなイメージで再試行し、必要ならプロキシ経路を含む接続ログを照合してください。