Docker代理配置

发表于 更新于

在使用Docker过程中，镜像拉取超时、构建镜像时依赖下载失败是开发者常遇到的问题，其核心原因在于网络环境限制。为Docker配置代理是解决该问题最直接、高效的方案。本文将详细介绍三种常用的Docker代理配置方式，分别适配守护进程（Systemd、daemon.json）和客户端（config.json）场景，配套完整操作步骤、验证方法及关键注意事项，助力开发者快速完成配置、规避常见坑。

一、配置前提说明

在启动配置前，请确认以下两个核心前提，避免因前提缺失导致配置失败：

  1. 已完成Docker安装（未安装用户可参考Docker官方文档，根据自身操作系统执行对应安装命令，确保安装版本与系统兼容）；

  2. 已拥有可用的代理服务（如Clash、V2Ray等），并准确获取代理地址及端口（常规格式为http://127.0.0.1:端口号，常见端口包括7890、1080等，需与本地代理工具监听端口一致）。

本文涵盖三种配置场景，开发者可根据自身需求灵活选择：守护进程代理（Systemd、daemon.json，优先推荐，核心解决镜像拉取超时）、客户端代理（config.json，补充配置，解决容器内网络访问需求）。

二、方式一：守护进程代理（Systemd，推荐）

该方式直接作用于Docker守护进程（dockerd），是Docker官方推荐的生产级配置方案，稳定性强，核心解决docker pull镜像拉取超时问题，配置后所有Docker服务相关的网络请求均会通过代理转发（适配基于Systemd管理服务的操作系统，如CentOS、Ubuntu等主流Linux发行版）。

步骤1：创建Systemd配置目录

在基于Systemd的系统中，Docker服务通过Systemd管理，需先创建专属配置目录（用于存放代理配置文件），若目录已存在，可直接跳过此步骤：

1
sudo mkdir -p /etc/systemd/system/docker.service.d

步骤2：新建代理配置文件

在上述创建的目录中，新建http-proxy.conf配置文件，用于定义Docker守护进程的代理环境变量：

1
sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

步骤3：写入代理配置信息

打开配置文件后，输入以下内容，将<proxy-addr>替换为实际代理地址（示例：http://127.0.0.1:7890），保存并退出（nano编辑器操作：Ctrl+O保存，Ctrl+X退出）：

1
2
3
4
[Service]
Environment="HTTP_PROXY=http://<proxy-addr>"
Environment="HTTPS_PROXY=http://<proxy-addr>"
Environment="NO_PROXY=localhost,127.0.0.1,::1"

关键说明：

  • HTTP_PROXY/HTTPS_PROXY：分别指定HTTP、HTTPS协议请求的代理地址，确保所有Docker网络请求均走代理；

  • NO_PROXY：指定无需走代理的地址，必须包含本地回环地址（localhost、127.0.0.1、::1），避免本地通讯走代理导致性能损耗，可根据实际需求添加内网地址。

步骤4：重载配置并重启Docker服务

配置文件修改后，需重载Systemd配置，重启Docker服务，确保代理配置生效：

1
2
sudo systemctl daemon-reload
sudo systemctl restart docker

步骤5：验证代理是否生效

通过以下命令查看Docker服务的环境变量，若输出中包含配置的代理信息，即说明守护进程代理配置成功：

1
sudo systemctl show --property=Environment docker

预期输出示例：Environment=HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 NO_PROXY=localhost,127.0.0.1,::1

三、方式二：守护进程代理（daemon.json，通用）

除Systemd方式外，通过Docker守护进程配置文件daemon.json配置代理，是更通用的方案，适配所有支持Docker的操作系统（Linux、Windows、Mac），配置逻辑简洁，直接通过JSON格式定义代理参数，同样作用于dockerd守护进程，可有效解决镜像拉取超时问题，适合跨系统使用场景。

步骤1：定位并编辑daemon.json文件

Docker守护进程配置文件daemon.json的默认路径因操作系统而异，开发者可根据自身系统查找，若文件不存在，直接创建即可：

  • Linux系统：/etc/docker/daemon.json

  • Windows系统（Docker Desktop）：通过界面进入「设置」→「Docker Engine」，直接编辑JSON内容

  • Mac系统（Docker Desktop）：通过界面进入「设置」→「Docker Engine」，直接编辑JSON内容

Linux系统编辑命令（若文件不存在，执行命令后会自动创建）：

1
sudo nano /etc/docker/daemon.json

步骤2：写入代理配置信息

在daemon.json文件中输入以下JSON格式内容，将<proxy-addr>替换为实际代理地址（示例：http://127.0.0.1:7890），注意严格遵循JSON格式规范（逗号分隔、无多余空格），保存并退出：

1
2
3
4
5
6
7
{
  "proxies": {
    "http-proxy": "http://<proxy-addr>",
    "https-proxy": "http://<proxy-addr>",
    "no-proxy": "localhost,127.0.0.1,::1"
  }
}

关键说明：

  • 与Systemd方式区分：daemon.json中代理参数均为小写（http-proxy、https-proxy、no-proxy），切勿与Systemd方式的大写参数混淆，否则会导致配置失效；

  • 若daemon.json中已存在其他配置（如镜像源），无需新建文件，只需在原有JSON对象中添加proxies节点即可，示例如下：

