docker pull 不支持断点续传，因镜像层以原子 tar.gz blob 下载，中断即全量重传；实际应通过智能重试、镜像缓存、registry mirror 或 skopeo 等手段优化拉取可靠性。

docker pull 本身不支持断点续传

这是最常被误解的一点：docker pull 底层用的是 HTTP/HTTPS 拉取镜像层（layer），而每个 layer 是一个独立的 tar.gz blob，Docker 客户端在下载时不会对单个 layer 做分块校验或断点记录。一旦连接中断，整个 layer 就得重下——不是“续传”，是“重传”。

常见错误现象：pull access denied 看似权限问题，实则是网络中断后重试时 token 过期；或者看到 waiting for download to finish 卡住十几分钟，其实是底层连接已死但客户端没及时超时。

• 根本原因：Docker daemon 使用的是 containerd 的 content store，它把 layer 当作原子单元存取，不暴露 chunk-level 接口
• 影响场景：弱网环境（如跨国拉取 python:3.12-slim）、CI/CD 中间节点频繁掉线、代理不稳定
• 参数无效项：--max-concurrent-downloads 只控并发数，不解决单层失败重试逻辑

靠重试 + 镜像缓存绕过“断点”需求

既然不能断点，就让重试更聪明、让重复下载更少——这才是实际可行的路径。

使用场景：Jenkins 流水线跑 docker pull 失败后自动重试；本地开发机反复拉同一个大镜像（如 nvidia/cuda:12.2.0-devel-ubuntu22.04）。

• 基础重试命令：until docker pull ubuntu:22.04; do echo "Pull failed, retrying in 5s..."; sleep 5; done
• 加超时和次数限制（避免无限循环）：timeout 600 bash -c 'for i in {1..5}; do docker pull alpine && break || sleep 10; done'
• 关键技巧：提前用 docker images -q ubuntu:22.04 检查是否已存在，跳过拉取——很多失败其实是因为上一次已下了一半但没 commit 成功镜像
• 注意：docker pull --platform linux/amd64 这类参数若错配，会导致重试永远失败（比如在 Apple Silicon 上硬拉 amd64 镜像）

用 registry mirror 和本地 registry 缓解网络压力

真正降低失败率的不是“重试更强”，而是“请求更短、路径更稳”。国内用户尤其明显：直连 registry-1.docker.io 动辄 30s+ 延迟，TLS 握手失败频发。

性能影响：开启 mirror 后，docker pull 的 DNS 解析、TCP 建连、TLS 握手全部落在国内节点，单层下载耗时可从 2min+ 降到 20s 内。

• 配置方式（/etc/docker/daemon.json）：

  {"registry-mirrors": ["https://xxx.mirror.aliyuncs.com"]}

  ，改完必须 sudo systemctl restart docker
• 自建本地 registry（如 registry:2）适合团队：第一次拉取后所有机器都从内网取，完全避开公网波动
• 坑点：registry-mirrors 不支持带路径的地址（如 https://mirrors.example.com/docker 会报错），只接受根域名形式
• 兼容性注意：Docker Desktop for Mac/Windows 的镜像设置入口在 GUI 里，和 Linux daemon.json 不互通

用 skopeo 替代 docker pull 做可控拉取

当需要精确控制下载行为（比如只拉某几个 layer、跳过校验、指定 TLS 版本），docker pull 就太黑盒了。skopeo 是更底层的工具，能暴露 transport 层细节。

使用场景：离线环境预热镜像、审计 layer 内容、调试 registry 认证流程。

• 基本用法：skopeo copy docker://docker.io/library/alpine:latest docker-daemon://alpine:latest
• 加重试逻辑（需配合 shell）：skopeo --insecure-policy --override-arch amd64 copy --retry-times 3 ...
• 优势：skopeo 支持 --src-tls-verify=false 和自定义 CA，遇到私有 registry 证书问题比 docker pull 更易调试
• 注意：skopeo 不走 Docker daemon，所以不会触发 buildkit cache 或 docker images 列表，最后得用 docker load 导入

真正难处理的不是“怎么重试”，而是“怎么判断该不该重试”——比如 401 错误是 token 过期（该刷新 credential），503 是 registry 临时不可用（该等），而 TLS handshake timeout 才是该重试。这些状态码和底层连接细节，docker pull 全部吞掉了。