一、核心配置结构说明

containerd 2.x 对镜像仓库配置进行了结构化优化，所有相关配置均集中在 /etc/containerd/certs.d/ 目录下，遵循 “一仓库一目录” 的配置原则：

• 每个镜像仓库（registry）对应一个独立目录，目录名需与仓库域名（或 IP 地址）完全一致
• 每个目录下必须包含一个 hosts.toml 文件，用于定义仓库连接参数
• hosts.toml 核心配置项：仓库服务地址（server）、操作权限（capabilities）、认证信息（auth）、证书验证开关（skip_verify）

二、分步配置实战

1. 版本确认

首先通过以下命令验证 containerd 版本是否为 2.x 系列：

[root@k8s-master ~]# containerd --version
containerd containerd.io v2.2.0 1c4457e00facac03ce1d75f7b6777a7a851e5c41

2. 创建配置目录

根据 Harbor 仓库地址创建对应的配置目录，目录名需与仓库域名（或 IP）严格匹配（示例中 Harbor 仓库地址为 harbor.liyb.com）：

mkdir -p /etc/containerd/certs.d/harbor.liyb.com

注意：若仓库未使用域名（直接通过 IP 访问），可直接以 IP 地址作为目录名（如 /etc/containerd/certs.d/192.168.1.100）

3. 编写 hosts.toml 配置文件

创建并编辑 hosts.toml 文件，配置仓库连接参数：

vi /etc/containerd/certs.d/harbor.liyb.com/hosts.toml

添加如下配置内容：

server = "https://harbor.liyb.com"

[host."https://harbor.liyb.com"]
capabilities = ["pull", "resolve", "push"]  # 支持的操作：拉取、解析、推送
skip_verify = true  # 自签名证书时启用（跳过证书验证）
[host."https://harbor.liyb.com".auth]
username = "admin"  # Harbor 登录用户名
password = "Harbor12345"  # Harbor 登录密码

配置说明：

• 若使用企业级可信证书，无需设置 skip_verify = true，只需将 CA 证书文件放置到对应配置目录（如 /etc/containerd/certs.d/harbor.liyb.com/）即可
• 权限配置可根据实际需求调整，例如仅需拉取镜像时可改为 capabilities = ["pull", "resolve"]

4. 确认主配置文件路径

检查 containerd 主配置文件 /etc/containerd/config.toml 中是否正确指定了仓库配置路径，确保以下配置项存在且无误：

toml

# /etc/containerd/config.toml
[plugins."io.containerd.grpc.v1.cri".registry]
config_path = "/etc/containerd/certs.d"  # 仓库配置目录路径（默认已启用）

注意：containerd 2.x 默认启用该配置，但生产环境部署时务必手动校验，避免路径配置错误导致配置失效

三、配置验证方法

1. 使用 nerdctl 验证（推荐）

通过 nerdctl 工具拉取 Harbor 仓库镜像，验证配置是否生效：

nerdctl pull harbor.liyb.com/prod/nginx:1.27

成功输出示例：

plaintext

harbor.liyb.com/prod/nginx:1.27: manifest-sha256:114dff0fc8ee3d0200c3a12c60e3e2b79d0920dd953175ecb78a0b157425b25e: done
config-sha256:1e5f3c5b981a9f91ca91cf13ce87c2eedfc7a083f4f279552084dd08fc477512: done
elapsed: 0.1 s
total: 0.0 B (0.0 B/s)

2. Kubernetes 节点验证

在 Kubernetes 节点上通过 crictl 工具拉取镜像（适用于 K8s 集群环境）：

crictl pull harbor.liyb.com/prod/nginx:1.27

关键注意点：镜像名称必须显式包含 Harbor 仓库地址（完整格式：仓库地址 / 项目名 / 镜像名：标签），否则会导致 K8s Pod 拉取镜像失败

四、高频踩坑与解决方案

常见问题	排查方向	解决方案
hosts.toml 配置不生效	配置目录名与仓库域名 / 端口不一致	确保目录名与镜像中使用的 registry 地址完全匹配（含端口，如 harbor.liyb.com:8080 需对应创建 harbor.liyb.com:8080 目录）
HTTP 仓库镜像拉取失败	配置文件中未指定 http 协议	将 server 地址改为 http:// 开头（如 server = "http://harbor.liyb.com:80"）
K8s Pod 无法拉取镜像	镜像名称未包含仓库地址	Pod 配置中 image 字段需填写完整路径（如 harbor.liyb.com/prod/nginx:1.27），不可省略仓库地址
配置后仍无法连接仓库	误沿用 Docker 的 daemon.json 配置	containerd 2.x 不读取 Docker 的 daemon.json 配置，需按本文方法在 certs.d 目录下配置