Docker拉取PyTorch镜像时无法连接Docker Hub registry

Question

常见问题：在国内网络环境下，执行 `docker pull pytorch/pytorch:latest` 时频繁报错“`net/http: TLS handshake timeout`”或“`connection refused`”，提示无法连接 Docker Hub registry（registry-1.docker.io）。根本原因多为 DNS 污染、运营商劫持、防火墙策略或 IPv6 协议栈异常导致 TLS 握手失败；此外，Docker 默认使用 IPv4/IPv6 双栈，而部分局域网环境 IPv6 不可达却未及时回退，加剧连接超时。值得注意的是，PyTorch 官方镜像仅托管于 Docker Hub（非 GitHub Container Registry 或其他镜像源），故无法通过简单更换 registry 域名绕过——必须确保对 registry-1.docker.io 的 HTTPS（443端口）直连能力。该问题与镜像标签是否存在、本地磁盘空间或权限无关，属典型网络连通性故障，需从 Docker daemon 网络配置、系统 DNS 设置及代理策略三方面协同排查。

Answer 1

```html

一、现象定位：从错误日志反推网络故障层级

执行 docker pull pytorch/pytorch:latest 时出现 net/http: TLS handshake timeout 或 connection refused，本质是 Go 标准库 net/http 在建立 HTTPS 连接时卡在 TCP 握手后、TLS ClientHello 发送前（或响应未达），表明：

• 底层 IP 可达性（ICMP/Ping）可能正常，但 443 端口不可达；
• DNS 解析结果被污染（如返回虚假 IPv6 地址或内网地址）；
• IPv6 路由黑洞导致双栈连接阻塞（Docker daemon 默认启用 ipv6: true）。

二、根因分层诊断：DNS → 网络协议栈 → Docker Daemon 配置

按 OSI 模型自下而上验证连通性：

1. DNS 层：运行 dig registry-1.docker.io +short 与 nslookup registry-1.docker.io 114.114.114.114 对比结果，识别是否被劫持；
2. 传输层：用 curl -vI https://registry-1.docker.io/v2/ 测试 TLS 握手全过程（注意观察 * Connected to... 与 * TLS handshake completed）；
3. Docker 层：检查 systemctl cat docker | grep -A5 ExecStart 是否含 --dns 或 --iptables=false 异常参数。

三、系统级修复方案（优先级由高到低）

方案	操作命令	生效范围
强制禁用 IPv6（治本）	echo 'net.ipv6.conf.all.disable_ipv6 = 1' | sudo tee -a /etc/sysctl.conf && sudo sysctl -p	全局内核协议栈
指定可信 DNS（防污染）	sudo systemctl edit docker && echo '[Service]\nExecStart=\nExecStart=/usr/bin/dockerd --dns 223.5.5.5 --dns 119.29.29.29'	Docker daemon 启动时

四、Docker Daemon 高级调优策略

当企业环境需保留 IPv6 时，可精细化控制：

{
  "ipv6": true,
  "fixed-cidr-v6": "2001:db8:1::/64",
  "default-address-pools": [
    {"base": "172.30.0.0/16", "size": 24}
  ],
  "max-concurrent-downloads": 3,
  "registry-mirrors": []
}

⚠️ 注意："registry-mirrors" 对 registry-1.docker.io 无效——PyTorch 镜像不支持镜像站代理，该字段仅对 docker.io 前缀的公共镜像生效。

五、验证流程图（Mermaid）

graph TD
  A[执行 docker pull] --> B{curl -vI https://registry-1.docker.io/v2/}
  B -->|Success| C[检查 /etc/docker/daemon.json]
  B -->|Fail| D[排查 DNS/防火墙/IPv6]
  C --> E[确认无 registry-mirrors 误配]
  D --> F[执行 nslookup + tcpdump port 443]
  F --> G[定位劫持节点：Local DNS / ISP / 企业网关]

六、进阶排查：抓包分析 TLS 握手失败点

在宿主机执行：

sudo tcpdump -i any -w docker_hub.pcap host registry-1.docker.io and port 443
# 然后另起终端运行 docker pull，结束后用 Wireshark 分析：
# 关键帧：Client Hello → Server Hello → [Missing Certificate]

若捕获到 Client Hello 但无 Server Hello 响应，证明数据包在运营商层被丢弃（非超时，是静默丢包）；若 Client Hello 未发出，则为本地路由或 DNS 解析失败。

七、企业级部署建议

• 在 CI/CD Agent 节点统一配置 /etc/systemd/system/docker.service.d/override.conf 禁用 IPv6 并锁定 DNS；
• 通过 Ansible Playbook 批量下发 sysctl 参数与 daemon.json；
• 监控项新增：curl -o /dev/null -s -w '%{http_code}' https://registry-1.docker.io/v2/ 健康检查。

```