Docker 代理设置指南 - 国内环境下的镜像加速与代理配置

快速搭建 Linux 代理环境#

如果你还没有在 Linux 上配置代理，推荐使用 clash-for-linux-install 项目快速部署。

NOTE

不要在公网部署这个，尤其面板之类的。务必关掉端口，走私网链接。

安装命令：

1
git clone --branch master --depth 1 https://gh-proxy.org/https://github.com/nelvko/clash-for-linux-install.git && cd clash-for-linux-install && bash install.sh

常用命令：

1
Usage:
2
  clashctl COMMAND [OPTIONS]
3

4
Commands:
5
    on                    开启代理
6
    off                   关闭代理
7
    status                内核状况
8
    proxy                 系统代理
9
    ui                    Web 面板
10
    secret                Web 密钥
11
    sub                   订阅管理
12
    upgrade               升级内核
13
    tun                   Tun 模式
14
    mixin                 Mixin 配置
15

16
Global Options:
17
    -h, --help            显示帮助信息

理解代理地址的选择#

在配置 Docker 代理之前，需要先理解你的代理部署在哪里：

场景一：代理在远程服务器（如通过 Tailscale/WireGuard 访问）

1
┌─────────────────┐      VPN 网络        ┌─────────────────┐
2
│  代理服务器      │◄──────────────────►│  本机 (Docker)  │
3
│  100.98.32.42   │                      │                 │
4
│  :7890          │                      │                 │
5
└─────────────────┘                      └─────────────────┘

这种情况下，无论是宿主机还是容器，都直接使用远程代理地址 100.98.32.42:7890。Docker 容器（即使使用 bridge 网络）的流量会经过宿主机路由，可以正常访问 VPN 网络。

场景二：代理运行在宿主机本地

1
┌─────────────────────────────────────────┐
2
│  宿主机                                  │
3
│  ┌─────────────┐    ┌─────────────────┐ │
4
│  │ 代理服务    │    │ Docker 容器     │ │
5
│  │ 127.0.0.1   │◄───│ (bridge 网络)   │ │
6
│  │ :7890       │    │                 │ │
7
│  └─────────────┘    └─────────────────┘ │
8
└─────────────────────────────────────────┘

这种情况下比较复杂：

• 宿主机上的服务可以直接使用 127.0.0.1:7890
• 但容器内的 127.0.0.1 指向容器自己，不是宿主机
• 容器需要使用 172.17.0.1:7890（docker0 网桥地址）来访问宿主机上的代理

Docker Pull/Push 代理配置#

Docker 的 pull 和 push 命令由 systemd 管理，需要为 Docker 服务配置代理环境变量。

创建配置目录和文件：

1
sudo mkdir -p /etc/systemd/system/docker.service.d
2
sudo vim /etc/systemd/system/docker.service.d/http-proxy.conf

写入以下内容（将代理地址替换为你自己的）：

1
[Service]
2
Environment="HTTP_PROXY=http://100.98.32.42:7890"
3
Environment="HTTPS_PROXY=http://100.98.32.42:7890"

NOTE

如果代理运行在宿主机本地，这里可以直接使用 127.0.0.1:7890，因为 Docker daemon 运行在宿主机上。

重新加载配置并重启 Docker：

1
sudo systemctl daemon-reload
2
sudo systemctl restart docker

验证配置是否生效：

1
sudo systemctl show --property=Environment docker

此时 docker pull 就会通过代理拉取镜像了。

Docker Build 时使用代理#

构建镜像时需要通过 --build-arg 参数传递代理设置：

1
docker build \
2
    --build-arg http_proxy=http://100.98.32.42:7890 \
3
    --build-arg https_proxy=http://100.98.32.42:7890 \
4
    -t image_name .

NOTE

如果你的代理在远程服务器（通过 VPN 访问），直接使用远程地址即可。容器的网络流量会经过宿主机路由，可以正常访问 VPN 网络中的代理。

如果代理在宿主机本地，需要使用 docker0 网桥地址：

1
docker build \
2
    --build-arg http_proxy=http://172.17.0.1:7890 \
3
    --build-arg https_proxy=http://172.17.0.1:7890 \
4
    -t image_name .

或者使用 --network=host 让构建过程直接使用宿主机网络：

1
docker build --network=host \
2
    --build-arg http_proxy=http://127.0.0.1:7890 \
3
    --build-arg https_proxy=http://127.0.0.1:7890 \
4
    -t image_name .

Docker 全局代理配置#

通过配置 ~/.docker/config.json 可以为所有新创建的容器设置代理：

1
vim ~/.docker/config.json

1
{
2
    "proxies": {
3
        "default": {
4
            "httpProxy": "http://100.98.32.42:7890",
5
            "httpsProxy": "http://100.98.32.42:7890",
6
            "noProxy": "localhost,127.0.0.1,.local"
7
        }
8
    }
9
}

IMPORTANT

这个配置只对 build 和 run 创建的新容器生效，不影响 docker pull。pull 仍需按上文配置 systemd 代理。

CAUTION

容器一旦创建，代理环境变量就会被固化。即使之后修改或删除 config.json，已有容器仍会使用创建时的代理设置。如需关闭代理，需要在容器内手动清除环境变量：

1
export http_proxy=
2
export https_proxy=

最终验证#

容器内使用代理#

有时需要在运行中的容器内访问外网，以下是几种常用方法。

1
export ALL_PROXY='socks5://100.98.32.42:7890'
2
# 或者
3
export http_proxy='http://100.98.32.42:7890'
4
export https_proxy='http://100.98.32.42:7890'

1
export ALL_PROXY='socks5://172.17.0.1:7890'

1
docker run --network=host your_image

1
export ALL_PROXY='socks5://127.0.0.1:7890'

验证容器能否访问代理#

在容器内测试代理连通性：

1
# 测试 HTTP 代理
2
curl -x http://100.98.32.42:7890 https://www.google.com
3

4
# 测试 SOCKS5 代理
5
curl -x socks5://100.98.32.42:7890 https://www.google.com

查看 docker0 网桥地址#

1
ip addr show docker0

通常是 172.17.0.1，但可能因配置而异。

确认 VPN 网络可达#

如果代理通过 VPN 访问，先在宿主机上确认能正常连接：

1
curl -x http://100.98.32.42:7890 https://www.google.com

SOCKS5 代理支持#

Docker 的 config.json 配置目前只支持 HTTP/HTTPS/FTP 协议，不直接支持 SOCKS5。如果你使用的是 Clash 等支持混合端口的代理，同一端口通常同时支持 HTTP 和 SOCKS5，直接使用 HTTP 方式配置即可。

临时禁用代理#

如果配置了全局代理但临时需要禁用：

1. 重命名 ~/.docker/config.json 文件
2. 在容器内清除环境变量：export http_proxy= https_proxy=
3. 使用 --build-arg http_proxy= --build-arg https_proxy= 覆盖