containerd拉取docker.io镜像卡顿是因未配置国内镜像源，需按版本编辑/etc/containerd/certs.d/docker.io/hosts.toml（1.5+）或/etc/containerd/config.toml（≤1.4.x），填入阿里云等镜像地址并重启服务。
在 Kubernetes 或 k3s 集群中，containerd 拉取 docker.io 镜像时卡在 manifest 获取阶段、超时失败或速度极慢，是因为它默认直连海外 registry-1.docker.io，未配置国内镜像源。Docker 的 daemon.json 配置对 containerd 完全无效，必须单独编辑其 TOML 配置文件并重启服务。
确认 containerd 版本与配置路径
先执行 containerd --version 查看版本号。若为 1.5 及以上版本（2026 年主流发行版均属此列），官方推荐将镜像仓库配置分离到 /etc/containerd/certs.d/ 目录下管理；若为 1.4.x 或更低，则全部写入 /etc/containerd/config.toml 即可。这一步不跳过，否则后续配置可能被忽略。
运行 ls /etc/containerd/config.toml 确认文件存在。若不存在，用 containerd config default > /etc/containerd/config.toml 生成基础模板。
方法一：新版 containerd（1.5+）使用 certs.d 分离配置
此方式更灵活，支持 per-host 配置、TLS 证书覆盖和私有仓库认证，且避免主配置文件臃肿。
第一步：创建 certs.d 目录结构
执行 sudo mkdir -p /etc/containerd/certs.d/docker.io，确保路径存在。
第二步：新建镜像源配置文件
在该目录下创建 hosts.toml：sudo nano /etc/containerd/certs.d/docker.io/hosts.toml
第三步：填入可用镜像源列表（截至 2026 年 10 月实测有效）
内容如下（注意缩进必须为 2 个空格，TOML 对格式敏感）：
server = "https://docker.io"
[host."https://registry.cn-hangzhou.aliyuncs.com"]
capabilities = ["pull", "resolve"]
[host."https://docker.mirrors.ustc.edu.cn"]
capabilities = ["pull", "resolve"]
[host."https://docker.1panel.live"]
capabilities = ["pull", "resolve"]
⚠️ 注意：不要删除或注释掉 [host."https://registry.cn-hangzhou.aliyuncs.com"] 这一行前面的方括号，否则 containerd 启动时会报错退出。
方法二：兼容所有版本的 config.toml 内联配置
适用于快速验证、临时调试或旧环境迁移，无需额外目录结构，但配置耦合度高。
用 vim 打开配置文件：sudo vim /etc/containerd/config.toml
定位到 [plugins."io.containerd.grpc.v1.cri".registry] 区块。若该区块不存在，手动添加以下完整段落（位置任意，但需在 plugins 大节内）：
[plugins."io.containerd.grpc.v1.cri".registry]
config_path = "/etc/containerd/certs.d"
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
endpoint = ["https://registry.cn-hangzhou.aliyuncs.com", "https://docker.mirrors.ustc.edu.cn", "https://docker.1panel.live"]
这三行 endpoint 地址按顺序尝试，第一个不可用时自动 fallback 到下一个。阿里云地址建议保留为首项，因它缓存最全、响应最快；USTC 源稳定性好，适合作为兜底。
重启 containerd 并验证加速是否生效
执行 sudo systemctl daemon-reload && sudo systemctl restart containerd。
用 crictl 测试拉取：sudo crictl pull nginx:1.27。如果输出中出现 Pulling image "nginx:1.27" 后迅速进入 Download complete，说明加速已起效。
必须用 crictl 或 kubectl 测试，ctr 命令绕过 CRI 插件，不会读取镜像源配置。
