镜像拉取失败不一定是containerd故障，需先用crictl验证网络、TLS证书、认证及镜像地址；再检查containerd的config.toml中私有仓库CA、registry配置和auth凭据；修改后须重启k3s或containerd，并用crictl info、ctr命令确认生效；应急可手动导入镜像并重打标签，或通过启动参数指定私服。
确认镜像拉取失败是否真由 containerd 引起
先别急着改配置。K3s 默认用 containerd，但错误日志里出现 failed to pull and unpack image，不等于一定是 containerd 自身故障——它只是执行层，真正卡点往往在上游：网络、证书、认证或镜像地址本身。
最直接的验证方式是在出问题的节点上，用 crictl 模拟 kubelet 行为：
- 运行
sudo crictl pull harbor.intra.example.com/proj/app:v1.2.3（替换为你实际的镜像地址） - 如果报
x509: certificate signed by unknown authority，说明是 TLS 信任问题 - 如果报
context deadline exceeded或连接拒绝，优先查网络连通性与端口开放情况（如 Harbor 的 443/80 是否可达） - 如果提示
unauthorized: authentication required，说明需要 registry 认证，但 K3s 未配置对应 secret 或 containerd 配置未生效
检查 containerd 对私有仓库的 TLS 和认证配置
K3s 不读 Docker 的 ~/.docker/config.json，它依赖 containerd 的 config.toml。关键配置路径通常是：
-
/var/lib/rancher/k3s/agent/etc/containerd/config.toml（agent 节点） -
/var/lib/rancher/k3s/server/etc/containerd/config.toml（server 节点）
重点确认以下几项是否正确写入（需重启 containerd 或整个 k3s 才生效）：
-
私有仓库 CA 证书：把 Harbor 自签名 CA 证书（如
ca.crt）拷到/var/lib/rancher/k3s/agent/etc/containerd/certs.d/harbor.intra.example.com/ca.crt（目录需手动创建） -
registry 配置块：在
config.toml的[plugins."io.containerd.grpc.v1.cri".registry]下添加对应 host 的host条目，启用skip_verify = true（仅测试环境）或指定ca路径 -
认证凭据：若需账号密码，在
hosts.toml中配置auth字段（Base64 编码后的username:password），或使用kubectl create secret docker-registry并在 Pod 中引用
验证 containerd 实际使用的配置是否加载成功
修改 config.toml 后容易忽略一步：containerd 不会热重载该文件。必须重启服务：
- 执行
sudo systemctl restart k3s（k3s 会一并重启内置 containerd） - 或单独重启 containerd：
sudo systemctl restart containerd（仅当 K3s 以外部 containerd 模式运行时）
验证是否生效的方法：
- 运行
sudo ctr -n k8s.io image ls | grep your-image查看本地是否有缓存镜像 - 执行
sudo crictl info | grep -A5 registry看输出中是否列出你配置的私有 registry 地址 - 查看 containerd 日志：
sudo journalctl -u k3s -n 100 --no-pager | grep -i "harbor\|pull\|cert"
绕过拉取失败的临时应急手段
生产环境不能长期卡在镜像拉取上。当排查耗时较长，可快速恢复业务：
-
手动导入镜像：在能联网的机器上
docker pull镜像 →docker save -o app.tar image:tag→ 拷贝到目标节点 →sudo ctr -n k8s.io image import app.tar -
重打标签匹配原需求：比如 K3s 默认要拉
docker.io/rancher/pause:3.6，但你已导入harbor.intra/pause:3.6，则运行：sudo ctr -n k8s.io image tag harbor.intra/pause:3.6 docker.io/rancher/pause:3.6 -
修改 K3s 启动参数跳过默认镜像拉取：通过
--pause-image或--system-default-registry指定私服前缀，避免硬编码依赖外网
