镜像拉取失败是什么问题
docker pull 或 Pod 拉镜像失败时，报错文本里的关键词直接决定排查方向：认证、网络、证书、磁盘、架构五类原因各占一片。先完整读取报错（尤其是带服务端返回状态码的那一句），再对症处置，不要一律当成网络问题去换镜像源。
基本信息
| 读报错 | 完整输出包含仓库地址与 HTTP 状态，先看全再动手 |
|---|---|
| 认证 | docker login <仓库地址>，凭据存于 ~/.docker/config.json |
| 镜像源 | daemon.json 的 registry-mirrors 只加速 Docker Hub |
| 磁盘 | docker system df 查看镜像与缓存占用 |
| 架构 | 多架构清单可用 --platform 指定，单架构镜像只能换 |
报错关键词速查
| 报错 | 原因 | 处置 |
|---|---|---|
| manifest unknown | tag 或仓库不存在 | 核对镜像名与 tag，确认已推送 |
| unauthorized | 未登录或凭据过期 | docker login 对应仓库 |
| i/o timeout、TLS handshake timeout | 网络、代理或镜像源不通 | 配镜像源/代理，或换网络 |
| x509 certificate | 自签证书不受信 | 把 CA 加入系统信任后重启 docker |
| no space left | 磁盘满 | docker system prune 清空间再拉 |
| no matching manifest | 架构不匹配 | 加 --platform 或换对应架构镜像 |
验证步骤
验证步骤
docker pull registry.example.com/team/app:1.2.3 # 复现并保留完整报错
docker login registry.example.com # 认证类问题就地验证
docker info | grep -A3 "Registry Mirrors" # 确认镜像源真的生效
df -h /var/lib/docker # 先排除磁盘满
curl -v https://registry.example.com/v2/ # 看 TLS 与拦截在哪一步
docker pull --platform linux/arm64 nginx:1.27-alpine典型使用场景
- CI 流水线拉私有仓库报 unauthorized：runner 没做过 docker login
- 内网机器拉 Docker Hub 超时：需要配镜像源或走代理
- ARM 机器拉 amd64 镜像报 no matching manifest，需指定平台
- 节点被旧镜像与日志占满后 pull 失败，先清理再重试
registry-mirrors 只对 Docker Hub 的官方仓库生效；带域名前缀的私有仓库仍走原地址。「配了镜像源还是超时」多半是这一条，或者改完 daemon.json 没有 reload docker。
insecure-registries 允许跳过证书校验访问仓库，共享 CI 与生产节点长期开启会让镜像可被中间人替换，仅限临时排障使用。
私有仓库的证书问题有固定排查顺序：curl -v 直连仓库的 v2 接口，看失败停在 DNS、TCP 还是 TLS；出现 x509 报错说明连接已建立只是证书链不受信，把 CA 放到仓库域名对应的信任目录并重启 docker 即可，无需放宽全局校验。