Docker Hub 拉取超时,先判断到底是哪一段链路出问题

搜索「Docker pull 超时」「Docker Hub 无法连接」或「Clash TUN 透明代理 Docker」的人,通常已经确认宿主机浏览器可以打开网页,却发现执行 docker pull nginx、docker pull alpine 时长时间停在 Pulling fs layer、Waiting 或 Head https://registry-1.docker.io/v2/: net/http: request canceled。这类故障并不一定是节点失效,也可能是 Docker 守护进程没有使用桌面端的系统代理,或者 DNS 解析先把 Registry 域名解析到了当前网络无法访问的地址。

Docker Hub 的一次镜像拉取并不是只访问一个域名。客户端通常先请求 registry-1.docker.io 获取认证信息,再访问 auth.docker.io,随后根据返回结果连接镜像仓库、对象存储或 CDN。浏览器能够访问 Docker Hub 首页,只能证明浏览器这条路径正常,并不能证明后台运行的 dockerd、容器网络命名空间以及每个镜像层下载地址都能通过同一代理。排查时应把问题拆成代理是否接管、DNS 是否正确、规则是否命中、Docker daemon 是否继承代理四个部分。

本文以 Mihomo(Clash.Meta)内核为例。不同 Clash 图形客户端的菜单名称可能略有差异,但 TUN、DNS、规则和 Docker daemon 的网络原理基本一致。请使用你有权访问的镜像仓库,并遵守所在网络环境与服务条款。

理解流量路径:系统代理不等于 Docker 已经走 Clash

在 Windows 或 macOS 上,打开 Clash 的系统代理后,浏览器通常会读取 HTTP、HTTPS 或 SOCKS 代理环境;但 Docker Engine 的网络请求由后台 daemon 发起。Linux 上的 dockerd 常由 systemd 启动,Windows 与 macOS 上也可能由 Docker Desktop 内部虚拟机运行。因此,浏览器能翻、终端能翻,不代表 Docker daemon 必然能翻。如果只设置了 Clash 的系统代理而没有设置 daemon 代理,最常见的结果就是 Docker Registry 请求直接从宿主机默认出口发出。

TUN 模式的作用,是在系统网络层创建虚拟网卡,将原本不会读取代理变量的 TCP、UDP 连接透明交给 Mihomo,再依据域名、IP 和进程信息进行分流。它比单纯的系统代理覆盖范围更广,适合 Docker、Git、虚拟机和部分后台服务。不过 TUN 并不是「打开后所有请求自动成功」:如果 DNS 请求仍由本地网络处理、规则把 Registry 误判为直连,或者 Docker Desktop 的流量隔离在另一层虚拟网络中,仍然会出现超时。

建议先画出一条实际链路:docker CLI → dockerd → DNS 解析 → registry/auth/CDN → Clash TUN → 代理策略组 → 远端节点。其中任意一段没有进入 Clash,连接日志里就不会出现对应域名。不要只盯着终端最后一行错误,应该在执行 docker pull 的同时打开 Mihomo 连接面板,观察是否出现 registry-1.docker.io、auth.docker.io 和实际下载域名。

Mihomo Clash 的 TUN 与 DNS 基础配置

下面是一份适合排障的基础片段。它不包含节点、订阅和策略组定义,因此不能直接替代你的完整配置;你需要把 PROXY 替换为实际存在的策略组名称。配置的重点是开启 TUN、让 DNS 请求进入 Mihomo,并避免 fake-ip 与局域网访问发生冲突。

mixed-port: 7890
allow-lan: true
mode: rule
log-level: info

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  fallback:
    - https://9.9.9.9/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

proxies-groups:
  - name: PROXY
    type: select
    proxies:
      - your-node
      - DIRECT

rules:
  - DOMAIN-SUFFIX,docker.io,PROXY
  - DOMAIN,registry-1.docker.io,PROXY
  - DOMAIN,auth.docker.io,PROXY
  - DOMAIN-SUFFIX,docker.com,PROXY
  - MATCH,DIRECT

这里的 dns-hijack 负责把经过 TUN 的 53 端口请求交给 Mihomo;auto-route 与 auto-detect-interface 用于自动建立路由并识别出口网卡。若你的网络中已经有其他 DNS 服务、旁路由或企业内网解析,不要机械复制全部选项,应先确认谁负责解析。Docker Hub 的域名解析结果可能随着地区和时间变化,规则应优先使用域名匹配,而不是把某次解析得到的 IP 永久写死。