1
2
3
4
5
6
7
8
{
  "registry-mirrors": ["https://docker.mirrors.aliyun.com"],
  "proxies": {
    "http-proxy": "http://127.0.0.1:7890",
    "https-proxy": "http://127.0.0.1:7890",
    "no-proxy": "localhost,127.0.0.1,::1"
  }
}

步骤3：重启Docker服务，使配置生效

配置完成后，需重启Docker服务，不同操作系统的重启方式如下，按需选择：

  • Linux系统（Systemd）：sudo systemctl restart docker

  • Windows/Mac系统（Docker Desktop）：直接在界面点击「重启」按钮，或关闭Docker后重新启动即可。

步骤4：验证代理是否生效

提供两种验证方式，开发者可任选其一，操作简单高效：

  1. 拉取测试镜像：执行docker pull hello-world，若能成功拉取镜像，说明代理配置生效；

  2. 查看守护进程配置：Linux系统执行sudo docker info，在输出结果中找到「HTTP Proxy」「HTTPS Proxy」字段，若显示配置的代理地址，即配置成功。

四、方式三：客户端代理（config.json，可选）

该方式作用于Docker CLI（客户端），适配所有Docker支持的操作系统，核心影响docker build镜像构建、容器内网络访问等场景，与守护进程代理形成互补。若仅需解决镜像拉取问题，配置方式一或方式二即可；若需容器内访问外部网络（如构建时下载依赖包），需补充配置此方式。

步骤1：创建/编辑客户端配置文件

Docker客户端配置文件位于用户目录下的.docker文件夹中，若文件夹或配置文件不存在，执行命令后会自动创建，不同操作系统路径如下：

  • Windows系统：C:\Users\用户名\.docker\config.json

  • Linux/Mac系统：~/.docker/config.json

Linux/Mac系统编辑命令：

1
2
mkdir -p ~/.docker
nano ~/.docker/config.json

步骤2：添加客户端代理配置

在config.json文件中输入以下JSON格式内容，将<proxy-addr>替换为实际代理地址，保存并退出：

1
2
3
4
5
6
7
8
9
{
  "proxies": {
    "default": {
      "httpProxy": "http://<proxy-addr>",
      "httpsProxy": "http://<proxy-addr>",
      "noProxy": "localhost,127.0.0.1,::1"
    }
  }
}

关键说明：该配置仅对当前用户生效，若需对所有用户生效，可将配置文件复制到系统级Docker配置目录（Linux系统为/etc/docker/config.json，Windows系统可参考官方文档配置系统级路径）。

五、全局测试：验证代理是否正常工作

无论采用哪种配置方式，均可通过拉取官方测试镜像hello-world验证代理有效性，操作简单且直观：

1
docker pull hello-world

若镜像拉取成功，会提示“Hello from Docker!”相关信息；若仍出现超时，需优先检查代理地址是否正确、本地代理服务是否正常运行。

六、关键注意事项与常见问题

1. 代理地址填写规范

代理地址需与本地代理工具的监听设置完全一致，避免因地址或端口错误导致配置失效。示例：Clash默认HTTP代理地址为http://127.0.0.1:7890，V2Ray默认地址通常为http://127.0.0.1:10809，配置前需确认代理工具的监听参数。

2. NO_PROXY列表不可遗漏

本地回环地址（localhost、127.0.0.1、::1）必须加入NO_PROXY列表，否则会导致Docker容器无法访问本地服务，或本地服务与Docker容器通讯异常，影响使用体验。

3. 配置不生效的排查方法

  • 检查代理服务状态：通过访问代理地址（如curl http://127.0.0.1:7890）测试，确认代理服务正常运行；

  • 核对配置路径：基于Systemd的系统，守护进程配置路径为/etc/systemd/system/docker.service.d/http-proxy.conf；daemon.json路径为/etc/docker/daemon.json，确保路径和文件名无误；

  • 重启服务重试：配置修改后需重启Docker服务，若仍不生效，可通过对应系统的日志查看命令（如Linux系统sudo journalctl -u docker）排查错误原因；

  • 检查JSON格式：daemon.json配置不生效时，需重点检查JSON格式（可通过在线JSON校验工具验证），避免逗号遗漏、引号不匹配等语法错误。

4. 代理关闭后的清理

若后续无需使用代理，可按以下步骤清理配置（适配基于Systemd的Linux系统，其他系统可参考对应路径调整）：

  1. 删除Systemd守护进程代理配置：sudo rm /etc/systemd/system/docker.service.d/http-proxy.conf；

  2. 删除daemon.json守护进程代理配置：编辑/etc/docker/daemon.json，删除proxies节点（若文件中无其他配置，可直接删除该文件）；

  3. 删除客户端代理配置：rm ~/.docker/config.json；

  4. 重载并重启Docker服务：sudo systemctl daemon-reload && sudo systemctl restart docker。

七、总结

Docker代理配置的核心原则是“守护进程代理为主，客户端代理为辅”：优先选择守护进程代理（Systemd方式适配Linux Systemd系统，稳定性强；daemon.json方式适配所有系统，通用性更高），可高效解决镜像拉取超时问题；若需容器内访问外部网络，补充配置客户端代理（config.json）即可。本文提供的三种配置方式均经过实际场景验证，步骤清晰、重点突出，适配Docker支持的各类操作系统，开发者可根据自身网络环境和实际需求，灵活选择合适的配置方式，快速解决Docker网络访问难题。