imagepullbackoff 表示 pod 因镜像拉取失败进入退避重试状态，主因包括镜像不存在或标签错误、私有仓库认证缺失、节点网络/证书配置不当、拉取超时或并发限制、镜像元数据损坏等，需依序排查镜像可达性、secret 配置、节点运行时设置、加速策略及仓库健康度。
镜像拉取失败在 Kubernetes 中最常见表现为 ImagePullBackOff 或 ErrImagePull，但背后原因差异很大。直接重启 kubelet 或节点往往无效，关键是要快速定位具体环节——是镜像地址错了、没权限、连不上仓库，还是证书或网络卡住了。
确认镜像是否存在且标签正确
很多失败其实源于“镜像根本不存在”。Kubernetes 不会主动告诉你标签错，只会报 manifest unknown 或 repository does not exist。
- 用
skopeo inspect docker://检查（无需登录，不拉取镜像） - 注意镜像地址是否漏写 registry 域名，比如把
nginx:1.25写成registry.k8s.io/nginx:1.25才对 - 私有仓库镜像要带完整路径，如
harbor.example.com/proj/app:v2.1，不能省略域名和项目名
检查认证配置是否生效
私有仓库必须提供有效凭证，而 Secret 配置极易出错。
- 确保使用
kubernetes.io/dockerconfigjson类型创建 Secret，不是旧的docker.io/dockercfg - Secret 必须和 Pod 在同一命名空间；跨命名空间需显式引用或绑定 ServiceAccount
- 在 Pod spec 中通过
imagePullSecrets正确引用，例如：- name: regcred - 执行
kubectl describe pod <name></name>查看 Events 是否提示Failed to pull image ... unauthorized，这是典型认证失败信号
验证仓库连接与证书信任
即使有凭证，也得能连上、信得过。
- 在对应节点上手动测试：运行
curl -I https://your-registry.com/v2/，看是否返回200 OK或401 Unauthorized（后者说明通路正常，只是没权限） - 遇到
x509: certificate signed by unknown authority，需将 CA 证书添加到节点系统信任链，或为 containerd 配置ca_file路径（/etc/containerd/certs.d/your-registry.com/ca.crt） - 若用自签名证书，不要简单关闭校验——生产环境应补全证书链，而非禁用 TLS 验证
排查网络与中间件干扰
尤其在访问国外镜像（如 gcr.io、quay.io）或使用代理/防火墙时，问题更隐蔽。
- 检查节点 DNS 是否能解析目标域名：
nslookup k8s.gcr.io；失败则需调整/etc/resolv.conf或 CoreDNS 配置 - 确认节点可访问仓库端口（通常是 443），用
telnet your-registry.com 443或nc -zv your-registry.com 443 - 企业环境中常见代理拦截或 TLS 中间人设备，导致证书校验失败或连接重置；可临时关闭代理对比验证
- 国内用户访问 gcr.io 等仓库，建议配置镜像代理（如阿里云容器镜像服务）或改用国内镜像源