启用 fake-ip 后,部分局域网设备、内网域名或 Docker 自定义网络可能出现解析异常。若 Clash 日志显示请求已命中,但 Docker 仍然无法连接,可临时切换为 enhanced-mode: redir-host 做 A/B 测试;不要在没有备份的情况下同时修改 TUN、DNS 和规则。

为 Docker Hub 单独建分流规则与策略组

仅写一条 DOMAIN-SUFFIX,docker.io,PROXY 往往不够。Docker Hub 的认证、仓库和镜像层下载可能落在不同的主机名上,某些区域还会返回第三方 CDN 地址。推荐把 Docker 流量单独放入 DOCKER 策略组,这样可以在出现失败时快速切换节点,不必影响浏览器、办公软件和其他代理业务。

proxy-groups:
  - name: DOCKER
    type: select
    proxies:
      - PROXY
      - DIRECT

rules:
  - DOMAIN,registry-1.docker.io,DOCKER
  - DOMAIN,auth.docker.io,DOCKER
  - DOMAIN-SUFFIX,docker.io,DOCKER
  - DOMAIN-SUFFIX,docker.com,DOCKER
  - DOMAIN-SUFFIX,cloudflare.com,DOCKER
  - MATCH,DIRECT

规则的先后顺序非常关键。宽泛的 GEOIP,CN,DIRECT、远程规则集或默认兜底规则如果排在 Docker 规则之前,可能会抢先把请求判定为直连。实际配置中应把 Docker 的精确域名放在 GEOIP、IP-CIDR 和大范围规则之前。对于镜像层下载时出现的新域名,不要凭猜测添加大量公共云后缀;先从 Mihomo 连接日志读取真实 SNI,再添加最小范围的 DOMAIN 或 DOMAIN-SUFFIX 规则。

现象 优先检查对象 处理方向
认证阶段超时 auth.docker.io 确认域名命中 DOCKER,检查节点 TLS 与 DNS
Registry 可访问但镜像层失败 日志中的 CDN 或对象存储域名 为真实下载域名补充规则,不要只代理 docker.io
规则模式失败,全局模式成功 规则顺序与策略组选择 移动精确规则到前面,确认没有被 GEOIP 抢答
所有域名都没有连接记录 TUN 权限、路由和 Docker Desktop 网络 检查内核权限、虚拟网卡及宿主机防火墙

Docker daemon 代理适配:Linux、Docker Desktop 与环境变量

如果你使用 Linux 原生 Docker Engine,最稳定的做法是为 systemd 服务显式设置代理,而不是只在当前 Shell 里执行 export HTTP_PROXY。Shell 环境变量只影响随后启动的命令,已经在后台运行的 dockerd 不会自动继承。假设 Clash 在宿主机监听 127.0.0.1:7890,可以创建 systemd 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,::1,.local"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl show --property=Environment docker

如果 Clash 与 Docker daemon 不在同一台机器上,不能填写远程机器的 127.0.0.1,因为这代表 Docker 所在机器自身。此时应让 Clash 监听局域网地址,设置合理的访问控制,并把代理地址改为 Clash 主机的内网 IP。allow-lan: true 只解决监听范围问题,不等于安全授权;请避免把混合端口直接暴露到公网。

Docker Desktop 的情况更复杂:CLI 可能在宿主机,daemon 却运行在 Desktop 管理的 Linux 虚拟机内。此时宿主机系统代理、Clash TUN 和 Desktop 内部网络可能形成多层路径。优先在 Docker Desktop 的代理设置中填写可达的 HTTP 代理,再用连接日志确认请求是否进入 Clash;如果只依赖宿主机回环地址,虚拟机通常无法访问宿主机的 127.0.0.1。修改代理后重启 Docker Desktop,并检查 daemon 是否重新加载配置。

代理变量中的 NO_PROXY 应保留 localhost、回环地址、内网域名和你明确需要直连的私有 Registry。若把 docker.io 或所有域名加入 NO_PROXY,Docker 会绕过代理,导致你误以为 TUN 没有生效。

日志诊断与常见网络错误修复

