Docker Hub 拉取超时:Clash 配置排查与修复

先弄清:Docker Hub 超时到底卡在哪一层

docker pull 超时,不见得是 Docker Hub 挂了。同样的报错可能来自好几个地方:域名没解析出来、TLS 连接建不起来、镜像清单请求被拦、分层文件下得太慢,或者 Docker 引擎压根没用你在桌面客户端里配的代理。尤其在 Windows、macOS 上用 Clash Verge Rev、Clash for Windows 或 ClashX 时,浏览器能上网只说明浏览器那条路是通的,证明不了 Docker daemon 也能借同一个代理出去。

常见报错有 i/o timeout、Client.Timeout exceeded while awaiting headers、context deadline exceeded、net/http: TLS handshake timeout,还有拉到某一层时长时间停在 Downloading。hub.docker.com 能打开、docker pull nginx 却失败,先查 Docker 引擎的代理设置,以及 registry-1.docker.io、认证服务和 CDN 有没有分流到位;网页和命令行都不通,就先查 Clash 节点、DNS 和系统网络。

💡
快速定位顺序

顺序是:先看 Clash 代理端口在不在监听,再测域名解析和 HTTPS,最后查 Docker daemon 有没有拿到代理。查的时候 Clash 的连接记录·Docker 命令的输出·Docker Desktop 里的设置 三处一起看,别光凭浏览器能不能开就下结论。

第一步:先确认 Clash 客户端和节点没问题

查 Docker Hub 之前,先别忙着动 Docker 的配置。打开你正在用的 Clash 客户端,确认配置文件加载成功、混合端口或 HTTP 代理端口在监听。Clash Verge Rev、Mihomo Party、Clash for Windows 这些客户端页面叫法不一样,端口号一般能在「设置」「端口」「常规」或「General」里找到。混合端口很多是 7890,但别直接照搬,以你本机界面上显示的为准。

接着手动挑一个稳的节点,第一次测试别用老在换线的 url-test 或负载均衡组。拉镜像要走认证、取清单、下好几个分层文件,中途换出口可能导致连接被重置、CDN 重新分配,甚至触发仓库那边的访问限制。先调通,再改回自动选择,这样才分得清问题出在规则还是节点。

  • 端口在监听:客户端显示代理已经起来,而且没和别的 VPN、开发工具或老版本 Clash 抢端口。
  • 模式对不对:排错时可以临时切全局做对比;全局行、规则模式不行,问题就在分流规则上。
  • 节点好不好:别只看延迟,HTTPS 握手、持续下载、长连接稳不稳都要试。
  • 时间和证书:系统时间差得多,Docker Hub 的 TLS 连接可能直接失败。

开着 Clash 日志拉一次镜像,搜 docker.io、auth.docker.io、registry-1.docker.io 这些主机名。一条相关请求都没有,多半是 Docker 没走 Clash;有请求但命中 DIRECT,是分流规则的问题;进了代理还反复超时,就转去查节点和 DNS。怎么看连接日志和规则命中,也可以看 Clash 日志排查教程。

第二步:把 Docker Hub 用到的域名分流配全

Docker Hub 不只是一个网页域名。拉镜像时客户端一般先找认证服务,再去 registry 拿镜像清单,真正的分层数据还可能放在对象存储或 CDN 上。只把 hub.docker.com 加进代理规则,多半只修好了网页,命令行照样拉不动。建议在 Clash 配置里给 Docker 相关域名单独建一个策略组,比如叫 DOCKER,调试期间固定在一个可靠节点上。

基础规则一般要覆盖这些主机:

  • hub.docker.com:搜镜像、登录、网页端管理。
  • registry-1.docker.io:镜像清单与仓库 API。
  • auth.docker.io:获取 Bearer Token 等认证信息。
  • index.docker.io:一些老客户端或兼容流程还会用到。
  • production.cloudflare.docker.com:有些镜像层从这个分发域名下载。

具体语法看你用的内核认什么,常见写法如下。把 DOCKER 换成你实际建的策略组名,并且让这几条排在笼统的直连、地区和兜底规则前面:

rules:
  - DOMAIN,hub.docker.com,DOCKER
  - DOMAIN,registry-1.docker.io,DOCKER
  - DOMAIN,auth.docker.io,DOCKER
  - DOMAIN,index.docker.io,DOCKER
  - DOMAIN,production.cloudflare.docker.com,DOCKER
  - MATCH,PROXY

