Docker 代理设置详解：解决网络问题 – wiki基地

作者： /

Docker 代理设置详解：解决网络问题

在现代软件开发和部署流程中，Docker 已成为不可或缺的工具。然而，在使用 Docker 的过程中，尤其是在企业内部网络、受限环境或需要访问特定资源的场景下，网络问题常常成为绊脚石。其中最常见的挑战之一就是如何正确配置 Docker 及其容器通过代理服务器访问外部网络。

本文将深入探讨 Docker 的代理设置，涵盖 Docker Daemon、Docker Build 和 Docker Container Runtime 三个层面的配置方法、原理、常见问题及解决方案，帮助您彻底解决 Docker 在代理环境下的网络连接难题。

目录

  1. 引言：为何 Docker 需要代理？

    • Docker 的网络依赖性
    • 代理服务器的角色
    • 不同场景下的代理需求

  2. 理解 Docker 中的代理配置层级

    • Docker Daemon 代理：影响 Docker 服务本身
    • Docker Build 代理：影响镜像构建过程
    • Docker Container Runtime 代理：影响运行中的容器

  3. Docker Daemon 代理配置

    • 作用范围：影响 Docker 服务的行为
    • 配置方法：daemon.json 文件
    • 详细参数：http-proxy, https-proxy, no-proxy
    • 配置示例 (Linux, Windows, macOS)
    • 验证配置
    • 注意事项

  4. Docker Build 代理配置

    • 作用范围：影响 Dockerfile 中的构建指令（如 RUN）
    • 配置方法一：使用 Build Arguments (--build-arg)
      • 预定义 Build Arguments (HTTP_PROXY, HTTPS_PROXY, NO_PROXY)
      • 使用 --build-arg 的优缺点
      • 配置示例
    • 配置方法二：在 Dockerfile 中设置环境变量 (ENV)
      • 使用 ENV 指令
      • 使用 ENV 的优缺点
      • 配置示例
    • 选择合适的配置方法

  5. Docker Container Runtime 代理配置

    • 作用范围：影响运行中的容器内部应用程序的网络请求
    • 配置方法一：在 Dockerfile 中设置环境变量 (ENV)
      • 设置默认的容器环境变量
      • 配置示例
    • 配置方法二：使用 docker run 命令的 -e 选项
      • 在启动时覆盖或添加环境变量
      • 配置示例
    • 运行时代理与构建时代理的区别

  6. 深入理解 NO_PROXY

    • NO_PROXY 的作用与重要性
    • 配置格式和示例
    • 应用场景：内部网络、本地通信

  7. 处理 HTTPS 代理与证书问题

    • HTTPS 代理的挑战
    • Docker Daemon 对证书的处理
    • 在容器内信任自定义 CA 证书
    • 配置示例

  8. 常见问题与故障排除

    • 代理配置未生效
    • 证书错误 (x509: certificate signed by unknown authority)
    • NO_PROXY 配置不正确
    • 代理需要认证
    • DNS 解析问题
    • 网络防火墙问题

  9. 最佳实践

    • 区分不同层级的代理需求
    • 使用环境变量而非硬编码
    • 妥善管理代理认证信息
    • 有效利用 NO_PROXY
    • 保持 Docker 版本更新

  10. 总结

1. 引言：为何 Docker 需要代理？

Docker 的核心功能之一是拉取（Pull）和推送（Push）镜像。这些镜像通常存储在远程镜像仓库中，最常见的是 Docker Hub。此外，在构建镜像时，Dockerfile 中的 RUN 指令可能需要从各种源下载软件包、代码或依赖项（例如，使用 apt-get update, yum install, pip install, npm install 等命令）。运行中的容器内的应用程序也可能需要访问外部 API、数据库或服务。

在许多企业或组织的网络环境中，出于安全、审计或带宽管理的考虑，直接访问外部互联网是被禁止的。所有的外部网络流量必须通过一个或多个代理服务器。在这种环境下，如果 Docker 没有正确配置代理，将无法完成上述网络密集型任务，导致镜像拉取失败、构建失败或容器应用无法正常工作。

因此，了解并正确配置 Docker 的代理设置，是确保 Docker 在复杂网络环境中顺利运行的关键。我们需要根据不同的场景，将代理信息告知 Docker Daemon、Docker Build 过程以及运行中的容器。

