docker镜像拉取不了？使用本地代理从官方拉取镜像，附脚本

背景

在国内服务器上拉取 Docker 镜像，常见方案是配置国内镜像加速源，但镜像源经常同步不及时、限速、甚至关停。

最靠谱的方式其实是——通过代理直连 Docker Hub 官方源。只需要让 Docker daemon 走代理即可。

本文提供两个一键脚本，在代理直连和镜像源模式之间快速切换。

原理

Docker 拉取镜像的网络请求是由 dockerd 进程发出的，不是 docker CLI。因此不能简单设置 shell 环境变量，而是需要通过 systemd 的 drop-in 文件为 Docker 服务注入 HTTP_PROXY / HTTPS_PROXY 环境变量。

开启代理时需要做两件事：

1. 清空 daemon.json 中的镜像源配置——如果配了 registry-mirrors，Docker 会优先走镜像源，即使配了代理也可能拉取失败
2. 创建 systemd drop-in 配置——在 /etc/systemd/system/docker.service.d/http-proxy.conf 中注入代理环境变量

脚本

开启代理：docker_proxy_on.sh

备份当前 daemon.json，清空镜像源配置，为 Docker 添加代理：

#!/bin/bash
# 启用 Docker 代理直连官方源（临时）

# 备份 daemon.json
sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak
echo "已备份 daemon.json -> daemon.json.bak"

# 清空镜像源，走官方
sudo tee /etc/docker/daemon.json > /dev/null << 'EOF'
{}
EOF

# 添加代理
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null << 'EOF'
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:10808"
Environment="HTTPS_PROXY=http://127.0.0.1:10808"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker
echo "Docker 已切换为代理直连官方源"

注意：脚本中代理地址为 127.0.0.1:10808，请根据实际代理端口修改。

关闭代理：docker_proxy_off.sh

拉完镜像后，恢复原来的镜像源配置并移除代理：

#!/bin/bash
# 还原 Docker 配置（关闭代理，恢复镜像源）

# 还原 daemon.json
sudo cp /etc/docker/daemon.json.bak /etc/docker/daemon.json
echo "已还原 daemon.json"

# 删除代理配置
sudo rm -f /etc/systemd/system/docker.service.d/http-proxy.conf
echo "已删除代理配置"

sudo systemctl daemon-reload
sudo systemctl restart docker
echo "Docker 已还原为镜像源模式"

使用方式

# 1. 赋予脚本执行权限
chmod +x docker_proxy_on.sh docker_proxy_off.sh

# 2. 需要拉镜像时，开启代理
./docker_proxy_on.sh

# 3. 正常拉取镜像
docker pull vllm/vllm-openai:v0.19.1

# 4. 拉完之后，关闭代理，恢复镜像源
./docker_proxy_off.sh

用 SSH 隧道转发本地代理

脚本中代理地址是 127.0.0.1:10808，即服务器本地的 10808 端口。如果服务器上已经有代理客户端监听该端口，直接用即可。

如果服务器本身没有代理客户端，可以通过 SSH 远程端口转发，把你本地电脑上的代理”映射”到服务器上。

前提条件

你的本地电脑（笔记本/台式机）上有一个 HTTP 代理，监听在 127.0.0.1:10808。

操作步骤

第一步：在服务器的 sshd 配置中允许 GatewayPorts（默认是关闭的，只需设置一次）：

# 在服务器上执行
sudo sed -i 's/#GatewayPorts no/GatewayPorts no/' /etc/ssh/sshd_config
sudo systemctl restart sshd

这里保持 GatewayPorts no 即可，因为我们只需要转发到服务器的 127.0.0.1，不需要监听在 0.0.0.0。

第二步：从本地电脑发起 SSH 连接，带上 -R 参数：

# 在本地电脑上执行
ssh -R 10808:127.0.0.1:10808 user@your-server

这条命令的含义：

• -R 10808:127.0.0.1:10808：让服务器上的 127.0.0.1:10808 转发到本地电脑的 127.0.0.1:10808
• 连接建立后，服务器访问 127.0.0.1:10808 的流量，会通过 SSH 隧道回到你本地电脑的代理

第三步：保持这个 SSH 会话不要断开，在服务器上另开一个终端，运行脚本拉取镜像：

./docker_proxy_on.sh
docker pull vllm/vllm-openai:v0.19.1
./docker_proxy_off.sh

第四步：镜像拉完后，关闭那个带 -R 参数的 SSH 会话即可，隧道会自动断开。

提示：如果你本地代理监听的端口不是 10808，需要同时修改 SSH 命令和脚本中的端口号，保持一致。

注意事项

脚本会执行 systemctl restart docker，所有正在运行的容器会短暂重启（设置了 restart: always 或 unless-stopped 的容器会自动恢复）。建议在业务低峰期操作。