日志里冒出新的下载主机名时,别一股脑把所有陌生域名都丢给代理。先确认它确实是这次 Docker 拉取产生的,再用 DOMAIN 或 DOMAIN-SUFFIX 精确补上。有些镜像的构建脚本还会去 GitHub、npm、PyPI 或自建仓库拉依赖,这些不算 Docker Hub 的流量,应该各建各的规则,别把不相干的流量全塞进一个策略组。

⚠️
光代理网页域名是不够的

浏览器能打开 Docker Hub,不代表 registry 也通了。日志里只有 hub.docker.com,却找不到 auth.docker.io 或 registry-1.docker.io,说明你的排查还缺了一块。

第三步:让 Docker Engine 真的用上 Clash 代理

这一步最容易漏。Docker Desktop 的图形界面、终端里的 curl、Docker CLI、后台的 Docker Engine,可能各自处在不同的网络环境里。在终端执行 export HTTPS_PROXY=...,一般只影响这条命令拉起的进程,对早已在跑的 Docker daemon 不一定起作用;Windows 上设了系统代理,Docker Engine 也不会因此自动去读。

用 Docker Desktop 的话,到设置里找代理选项(HTTP/HTTPS Proxy),填上 Clash 的本机代理地址。比如混合端口是 7890,可以写:

http://host.docker.internal:7890

不同版本的 Docker Desktop,代理入口和作用范围可能有点不一样。改完要点应用并重启 Docker Desktop,再拉一次试试。host.docker.internal 用不了的话,可以按客户端和系统情况换一个宿主机能访问到的地址,但别想当然认为容器里的 127.0.0.1 就是宿主机。对容器来说,127.0.0.1 是它自己;对 Docker daemon 来说,它又可能落在另一个网络命名空间里。

Linux 上 Docker Engine 由 systemd 管的,可以给这个服务配代理环境变量。下面只是写法示意,具体路径和权限照你的发行版来:

sudo mkdir -p /etc/systemd/system/docker.service.d

sudo tee /etc/systemd/system/docker.service.d/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"
EOF

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

验证时先确认 Docker 服务真的读到了变量,再执行 docker pull hello-world,或者拉一个很小的公共镜像。服务那边已经配了代理、Clash 日志里还是没有请求,说明这个地址 Docker daemon 访问不到,或者 Docker Desktop 用的是它自己那套代理配置。能看到请求、却在下载分层时超时,就接着查节点稳不稳、MTU 合不合适,别一遍遍改环境变量。

第四步:查 DNS、IPv6 和 TLS 握手

Docker Hub 超时有时跟代理规则无关,是 DNS 给了一个连不上的地址。Clash 的增强模式和 Fake-IP、操作系统的 DNS、Docker 自带的 DNS 可能同时在解析,浏览器和 Docker 拿到的结果就不一样。特别是某个域名优先解析成 IPv6、而你的网络又没有稳定的 IPv6 出口时,Docker 可能先去试一条走不通的路,等超时了才退回 IPv4。

可以先在宿主机上跑下面几条,把解析、HTTPS、走代理三种结果对比一下:

nslookup registry-1.docker.io
curl -I --connect-timeout 10 https://registry-1.docker.io/v2/
curl -x http://127.0.0.1:7890 -I --connect-timeout 10 https://registry-1.docker.io/v2/

registry 的 /v2/ 回 401 Unauthorized 未必是坏事,多数时候说明网络已经到了 Docker Registry,只是还没带认证信息。真正要看的是 DNS、TCP、TLS 能不能很快建立起来。直连超时、经 Clash 能拿到 401,说明代理这条路基本是通的;两边都超时,就换节点或查本地网络;宿主机正常、docker pull 却失败,重点还是 Docker daemon 有没有拿到代理。

DNS 这块,Clash 里保持一套清楚的解析方案就好,别同时叠好几个改解析的工具。排错期间可以先关掉复杂的 Fake-IP 规则,或者在客户端 DNS 设置里换成可信的远程解析做个对比。确认是 IPv6 拖慢了连接,可以临时关掉系统 IPv6,或者在 Docker、Clash 的网络设置里优先走 IPv4;这只是为了定位,要不要长期关,得看局域网、运营商和你其他业务的需要。

第五步:用最小的测试确认修好了

别每次都拿几百兆的大镜像来试。先拉一个小镜像,看认证、清单、分层下载能不能全部走完:

docker pull hello-world
docker pull alpine:latest
docker info
docker system info

