构建 Docker 镜像时，告别龟速下载：网络代理加速构建效率秘籍（亲自测试：2025年8月10日）

构建 Docker 镜像时，告别龟速下载：优化构建过程的网络连接效率秘籍

在 Docker 的世界里，构建镜像是开发部署的核心环节。然而，当你的 Dockerfile 中包含 RUN apt-get update、RUN pip install、RUN npm install 等命令，需要从互联网下载大量依赖时，你是否曾被那漫长的等待折磨？特别是当你的网络环境存在资源获取效率瓶颈，或者你希望通过更优化的连接路径进行加速时，这个问题会更加突出。
在这里插入图片描述

本文将深入探讨如何在构建 Docker 镜像时，巧妙利用 HTTP_PROXY 和 HTTPS_PROXY 环境变量，为你的依赖下载提速，确保你的构建过程顺畅高效，大幅提升开发效率。

为什么需要优化网络连接？

在企业环境、特定网络部署或需要访问特定资源时，直接连接外部网络可能会遇到：

网络访问限制： 防火墙或网络策略可能阻止直接访问公共软件包仓库或资源站点。
下载速度慢： 某些区域到外部软件包源的连接效率不理想。
网络通信合规： 所有出站流量可能需要经过统一的通信管理和审计。
内容缓存： 中间传输机制可以缓存已下载的软件包，提高后续下载速度。

在这种情况下，通过配置中间传输机制来转发网络请求，是解决这些问题的有效途径。

核心概念：HTTP_PROXY 与 Docker 构建原理

Docker 构建过程可以分为几个阶段：

拉取基础镜像 (FROM)： 这是 Docker Daemon 自身的操作，不直接受 Dockerfile 内部环境变量控制。
构建步骤 (RUN, COPY 等)： 在此阶段，Dockerfile 中的指令会被执行。

为了让这两个阶段都能有效利用优化的网络连接，我们需要做两件事：

为 Docker Daemon 配置外部连接： 确保 Docker Daemon 在拉取基础镜像时也能通过预设的连接路径。
为 Dockerfile 内部的构建命令配置连接： 确保 RUN 命令中的包管理器（如 apt-get, pip, npm 等）能够通过预设的连接路径下载依赖。

步骤一：配置 Docker Daemon 的外部连接 (处理 `FROM` 阶段)

这是确保 Docker Daemon 能够拉取 Docker Hub 等外部镜像的关键。

对于 Docker Desktop (Windows / macOS)

这是最简单直接的方法：

打开 Docker Desktop 应用。
点击右上角的 齿轮图标 (Settings / Preferences)。
导航到 “Resources” > “Proxies” 或直接是 “Proxies” 选项卡。
选择 “Manual proxy configuration”。
在 Web Proxy (HTTP) 和 Secure Web Proxy (HTTPS) 字段中输入你的中间传输服务地址。通常，如果你的传输软件运行在宿主机上，可以使用宿主机的局域网 IP 地址或 host.docker.internal。
- 示例： http://192.168.1.100:1080 (替换为你的实际 IP 和端口)
- 或： http://host.docker.internal:1080
点击 “Apply & Restart” 或 “Apply”。

对于 Linux

编辑 Docker Daemon 的配置文件。通常是 /etc/docker/daemon.json。如果文件不存在，则创建它。

添加或修改以下内容：

{
  "proxies": {
    "http-proxy": "http://127.0.0.1:1080",
    "https-proxy": "http://127.0.0.1:1080",
    "no-proxy": "localhost,127.0.0.1,.svc,.local" # 根据需要配置不走连接优化的地址
  }
}

请注意，这里使用 127.0.0.1 假定中间传输服务也在 Linux 宿主机上运行。如果服务在其他机器上，请替换为相应的 IP 地址。

保存文件并重启 Docker Daemon：

sudo systemctl daemon-reload
sudo systemctl restart docker

步骤二：为 Dockerfile 内部构建命令配置连接 (处理 `RUN` 阶段)

这是确保 pip, apt-get 等工具能正常通过预设连接下载的关键。