配置完成后,不要直接反复拉取大型镜像。先从小请求开始验证:使用 docker login 或执行 curl -v https://registry-1.docker.io/v2/,同时观察 Clash 的连接日志。Registry 返回 401 Unauthorized 并不一定是故障,它通常说明网络已经到达服务端,只是请求缺少认证令牌;相反,持续的 i/o timeout、context deadline exceeded、connection reset by peer 更值得从代理链路排查。

  1. 确认 daemon 状态:执行 docker info,确认客户端连接的是预期的 Docker Engine,而不是远程 Context 或另一套 Desktop 虚拟机。
  2. 确认 DNS:使用 getent hosts registry-1.docker.io、nslookup auth.docker.io 或系统等效命令,检查解析是否失败、是否出现明显异常的内网地址。
  3. 确认代理命中:执行一次短请求,在 Mihomo 面板过滤 docker,查看域名、进程、策略组和最终节点是否符合预期。
  4. 确认规则顺序:如果连接显示为 DIRECT,检查 Docker 精确规则是否被 GEOIP、IP-CIDR 或远程规则集提前匹配。
  5. 确认 MTU 与协议:若 TLS 能建立但大镜像层经常中断,可测试更稳定的节点,检查 TUN 网卡 MTU,并在必要时暂时关闭对 UDP 或 QUIC 的激进设置。
  6. 清理并重试:网络恢复后再执行 docker system prune 前先确认没有重要的停止容器和缓存;通常只需重新运行 docker pull image:tag,不必贸然删除全部数据。

遇到 no such host,重点看 DNS;遇到 proxyconnect tcp,重点看 Docker daemon 的代理地址和端口;遇到 server gave HTTP response to HTTPS client,通常是把 HTTP 明文代理、镜像仓库地址或 TLS 配置混在了一起;遇到 manifest unknown 或 pull access denied,则更可能是镜像标签、私有仓库权限或登录凭据问题,而不是 Clash 透明代理故障。把错误分类后再改配置,能避免用换节点去解决权限问题。

常见问题:Docker 与 Clash TUN 配置疑问

打开 Clash 系统代理后,为什么 Docker 还是超时?

因为系统代理主要面向会读取代理设置的应用,Docker 请求通常由后台 dockerd 发起。请为 Docker daemon 显式配置 HTTP_PROXY、HTTPS_PROXY,或使用能够接管该流量的 TUN 模式;如果是 Docker Desktop,还要确认内部虚拟机可以访问代理地址。

Docker 使用 fake-ip 时必须改成 redir-host 吗?

不必须。fake-ip 能减少部分 DNS 污染和解析绕行问题,但可能影响局域网域名、容器网络或某些需要真实地址的服务。建议先用当前模式验证,只有在日志明确显示解析异常时,再临时切换 redir-host 做对照测试。

只代理 docker.io,为什么镜像层仍然下载失败?

认证和镜像层可能来自不同的 CDN 或对象存储域名。请在拉取过程中查看 Mihomo 连接日志,找出实际出现的 SNI,再为这些真实域名补充分流规则,同时确认它们没有被更早的直连规则命中。

把 Clash 代理端口开放给 Docker 或局域网安全吗?

应限制监听范围和访问来源,只允许可信局域网网段访问,并避免将混合端口暴露到公网。修改 allow-lan、防火墙和 Docker daemon 代理后,都应检查监听地址与日志,防止开放代理被滥用。

相比之下,部分同类代理客户端只提供系统代理开关,缺少 TUN 流量接管、DNS 劫持和可读的连接日志;传统 VPN 方案也常把 Docker Registry、认证服务与镜像 CDN 粗略塞进同一条隧道,遇到解析漂移或后台 daemon 不继承代理时,用户很难判断究竟是网络、规则还是 Docker 本身出错。Clash 配合 Mihomo 内核则可以通过 TUN 接管非代理感知应用,用独立的 DOCKER 策略组拆分 Registry 流量,并利用规则顺序、DNS 配置和实时日志逐项验证链路,无论是 Linux 原生 Docker Engine 还是 Docker Desktop,都能建立更清晰、可复现的排障流程。

如果你还没有配置 Clash 客户端,可以前往客户端下载页选择适合系统的版本,再按照本文思路完成 Docker Hub 分流与 TUN 调试。

→ 立即免费下载 Clash,开启流畅上网新体验

前往本站下载页获取客户端