1. 为什么在 Windows/Mac 开了 Clash，终端执行 docker pull 依然报 TLS handshake timeout？

因为 `docker pull` 指令并不是由当前命令终端执行的，而是由后台常驻的 Docker Daemon（守护进程 dockerd）发起的。在 Windows/Mac 上，dockerd 运行在一个由 Hyper-V / WSL2 管理的轻量级虚拟 Linux 虚拟机内部，默认不继承宿主机的操作系统图形代理。必须在 Docker Desktop 的 Resources → Proxies 中显式配置，或开启 TUN 模式。

2. Docker Desktop 设置代理后，本地构建或运行私有容器（如 localhost:5000）报错无法连接怎么办？

需要在 Docker Desktop 代理设置中的 "Bypass for these hosts & domains (忽略的主机与域名)" 列表填入：`localhost,127.0.0.1,docker-registry.internal,.local,.internal`。否则发往本地内网的请求也会被错误转发至代理客户端导致连接失败。

3. 如何在 Linux (Ubuntu / CentOS) 无图形界面的服务器上为 Docker 配置代理？

在 Linux 上不可通过 export 临时变量配置。标准方案是创建 systemd drop-in 文件：`sudo mkdir -p /etc/systemd/system/docker.service.d`，新建 `http-proxy.conf` 写入 `Environment="HTTP_PROXY=http://127.0.0.1:7897"`，然后执行 `sudo systemctl daemon-reload && sudo systemctl restart docker`。

4. 执行 docker build 构建镜像时，RUN apt-get / RUN pip install 连不上网怎么解决？

`docker build` 会在临时隔离的容器沙箱中运行指令。有两种解决方法：1. 在构建命令后传入代理参数：`docker build --build-arg HTTP_PROXY=http://192.168.1.100:7897 -t myapp .`；2. 编辑当前宿主机用户的 `~/.docker/config.json`，在 "proxies" 字段中注入全局客户端代理配置。

5. 国内各大云厂商的 Public Docker Mirror 镜像源还能用吗？

由于合规与上游政策调整，国内绝大多数公开公用 Docker Hub 镜像加速源（如各大云厂商面向公众开放的公共 mirror）已全面下线或仅对自身云服务器白名单用户开放。直接通过官方 registry-1.docker.io 配合出海专线代理是目前最稳定持久的方案。

6. 使用 Clash Verge TUN 模式能自动接管 Docker 流量吗？

在 Windows 上，TUN 模式能够直接接管 WSL2 与 Docker Desktop 发出的底层 raw TCP 数据包，无需在 Docker Desktop 中单独手动输入 IP 与端口即可直接拉取镜像。

7. 为什么拉取 gcr.io 或 k8s.gcr.io 镜像经常卡在 Downloading？

Google Container Registry (gcr.io) 国内完全被阻断。只要正确为 Docker Daemon 配置了出海代理，拉取 gcr.io 或 quay.io 将与官方 Docker Hub 一样高速稳定。

8. 提示 "Error response from daemon: received unexpected HTTP status: 502 Bad Gateway" 怎么排查？

说明 dockerd 成功连接到了你填写的本地代理端口，但本地代理客户端未能成功将请求转发至海外（如节点离线或机场订阅已欠费）。请检查本地 Clash 的节点连通性。

Docker pull 镜像拉取超时排障：Docker Desktop 与 Linux 守护进程代理完整配置指南

一、Docker 镜像拉取超时核心结论

在国内网络环境下，直接通过 docker pull 拉取官方 Docker Hub (registry-1.docker.io)、Google GCR (gcr.io) 或 Quay (quay.io) 镜像时，几乎 100% 会遭遇 DNS 污染、握手超时（TLS Handshake Timeout）或连接重置。配置专属代理是容器化研发与部署的绝对刚需。

二、为什么配了系统代理 docker pull 依然超时？(Client 与 Daemon 架构分离)

Docker 采用经典的客户端-服务器（C/S）架构：

我们在终端输入的 docker pull ubuntu 只是向本地 Docker Client 发送请求；
真正发起跨国网络通信、下载镜像 Layer 并解压的是后台的 Docker Daemon (dockerd 守护进程)。

