Docker 拉镜像总超时:走宿主机 Clash HTTP 代理端口(2026)

浏览器能上网,docker pull 怎么还会卡住

电脑上 Clash 的订阅和分流都已经跑通,浏览器打开 Docker Hub 或国内镜像站好像也「没问题」,可终端里 docker pull、docker build 却老是 Connection timed out,或者慢得出奇。最常见的误会是:「电脑能出去,Docker 自然也能」。其实 docker 命令多数时候是在跟本机的 Docker 守护进程(dockerd)打交道,真正发 HTTPS 请求去拉镜像层、连 registry 的,是守护进程那一侧的网络,跟你浏览器里勾的「使用系统代理」、Clash 的 TUN 或系统代理不是一回事。另外,TUN 这类路由层的透明代理虽然能罩住很多进程,但 Docker 自己的虚拟网段、docker0 网桥和网络命名空间,经常让人看不清流量到底有没有走你想要的那个出口。下面专讲一条能照着做的路子:在宿主机上给 Clash 开一个显式的 HTTP 代理端口,再让 Docker 那边(命令行一端、后台服务一端,或者两端都配)通过 HTTP_PROXY / HTTPS_PROXY 指过去。这跟 Clash站 的WSL2 里让 apt 走宿主机 Clash 是并列的两种情况:那篇处理 Linux 子系统里敲的命令,这篇处理容器运行时与 image registry之间的流量,两边可以同时配。

要是你想让「每个进程都免去手动设变量」,那得靠 TUN 模式 加系统路由;放到 Docker 里,TUN 有时能少配几样,但出了问题要排查时,「显式代理加一个看得见的端口」还是最好上手的。这里主要讲HTTP 代理到宿主机这条路,跟那种「只换镜像加速站」的教程不是一回事:出口配好之后,你照样可以再叠加 Docker Desktop 镜像、registry 镜像来降低公网延迟,两者并不冲突。

💡
看完应该能搞定四件事:宿主机上的 Clash 在监听,而且对局域网/非环回地址可见;你写的代理 URL 指向的是「Docker 眼里的宿主机 IP」或 host.docker.internal;NO_PROXY 把不该进隧道的内网和国内镜像排除掉;最后用一条 docker pull 把整条路验一遍。

宿主机上的 Clash:端口、局域网访问和防火墙

跟 WSL2 那篇一样,头一件事是:Clash 的入站如果只绑在 127.0.0.1 上,就别指望从别的网络命名空间过来的连接能碰到它。在图形客户端里打开允许局域网 / Allow LAN 这类开关,或者确保 mixed-port/HTTP 绑在外部看得见的地址上(各客户端菜单位置不同,比如 Clash Verge Rev,意思跟「监听 0.0.0.0」差不多)。文中端口写 7890 只是举例,你改过 mixed-port 的话,全部换成自己的值;7890 被别的程序占了,可以先看7890 端口与 mixed-port 排查把端口理清楚。

Windows 上就算开了 Allow LAN,也最好在「防火墙入站规则」里给 Clash 的程序或它用的 TCP 端口放行。不然经常是这样:宿主机上 curl -x 能通,从 Hyper-V、WSL 或 Docker 子网过来的连接却被悄悄丢掉。拿不准 Clash 到底有没有收到 Docker 发来的 CONNECT,可以照查看连接记录、看匹配到哪条规则那篇的办法,确认请求有没有进内核、落在哪条规则上,这比瞎改 DNS 管用。

站在容器里看,「宿主机」该怎么写

Docker Desktop(macOS / Windows)上最省心的是用 host.docker.internal:容器和 LinuxKit 里会把它解析成能连到的宿主机,代理 URL 写成 http://host.docker.internal:7890 这样一般都行。碰到解析或证书方面的怪问题,再去翻当前版本 Desktop 文档里讲宿主机网关的那部分。

原生 Linux / rootful Docker上,通常没有现成的 host.docker.internal 可用;稳一点的办法是找出宿主机在 docker0 网桥或默认路由那一边的地址(常见的是 172.17.0.1 这类网桥网关,具体看你机器上 ip route / ip -4 addr 的输出),再跟 Clash 的入站地址对上。Docker 要是以 rootless 或自定义网段的方式跑,就按官方文档里「从容器访问宿主机」那一节来,道理不变:代理 URL 里的主机部分,必须是容器或守护进程真能路由过去的宿主机侧 IP,而不是想当然地照搬浏览器那边的「127.0.0.1」。

办法一:Docker Desktop 的 Proxies 设置页(最直观)

打开 Docker Desktop 设置里的 Resources → Proxies(名字可能略有不同),在 Manual proxy 下填 Web Server (HTTP) 和 Secure Web Server (HTTPS),比如 http://host.docker.internal:7890,再在下面的「绕过」列表里写上不需要走代理的地址:起码要有 localhost、127.0.0.1、*.local,以及你打算用的国内 registry 与镜像站。点保存,等 Docker 把服务重新拉起来,然后执行一次 docker pull 看看。这个入口的好处是守护进程和一部分客户端都能顾到;要跟下面的配置文件二选一还是一起用,先看你这个 Desktop 版本的文档,免得两边设置打架。

