docker pull 慢或失败：系统化排查清单（网络、代理与 Registry）

「pull 很慢」在团队里经常被归因成一句话：网络不好。实际上，镜像拉取链路很长：DNS 解析 → TLS 握手 → Registry API → blob（layer）下载 → 本地存储。任何一层都可能成为瓶颈。

本文提供一套分层排查方法，尽量把问题从「感觉慢」变成「慢在哪」。

1. 先区分：是 API 慢还是 layer 下载慢

很多时候 Registry 的清单（manifest）早已返回，但 layer 下载很慢。反之也可能是 manifest 请求失败导致不断重试。最简单的判断方式是观察客户端日志：停滞阶段发生在哪个步骤。

2. DNS 与 TLS：高频但容易被忽略

• DNS：解析不稳定会导致间歇性超时；企业内网 DNS 策略变更也经常「顺便」影响容器环境。
• TLS 握手超时：可能是跨国链路、代理配置不当、或中间设备替换证书导致校验失败。

验证思路通常是从运行容器的主机出发，用最小工具验证解析与 TLS（例如 dig / nslookup、针对性 curl -v）。不要在未确认路径的情况下盲目加大超时时间。

3. 代理：Daemon 代理与系统代理不是同一件事

常见误区是把系统环境变量当成万能钥匙。容器引擎、守护进程与构建工具各自可能有独立的代理配置入口；另外要注意：哪些流量需要代理、哪些必须直连，混用会导致「有时候快，有时候慢」。

4. Registry 限流：toomanyrequests 不是偶然

公共 Registry 往往对匿名与登录用户有不同的速率限制。CI 并发拉取多个镜像时，最容易触发限流。应对策略通常包括：

• 登录后拉取（提高配额）
• 降低并发或引入缓存/镜像分发（治理层面）
• 错峰与退避重试（工程层面）

5. 本地存储：磁盘慢也会表现为 pull 卡

磁盘接近写满、inode 不足、存储驱动异常，都可能让 pull 过程长时间停顿。建议把主机磁盘与 Docker/containerd 存储目录纳入常规巡检。

6. 面向团队的「最小标准化」

把以下内容写成一页团队规范，会显著减少扯皮：

• 允许使用的 Registry 列表与默认镜像源策略
• CI 拉取的并发上限与重试策略
• 代理与证书问题的升级路径（谁能改、改哪里）

7. 小结

docker pull 的问题很少是单一原因。把链路分层定位，才能避免「只会重启」或「只会换镜像站」。当你能稳定复现并指出瓶颈层级时，治理方案（缓存、权限、网络）才会有针对性。