拉取失败主因是本地环境与远程仓库“握手”异常，首要排查网络连通性与DNS解析：curl -v测试HTTPS连接，超时或解析失败即定位问题；其次检查代理配置、镜像源有效性、权限认证、Docker服务状态及磁盘空间。
拉取失败大多不是镜像本身的问题，而是本地环境与远程仓库之间的“握手”出了问题。找准卡在哪一环，基本就能快速恢复。
网络连通性与 DNS 解析
这是最常被忽略的第一步。Docker 要访问 registry-1.docker.io，得先能解析域名、再能建立 HTTPS 连接。
- 用
curl -v https://registry-1.docker.io/v2/测试——返回HTTP/2 401或403是正常的（说明通了）；超时或Could not resolve host就是网络或 DNS 问题 - DNS 不稳时，临时改
/etc/resolv.conf，加两行：nameserver 8.8.8.8nameserver 1.1.1.1 - 企业内网若走代理，光设系统环境变量不够，Docker 守护进程必须单独配——在
/etc/systemd/system/docker.service.d/http-proxy.conf里写清楚HTTP_PROXY和HTTPS_PROXY，然后sudo systemctl daemon-reload && sudo systemctl restart docker
镜像源配置与加速器
国内直连 Docker Hub 延迟高、易超时，换镜像源是最立竿见影的优化。
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- 编辑
/etc/docker/daemon.json（不存在就新建），填入国内可信加速地址，例如：{"registry-mirrors": ["https://<your-id>.mirror.aliyuncs.com", "https://docker.mirrors.ustc.edu.cn"]}</your-id> - 注意：不要用已失效的老地址（如
https://registry.docker-cn.com已停服）；阿里云加速地址需登录容器镜像服务控制台获取专属链接 - 改完务必执行
sudo systemctl restart docker，再用docker info | grep Mirrors确认生效
权限与认证状态
非 root 用户没加 docker 组、私有仓库没登录、令牌过期，都会在拉取时突然报错。
- 运行
groups查看当前用户是否在docker组里；不在就执行sudo usermod -aG docker $USER，然后彻底退出终端重登 - 拉私有镜像（比如公司内部 registry）前，先
docker login your-registry.example.com:5000；登录后凭证存在~/.docker/config.json，可打开检查是否为空或格式损坏 - 如果用的是短期 token，偶尔会因过期导致
unauthorized，重新docker login即可
服务状态与资源瓶颈
Docker 本身不健康，或者磁盘快满了，也会让拉取中途失败。
- 查服务是否活着：
systemctl status docker；显示active (running)才算正常，否则sudo systemctl start docker - 看磁盘空间：
df -h /var/lib/docker；低于 10% 剩余空间容易出错，清理命令：docker system prune -a（慎用，会删所有未使用镜像和构建缓存） - 配置文件语法错误也常见——
/etc/docker/daemon.json多一个逗号、少一个引号，Docker 就启动失败；可用jsonlint或在线 JSON 校验工具验证
