拉取或推送镜像失败90%源于本地与远程仓库“握手”异常，需按DNS解析→网络连通→镜像源→代理/权限/服务状态四环节排查：先用nslookup和curl -v验证解析与HTTPS连通性，再配置2026年可用镜像源并重启Docker，最后检查代理配置、docker组权限、登录状态及磁盘空间。
拉取或推送镜像失败，90%不是镜像本身的问题，而是本地环境与远程仓库之间“握手”卡在了某个环节。问题往往藏在网络链路、配置生效、权限状态或服务健康度里，而不是命令写错了。
网络连通性与 DNS 解析是第一道关
很多报错如 i/o timeout、connection refused 或 Could not resolve host，都指向这一步没走通。
- 先用
curl -v https://registry-1.docker.io/v2/模拟 Docker 请求——返回 HTTP 401/403 是正常（说明通了）；卡住或报解析失败才是真问题 - 若
nslookup registry-1.docker.io无响应，临时改/etc/resolv.conf，加两行：
nameserver 8.8.8.8
nameserver 1.1.1.1 - 企业内网必须配代理？光设
HTTP_PROXY环境变量不够，Docker 守护进程要单独配：在/etc/systemd/system/docker.service.d/http-proxy.conf里写明代理地址，再执行sudo systemctl daemon-reload && sudo systemctl restart docker
镜像源配置不是“填了就完事”
2026 年实测，大量老教程里的镜像源已失效或转为登录制。配错、配多、不重启，都会让加速器形同虚设。
- 推荐用当前稳定可用的地址（截至 2026 年 10 月）：
https://.mirror.aliyuncs.com（需登录阿里云容器镜像服务获取专属链接）
https://docker.mirrors.ustc.edu.cn
https://docker.m.daocloud.io - 编辑
/etc/docker/daemon.json，只留 2–3 个有效地址，避免顺序尝试拖慢速度 - 改完必须重启服务：
sudo systemctl restart docker，再用docker info | grep -A 1 "Registry Mirrors"确认是否加载成功 - 注意：
registry-mirrors只对docker.io域名下的镜像生效；拉ghcr.io、quay.io或k8s.gcr.io镜像时，它不参与转发
权限、认证与服务状态常被忽略
非 root 用户没加组、私有仓库没登录、Docker 服务宕了、磁盘快满了——这些都会让拉取静默失败或突然中断。
- 运行
groups查看是否在docker组；不在就执行sudo usermod -aG docker $USER，然后彻底退出终端重登 - 拉私有镜像前务必
docker login your-registry.example.com:5000；登录后检查~/.docker/config.json是否含对应 auth 字段 - 用
systemctl status docker确保服务是 active (running)；否则先sudo systemctl start docker - 运行
df -h /var/lib/docker查剩余空间；低于 10% 易失败，可执行docker system prune -a清理（注意会删掉未使用的镜像和容器）
推送失败重点查认证与仓库策略
推送（push）比拉取（pull）更敏感，尤其涉及私有仓库或云厂商 ACR 时，报错多集中在权限和策略限制上。
- 阿里云 ACR 推送失败？别用主账号密码登录——必须去容器镜像服务控制台设置独立 Registry 密码，再
docker login registry.cn-hangzhou.aliyuncs.com - 使用 RAM 子用户？不能复用主账号密码，同样要在控制台单独配访问凭证
- 报 unauthorized: authentication required？先确认
docker login是否针对目标仓库域名执行（比如registry.example.com不等于registry.example.com:5000） - 报 denied: requested access to the resource is denied？检查仓库是否开启匿名拉取但禁止匿名推送，或目标命名空间是否有 push 权限
