执行 docker pull 时一直等待,最后出现 i/o timeout、Client.Timeout exceeded 或无法连接 Docker Hub,问题不一定出在镜像源。更常见的原因是:Clash 当前模式或规则没有让相关请求走到可用节点;终端设置了代理,但 Docker 守护进程并没有使用该代理;或者代理节点无法稳定连接 Docker Hub 所需的认证与镜像分发域名。排查时应先确认是哪一层连接失败,再逐步验证代理端口、终端代理变量、Docker Engine 代理和规则命中情况,而不是一开始就更换镜像地址。
先判断卡在哪一层
Docker 拉取镜像不是只访问一个地址。客户端可能先向 auth.docker.io 请求令牌,再连接 registry-1.docker.io 获取清单,最后从内容分发网络下载镜像层。因此,浏览器可以打开 Docker Hub 首页,并不代表这些接口和下载域名都能正常访问;反过来,某一个域名打不开,也不一定说明 Clash 整体失效。
先记录完整错误信息和等待阶段。若命令几乎立刻返回 unauthorized、denied 或镜像名称错误,通常是账号权限、镜像名称或标签问题,不是代理超时。若已经开始下载部分 layer,随后长时间停顿并超时,问题更可能出现在传输链路、节点稳定性或分流规则。若错误中出现域名解析失败,则优先检查 DNS 与 Clash 的 DNS 设置;若是连接建立超时,则重点检查路由、代理端口及节点连通性。
| 现象 | 优先检查 | 不要先做的事 |
|---|---|---|
| 域名解析失败 | DNS 解析、系统 DNS、Clash DNS 状态 | 反复更换镜像标签 |
| 连接 Docker Hub 超时 | 代理端口、节点状态、规则命中 | 只在浏览器里测试首页 |
| 部分 layer 下载后卡住 | 节点稳定性、下载域名分流、网络丢包 | 仅凭一次失败判断镜像不存在 |
| 认证失败或无权限 | 镜像名、标签、Docker Hub 登录状态 | 盲目修改 Clash 的代理规则 |
开始前也要确认 Docker 服务本身正常,并检查本机时间是否准确。时间偏差、凭据过期和 Docker Hub 的限流可能表现为请求失败,但不属于 Clash 代理故障。后续测试尽量使用同一个镜像和同一组网络条件,避免把多个变量同时改动,导致无法判断哪项设置真正起作用。
检查 Clash 模式与本地代理端口
打开 Clash Verge、Clash Verge Rev 或其他 Mihomo 客户端,确认核心正在运行,并查看当前 HTTP 或 mixed 监听端口。常见端口是 7890,但端口可以在客户端设置或配置文件中修改,不能直接假定本机一定使用该值。若启用了认证,测试命令还需要包含相应凭据;不要把密码粘贴到公开日志或截图中。
排查时可以暂时将模式切换为「全局」,并选择一个已确认可用的节点。全局模式的目的只是缩小变量范围:如果全局模式下请求恢复,而规则模式下仍超时,问题通常在规则匹配或策略组选择;如果全局模式也不通,应继续检查节点、端口和网络,而不是急着编辑规则。测试结束后记得恢复日常模式。
127.0.0.1:7890,它只供当前主机访问;Docker Desktop、远程 Docker Engine 或容器中的程序可能无法通过这个地址连接到宿主机代理。用 curl 对本地代理做一次最小测试。将下面示例中的端口替换为客户端实际配置的端口:
curl -I --connect-timeout 10 -x http://127.0.0.1:7890 https://registry-1.docker.io/v2/
如果代理链路可用,Docker Registry 的未认证接口通常会返回 401 Unauthorized,这是正常响应,表示 DNS、TCP 和 HTTPS 请求已经到达服务端;它不等于代理失败。若输出是连接拒绝,检查 Clash 是否运行及端口是否正确;若连接一直等待后超时,切换节点并查看 Clash 日志。测试时不要只看浏览器,因为浏览器可能使用系统代理,而命令行工具和 Docker 服务使用的是另一套代理设置。
验证终端代理变量是否生效
在终端设置 HTTP_PROXY 或 HTTPS_PROXY,只会影响读取这些环境变量的进程,不会自动保证 Docker 守护进程也使用代理。先在运行 docker pull 的同一个终端中检查变量,再用带代理的 curl 测试相同域名。以下示例适用于 Bash、Zsh 等常见 Unix shell;端口仍需按本机实际值调整。
export HTTP_PROXY="http://127.0.0.1:7890" export HTTPS_PROXY="http://127.0.0.1:7890" export http_proxy="$HTTP_PROXY" export https_proxy="$HTTPS_PROXY" env | grep -i proxy curl -I --connect-timeout 10 https://auth.docker.io/
注意,curl 命令也可以通过 -x 单独指定代理,这比依赖环境变量更适合做对照测试。先比较直连和代理请求:如果代理请求成功、直连超时,说明本机代理通路有用;如果两种方式都失败,应检查网络、DNS 和节点;如果 curl 经代理成功,但 docker pull 仍超时,重点转向 Docker Engine 的代理配置。
Windows 用户可以在 PowerShell 中检查当前会话的环境变量,但要注意环境变量的作用范围:在某个窗口里设置的变量通常只对该窗口启动的程序有效,而且 Docker Desktop 后端并不一定沿用该终端的变量。macOS 上从图形界面启动的 Docker Desktop 也未必继承 shell 配置文件中的变量。测试结果应以 Docker Engine 实际采用的设置为准,而不是仅凭终端里能看到代理变量就认定拉取请求已经走代理。
单独检查 Docker Engine 的代理设置
docker pull 通常由 Docker Engine(守护进程)负责访问注册表。命令行客户端能够访问代理,不代表后台引擎也能访问。Linux 上通过 systemd 运行的 Docker 服务,可以配置服务级代理;修改后需要重载 systemd 并重启 Docker。请先确认系统发行版和服务名称,再应用配置,避免覆盖已有的服务参数。
sudo systemctl edit docker [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,.local" sudo systemctl daemon-reload sudo systemctl restart docker docker info
上面展示的是 drop-in 文件中的内容和后续命令,编辑器打开后应将 [Service] 及环境变量写入文件,再保存退出。127.0.0.1 在这里指 Docker Engine 所在的主机网络命名空间:若 Clash 运行在另一台机器、虚拟机或容器中,这个地址就不是 Clash 的地址。此时需要使用 Docker Engine 能访问到的宿主机地址,并确认防火墙允许连接。
检查 docker info 的输出,确认 Engine 是否显示预期的 HTTP Proxy、HTTPS Proxy 与 No Proxy 信息。不同 Docker 版本和安装方式的显示内容可能不同;如果没有出现代理设置,检查 drop-in 文件是否保存到正确位置、环境变量格式是否正确,以及服务是否确实已重启。若代理地址包含用户名或密码,不要将凭据写进公开配置仓库,也不要把 docker info 的完整输出未经检查地发到公开论坛。
Docker Desktop 用户应优先检查 Docker Desktop 设置中的代理选项,并按照当前版本界面配置,而不是直接套用 Linux 的 systemd 命令。桌面版的 Docker Engine 运行在受管理的虚拟化环境中,宿主机上的 127.0.0.1 不一定等于虚拟机中的回环地址。若代理只监听本机回环接口,Docker Desktop 后端可能无法连接;应使用客户端支持的宿主机代理设置,或按其网络配置选择可达的代理地址。修改后重启 Docker Desktop,再重新执行测试。
核对规则命中、节点与 Docker 地址
确认请求确实经过 Clash 后,再回到规则模式。观察 Clash 的连接记录或日志,执行一次新的拉取请求,并检查目标域名、命中的规则和最终策略组。排查时重点留意 auth.docker.io、registry-1.docker.io 以及错误信息中出现的内容分发域名。若认证请求走了代理、下载请求却命中直连,可能会出现登录或清单阶段成功、下载镜像层时超时的情况。
规则模式下若请求被错误地分到直连,可以先调整相关规则或策略组,让这些请求临时走一个已验证可用的代理出口,再测试是否改善。不要为了修复 Docker 而长期将所有流量设成全局代理,也不建议随意添加未经验证的宽泛规则。修改规则后重新加载配置,并清理或重新触发一次连接,避免误把旧连接的记录当成新结果。
节点测速显示延迟较低,只能说明测速目标在当时可达,不能保证 Docker Hub 认证和大文件下载也稳定。可选择另一个节点进行对照,并保持其他设置不变。若不同节点表现差异明显,问题更可能与节点出口、运营商路由或特定目标的连通性有关;若所有节点均失败而本地代理测试正常,则继续检查 Docker Engine 是否连接到了预期的 Clash 实例。
HTTP_PROXY 通常影响容器启动后的应用请求;而拉取镜像发生在 Engine 访问注册表的阶段。给容器设置代理变量,不能替代 Docker Engine 的代理设置。每次只改一个变量,并记录结果:例如先固定节点,只改变 Clash 模式;再固定模式,只改变 Engine 代理;最后才调整规则。这样可以区分是节点不可用、规则分流错误,还是 Docker 服务未使用代理。确认故障解除后,再恢复正常代理模式和策略,避免留下临时的全局代理或过宽规则。
用命令确认问题是否解决
配置完成后,先检查 Docker Engine 状态,再测试镜像拉取。选择一个公开且确实存在的镜像和明确标签,避免将镜像名拼写错误误判为网络故障。第一次请求可以使用较小的公开镜像;若它成功,再重试原来失败的镜像。执行期间同时查看 Clash 连接记录,确认相关请求命中了预期策略组。
docker info docker pull hello-world docker pull library/nginx:latest
若测试镜像成功、原镜像仍失败,检查原镜像的名称、标签、访问权限和 Docker Hub 限流提示,并确认失败是否发生在某个特定下载域名。若所有拉取均失败,但通过 Clash 代理的 curl 返回预期响应,说明代理端点可能可用,而 Engine 的代理仍未正确生效,或 Docker Desktop 后端无法访问该端点。若测试镜像也在相同阶段超时,则回到节点连通性和分流规则继续定位。
最终判断应基于完整证据,而不是只看某一条命令:本地代理端口可连接、相关请求在 Clash 中命中预期策略、Docker Engine 使用正确代理,并且 docker pull 能完成下载,才算闭环。修复后建议保留一份最小变更记录,写明代理地址、规则调整和验证命令;以后出现相似故障时,就能快速区分是订阅节点变化、客户端升级,还是系统代理配置被重置。
常见问题 FAQ
为什么 curl 经 Clash 能访问,docker pull 仍然超时?
因为两者可能由不同进程发起请求。终端中的 curl 可以使用命令参数或环境变量连接代理,而拉取镜像通常由 Docker Engine 访问注册表。检查 Linux systemd 的 Docker 服务环境,或 Docker Desktop 的代理设置,并确认 Engine 所在环境能够访问代理地址。
代理测试返回 401,是不是连接失败?
不一定。Docker Registry 的未认证接口返回 401 Unauthorized 很常见,通常表示请求已经到达服务端,只是当前请求没有认证令牌。若目标是验证网络连通性,这个响应往往比持续等待或连接超时更能说明代理链路正常;它不能证明镜像有访问权限。
Docker 服务为什么连不上 127.0.0.1:7890?
127.0.0.1 指发起连接的进程所在环境自身。Docker Desktop 的后端、远程 Engine 或容器与宿主机可能处于不同网络环境,因此它们看到的回环地址不一定是运行 Clash 的主机。应在 Docker 所在环境中配置可达的宿主机地址,并确认 Clash 监听范围和防火墙设置。
是不是改用其他镜像源就能解决超时?
不能一概而论。换源可能绕开某些注册表连接问题,但也会引入镜像同步延迟、标签不一致或访问策略差异。若错误源于 Engine 没有使用代理、DNS 失败或规则把下载域名分到不可用线路,单纯换源未必解决根因。先按本文方法确认故障阶段,再决定是否需要使用其他受信任的镜像服务。