はじめに
Docker Hub からイメージを取得しようとしたとき、「i/o timeout」「context deadline exceeded」「TLS handshake timeout」などのエラーが表示されることがあります。ブラウザでは問題なくウェブサイトを閲覧できるのに、docker pull だけが失敗する場合、回線全体が切断されているとは限りません。
最も多い原因は、ブラウザと Docker が別々の通信経路を使用していることです。Clash のシステムプロキシを有効にしても、Docker Engine は独立したバックグラウンドサービスとして動作するため、自動的に Clash のプロキシを利用するとは限りません。本記事では、ノードの確認、Clash のルール設定、Docker デーモンへのプロキシ設定、DNS と証明書の確認まで、原因別に順番を追って解説します。
この記事の目標
ブラウザだけでなく Docker Engine の通信も適切な Clash 経由にし、Docker Hub から安定してイメージを取得できる状態を作ります。
なぜDocker pullだけ失敗するのか？
Docker Hub のイメージ取得は、ブラウザでページを開く処理より複雑です。まず registry-1.docker.io に接続し、認証トークンを取得した後、イメージのマニフェストと複数のレイヤーを別々にダウンロードします。そのため、どこか一つのドメインや通信経路が失敗するだけでも、最終的に docker pull 全体がエラーになります。
| 症状 | 考えられる原因 | 確認する場所 |
|---|---|---|
| ブラウザは使えるがpullだけ失敗 | Dockerデーモンがプロキシ未設定 | Dockerサービスの環境変数 |
| 名前解決で失敗する | DNS遅延、DNS汚染、ClashのDNS競合 | nslookup、ClashのDNS設定 |
| TLS handshake timeout | ノードの混雑、MTU、HTTPS接続の不安定 | Clashのログ、別ノードでの接続 |
| 認証後にレイヤー取得が止まる | レジストリ関連ドメインのルール漏れ | ルールログ、接続先ドメイン |
また、Docker Desktop を使用している場合は、ホスト側の Docker CLI と、内部で動作する Docker デーモンの設定が異なることがあります。ターミナルで環境変数を設定しただけでは、バックグラウンドのサービスに反映されないケースがあるため注意してください。
1Clashノードと基本経路を確認する
いきなり YAML を編集する前に、使用中のノード自体が Docker Hub と相性のよい状態か確認します。Clash Verge Rev や Mihomo クライアントでプロファイルを読み込み、プロキシグループから応答速度だけでなく、実際の接続成功率が高いノードを選択してください。低遅延でも海外サイトへの接続が不安定なノードは、イメージの大容量レイヤー取得に向いていません。
- Clash クライアントを起動し、プロファイルが有効になっていることを確認します。
- 使用するプロキシグループで、通信が安定しているノードを選択します。
- System Proxy を有効にし、ブラウザで Docker Hub のページを開きます。
- Clash の「Logs」または「Connections」で、接続がプロキシグループを通っているか確認します。
切り分けのポイント
同じノードでブラウザは正常でも、Docker のログに接続記録が出ない場合は、ノードではなく Docker デーモンのプロキシ設定が原因である可能性が高いです。
端末から次のようなコマンドを実行すると、基本的な HTTPS 到達性も確認できます。これは Docker の通信そのものを完全に再現するものではありませんが、DNS や TLS の初期障害を見つけるのに役立ちます。
401 Unauthorized が返る場合でも、レジストリが応答しているという意味なので、必ずしも異常ではありません。タイムアウトや名前解決エラーが返る場合は、Clash の接続ログとノードを先に確認しましょう。
2Docker Hub向けのClashルールを追加する
Docker Hub の通信を確実にプロキシへ送るには、関連ドメインを専用のプロキシグループへ割り当てます。グループ名は自分の設定に合わせて変更してください。以下ではグループ名を Docker としています。
DOMAIN-SUFFIX は対象ドメインとそのサブドメインをまとめて指定できます。一方、registry-1.docker.io のように重要な接続先を DOMAIN で明示すると、認証やレジストリ本体のルール漏れを確認しやすくなります。すでにプロファイルの末尾に広い範囲の MATCH,DIRECT がある場合でも、Docker 用ルールをその前に置くことが重要です。
ルールの順番に注意
Clash は上から順番にルールを評価します。Docker 用ルールを既存の最終ルールより後ろに追加すると、先に別のルールへ一致してDIRECTになる場合があります。
Clash Verge Rev の場合は、プロファイルの編集機能や Merge 設定を使ってルールを追加できます。プロバイダーから配布された設定を直接書き換えると、次回更新時に消える可能性があるため、可能であれば上書き用の設定として管理してください。設定を保存した後は、プロファイルを再適用し、Clash の接続画面で auth.docker.io と registry-1.docker.io が意図したグループに入っているか確認します。
3Dockerデーモンにプロキシを設定する
ここが最も重要な手順です。Clash のシステムプロキシは、一般的に HTTP プロキシを利用するアプリケーションへ影響しますが、Docker Engine のサービス通信まで自動的に変更するとは限りません。Docker デーモンが動作する環境から、Clash の mixed port または HTTP ポートへ接続できるように設定します。
Linuxでsystemdを使う場合
Linux の Docker Engine では、systemd のドロップイン設定を利用する方法が一般的です。Clash が同じホストで動作し、HTTP プロキシを 127.0.0.1:7890 で待ち受けている例を示します。実際のポートは Clash の設定画面で確認してください。
設定後、環境変数が表示されればサービス側への反映を確認できます。そのうえで次を実行します。
127.0.0.1 は Docker デーモンが動作するホスト自身を指します。Docker Engine を別の仮想マシン、コンテナ、リモートサーバーで動かしている場合、そこから見た 127.0.0.1 はClashが動作するPCではありません。その場合は、Clash の待ち受けアドレス、ファイアウォール、LAN 内のアクセス許可を見直す必要があります。
Docker Desktopで設定する場合
Docker Desktop では、アプリケーションの設定画面にあるプロキシ項目を優先してください。バージョンによって表示名は異なりますが、通常は「Settings」内の「Resources」または「Proxies」付近にあります。手動プロキシを選択し、Clash の HTTP または mixed port を入力して保存した後、Docker Desktop を再起動します。
Docker Desktop が仮想環境内で Engine を実行している場合、ホストのClashポートが仮想環境から到達可能かも確認してください。設定を変更しても接続ログが出ないときは、Docker Desktop 側のプロキシ設定、Clash の「Allow LAN」、OS のファイアウォールを順に確認します。
4DNS・TLS・MTUを確認する
プロキシ設定後もタイムアウトが続く場合は、名前解決やパケットサイズの問題を確認します。Docker のエラーが常に同じ場所で止まるとは限らないため、複数のイメージや別ノードで試して、再現条件を整理することが大切です。
DNSの確認
registry-1.docker.io と auth.docker.io が解決できるかを確認します。
Clash の DNS を有効にしている場合でも、Docker デーモンがホストの DNS を使うのか、Clash の仮想 DNS を使うのかは構成によって異なります。TUN モードと Docker の仮想ネットワークを併用すると、DNS の経路が複雑になることもあります。まずはホスト上で名前解決が成功していることを確認し、必要に応じて信頼できる DoH または通常の DNS を設定してください。
TLSとMTUの切り分け
TLS handshake timeout が頻発する場合、ノードの混雑や経路上のパケット断片化が考えられます。Clash の別ノードへ切り替え、同じイメージを再取得してください。別ノードで成功するなら、YAML を何度も変更するよりノードを変更する方が効果的です。
VPN、TUN、Docker の仮想ネットワークを重ねている環境では、MTU が大きすぎると通信が不安定になることがあります。すべての環境で変更が必要なわけではありませんが、特定のレイヤーだけ取得が止まる場合は、仮想インターフェースの MTU を少し下げて再テストします。変更前の値を記録し、改善しなければ元に戻してください。
証明書エラーの場合
x509: certificate signed by unknown authority は、タイムアウトとは別の問題です。システム時刻、CA証明書、企業プロキシのSSL検査を確認し、安易に証明書検証を無効化しないでください。
5設定後のテストと安全な運用
変更後は、いきなり本番用の大きなイメージを取得するのではなく、小さなイメージで段階的に確認します。まず hello-world、次に nginx などを試し、Docker のログと Clash の接続ログを同時に確認します。Clash 側に対象ドメインの接続が表示され、Docker 側ではレイヤーが順番に完了すれば、基本的な経路は正しく動作しています。
認証情報を入力する際は、共有端末や信頼できないプロキシを避けてください。Docker Hub のユーザー名やアクセストークンは、Clash のログに表示されるURLへ直接含めないようにし、設定ファイルを公開リポジトリへ保存しないことも重要です。
- 最小権限： Docker Hub では必要な操作だけを許可するアクセストークンを使用します。
- ログ確認： トークンやパスワードが表示されていないか、Clash と Docker のログを確認します。
- ルールの限定： Docker 関連ドメインだけをプロキシし、不要な全通信プロキシは避けます。
- 再現テスト： ノード変更前後で同じイメージを試し、問題が設定か回線かを分けます。
なお、プロキシ経由で取得したイメージが安全になるわけではありません。利用するイメージの配布元、タグ、ダイジェストを確認し、本番環境では可能な限り固定タグやイメージダイジェストを使ってください。ネットワークの問題を解決する設定と、コンテナのサプライチェーンを守る対策は別々に考える必要があります。
よくある質問
Q1. ClashのSystem ProxyをオンにすればDockerも使えますか？
必ずしも使えるとは限りません。System Proxy は主にユーザーアプリケーション向けの設定であり、Docker Engine は独立したサービスとして動作します。Linux では systemd のサービス設定、Docker Desktop ではアプリ内のプロキシ設定を追加してください。
Q2. ClashのどのポートをDockerに指定すればよいですか？
Docker のHTTPプロキシとして利用できるポートを指定します。一般的には Clash の HTTP ポートまたは、HTTP と SOCKS の両方に対応する mixed port です。Socks 専用ポートを HTTP_PROXY に指定しても動作しない場合があるため、クライアントのポート一覧を確認してください。
Q3. Docker HubのドメインをすべてDIRECTにしてもよいですか？
通信できる環境なら可能ですが、接続経路が不安定な場合はプロキシの方が安定することがあります。まず関連ドメインを同じプロキシグループへ割り当て、接続成功後に必要なドメインだけDIRECTへ戻す方法が安全です。
Q4. 設定後も直らない場合、何を再起動すべきですか？
まず Clash のプロファイルを再適用し、次に Docker Engine または Docker Desktop を再起動します。Linux では systemctl daemon-reload の後に Docker を再起動してください。それでも改善しなければ、別ノード、別イメージ、別ネットワークで試し、DNS・ノード・デーモン設定のどこに問題があるかを切り分けます。
Docker のタイムアウトは、Clash のノード品質だけでなく、Docker デーモンが実際にどのプロキシを使っているか、関連ドメインが正しいルールに一致しているか、DNS と仮想ネットワークが競合していないかによって発生します。ブラウザの表示結果だけで判断せず、Docker のサービス設定と Clash の接続ログを照合することが最短の解決方法です。