小镜像能拉、大镜像不行,问题更可能出在节点带宽、连接能保持多久、CDN 分发或 MTU 上。这时可以换个稳的节点、关掉自动切换,把同一个镜像连拉两三次,记下每次断在哪个阶段。总卡在同一层,可能是那一层所在 CDN 的出口不好;每次卡的层都不一样,更像是线路在抖、在丢包,或者多条连接同时开时撑不住。

报镜像找不到、没有权限的,别当成网络超时。私有仓库先执行 docker login,再看账号有没有权限、令牌是否有效、组织那边有没有限制。公司自己的镜像,还得想清楚那个仓库地址是不是该走公司内网直连,而不是跟着 Docker Hub 的规则进了代理。docker pull --quiet 可以少打点输出,不过排错的时候留着完整日志更有用。

ℹ️
改完配置记得重启

改了 Clash 规则,要确认配置已经重新载入;改了 Docker Desktop 的代理,多半要重启 Docker Engine。只刷新浏览器,已经在跑的 daemon 不会自己换上新代理。

第六步:别掉进这些「看着管用」的修法

网络一出问题,很多人直接从网上抄一个加速镜像源,或者干脆全部流量切到全局代理。眼下可能拉成功了,时间一长维护和安全上都会多出麻烦。第三方加速器可能同步慢、命名空间不全、限流、证书策略变了,或者有隐私隐患;要你把账号凭据交给一个不熟的服务的,更要小心。先让官方 Docker Hub 经靠谱的 Clash 节点跑通,再考虑公司认可的镜像缓存。

也别在规则文件里一遍遍追加重复的 MATCH、DOMAIN-SUFFIX 和代理组名。Clash 规则从上往下匹配,写在后面的再精确,也盖不过前面已经命中的那条。每次只改一样:先补认证域名,再补 registry,再补日志里新冒出来的 CDN 域名,每改一次测一次,才知道到底是哪一步解决了问题。

还有,容器里跑的命令和宿主机上的 Docker CLI 是两回事。宿主机开了 Clash,不等于容器里的 apt、git 或应用启动脚本自动有代理。构建镜像要访问外部依赖的,要在构建参数、Dockerfile、运行时环境里分别配置,并用 NO_PROXY 把内网域名排除掉,免得内部服务被送到外面的节点。

常见问题排解(FAQ)

浏览器能开 Docker Hub,docker pull 为什么还超时?

最常见的原因是浏览器用上了系统代理或 Clash 插件,Docker daemon 却没配代理。打开网页主要靠 hub.docker.com,拉镜像还得经过认证服务、Registry API 和分层 CDN。到 Docker Desktop 的代理设置里填一个 Docker Engine 访问得到的地址,重启后看 Clash 日志里有没有出现这些域名。

访问 registry 回 401,是配置失败了吗?

不见得。Docker Registry 的 /v2/ 接口没认证时回 401 很正常,反而说明 DNS、TLS、HTTP 请求都已经到了服务端。只有拿到认证令牌后还失败,或者 docker pull 报权限错误,才需要再看是否已登录、令牌给了哪些权限、私有仓库怎么设的。

开了 Clash 的 TUN 模式,Docker 还用单独配代理吗?

要看情况。TUN 能接管更多系统流量,但 Docker Desktop 可能跑在一套独立的虚拟化网络里,Docker daemon 走不走 TUN,取决于系统、客户端的实现和路由设置。最稳妥的还是看 Clash 日志,并在 Docker Desktop 里把代理明确配上;Linux 原生 Docker 则要确认服务级的环境变量和路由都生效了。

怎么分辨是节点不行,还是规则写错了?

先锁一个节点,看 Docker 用到的那几个域名是不是全进了同一个代理组,然后连续拉小镜像。换了节点马上就好、规则命中又没变化,基本就是原来那个节点在丢包、带宽、TLS 或 CDN 兼容上有问题。所有节点都不行、全局代理测试却正常,就回头查 Docker daemon 填的代理地址,以及容器所在的网络命名空间。

有些工具只管网页代理,或者要你手动维护好几套环境变量,在 Docker 这种场景下常见的麻烦是看不到规则、节点切换不稳,浏览器、终端、Docker daemon 各走各的路。要长期管理开发网络,最好用一个能导入订阅、按域名看规则命中、能锁定节点的客户端,几个平台之间配置思路也统一。不想反复试错的话,可以去 Clash站 下载页挑一个,安装包取自官方 GitHub 发布页,再照上面的步骤把 Docker Hub 的代理验一遍。