ブラウザは使えるのに docker pull が失敗する理由

ブラウザで Docker Hub を開けても、ターミナルからの docker pull が成功するとは限りません。ブラウザは OS のシステムプロキシ設定を参照できますが、Docker CLI の通信は多くの場合、コマンドを実行した端末ではなくDocker デーモンが行います。そのため、シェルに HTTP_PROXY や HTTPS_PROXY を設定しても、デーモン側にプロキシが設定されていなければイメージ取得には反映されないことがあります。

失敗時の表示も、原因を一つに絞る手掛かりとしては不十分です。認証トークンの取得で止まる場合、レイヤーを配信する CDN への接続でタイムアウトする場合、DNS の応答が遅い場合は、いずれも最終的に「pull に失敗した」と見えます。まず Clash の接続画面やログで、失敗した時刻に Docker 関連の通信が現れるかを確認し、ノード、モード、ルール、DNS の順に調べると無駄な設定変更を避けられます。

ここでは Linux の Docker Engine、macOS／Windows の Docker Desktop、Clash Verge Rev や Mihomo などのクライアントを使う環境を想定します。画面名はクライアントやバージョンで異なりますが、確認する原則は共通です。組織やクラウドの管理下にある端末では、許可されたネットワーク設定と管理者の指示を優先してください。

ℹ 最初に覚えておく点：docker pull の通信主体は CLI と同じとは限りません。Clash のログに該当通信が出ない場合は、ノードを何度も切り替える前に、Docker デーモンまたは Docker Desktop がプロキシを利用しているかを確認します。

最初に切り分ける：Docker Engine と Docker Desktop

まず、Docker をどの形で動かしているかを確認します。Linux では Docker Engine がホスト上のサービスとして動き、シェルとは別の環境で外部へ接続します。macOS と Windows の Docker Desktop では、Linux 仮想マシン上のエンジンとデスクトップアプリの設定が関係します。WSL、リモートサーバー、開発コンテナから操作している場合は、コマンドを入力した端末の OS と、実際に Docker デーモンが動く場所が異なることもあります。

次に、失敗するコマンドを一つだけ決めて再現します。タグを省略したイメージは既定タグの取得を試みるため、比較にはタグを明示した既知のイメージを使うと条件が揃います。実行した時刻、イメージ名、エラー全文を控え、同じ時間帯の Clash の接続ログを確認してください。認証先らしい通信だけが記録されるのか、イメージデータらしい通信まで進むのかによって、問題が起きている段階を絞れます。

ブラウザで Docker Hub のトップページを開けることは、Docker の通信が通る証拠にはなりません。一方、ホストのターミナルからプロキシ経由の HTTPS 接続が成功するなら、Clash の待受ポートとノードの基本疎通は確認できます。その結果と docker pull の結果を分けて記録すれば、「Clash 全体が使えない」のか「Docker 側だけがプロキシを使っていない」のかを見分けやすくなります。

ノードと Clash のモードを確認する

最初の試験では、複雑なルール変更をせず、Clash のプロキシグループから応答の安定したノードを一つ選びます。選んだノードが実際にアクティブになっているか、遅延測定だけでなく通常の HTTPS 通信も成立するかを確かめてください。遅延テストが成功しても、認証や大容量のイメージレイヤー転送が同じ品質で通るとは限りません。小さなリクエストは成功するのに pull が毎回途中で止まる場合は、帯域、接続の維持、ノードの混雑も候補になります。

Clash のモードが Rule なら、最終的な通信先は設定ルールとその順序で決まります。Global に一時的に切り替えるテストは、ルールが原因かどうかを調べるのに役立ちますが、恒久設定として常に使う必要はありません。Global では成功し、Rule では失敗するなら、Docker Hub 関連の接続が意図しないポリシーへ流れている可能性があります。どちらでも失敗する場合は、デーモンのプロキシ設定や DNS、ノードの状態を引き続き確認します。

TUN は、システムプロキシを参照しないプロセスの通信も捕捉したい場合に候補となります。ただし、TUN を有効にしただけで Docker Engine や Docker Desktop の全通信が必ず期待どおりに流れるわけではありません。仮想マシン、WSL、リモート Docker ホストが関わる構成では、通信が通るネットワーク境界を特定する必要があります。まずアプリ側のプロキシ機能やデーモン設定を確認し、それで届かない通信を補う手段として TUN を検討するのが安全です。

ルールと接続ログから接続先を特定する

Docker Hub からの取得では、単一のホストだけが使われるとは限りません。認証、レジストリとのやり取り、イメージレイヤーの配信など、処理段階によって接続先が変わることがあります。よく見かける名前として auth.docker.io や registry-1.docker.io がありますが、データ配信の接続先や経路は環境や時期によって変化し得ます。ドメイン名のリストをそのまま固定ルールにするのではなく、失敗した時刻の Clash ログと Docker のエラーから実際の接続先を確認してください。

Rule モードでログに接続先が出ている場合は、その接続に適用されたルール名、最終的なポリシー、選択中のノードを一緒に見ます。意図しない DIRECT や別のプロキシグループに流れているなら、該当するホストを既存ルールより前に配置する必要があるかもしれません。上位に広いルールや別のルールセットがあると、後から追加したルールまで評価されない場合があります。変更後は設定を再読み込みし、同じイメージで結果を比較しましょう。

接続ログに Docker 関連の通信がまったく現れないなら、Clash のルールを追加する前に、Docker の接続が Clash の捕捉範囲に入っているかを調べます。ログに通信が現れているのに一部だけ失敗する場合は、認証とレイヤー取得が異なる経路に割れていないかを確認します。設定例を作るときも、実測していない CDN ホストを推測で追加せず、ログに現れた接続先を一つずつ検証することが大切です。

