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 全部吞掉了。
