containerd 2.x 接入 Harbor 私有仓库：避坑配置全指南

本文将指导你如何在 containerd 2.x 版本中配置容器镜像仓库，以 Harbor 仓库的配置为例。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

如今，不少操作系统在安装 containerd 时，若未明确指定，默认会采用 2.x 版本。其配置镜像仓库的方式与 1.x 版本有所不同。如果你的 containerd 仍是 1.x 版本，可以参考我之前的文章进行配置：

《快速配置 Containerd 镜像加速（附最新可用加速地址）》

接下来，我们将演示如何在 containerd 2.x 版本中配置镜像仓库，这里以 Harbor 仓库为例。

1. 配置结构

containerd 2.x 版本的所有镜像仓库配置均位于 /etc/containerd/certs.d/ 目录下。

其配置结构如下：

• 一个 registry 域名对应一个目录
• 一个目录内包含一个 hosts.toml 文件
• 在 hosts.toml 文件中定义：服务器地址、认证信息、以及是否跳过证书验证

2. 配置实战

首先，确认你的 containerd 是否为 2.x 版本：

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

创建对应的配置目录：

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

目录名称必须与镜像操作中使用的 registry 地址完全一致。如果没有使用域名，直接使用 IP 地址作为目录名也是可以的。

创建 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"
    password = "Harbor12345"

由于我使用的是自签名证书，因此设置了跳过验证 (skip_verify = true)。如果你使用的是企业级有效证书，则无需设置此项，只需将 CA 证书文件放入 /etc/containerd/certs.d/harbor.liyb.com/ 目录即可。

接下来，需要去主配置文件 config.toml 中确认 config_path 的配置路径：

# /etc/containerd/config.toml
[plugins."io.containerd.grpc.v1.cri".registry]
  config_path = "/etc/containerd/certs.d"

containerd 2.x 版本通常默认开启此配置，但在生产环境中务必进行检查确认。

3. 验证方式

可以使用 nerdctl 命令行工具进行验证：

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

也可以在 Kubernetes 节点上使用 crictl 验证：

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

请注意，镜像名称必须显式包含完整的 registry 地址。

4. 最容易踩的几个坑

hosts.toml 配置不生效 → 目录名称写错（域名或端口不一致）。

HTTP 仓库拉不下来 → 忘了写 http:// 协议头。

K8s Pod 拉不到镜像 → Image 字段没写 registry 地址。

误以为 daemon.json 生效 → containerd 不读取 Docker 的配置。