Docker デーモンと Docker Desktop のプロキシ設定

Linux の Docker Engine では、シェルの環境変数とデーモンのプロキシ設定を区別します。シェルで HTTPS_PROXY を設定しても、サービスとして起動しているデーモンがその値を引き継ぐとは限りません。Docker Engine の公式ドキュメントに従い、利用中のバージョンや起動方式に合ったデーモン用設定を行い、サービスを再起動して反映を確認してください。企業環境では、認証情報を含むプロキシ URL を共有ログや設定ファイルに不用意に残さないよう注意が必要です。

Docker Desktop では、アプリの設定画面にあるプロキシ関連項目を確認します。OS のシステムプロキシを使う構成と、手動でプロキシのアドレスを指定する構成では、必要な入力内容が異なります。Clash の mixed-port を使う場合は、Docker Desktop が動作する環境からそのアドレスとポートへ到達できるかを確認してください。ホストの 127.0.0.1 が仮想マシンやコンテナ内部から見た同じホストを指すとは限らないため、ポート番号だけを合わせても接続できないことがあります。

プロキシ設定の反映後は、Docker Engine または Docker Desktop を再起動してから同じ pull を試します。設定変更の前後で Clash の接続ログに差が出るか、Docker の状態表示に想定したプロキシが反映されているかも確認しましょう。設定を一度に複数変えると、何が効いたのか分からなくなります。まずデーモン側のプロキシだけを追加し、結果を記録してから次の変更へ進んでください。

DNS、TLS、タイムアウトを区別する

エラーが名前解決の失敗を示すなら、Clash の DNS 設定だけでなく、Docker デーモンがどの DNS を使っているか、ホストや仮想マシンの DNS が別の設定に固定されていないかを確認します。ブラウザの名前解決が成功しても、Docker Desktop 内部やリモートホストの DNS が同じとは限りません。Clash の DNS を変更した場合は、設定の再読み込み後に一度だけ再試行し、接続ログで解決されたホストと処理結果を見比べます。

TLS エラーや証明書検証エラーが出る場合は、時刻のずれ、企業ネットワークの TLS 検査、独自 CA の設定、途中のプロキシによる接続処理を確認します。原因を切り分けるために証明書検証を無効化する方法は、安全性を大きく損なうため恒久対策にしてはいけません。ネットワーク管理者が TLS 検査を運用している環境では、Docker デーモンと Desktop が必要な証明書を信頼できるよう、公式の手順に沿って管理者と調整します。

「タイムアウト」だけが表示される場合は、発生する段階も重要です。開始直後に止まるなら、認証やレジストリへの接続、DNS を疑います。レイヤーのダウンロード中に一定時間で止まるなら、ノードの帯域、CDN への経路、通信の維持、Docker 側のプロキシ設定を調べます。複数のタグや別の小さなイメージでも同じ症状かを比較すれば、特定イメージの問題とネットワーク全体の問題を分けやすくなります。

変更後の確認とよくある質問

検証では、毎回同じイメージ、同じモード、同じノードを使い、変更した項目を一つに絞ります。まずホスト側から Clash の待受ポートを通した HTTPS 接続を確認し、その後に Docker デーモンから pull を実行します。前者だけ成功して後者が失敗するなら、Docker 側のプロキシ継承または仮想ネットワークが有力です。両方失敗するなら、Clash のノード、待受ポート、ルール、DNSを先に見直します。成功した場合も、別のタグで再確認して一時的な復旧でないことを確かめてください。

シェルで HTTPS_PROXY を設定したのに pull が失敗するのはなぜですか？

docker pull の実際の通信を Docker デーモンが担当する構成では、シェルの環境変数がデーモンに引き継がれないことがあります。Linux Engine ならデーモン側のプロキシ設定、Docker Desktop ならアプリ内のプロキシ設定を確認し、変更後に該当サービスやアプリを再起動してください。

TUN モードを有効にすれば必ず直りますか？

必ず直るわけではありません。TUN はシステムプロキシを使わない通信の捕捉に役立つ場合がありますが、Docker Desktop の仮想マシンやリモート Docker ホストでは、通信が通る境界や経路が別にあります。まず Docker の実行場所と Clash のログを確認し、必要なら TUN とデーモン側プロキシを個別に検証してください。

Docker Hub のドメインをまとめてプロキシルールに追加してよいですか？

推測したドメインを広く追加するのではなく、失敗時のログに現れた接続先と適用ルールを確認してから必要なものだけを追加します。認証とレイヤー配信で接続先が異なることがあるため、pull の全段階で結果を見て、ルール順も合わせて確認してください。

curl は成功するのに docker pull だけ失敗する場合は？

curl を実行したホストと Docker デーモンが同じネットワーク環境にいるとは限らず、curl と Docker が参照するプロキシ設定も異なる場合があります。Docker Desktop の設定、Linux デーモンの設定、WSL やリモート接続の有無を確認し、Clash のログに pull の通信が現れるかを比較してください。

Docker Hub の pull 障害では、ブラウザ用プロキシ設定だけで対処しようとすると、Docker デーモンや仮想環境との境界が見えにくくなります。別の VPN クライアントや手動ルールだけで運用する方法もありますが、通信主体ごとの設定場所や接続ログを確認しづらいことがあります。Clash V.CORE なら、ノードとモードを切り替えながら接続ログを確認し、Docker の通信がどのルールと出口を通ったかを追いやすくできます。設定を段階的に試したい方は、ダウンロードページから利用環境に合うクライアントを確認してください。