在 Windows / macOS 上，dockerd 运行在独立的 WSL2 或 Hyper-V Linux 虚拟机中，完全隔离于宿主机的操作系统系统代理。因此必须针对守护进程进行显式代理注入。

三、Docker Desktop (Windows/macOS) 图形代理配置详解

打开 Docker Desktop，点击右上角的 设置齿轮图标 (Settings)。
在左侧导航栏中依次点击 Resources → Proxies。
开启 Manual proxy configuration 开关。
在 Web Server (HTTP) 与 Secure Web Server (HTTPS) 栏中填入：http://127.0.0.1:7897（请根据实际客户端本地监听端口填写）。
在 Bypass for these hosts & domains 栏中填入：localhost,127.0.0.1,.internal。
点击右下角的 Apply & restart 保存并重启 Docker 守护进程。

// Docker Desktop 代理设置示范 (Settings -> Resources -> Proxies)
Web Server (HTTP):  http://127.0.0.1:7897
Secure Web Server:  http://127.0.0.1:7897
Bypass:             localhost,127.0.0.1,.internal

四、Linux 服务器：systemd 守护进程 (dockerd) 环境变量配置

对于 Ubuntu、CentOS、Debian 等 Linux 生产服务器：

# 1. 创建 systemd 配置目录
sudo mkdir -p /etc/systemd/system/docker.service.d

# 2. 创建并编辑 http-proxy.conf 配置文件
sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

在文件中写入以下内容：

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7897"
Environment="HTTPS_PROXY=http://127.0.0.1:7897"
Environment="NO_PROXY=localhost,127.0.0.1,docker-registry.internal"

重新加载 systemd 单元并重启 Docker 服务：

sudo systemctl daemon-reload
sudo systemctl restart docker

# 验证配置是否生效
sudo docker info | grep -i proxy

五、容器构建代理：Dockerfile 与 ~/.docker/config.json 配置

如果希望在执行 docker build 编译镜像时让容器沙箱内部自动走代理，可编辑当前系统用户的 ~/.docker/config.json：

{
  "proxies": {
    "default": {
      "httpProxy": "http://127.0.0.1:7897",
      "httpsProxy": "http://127.0.0.1:7897",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

六、国内公开镜像加速源现状与局限性分析

由于合规要求，2024 年至今各大云厂商已陆续关闭面向公众的公开 Registry 镜像加速功能。自行配置专线出海代理不仅速度可跑满千兆带宽，而且彻底避免了镜像源被投毒或临时失效的风险。

七、WSL2 后端 Docker 引擎网络连通性调优

若在 Windows 上直接使用 WSL2 内部的 Docker，推荐直接在 Windows 端开启 Clash Verge TUN 模式，TUN 虚拟网卡将自动穿透 WSL2 子网捕获全部流量。

八、Docker 常见拉取报错与诊断矩阵表

Docker 常见网络拉取故障诊断表

故障现象	核心原因分析	首先检查 / 处理动作
Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: TLS handshake timeout	Docker Daemon 守护进程直连官方 Registry 超时	在 Docker Desktop Settings → Resources → Proxies 中填写 http://127.0.0.1:7897 并重启。
docker pull 极慢，一直卡在 "Waiting" 或每秒仅几十 KB	当前代理节点为低带宽公网中转，遭遇晚高峰 QoS 限速	在客户端中切换为大带宽香港/日本 IEPL 专线节点。
docker build 时内部 apt-get update 报 "Could not resolve host"	容器内部构建环境未配置 DNS 或未传入 --build-arg 代理参数	在 ~/.docker/config.json 中配置 proxies，或在构建命令行传入 --build-arg HTTP_PROXY。
连接本地自建私有 Registry 时报 502 / Connection refused	本地私有域名被错误纳入了代理转发规则	在 Docker 代理设置的 Bypass 列表中添加该私有 Registry 的域名或 IP。

九、常见问题解答 (FAQ 8 问 8 答)

详见文首与右侧核心问答列表，涵盖容器构建代理、502 报错与私有镜像仓库白名单设置。