Docker代理配置

Docker 在国内网络环境下的代理配置方案

#tech / ops #type / howto #status / growing

Docker 代理配置

目标

配置 Docker 使用代理服务器，解决国内网络环境下拉取镜像、构建镜像时网络不通的问题。

Windows（Docker Desktop）

直接在 Docker Desktop 设置中配置：Settings → Resources → Proxies

HTTP Proxy: http://host.docker.internal:7890
HTTPS Proxy: http://host.docker.internal:7890
No Proxy: localhost,127.0.0.1

[!NOTE] 注意事项

Docker Desktop 底层运行在 WSL 中，因此应使用 http://host.docker.internal:7890（指向宿主机）而非 http://localhost:7890（指向 WSL 内部）。如果 WSL 网络模式为 mirror 则不需要。

代理客户端必须 允许局域网连接（如 Clash 中的 “Allow LAN” 选项）

如果仍无法连接，先关闭防火墙测试。确认是防火墙问题后，为代理软件添加入站规则

Dockerfile 构建时报网络错误时，先单独拉取基础镜像验证代理是否生效

Linux（systemd 配置）

Docker Daemon 代理

创建 systemd override 文件：

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,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

验证 Daemon 代理

# 检查 Docker 环境变量
docker info | grep -i proxy

# 测试拉取镜像
docker pull hello-world

容器内代理（运行时）

容器运行时也需要代理访问外网（如 apt-get、pip install），需通过环境变量注入：

docker run -e HTTP_PROXY=http://host.docker.internal:7890 \
           -e HTTPS_PROXY=http://host.docker.internal:7890 \
           -e NO_PROXY=localhost,127.0.0.1 \
           -it ubuntu bash

Dockerfile 构建代理

在 docker build 阶段使用 ARG 传递代理：

FROM ubuntu:22.04

ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

RUN apt-get update && apt-get install -y curl

构建时传入：

docker build \
  --build-arg HTTP_PROXY=http://host.docker.internal:7890 \
  --build-arg HTTPS_PROXY=http://host.docker.internal:7890 \
  --build-arg NO_PROXY=localhost,127.0.0.1 \
  -t myimage .

[!WARNING] 安全提醒 ARG 值会保留在镜像层中，生产镜像建议使用多阶段构建，避免代理信息泄露。

镜像加速（Mirror Registry）

如果代理不稳定，可配置国内镜像源加速拉取：

// /etc/docker/daemon.json (Linux)
// %USERPROFILE%\.docker\daemon.json (Windows)
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://docker.m.daocloud.io"
  ]
}

配置后重启 Docker：

sudo systemctl restart docker  # Linux
# Windows: 重启 Docker Desktop

排查清单

症状	可能原因	检查方法
pull 超时	Daemon 代理未生效	`docker info \| grep proxy`
构建时网络错误	Dockerfile 内无代理	检查 `--build-arg` 是否传入
`host.docker.internal` 不通	WSL/防火墙问题	尝试用宿主机实际 IP
容器内无法访问外网	运行时未注入代理	`docker run -e` 注入环境变量

信息参考

Docker MOC
[[docker-usage|Docker 常用操作]]