2. 理解 Docker 中的代理配置层级

在 Docker 中，代理设置并非一概而论，它根据应用阶段的不同，有三个主要的配置层级：

  • Docker Daemon 代理： 这是最基础的层级，影响的是 Docker 服务本身。配置此代理后，Docker Daemon 在执行诸如拉取/推送镜像到配置的镜像仓库（如 Docker Hub）等操作时会通过指定的代理服务器进行连接。这解决了 Docker 服务与外部镜像仓库通信的问题。
  • Docker Build 代理： 这个层级影响的是使用 docker build 命令构建镜像的过程。当 Dockerfile 中的 RUN 指令需要访问外部网络（例如，安装软件包、下载文件）时，需要 Build 过程能够通过代理连接。如果没有正确配置，apt-get update 或 pip install 等命令可能会失败。
  • Docker Container Runtime 代理： 这个层级影响的是使用 docker run 命令启动后，在容器内部运行的应用程序。如果您的容器内运行的应用需要访问外部网络，那么这个应用需要知道如何通过代理服务器进行连接。这通常是通过在容器内部设置环境变量来实现的。

理解这三个层级的区别至关重要，因为它们解决的是不同环节的网络问题。有时您可能只需要配置其中一个层级，有时则需要同时配置多个层级。

3. Docker Daemon 代理配置

Docker Daemon 是运行在主机上的后台服务，负责管理 Docker 对象（镜像、容器、网络、数据卷等）。它的代理配置影响的是 Docker 服务本身的网络行为，主要是与 Docker Hub 或其他远程镜像仓库的通信。

作用范围

  • 拉取（docker pull）镜像
  • 推送（docker push）镜像
  • 与默认的 Docker Hub (docker.io) 或配置的其他注册中心进行通信。

配置方法：daemon.json 文件

Docker Daemon 的配置主要通过修改其配置文件 daemon.json 来完成。这个文件通常位于 Docker 的配置目录下。

  • Linux: /etc/docker/daemon.json
  • Windows Server: C:\ProgramData\Docker\config\daemon.json
  • Windows Desktop (Docker Desktop): %APPDATA%\Docker\config\daemon.json 或通过 Docker Desktop GUI 配置。
  • macOS (Docker Desktop): 通过 Docker Desktop GUI 配置。配置文件通常在内部，不推荐直接编辑。

如果文件不存在，您可以创建一个新的。daemon.json 是一个 JSON 格式的文件。

详细参数

在 daemon.json 中，您可以使用以下键来配置代理：

  • "http-proxy": 指定 HTTP 代理服务器地址。例如 "http://proxy.example.com:8080"。
  • "https-proxy": 指定 HTTPS 代理服务器地址。例如 "https://proxy.example.com:8443"。通常，这个地址和端口与 http-proxy 相同，但如果代理服务器对 HTTPS 连接有特殊处理，可能需要单独设置。
  • "no-proxy": 指定不需要通过代理访问的主机或域名的列表。这是一个字符串，包含以逗号分隔的主机名、域名、IP 地址或 CIDR 表示法（例如 "localhost,127.0.0.1,*.local,10.0.0.0/8"）。注意： 这里的配置会覆盖系统级别的 NO_PROXY 环境变量。

重要的环境变量对应关系：

Docker Daemon 实际上会读取并使用系统级别的 HTTP_PROXY, HTTPS_PROXY, NO_PROXY (或小写的 http_proxy, https_proxy, no_proxy) 环境变量。然而，官方推荐使用 daemon.json 进行配置，因为它更加明确且不容易受到宿主机环境变量变化的影响。如果在 daemon.json 中配置了代理，它会优先于系统环境变量。

配置示例 (Linux)

假设您的 HTTP 代理是 http://proxy.example.com:8080，HTTPS 代理是 http://proxy.example.com:8080 (注意：HTTPS 代理通常也监听 HTTP 端口，但处理 HTTPS 流量)，并且您希望访问本地地址和内部网络 192.168.0.0/16 时不通过代理。

编辑或创建 /etc/docker/daemon.json 文件：

