Docker Pull 报错 Connection Refused / 镜像拉取超时全解：国内镜像源与专线代理配置

快速结论与 Docker 镜像拉取故障机理

在 Linux 服务器、Windows WSL2 或 Mac 终端上执行 Docker 镜像拉取（如 docker pull nginx:latest 或 docker compose up -d）时，控制台频繁抛出以下致命异常：

Error response from daemon: Get "https://registry-1.docker.io/v2/": dial tcp 199.59.148.82:443: connect: connection refused
或 Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: TLS handshake timeout
或 error pulling image configuration: download failed after 6 attempts: EOF

其本质原因是 Docker 官方核心注册表（registry-1.docker.io 与 auth.docker.io）位于海外 AWS 机房，在国内常规运营商网络下遭遇了严重的路由级 TCP 连接重置与 DNS 污染。

架构解析：为什么终端 Shell 代理对 Docker 守护进程完全无效？

许多开发者在遇到问题时，首先会在终端运行 export http_proxy=http://127.0.0.1:7890，但发现 docker pull 依然超时。必须从 Docker 的分层架构理解这一现象：

[开发者终端 (CLI Shell)]  ──► 执行 docker pull alpine (读取终端环境变量)
          │
          │ (通过本地 UNIX Socket: /var/run/docker.sock 传递指令)
          ▼
[Docker Daemon 守护进程 (dockerd)] ──► 真正发起网络请求拉取镜像 (受 Systemd 托管)
          │
          ├─► 默认情况下：无法继承终端 Shell 的 HTTP_PROXY 环境变量！
          └─► 必须直接为 Systemd 服务注入 Environment 变量才能生效！

方案一：为 Linux Systemd Docker Daemon 配置持久化代理（生产与服务器首选）

这是最标准、最稳定且不依赖任何第三方镜像源的官方解决方案：

1. 创建 Systemd 服务覆盖配置目录

以 root 或 sudo 权限在终端执行：

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

2. 创建并编辑 http-proxy.conf 配置文件

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

在文件中写入以下标准配置（请将 127.0.0.1:7890 替换为您本地代理客户端的实际监听地址与端口；若是远程局域网代理，请填入对应的局域网 IP）：

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,docker-registry.local,*.aliyuncs.com,*.mycompany.com"

3. 重载 Systemd 守护进程并重启 Docker 服务

依次执行以下命令使配置立即生效：

sudo systemctl daemon-reload
sudo systemctl restart docker

4. 验证代理注入是否成功

运行以下验证指令：

docker info | grep -i proxy

如果控制台正确输出了 HTTP Proxy: http://127.0.0.1:7890 和 HTTPS Proxy: http://127.0.0.1:7890，说明配置已完全生效。此时执行 docker pull mysql:8.0 即可享受秒级拉取体验。

方案二：Windows 11 / macOS Docker Desktop 图形化一键配置

如果你是在个人电脑上使用官方 Docker Desktop：

1. 打开 Docker Desktop 客户端主界面；
2. 点击右上角 齿轮图标 (Settings) 进入设置中心；
3. 在左侧功能导航栏中点击 Resources → 选择 Proxies；
4. 将 Manual proxy configuration 开关切换为 开启状态；
5. 在 Web Server (HTTP) 输入框中填入：http://127.0.0.1:7890；
6. 在 Secure Web Server (HTTPS) 输入框中填入：http://127.0.0.1:7890；
7. 在 Bypass for these hosts & domains 中填入：localhost,127.0.0.1；
8. 点击右下角 Apply & restart，等待 Docker 引擎重启完成（左下角变绿）。

方案三：配置本地 / 私有镜像加速源 (daemon.json)

如果你拥有阿里云或企业内部的专属 Harbor 镜像源加速地址：

1. 编辑 Docker 核心守护进程配置文件：

   sudo nano /etc/docker/daemon.json

2. 写入 registry-mirrors 数组配置：

   {
     "registry-mirrors": [
       "https://your-custom-id.mirror.aliyuncs.com",
       "https://dockerproxy.net"
     ]
   }

3. 保存退出后重启 Docker：

   sudo systemctl restart docker

排错与调试命令大全

在排查拉取异常时，推荐运行以下指令快速定位链路故障：

# 1. 查看 Docker 守护进程的实时运行日志
journalctl -u docker.service -n 50 --no-pager

# 2. 手动测试与 Docker 官方认证服务器的连通性
curl -i -x http://127.0.0.1:7890 https://auth.docker.io/token?service=registry.docker.io

# 3. 手动测试与镜像存储 CDN 的握手延迟
curl -i -x http://127.0.0.1:7890 https://registry-1.docker.io/v2/

不同镜像拉取方案全维度对比表