在 Dockerfile 中，我们需要使用 ARG 和 ENV 指令来传递连接配置。

# Dockerfile 示例

# Stage 1: BUILD (或直接作为单阶段)
FROM python:3.12-slim AS build
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV http_proxy=${HTTP_PROXY}
ENV https_proxy=${HTTPS_PROXY}
# 设置工作目录
WORKDIR /code

# 复制应用程序依赖文件
COPY requirements.txt .

# 安装 Python 依赖
# 使用 --no-cache-dir 减少镜像大小
RUN pip install --no-cache-dir -r requirements.txt

# 复制所有应用程序代码
# 这一步应在安装依赖之后，以便利用Docker层缓存
COPY . .

# 暴露 FastAPI 默认端口
EXPOSE 8001

# 定义容器启动时运行的命令
# --host 0.0.0.0 允许从外部访问
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8001"]


# docker build \
#   --build-arg HTTP_PROXY="http://your.proxy.server:port" \
#   --build-arg HTTPS_PROXY="http://your.proxy.server:port" \
#   -t kingsyardfastapi:24-11-10 \
#   -f Dockerfile.fastapi .

步骤三：执行 `docker build` 命令时传入连接参数

现在，当你执行构建命令时，通过 --build-arg 参数将连接地址传递给 Dockerfile：

# 假设你的中间传输服务在宿主机上，并且地址为 172.17.153.51:1080
# 请将 172.17.153.51 替换为你的实际宿主机 IP 或 host.docker.internal

docker build \
  --build-arg HTTP_PROXY="http://172.17.153.51:1080" \
  --build-arg HTTPS_PROXY="http://172.17.153.51:1080" \
  --build-arg NO_PROXY="localhost,127.0.0.1,example.com" \ # 如果有不需要走连接优化的地址
  -t my-fast-app:latest \
  -f Dockerfile .

重要提示：

--build-arg 的值是你在 Dockerfile 中 ARG 声明的变量的值。
host.docker.internal： 这是 Docker Desktop (Windows/macOS) 提供的一个特殊 DNS 名称，它解析到宿主机的 IP 地址。在容器内部，你可以通过它访问宿主机上的服务。但在某些复杂的网络或 WSL2 环境下，直接使用宿主机的局域网 IP 地址可能会更稳定。
- 如何获取宿主机 IP (Windows): ipconfig 命令，找到你的 “IPv4 地址”。
- 如何获取宿主机 IP (macOS): ifconfig | grep "inet " | grep -v 127.0.0.1。
中间传输服务配置： 请确保你的中间传输软件（如支持 HTTP/SOCKS5 转发的工具，请自行配置）已经开启了 HTTP 或混合模式，并在指定的端口（如 1080）上监听 HTTP/HTTPS 流量。如果只开启了 SOCKS5 传输，那么 HTTP 连接是无法通过的。

故障排除小贴士

ProxyError('Cannot connect to proxy.', NewConnectionError('[Errno -2] Name or service not known'))： 这通常是容器无法解析中间传输服务地址（host.docker.internal 或你填写的 IP）的 DNS 问题，或者服务根本没有正常运行。
- 解决方案： 尝试将 host.docker.internal 替换为宿主机的实际局域网 IP 地址。
- 测试服务： 在宿主机命令行运行 curl -x http://127.0.0.1:1080 https://www.google.com (请用你中间传输服务的真实IP和端口替换 127.0.0.1:1080)，看是否能成功访问 Google。如果不能，说明传输服务本身没有正常提供 HTTP 连接能力。
i/o timeout (在 FROM 阶段)： 这意味着 Docker Daemon 无法连接到 Docker Hub。检查 Docker Desktop 的连接设置是否正确，并且中间传输服务是否正常运行。
WARNING: Retrying... connection broken by 'ProxyError' (在 RUN pip install 阶段)： 这通常是 Dockerfile 内部的连接配置问题，或者传输服务器没有正确响应。检查 ARG 和 ENV 设置，并确保 pip 等工具能够识别这些环境变量。