Docker 配置代理示例

以下是在 Docker 中配置代理的常见场景和示例。

背景说明：在构建 Docker 镜像时，部分依赖需要从国外源下载（如 GitHub、Go 模块、Python 包等），如果服务器无法直接访问，可通过代理加速。

1. Docker Daemon 全局代理

此方式对所有容器和构建生效，包括拉取基础镜像。

创建配置文件：

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://你的代理:端口"
Environment="HTTPS_PROXY=http://你的代理:端口"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF
sudo systemctl daemon-reload && sudo systemctl restart docker

2. Docker Build 时使用代理（--build-arg）

在构建镜像时通过 --build-arg 传入代理变量，仅在本次构建中生效：

docker build \
  --build-arg HTTP_PROXY=http://192.168.1.100:7890 \
  --build-arg HTTPS_PROXY=http://192.168.1.100:7890 \
  --build-arg NO_PROXY=localhost,127.0.0.1 \
  -t my-image:latest .

3. 在 Dockerfile 中设置代理

在构建过程中临时设置代理（注意：生产镜像中不要保留代理配置）：

FROM ubuntu:22.04

# 设置构建时的代理
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# 安装依赖时会使用代理
RUN apt-get update && apt-get install -y curl wget && rm -rf /var/lib/apt/lists/*

构建时传入：

docker build \
  --build-arg HTTP_PROXY=http://192.168.1.100:7890 \
  --build-arg HTTPS_PROXY=http://192.168.1.100:7890 \
  -t my-image:latest .

4. Docker Compose 中配置代理

services:
  app:
    build:
      context: .
      args:
        - HTTP_PROXY=http://192.168.1.100:7890
        - HTTPS_PROXY=http://192.168.1.100:7890
    environment:
      - HTTP_PROXY=http://192.168.1.100:7890
      - HTTPS_PROXY=http://192.168.1.100:7890
      - NO_PROXY=localhost,127.0.0.1

5. 容器运行时代理

运行容器时传入代理环境变量：

docker run -e HTTP_PROXY=http://192.168.1.100:7890 \
  -e HTTPS_PROXY=http://192.168.1.100:7890 \
  my-image

6. Docker 客户端代理（~/.docker/config.json）

在 Docker 客户端配置文件中对特定镜像仓库使用代理：

{
  "proxies": {
    "default": {
      "httpProxy": "http://192.168.1.100:7890",
      "httpsProxy": "http://192.168.1.100:7890",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

注意事项

拉取基础镜像也需要代理

构建时使用 --build-arg 传入的代理仅影响 Dockerfile 中的 RUN 指令，不影响 FROM 拉取基础镜像。

如果需要代理来拉取基础镜像，必须使用 Docker Daemon 级别代理（第 1 种方式），即通过编辑 /etc/systemd/system/docker.service.d/proxy.conf 配置系统级代理后重启 Docker。

代理在某些指令下可能失效

有部分网络操作（如 pip install、npm install、go mod download 等）有自己的代理配置逻辑，不会自动读取 HTTP_PROXY 环境变量。

常见问题：

apt-get install 能正常走代理，速度较快
pip install 走代理慢或不走代理，需要在 Dockerfile 中额外设置 pip config set global.proxy，或传入 PIP_PROXY 环境变量，或者用国内镜像源（如 -i https://pypi.tuna.tsinghua.edu.cn/simple）
npm install 也需要用 --registry 参数或设置 npm config set registry
go mod download 需要设置 GOPROXY 环境变量
如果代理不稳定，可能出现某个 RUN 步骤超时失败，必须调大 timeout 或换更稳定的代理

代理断连或重启后未生效

镜像构建过程中网络中断，可能导致构建失败。常见的表现：

某条 RUN 指令执行到一半卡住然后报网络错误
重新构建时 Docker layer cache 会跳过该指令重跑，但下次仍然可能断连

规避方法：

分层执行，合理利用缓存 — 将容易失败的网络操作单独写一个 RUN，成功后缓存下来。下次即使断连也只需重跑这一层，而不是重跑整个构建
增加重试机制 — 对于 curl、wget 等命令可以加上 --retry 参数
本地构建后推送 — 对于基础依赖多的情况，建议先在本机完成构建，再用 docker push 推到仓库，服务器直接 docker pull 拉取，避免在构建机上频繁网络请求

多个镜像同时构建时代理负载过高

如果同时构建多个镜像，代理（特别是自建代理）可能承受不住并发请求，导致部分连接超时。

对应措施：

顺序构建，减少并发
使用更稳定的代理服务
考虑将基础层预构建并放到本地镜像仓库

其他

代理地址中的 IP 和端口根据实际情况替换
镜像发布前应清除代理相关环境变量以避免泄露内网信息

1. Docker Daemon 全局代理​

2. Docker Build 时使用代理（--build-arg）​

3. 在 Dockerfile 中设置代理​

4. Docker Compose 中配置代理​

5. 容器运行时代理​

6. Docker 客户端代理（~/.docker/config.json）​

注意事项​

拉取基础镜像也需要代理​

代理在某些指令下可能失效​

代理断连或重启后未生效​

多个镜像同时构建时代理负载过高​

其他​