AI 与开发工具网络

Docker 代理设置教程:拉取镜像、构建镜像、容器内三种情况分别怎么配

更新于 · 约 19 分钟读完 · 登机口编辑整理

为什么在终端里设了代理,docker pull 还是超时

很多人已经按终端代理设置教程在 shell 里设置了 https_proxy,curl 和 git 都正常,唯独 docker pull 还是超时。原因在 Docker 的结构上。

你在终端里敲的 docker 只是一个命令行客户端,它把指令发给后台的守护进程 dockerd,真正去仓库下载镜像的是守护进程。守护进程是系统服务,由 systemd 启动,不会读取你当前终端里的环境变量。

同样的道理,构建过程和容器内部又各是独立的环境。于是就有了三种场景:

场景 谁在发起网络请求 在哪里设置代理 代理地址能否用 127.0.0.1
docker pull / docker push 守护进程 dockerd systemd drop-in 或 Docker Desktop 设置 可以(守护进程运行在宿主机上)
docker build 中的下载 构建容器里的命令 --build-arg 不可以,要用宿主机地址
容器运行时联网 容器里的程序 -e 或 ~/.docker/config.json 不可以,要用宿主机地址

下文的端口都以 7890 为例,实际填你的代理客户端设置页里显示的端口。

场景一:给守护进程设置代理(解决 docker pull 超时)

Linux:使用 systemd drop-in

  1. 创建 drop-in 目录:
sudo mkdir -p /etc/systemd/system/docker.service.d
  1. 新建文件 /etc/systemd/system/docker.service.d/http-proxy.conf,写入:
[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. 重新加载配置并重启 Docker:
sudo systemctl daemon-reload
sudo systemctl restart docker
  1. 确认环境变量已经生效:
sudo systemctl show --property=Environment docker

输出里能看到刚才写的三个变量,再执行 docker pull 测试。

几点说明:

  • HTTPS_PROXY 的值仍然以 http:// 开头,这是对的。它表示「访问 HTTPS 地址时使用哪个代理」,而本地代理端口说的是 HTTP 代理协议。
  • NO_PROXY 用来列出不走代理的地址。公司内网有私有镜像仓库的话,把它的域名加进去,用英文逗号分隔。
  • 重启 Docker 会让正在运行的容器停止,除非另外配置过相关选项。在有业务运行的机器上要选好时间。
  • 这里的 127.0.0.1 可以直接用,因为守护进程就运行在宿主机上,前提是代理客户端也在同一台机器上运行。Linux 上客户端的安装见 Linux 机场使用教程。

较新版本的 Docker Engine 也支持在 /etc/docker/daemon.json 里用 proxies 字段配置守护进程代理。两种方式选一种即可,systemd drop-in 的写法适用的版本范围更广。

Docker Desktop:在设置界面里配置

Windows 和 macOS 上的 Docker Desktop,守护进程运行在它自带的虚拟机里,不需要手动改 systemd。打开 Docker Desktop 的设置,在资源相关的分类下找到代理设置,可以选择跟随系统代理,或者手动填写 HTTP 和 HTTPS 代理地址,保存后 Docker Desktop 会自动重启生效。界面文字随版本有调整,以你安装的版本为准。

场景二:docker build 时传入代理

构建镜像时,FROM 那一行拉取基础镜像由守护进程完成,走的是场景一的设置。而 RUN apt-get update、RUN npm install、RUN pip install 这些命令是在一个临时的构建容器里执行的,需要另外把代理传进去:

docker build \
  --build-arg HTTP_PROXY=http://172.17.0.1:7890 \
  --build-arg HTTPS_PROXY=http://172.17.0.1:7890 \
  --build-arg NO_PROXY=localhost,127.0.0.1 \
  -t myapp .

HTTP_PROXY、HTTPS_PROXY、NO_PROXY 以及它们的小写形式是 Docker 预定义的构建参数,不需要在 Dockerfile 里用 ARG 声明就能直接传,也不会被留在最终镜像的构建历史里。有些程序只认小写的变量名,遇到不生效时,把 http_proxy、https_proxy 也一并传入。

不要在 Dockerfile 里用 ENV 把代理地址写死。那样代理设置会被打进镜像,别人拿到镜像后在没有这个代理的环境里运行,所有网络请求都会失败。

上面例子里的 172.17.0.1 是宿主机地址,原因见下一节。

关键:容器里的 127.0.0.1 不是宿主机

这是 Docker 代理设置里最常见的错误。容器有自己独立的网络空间,在容器内部,127.0.0.1 指的是容器自己,那里并没有代理程序在监听。所以把 http://127.0.0.1:7890 传给构建或容器,得到的是连接被拒绝。

要访问宿主机上的代理,需要使用宿主机的地址:

  • Docker Desktop(Windows、macOS):直接用 host.docker.internal 这个特殊域名,例如 http://host.docker.internal:7890。
  • Linux:默认桥接网络下,宿主机在容器看来的地址是 docker0 网桥的地址,通常是 172.17.0.1,可以用 ip addr show docker0 确认。也可以在运行容器时加上 --add-host=host.docker.internal:host-gateway,之后在容器里同样能用 host.docker.internal。

还有一个必须同时满足的条件:宿主机上的代理客户端要开启「允许局域网连接」。 客户端默认只监听本机回环地址,来自容器的请求在它看来是外部来源,会被拒绝。在客户端设置里打开这个选项后重启客户端。Linux 上如果启用了防火墙,还要放行来自 Docker 网段到这个端口的访问。

Linux 上还有一种绕开地址问题的做法:让容器直接使用宿主机的网络,这时 127.0.0.1 就是宿主机。运行时加 --network host,构建时加 --network=host。代价是容器失去了网络隔离,只建议在本机开发时临时使用。

场景三:容器运行时使用代理

单次运行:用 -e 传环境变量

docker run --rm \
  -e HTTP_PROXY=http://host.docker.internal:7890 \
  -e HTTPS_PROXY=http://host.docker.internal:7890 \
  -e NO_PROXY=localhost,127.0.0.1 \
  curlimages/curl -I https://www.google.com

在 Linux 上把 host.docker.internal 换成 172.17.0.1,或者加上前面说的 --add-host 参数。使用 Docker Compose 时,同样的变量写在服务的 environment 字段里。

设为默认:写进 ~/.docker/config.json

不想每次都传参数,可以在当前用户的 ~/.docker/config.json 里加上 proxies 配置:

{
  "proxies": {
    "default": {
      "httpProxy": "http://host.docker.internal:7890",
      "httpsProxy": "http://host.docker.internal:7890",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

如果文件里已有其他内容,把 proxies 这一段合并进去,注意保持 JSON 格式正确。保存之后,新创建的容器和新的构建都会自动带上对应的代理环境变量,大小写两种形式都会设置。已经在运行的容器不受影响,需要重新创建。

这个文件是 Docker 命令行客户端的配置,只影响容器和构建,不影响 docker pull。拉镜像仍然要按场景一设置。

环境变量只对读取它的程序有效。curl、wget、pip、npm、apt 这些常见工具都认,但有些程序有自己的代理配置方式,需要查它的文档。

不想逐个配置时的替代方案

以上三处设置都嫌麻烦的话,可以在宿主机的代理客户端里开启 TUN 模式,由虚拟网卡接管整机流量。守护进程拉镜像的流量通常会被一并接管;容器的流量是经过转发出去的,是否被接管取决于客户端和系统的具体实现,不如显式设置环境变量可靠。TUN 的说明见系统代理与 TUN 模式。

另外,拉镜像的流量不小,一个镜像几百 MB 到几 GB 很常见,都会计入机场套餐。经常拉取大镜像的话留意流量消耗,参考机场流量多少够用。

常见报错对照

docker pull 失败时,报错信息里的关键字能帮你判断问题出在哪一步,不必每次都从头排查。

报错关键字 一般含义 处理方向
i/o timeout、context deadline exceeded 守护进程直接连仓库,超时了 守护进程没有用上代理,按场景一设置并确认生效
TLS handshake timeout 连接建立了,握手阶段超时 没走代理,或者代理节点到仓库的线路不稳,换节点
proxyconnect tcp 加 connection refused 守护进程在用代理,但代理端口没人监听 代理客户端没运行,或者端口号写错
first record does not look like a TLS handshake 把代理地址的协议写成了 https:// 改回 http:// 开头
unexpected EOF、下载到一半中断 传输过程中连接被断开 节点不稳定,固定一个节点后重试,已下载的层不会重复下载
toomanyrequests 触发了镜像仓库的拉取频率限制 与代理无关,等一段时间,或登录仓库账号后再拉

第三行是配置了代理之后最常遇到的情况:代理写进了系统服务,客户端没开时所有拉取都会失败,而且报错里出现的是本地地址,容易让人摸不着头脑。长期不用代理的机器,记得把 drop-in 文件删掉并重启 Docker。

用 daemon.json 配置,以及怎么验证生效

前面提到较新版本的 Docker Engine 可以在 /etc/docker/daemon.json 里配置守护进程代理,这里给出写法。它需要 Docker Engine 23.0 或更高的版本:

{
  "proxies": {
    "http-proxy": "http://127.0.0.1:7890",
    "https-proxy": "http://127.0.0.1:7890",
    "no-proxy": "localhost,127.0.0.1"
  }
}

文件里已有其他配置项时,把 proxies 这一段合并进去。保存后执行 sudo systemctl restart docker。注意这里的字段名带连字符,和 ~/.docker/config.json 里的 httpProxy 写法不同,两个文件不要混淆:daemon.json 管守护进程拉镜像,config.json 管容器和构建。

systemd drop-in 和 daemon.json 只用一种。两处都写而内容不一致时,排查起来很费劲。

不管用哪种方式,都可以用下面的命令确认守护进程当前使用的代理:

docker info | grep -i proxy

输出里有 HTTP Proxy、HTTPS Proxy、No Proxy 几行,显示的就是正在生效的设置。什么都没有输出,说明守护进程没有配置代理,回去检查文件位置和是否重启过服务。

镜像加速器和代理是两回事

搜索 docker pull 超时,另一类常见的建议是配置镜像加速器,也就是在 daemon.json 里填写 registry-mirrors。它和代理解决的是同一个问题,但原理不同,适用范围也不同。

对比项 守护进程代理 镜像加速器
原理 守护进程经由代理访问原始仓库 改为从第三方的镜像站拉取
适用的仓库 所有仓库 只对 Docker Hub 上的镜像生效
镜像内容来自 官方仓库 镜像站的缓存
依赖 自己的代理和节点 镜像站是否还在提供服务
消耗机场流量 是 否

加速器的优点是不消耗机场流量,缺点是公开可用的镜像站经常变动,今天能用的地址过一阵可能就失效了,同步也可能有延迟。另外它只管 Docker Hub,其他仓库上的镜像它帮不上忙,仍然需要代理。

两者可以同时配置。这时把镜像站的域名加进 NO_PROXY,让它直连,不要再绕一圈代理。公司内网的私有仓库同理,也应该放进 NO_PROXY,既快,也避免内部地址被送到节点上去。

常见问题

设置了守护进程代理,docker pull 仍然超时怎么办?

先用 sudo systemctl show --property=Environment docker 确认变量确实生效,没有的话检查文件路径和是否执行了 daemon-reload 与重启。变量已生效仍然超时,在宿主机上用 curl -x http://127.0.0.1:7890 -I https://registry-1.docker.io/v2/ 测试代理本身,能收到 HTTP 响应(返回 401 属于正常,说明已经连到仓库)就表示代理可用;连不上则是代理客户端或节点的问题,换节点再试。

容器里报 Connection refused 是什么原因?

基本是两种:代理地址写成了 127.0.0.1,指向了容器自身;或者宿主机的代理客户端没有开启「允许局域网连接」。按前文改用宿主机地址,并在客户端里打开该选项后重启客户端。Linux 上再检查防火墙是否拦截了来自 Docker 网段的访问。

build-arg 传入的代理会留在镜像里吗?

HTTP_PROXY 这一组预定义构建参数不会被写入镜像的环境变量,也不会出现在 docker history 的输出中。但如果你在 Dockerfile 里用 ENV 设置了代理,或者把代理地址写进了镜像里的某个配置文件,那就会留下。代理地址只通过构建参数传递是最干净的做法。

Docker Desktop 里设置了代理,容器内为什么还是不能访问外网?

Docker Desktop 设置界面里的代理主要作用于拉取镜像等守护进程的请求。容器内部的程序是否使用代理,仍然取决于容器里的环境变量。按场景三用 -e 传入,或者配置 ~/.docker/config.json,地址使用 host.docker.internal。

怎么确认 Docker 守护进程已经用上了代理?

执行 docker info,在输出里找 HTTP Proxy 和 HTTPS Proxy 两行,显示的地址就是当前生效的代理。没有这两行说明没有配置成功,检查配置文件的位置,并确认修改后重启过 Docker 服务。

配置了镜像加速器,还需要设置代理吗?

看你拉的是哪里的镜像。加速器只对 Docker Hub 的镜像有效,其他仓库上的镜像仍然要靠代理。加速器地址失效时也需要代理兜底。两者可以并存,把加速器的域名放进不走代理的名单即可。

rootless 模式的 Docker,代理配置文件放在哪里?

rootless 模式下守护进程是以普通用户的 systemd 服务运行的,drop-in 文件要放在当前用户的 ~/.config/systemd/user/docker.service.d/ 目录下,内容和系统级的写法相同,之后用 systemctl --user daemon-reload 和 systemctl --user restart docker 使它生效。

在 WSL2 里使用 Docker 该怎么设置?

要先分清 Docker 运行在哪里。如果用的是 Docker Desktop 的 WSL 集成,按 Docker Desktop 的方式在设置界面里配置。如果是在 WSL2 发行版里自己安装的 Docker Engine,就按 Linux 的方式处理,同时要注意 WSL2 里访问 Windows 上的代理客户端也存在「127.0.0.1 不一定指向 Windows」的问题,取决于 WSL 的网络模式,需要确认能从 WSL 里连到 Windows 上的代理端口。

除了 Docker,开发时常用的 git、npm 的代理设置见终端代理设置教程,GitHub 克隆慢的处理见 GitHub 访问慢,编辑器相关的见 VS Code 代理设置。

本文中的套餐与价格整理自公开资料,核对日期为 2026年11月14日,未经本站实测,购买前请以官网为准。整理方法见这里。

接着读