方式二:~/.docker/config.json 的 proxies 与 default

在命令行和 CI 里更方便照搬的办法,是改用户主目录下 Docker 的 config.json,给 default 或某个具体的 registry 写上 httpProxy / httpsProxy / noProxy。下面示例里的端口和主机,按上一节换成你自己的(HTTP 和 HTTPS 一般指向同一个代理就行):

{
  "proxies": {
    "default": {
      "httpProxy": "http://host.docker.internal:7890",
      "httpsProxy": "http://host.docker.internal:7890",
      "noProxy": "localhost,127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
    }
  }
}

纯 Linux 环境下,把 host.docker.internal 换成上一节查到的网关 IP。只想给个别 registry 走代理、其他直连的,可以把 default 改成以 registry 域名为键的配置块(结构以 Docker 当前文档为准)。BuildKit 在 build 过程中下载 FROM 用的镜像、或者联网取东西时,也会照这套代理配置走,团队之间共用同一份 config.json 或者由 CI 注入都方便。

办法三:给 dockerd 设环境变量(Linux 上用得多)

守护进程由 systemd 管的话,可以单独加一个 drop-in 文件,写上 Environment=HTTP_PROXY=...,然后对 docker.service 重新加载。要注意,这会作用到这台机器上所有经这个守护进程发起的拉取和元数据请求,跟「只改用户级 config」管的范围不一样。rootless Docker 的服务名和路径另有一套,一定照发行版和官方文档放文件,别直接抄一份对不上的示例路径。改完执行 systemctl daemon-reload,再 restart docker,然后看 journalctl -u docker 里还有没有直连超时。

docker build 与 --build-arg

有的 Dockerfile 在 RUN apt-get 或 curl 这几步需要连外网。除了全局 config 和守护进程环境变量,也可以在构建时传进去:

docker build \
  --build-arg HTTP_PROXY=http://host.docker.internal:7890 \
  --build-arg HTTPS_PROXY=http://host.docker.internal:7890 \
  .

Dockerfile 里用 ARG HTTP_PROXY 接住,在需要它的 RUN 层里生效;具体怎么写要看基础镜像和包管理器。用 docker compose 的,可以在 compose 文件的 build 段里声明 args,省得每次都在 shell 里手敲。

NO_PROXY 与国内镜像、Docker Hub 加速

把在国内本来就能比较稳地访问的registry 镜像、院校与公司内网写进 noProxy,这部分流量就不用绕到海外节点上去了,省带宽也少延迟。要是你在 Docker Desktop 里还配了 registry mirrors 或者镜像加速地址,记得把对应的主机名也一起考虑进 noProxy。网上讲「Docker Desktop 镜像加速」的文章,多半说的是 registry mirror,跟「给守护进程加 HTTP 代理」处理的不是同一层的问题:前者是从国内缓存拉,后者解决的是连到源站或 Registry 的跨境线路,实际用的时候常常两样都得有。

最小验证顺序

建议先在同一台机器上,用 curl -x http://host.docker.internal:7890(或者换成你的网关 IP)对外发一个 HTTPS 请求,去 Clash 的记录里看这次连接进来了没有。然后再 docker pull 一个小镜像试试。如果 curl 能通、docker 不行,就去怀疑「config 没生效、Desktop 没重启、守护进程没拿到变量」这几处,别马上去改容器的 DNS。

与 WSL2、TUN 的边界怎么记

Windows 上,你可能同时装着 Docker Desktop 的 WSL2 后端和平时开发用的 WSL2 发行版。这里只讲「Docker 拉镜像和 build」;想让发行版里 apt、git也走宿主机 Clash,还是回到WSL2 与宿主机 Clash 的环境变量那篇一步步来,两边的命令环境不同,别混成同一组 export。还没装电脑版 Clash 的,可以先看Clash Verge Rev on Windows 教程把订阅和入站配稳,再回来做 Docker 这边的步骤。

比起在镜像里再塞一套带内核的 Clash,把代理的唯一真源放在宿主机上、用显式的 HTTP_PROXY 把 Docker 接过去,长期维护和排错都简单得多。规则和策略组只在 Clash 里维护一份,也更好跟 Clash站 其他教程对得上。要换客户端或者换新电脑,到 Clash 客户端下载页 拿对应平台的安装包(取自各客户端官方 GitHub 发布页),再照着使用文档把字段核一遍就行。与其在容器里东拼西凑,不如让本机的 Clash 当稳定出口、Docker 只管声明「往哪儿指」,日常开发会省心不少。→ 去下载页挑一个 Clash 客户端