Docker 有三处代理设置,各管一段。拉取和推送镜像(docker pull、docker push)是后台的守护进程 dockerd 在联网,代理要配在 /etc/docker/daemon.json 的 proxies 里(Docker Engine 23.0 起支持),或者配成 systemd 的环境变量,改完重启 Docker。docker build 里 RUN 步骤的下载和容器运行时的访问,读的是客户端 ~/.docker/config.json 里的 proxies,保存即生效。Docker Desktop 不认 daemon.json 里的代理,要在它的设置页里填。只在终端里 export HTTPS_PROXY 对 docker pull 没用,因为真正去拉镜像的不是你敲命令的那个终端。
本文由 Proxy302 维护,我们出售这类代理 IP。下面的配置依据 2026 年 11 月的 Docker 官方文档核对,没有在本机实际运行。
| 动作 | 谁在联网 | 配在哪里 | 要不要重启 |
|---|---|---|---|
docker pull、docker push、docker login |
守护进程 dockerd | daemon.json 或 systemd 环境变量;Docker Desktop 用设置页 |
要 |
docker build 里 RUN apt-get、RUN pip install |
构建用的临时容器 | ~/.docker/config.json,或 --build-arg |
不要 |
| 容器跑起来以后访问外网 | 容器本身 | ~/.docker/config.json,或 docker run -e |
不要,只对新容器生效 |
编辑 /etc/docker/daemon.json。文件已经存在的话,把 proxies 这一段合并进去,别覆盖其他配置:
{
"proxies": {
"http-proxy": "http://USER:PASS@HOST:PORT",
"https-proxy": "http://USER:PASS@HOST:PORT",
"no-proxy": "localhost,127.0.0.0/8"
}
}
然后重启并检查:
sudo systemctl restart docker
docker info | grep -i proxy
docker info 会列出 HTTP Proxy、HTTPS Proxy 和 No Proxy 三行,账号密码会打码显示。注意 https-proxy 的值也是 http:// 开头:它表示「访问 HTTPS 仓库时用这个代理」,代理本身仍是普通 HTTP 代理。
适合旧版本 Docker。新建 /etc/systemd/system/docker.service.d/http-proxy.conf:
[Service]
Environment="HTTP_PROXY=http://USER:PASS@HOST:PORT"
Environment="HTTPS_PROXY=http://USER:PASS@HOST:PORT"
Environment="NO_PROXY=localhost,127.0.0.0/8"
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl show --property=Environment docker
两种方法同时存在时,daemon.json 优先。rootless 模式把文件放在 ~/.config/systemd/user/docker.service.d/,命令换成不带 sudo 的 systemctl --user。
密码里有特殊字符: 先做 URL 编码,例如 # 写成 %23、@ 写成 %40。写进 systemd 文件时,% 本身还要写成 %%,也就是 %%23。daemon.json 里不用这一步。
{
"proxies": {
"default": {
"httpProxy": "http://USER:PASS@HOST:PORT",
"httpsProxy": "http://USER:PASS@HOST:PORT",
"noProxy": "localhost,127.0.0.0/8"
}
}
}
保存后,新建的容器和新的构建会自动带上 HTTP_PROXY、HTTPS_PROXY、NO_PROXY 环境变量,已经在跑的容器不受影响。验证容器的出口:
docker run --rm curlimages/curl -s https://ipinfo.io/json
返回的 ip 和 country 应该是代理的,不是服务器自己的。
只想让某一次构建或某一个容器走代理,不改配置文件:
docker build --build-arg HTTPS_PROXY=http://USER:PASS@HOST:PORT .
docker run --rm -e HTTPS_PROXY=http://USER:PASS@HOST:PORT IMAGE
注意密码会留在哪里: 通过 config.json 或 -e 传进容器的代理是明文环境变量,用 docker inspect 能看到,docker commit 会把它带进镜像。不要在 Dockerfile 里用 ENV 写代理。--build-arg 传的代理变量只在构建过程里存在,不会写进构建结果。
Docker Desktop 忽略 daemon.json 里的代理。打开设置,在 Resources(新版本叫 VM resources)下的 Proxies 页选手动配置(Manual),把 http://HOST:PORT 填进 Web Server (HTTP) 和 Secure Web Server (HTTPS)。新版本把代理分成两项:Docker Desktop 自身的代理和 Containers 代理,拉镜像走后者,没单独设置时沿用前者。代理要求账号密码(Basic 认证)时,Docker Desktop 会弹窗询问,并存进系统的凭据管理里。官方文档写明 SOCKS5 代理需要 Business 订阅,个人用 HTTP 类型更省事。
| 报错里有 | 原因 |
|---|---|
proxyconnect tcp: dial tcp HOST:PORT: connect: connection refused |
代理地址或端口不对,或服务器出站被防火墙拦了 |
Proxy Authentication Required |
账号密码错,或特殊字符没编码 |
proxyconnect tcp: tls: first record does not look like a TLS handshake |
代理地址写成了 https://,改成 http:// |
x509: certificate signed by unknown authority |
网络里有设备在解密 HTTPS,需要把对方的 CA 证书加进系统信任;见 SSL errors through a proxy |
TLS handshake timeout、context deadline exceeded |
代理或仓库响应慢,先用 curl -x 单独测代理 |
| 改了配置还是直连 | 改的是 config.json 却在测 docker pull,或改了 daemon.json 没重启 |
toomanyrequests |
Docker Hub 的拉取次数限制。按 Docker 的规则登录账号或调整用量,代理不改变这条规则 |
终端里已经设了 HTTPS_PROXY,为什么还是拉不下来? 拉镜像的是 dockerd,它是系统服务,不读你当前终端的环境变量。
能不能只让 Docker Hub 走代理,公司内部仓库不走? 可以。把内部仓库的域名写进 no-proxy。
SOCKS5 的 IP 能用吗? Docker Engine 文档里的例子都是 HTTP 代理,没有写明守护进程对 SOCKS5 的支持;容器里的 apt、pip、curl 等工具对 SOCKS5 的支持也各不相同。给 Docker 用,买 HTTP 类型最省事。
服务器拉私有仓库,仓库设了 IP 白名单,用什么 IP? 用静态 ISP(静态住宅)IP。租期内地址不变,白名单上那一条一直有效。
Proxy302 卖静态 ISP(静态住宅)IP,购买时选 HTTP 或 SOCKS5,一个 IP 只有一种协议。每个 IP 1 天 0.50 美元、30 天 7.99 美元,所有国家同价,可以按 IP 开自动续费。没有免费试用,最便宜的测试是买 1 个 IP 用 1 天。价格见价格页。
事实核对于 2026 年 11 月 19 日。