json
{
"http-proxy": "http://proxy.example.com:8080",
"https-proxy": "http://proxy.example.com:8080",
"no-proxy": "localhost,127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.example.com"
}

注意： 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 是标准的私有 IP 地址范围，通常建议将它们添加到 no-proxy 中。.example.com 是一个示例，表示所有 example.com 的子域都不通过代理。

验证配置

配置完成后，需要重启 Docker Daemon 使配置生效。

  • Linux (systemd):
    bash
    sudo systemctl daemon-reload
    sudo systemctl restart docker
  • Linux (Upstart):
    bash
    sudo service docker restart
  • Windows Server:
    在 PowerShell 中运行 Restart-Service docker
  • Docker Desktop (Windows/macOS): 通常在应用界面中应用配置并重启。

重启后，您可以通过以下命令验证配置是否加载：

bash
docker info | grep -i proxy

如果配置成功，您应该能看到类似以下的输出：

HTTP Proxy: http://proxy.example.com:8080
HTTPS Proxy: http://proxy.example.com:8080
No Proxy: localhost,127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.example.com

现在，当您执行 docker pull ubuntu 等命令时，Docker Daemon 应该会通过配置的代理服务器去拉取镜像。

注意事项

  • daemon.json 文件必须是有效的 JSON 格式。任何语法错误都可能导致 Docker Daemon 启动失败或配置不生效。
  • 代理地址通常包含协议 (http:// 或 https://)、主机名或 IP 地址，以及端口号。
  • 如果代理服务器需要用户名和密码认证，您可以将凭据包含在 URL 中，例如 "http://user:[email protected]:8080"。然而，将凭据直接写在配置文件中存在安全风险，不推荐这样做，尤其是在共享环境中。 更好的做法是考虑使用不基于基本认证的代理方案，或者在宿主机系统级别配置需要认证的代理（但这取决于操作系统和代理软件的支持）。
  • no-proxy 的格式非常重要，请仔细检查。它支持 IP 地址、CIDR、主机名和域名通配符 (*.example.com 或 .example.com)。

4. Docker Build 代理配置

Docker Build 过程会执行 Dockerfile 中的指令。当执行 RUN 指令时，可能会需要访问外部网络来安装软件、下载依赖等。这些网络请求发生在构建环境内部，独立于 Docker Daemon。因此，即使您配置了 Docker Daemon 代理，构建过程中的网络请求可能仍然无法通过代理。

作用范围

  • RUN 指令中执行的网络相关命令（如 apt-get update, yum install, wget, curl, git clone 等）。

配置方法一：使用 Build Arguments (--build-arg)

推荐使用 Build Arguments 的方式来为构建过程设置代理。Docker 内置支持识别 HTTP_PROXY, HTTPS_PROXY, NO_PROXY (以及它们的小写形式) 作为 Build Arguments。

您可以在 Dockerfile 中定义这些参数，并在 docker build 命令中传入值。

Dockerfile 示例：

“`Dockerfile

定义代理相关的构建参数

ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

将构建参数的值传递给环境环境变量，供RUN指令使用

注意：ARG 只在 build 命令中可见，ENV 会写入镜像

ENV http_proxy=$HTTP_PROXY
ENV https_proxy=$HTTPS_PROXY
ENV no_proxy=$NO_PROXY

FROM ubuntu:latest

RUN apt-get update && apt-get install -y –no-install-recommends some-package && rm -rf /var/lib/apt/lists/*

… 其他指令

“`

构建命令示例：

假设您的代理地址是 http://proxy.example.com:8080。

bash
docker build \
--build-arg HTTP_PROXY="http://proxy.example.com:8080" \
--build-arg HTTPS_PROXY="http://proxy.example.com:8080" \
--build-arg NO_PROXY="localhost,127.0.0.1,*.local" \
-t my-image .

使用 --build-arg 的优缺点：

  • 优点：
    • 灵活性： 可以在构建时根据需要轻松切换代理或禁用代理，而无需修改 Dockerfile。
    • 安全性（相对）： 使用 ARG 定义的参数在镜像构建完成后不会保留在最终镜像的历史层中（尽管它们可能在构建过程中的中间层中可见，但这通常比直接用 ENV 好）。特别是对于包含认证信息的代理 URL。
    • 标准： HTTP_PROXY, HTTPS_PROXY, NO_PROXY 是许多工具（如 apt, yum, wget, curl, git 等）默认识别的标准环境变量。
  • 缺点：
    • 需要在每个 docker build 命令中手动指定 --build-arg，如果命令复杂，可能会显得冗长。
    • 如果代理需要频繁更改，维护构建脚本会比较麻烦。

配置方法二：在 Dockerfile 中设置环境变量 (ENV)

另一种方法是直接在 Dockerfile 中使用 ENV 指令设置代理相关的环境变量。

Dockerfile 示例：

“`Dockerfile
FROM ubuntu:latest

直接在Dockerfile中设置代理环境变量

ENV http_proxy=”http://proxy.example.com:8080″
ENV https_proxy=”http://proxy.example.com:8080″
ENV no_proxy=”localhost,127.0.0.1,*.local”

RUN apt-get update && apt-get install -y –no-install-recommends some-package && rm -rf /var/lib/apt/lists/*

… 其他指令

“`

构建命令：

直接运行 docker build -t my-image . 即可，无需额外的 --build-arg。

使用 ENV 的优缺点：

  • 优点：
    • 简洁： Dockerfile 包含了所有必要的代理信息，构建命令更简单。
  • 缺点：
    • 灵活性差： 如果需要更改代理，必须修改 Dockerfile 并重新构建。
    • 安全性风险： 使用 ENV 设置的变量会被”烘焙”到镜像的层中。如果代理 URL 包含敏感信息（如用户名/密码），这些信息会留在镜像历史中，容易被查看 (docker history <image-id>)。这通常是不推荐的做法。

选择合适的配置方法

在绝大多数情况下，推荐使用 --build-arg 结合 ARG 和 ENV 的方式。定义 ARG 参数，然后在 Dockerfile 中用 ENV 将 ARG 的值赋给环境变量。这样既保持了构建命令的灵活性，又能利用标准的代理环境变量。为了安全，请避免在 Dockerfile 中直接用 ENV 设置包含敏感信息的代理 URL。

如果您需要在构建过程中访问内部资源（不通过代理），请确保在 NO_PROXY 中包含这些资源的地址。

5. Docker Container Runtime 代理配置

即使 Docker Daemon 可以拉取镜像，构建过程可以下载依赖，但运行起来的容器内部的应用程序是否能正常访问外部网络，取决于容器自身的网络配置和应用是否支持代理。这通常是通过在容器的环境中设置代理相关的环境变量来实现的。

作用范围

  • 运行在容器内部的应用程序发起的网络请求。

配置方法一：在 Dockerfile 中设置环境变量 (ENV)

您可以在构建镜像时，就在 Dockerfile 中设置好容器运行时的默认代理环境变量。这样，所有基于这个镜像创建的容器都会继承这些环境变量。

Dockerfile 示例：

“`Dockerfile
FROM my-base-image # 假设这是您构建好的包含应用程序的基础镜像

设置运行时代理环境变量

注意：这里的代理信息会伴随容器整个生命周期

ENV HTTP_PROXY=”http://proxy.example.com:8080″
ENV HTTPS_PROXY=”http://proxy.example.com:8080″
ENV NO_PROXY=”localhost,127.0.0.1,*.local,internal.service.com”

… 其他配置或启动命令

CMD [“my-app”]
“`

使用此镜像创建容器：

bash
docker run -d my-app-image

容器启动后，内部的应用程序如果遵循 HTTP_PROXY, HTTPS_PROXY, NO_PROXY 等标准环境变量，就会通过指定的代理服务器进行网络通信。

使用 ENV 在 Dockerfile 中设置运行时代理的优缺点：

  • 优点：
    • 便捷性： 所有基于此镜像的容器都自动带有代理配置。
    • 一致性： 确保容器具有预期的网络环境。
  • 缺点：
    • 灵活性差： 如果需要更改代理，必须修改 Dockerfile 并重新构建镜像。
    • 安全风险： 同样，如果代理 URL 包含敏感信息，这些信息会保留在镜像中。
    • 强制性： 所有容器都继承此配置，可能不适合所有使用场景。

配置方法二：使用 docker run 命令的 -e 选项

更灵活的方式是在使用 docker run 命令启动容器时，通过 -e 选项传递环境变量。这可以覆盖 Dockerfile 中设置的默认值，或者为没有在 Dockerfile 中设置代理的环境变量提供值。

使用 -e 启动容器示例：

bash
docker run -d \
-e HTTP_PROXY="http://proxy.example.com:8080" \
-e HTTPS_PROXY="http://proxy.example.com:8080" \
-e NO_PROXY="localhost,127.0.0.1,*.local,internal.service.com" \
my-app-image

使用 -e 设置运行时代理的优缺点：

  • 优点：
    • 极高的灵活性： 可以为每个容器实例指定不同的代理配置，或者在启动时决定是否使用代理。
    • 安全性（相对）： 代理信息不存储在镜像中，而是在运行时传递。虽然在 docker inspect <container-id> 中仍然可见，但比存储在镜像历史中更安全一些。
  • 缺点：
    • 管理开销： 对于大量容器，管理 -e 参数可能会比较繁琐，尤其是在编排工具（如 Docker Compose, Kubernetes）中需要重复配置。

运行时代理与构建时代理的区别

务必区分运行时代理和构建时代理。构建时代理影响的是 Dockerfile 中的 RUN 指令，它在镜像构建完成后就不再起作用了。运行时代理影响的是容器启动后，容器内部应用程序的网络行为。它们是相互独立的配置。您可能只需要配置其中一个，或者两者都需要配置，具体取决于您的需求。

6. 深入理解 NO_PROXY

NO_PROXY (或 no_proxy) 环境变量是一个非常重要的概念，它用于指定一系列主机、域或 IP 地址范围，访问这些目标时应该不通过代理服务器直接连接。这对于访问内部网络资源、本地服务或避免不必要的代理开销至关重要。

NO_PROXY 的作用与重要性

在很多场景下，您的应用程序或构建过程需要访问位于同一内部网络中的其他服务、数据库或私有注册中心。如果所有流量都被强制通过外部代理，可能会导致：

  • 性能下降： 内部流量绕行外部代理，增加了延迟。
  • 连接失败： 外部代理可能无法解析内部域名，或者没有访问内部资源的权限。
  • 安全问题： 将内部流量暴露给外部代理服务器。

NO_PROXY 就是用来解决这些问题的。它告诉客户端（Docker Daemon, Build 进程, 容器内应用）：“如果目标地址匹配这个列表，就直接连接，不要走代理。”

配置格式和示例

NO_PROXY 的值是一个字符串，包含以逗号分隔的条目。这些条目可以是：

  • 主机名或域名： localhost, internal.service.com
  • IP 地址： 192.168.1.100
  • IP 地址范围 (CIDR 表示法)： 192.168.0.0/16, 10.0.0.0/8
  • 域名通配符： *.local, .internal.network (注意前导点号表示匹配该域名及其所有子域)

示例值：

"localhost,127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.mycompany.local,internal-registry.mycompany.com"

这个示例 NO_PROXY 配置表示：访问 localhost、标准私有 IP 地址范围内的地址、所有 .mycompany.local 域名下的主机以及 internal-registry.mycompany.com 时，都直接连接，不通过代理。

应用场景

  • 访问内部服务： 当容器需要访问企业内部的数据库、API 网关、消息队列等服务时。
  • 访问私有注册中心： 当 Docker Daemon 或 Build 过程需要从私有 Docker 注册中心（如 Harbor, Nexus）拉取镜像时。私有注册中心通常在内部网络中。
  • 本地开发/测试： 当容器需要与宿主机上的服务或同一 Docker 网络中的其他容器通信时。
  • Kubernetes 集群内部通信： 在 Kubernetes 环境中，Pod 之间的通信通常不需要通过外部代理。Kubernetes 相关的服务地址（如 Cluster IP）也需要添加到 NO_PROXY 中。

重要提示： NO_PROXY 列表需要包含所有您希望不通过代理访问的内部资源。漏掉任何一个都可能导致连接失败。

7. 处理 HTTPS 代理与证书问题

当使用 HTTPS 代理或需要访问使用自定义/企业内部 CA 签发的 HTTPS 服务的注册中心或网站时，会遇到证书信任问题。默认情况下，Docker 和操作系统只信任公共的 CA 证书。如果代理服务器或目标服务使用了不被默认信任的证书，连接会失败，通常会报 x509: certificate signed by unknown authority 错误。

解决这个问题需要在 Docker Daemon 层面和/或容器内部让系统信任这些自定义 CA 证书。

Docker Daemon 对证书的处理

Docker Daemon 在与注册中心通信时，会检查 TLS 证书。您可以将自定义 CA 证书放置在特定的目录下，让 Docker Daemon 信任它们。

对于一个注册中心 my-registry.example.com，您可以将其 CA 证书文件（通常是 .crt 格式）复制到 /etc/docker/certs.d/my-registry.example.com/ 目录下（Linux）。

bash
sudo mkdir -p /etc/docker/certs.d/my-registry.example.com
sudo cp my-ca.crt /etc/docker/certs.d/my-registry.example.com/
sudo systemctl restart docker # 重启Docker Daemon

Docker Daemon 启动时会读取此目录下的证书，并在与 my-registry.example.com 建立 TLS 连接时信任这些证书。

如果代理服务器本身使用了自定义 CA 签发的证书，并且 Docker Daemon 需要通过这个 HTTPS 代理访问外部（例如 Docker Hub），您可能需要将代理的 CA 证书添加到宿主机的系统信任存储中，具体步骤取决于您的操作系统。或者，如果代理 URL 中明确指定了 https://，Docker Daemon 可能会尝试验证代理服务器的证书。在这种情况下，可能也需要将代理的 CA 证书添加到上述 /etc/docker/certs.d/<proxy-address>:<proxy-port>/ 目录下，或者宿主机的系统信任存储中。

在容器内信任自定义 CA 证书

构建过程或运行中的容器内的应用程序也可能需要访问使用自定义 CA 签发的 HTTPS 服务（可能是通过代理，也可能是直连 NO_PROXY 中的地址）。容器内部通常基于一个精简的 Linux 发行版，可能不包含宿主机的证书信任链。因此，您需要在 Dockerfile 中明确地将所需的 CA 证书添加到容器的信任存储中。

Dockerfile 示例 (基于 Debian/Ubuntu)：

“`Dockerfile
FROM ubuntu:latest

复制CA证书到容器内部

COPY my-ca.crt /usr/local/share/ca-certificates/my-ca.crt

更新CA证书信任存储

RUN apt-get update && \
apt-get install -y –no-install-recommends ca-certificates && \
update-ca-certificates && \
rm -rf /var/lib/apt/lists/*

… 其他指令

“`

Dockerfile 示例 (基于 Alpine)：

“`Dockerfile
FROM alpine:latest

复制CA证书到容器内部

COPY my-ca.crt /usr/local/share/ca-certificates/my-ca.crt

更新CA证书信任存储

RUN apk update && \
apk add ca-certificates && \
update-ca-certificates && \
rm -rf /var/cache/apk/*

… 其他指令

“`

通过这些步骤，容器内部的环境（例如，使用 curl, wget, apt, pip 的构建过程，或者容器内运行的应用）就能信任您的自定义 CA 证书，从而成功建立 HTTPS 连接。

8. 常见问题与故障排除

配置 Docker 代理时，可能会遇到各种问题。以下是一些常见问题及其排除思路：

  • 代理配置未生效：
    • Daemon 代理： 检查 daemon.json 文件是否存在、路径是否正确、JSON 格式是否有效。确认 Docker Daemon 已正确重启。使用 docker info | grep -i proxy 验证配置是否加载。检查系统环境变量 HTTP_PROXY 等是否与 daemon.json 配置冲突（daemon.json 优先）。
    • Build 代理： 检查 Dockerfile 中是否正确定义了 ARG 或 ENV。检查 docker build 命令是否正确传递了 --build-arg。确认代理环境变量（http_proxy, https_proxy, no_proxy）是否在 RUN 指令执行前被设置（ENV 应该在 RUN 之前）。
    • Runtime 代理： 检查 Dockerfile 中是否设置了 ENV，或者 docker run 命令是否使用了 -e。进入运行中的容器 (docker exec -it <container-id> sh)，检查环境变量 (env | grep -i proxy) 是否正确设置。确认容器内的应用程序是否识别并使用这些标准代理环境变量。
  • 证书错误 (x509: certificate signed by unknown authority)：
    • Daemon 层面： 如果是拉取/推送镜像到私有仓库失败，确认私有仓库的 CA 证书已正确放置在 /etc/docker/certs.d/<registry>/ 目录下（Linux），并重启了 Docker Daemon。如果是通过 HTTPS 代理访问外部失败，可能需要将代理的 CA 证书添加到宿主机系统信任存储或 Docker 的 certs.d 目录。
    • Build/Runtime 层面： 如果是 RUN 指令中或容器内应用访问 HTTPS 资源失败，确认 Dockerfile 中已包含将自定义 CA 证书添加到容器信任存储的步骤，并成功执行。
  • NO_PROXY 配置不正确：
    • 仔细检查 no-proxy / NO_PROXY 列表中的条目格式和拼写。确保涵盖了所有需要直连的内部 IP 范围、主机名和域名。
    • 确认 NO_PROXY 配置是否在正确的位置（daemon.json, Build Args, Runtime Env Vars）。
  • 代理需要认证：
    • 如果代理 URL 中包含了用户名密码 (http://user:pass@proxy...)，首先检查用户名和密码是否正确。
    • 考虑安全性，避免将凭据直接暴露。研究是否有其他认证方式可用（如 Kerberos, NTLM）以及 Docker/应用是否支持。
  • DNS 解析问题： 即使通过代理，容器内部也需要正确解析域名。如果容器无法解析内部域名或外部域名，检查：
    • 宿主机的 DNS 设置是否正确。
    • Docker Daemon 的 DNS 配置（daemon.json 中的 dns 键）。
    • 容器自身的 /etc/resolv.conf 文件。有时容器会继承宿主机的 DNS 设置，有时需要手动配置。
  • 网络防火墙问题： 确认宿主机上的防火墙没有阻止 Docker 访问代理服务器的 IP 和端口。确认代理服务器所在的主机防火墙允许来自 Docker 宿主机的连接。

9. 最佳实践

  • 区分不同层级的代理需求： 明确您的代理需求是针对 Docker Daemon (拉取/推送)、Docker Build (RUN指令) 还是 Docker Runtime (容器内应用)，并针对性地进行配置，避免不必要的全局设置。
  • 使用环境变量而非硬编码： 尽量使用 daemon.json 或 --build-arg / -e 参数来传递代理信息，而不是直接在 Dockerfile 的 RUN 指令中硬编码 export HTTP_PROXY="..."。这提高了灵活性和安全性。
  • 妥善管理代理认证信息： 如果代理需要认证，避免将用户名和密码明文写在配置文件或 Dockerfile 中。考虑使用 BuildKit 的 secret 功能（用于 Build 过程），或者在运行时通过 Docker secrets/config (swarm/Kubernetes) 来管理敏感信息。最安全的方式是使用不需要基于基本认证的代理方案。
  • 有效利用 NO_PROXY： 仔细规划 NO_PROXY 列表，确保所有内部和本地资源都包含在内，以优化性能和避免连接问题。
  • 保持 Docker 版本更新： 新版本的 Docker 通常包含了对网络和代理处理的改进和错误修复。
  • 文档化您的代理配置： 在团队内部或项目文档中记录清楚 Docker 及其应用的代理配置要求，方便其他成员理解和排查问题。

10. 总结

在受限网络环境中，正确配置 Docker 代理是确保开发和部署流程顺畅的关键。本文详细介绍了 Docker Daemon、Docker Build 和 Docker Container Runtime 三个层面的代理设置方法，包括 daemon.json、--build-arg、ENV 指令以及 docker run -e 选项。同时，我们强调了 NO_PROXY 的重要性以及处理 HTTPS 代理和证书信任问题的步骤。

通过理解不同层级的作用范围，选择合适的配置方法，并结合本文提供的故障排除技巧，您将能够有效地解决 Docker 在代理环境下遇到的各种网络问题，让 Docker 在您的工作流程中发挥应有的作用。记住，详细检查配置、逐步排除问题是解决网络难题的有效途径。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部