Containerd 2.x 镜像加速配置 (含 K8s 环境)

在 containerd 的新版本（特别是 2.x 系列，配置文件版本为 3）中，镜像仓库的配置方式发生了重大变化。旧的 registry.mirrors 配置方式已被废弃，推荐使用基于 hosts.toml 的模块化配置。

为什么旧配置不生效？

• 旧版本 (1.x): 直接在 /etc/containerd/config.toml 中使用 [plugins."io.containerd.grpc.v1.cri".registry.mirrors] 段落。
• 新版本 (2.x): 废弃了上述配置，转而推荐使用 config_path 指向一个目录，并在该目录下为每个仓库创建独立的 hosts.toml 文件。

在 config.toml 文件头部的 version = 3 表明你正在使用新版配置格式。

推荐方法：使用 hosts.toml (模块化配置)

这是 containerd 2.x 的官方推荐方式，更加清晰和灵活。

1. 确认主配置
首先，确保你的 /etc/containerd/config.toml 文件中已经设置了 config_path。根据你的文件内容，这一行已经存在：

[plugins.'io.containerd.cri.v1.images'.registry]
  config_path = '/etc/containerd/certs.d:/etc/docker/certs.d'

这告诉 containerd 去 /etc/containerd/certs.d 目录寻找镜像配置。

2. 配置 Docker Hub 加速

• 创建目录：

  sudo mkdir -p /etc/containerd/certs.d/docker.io
  

• 创建配置文件：
  创建 /etc/containerd/certs.d/docker.io/hosts.toml 文件，并填入以下内容：

  server = "https://registry-1.docker.io"
  
  [host."https://docker.m.daocloud.io"]
    capabilities = ["pull", "resolve"]
  [host."https://docker.1panel.live"]
    capabilities = ["pull", "resolve"]
  [host."https://docker.1ms.run"]
    capabilities = ["pull", "resolve"]
  [host."https://docker.xuanyuan.me"]
    capabilities = ["pull", "resolve"]
  

  你可以添加多个 [host."..."] 块，containerd 会按顺序尝试。

3. 配置 K8s 官方镜像仓库加速
K8s 集群在拉取核心组件（如 kube-apiserver, coredns）时，会从 registry.k8s.io 拉取镜像。国内访问该仓库非常缓慢，配置加速至关重要。

• 创建目录：

  sudo mkdir -p /etc/containerd/certs.d/registry.k8s.io
  

• 创建配置文件：
  创建 /etc/containerd/certs.d/registry.k8s.io/hosts.toml 文件。这里以阿里云的镜像仓库为例：

  server = "https://registry.k8s.io"
  
  [host."https://registry.aliyuncs.com/google_containers"]
    capabilities = ["pull", "resolve"]
  

4. 配置私有仓库 (如 Harbor)

• 创建目录：

  sudo mkdir -p /etc/containerd/certs.d/harbor.wang.org
  

• 创建配置文件：
  创建 /etc/containerd/certs.d/harbor.wang.org/hosts.toml 文件：

  server = "https://harbor.wang.org"
  
  [host."https://harbor.wang.org"]
    capabilities = ["pull", "resolve", "push"]
    # 如果 Harbor 使用自签名证书，需要跳过 TLS 验证
    # skip_verify = true
  

• 配置认证信息：
  由于 hosts.toml 不直接支持用户名密码，认证信息仍需写在主配置文件 /etc/containerd/config.toml 中。在文件末尾添加：

  [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.wang.org".auth]
    username = "admin"
    password = "123456"
  

备选方法：旧版配置 (不推荐)

虽然不推荐，但如果你坚持在 config.toml 中直接配置，可以使用以下格式。请确保将其添加到 [plugins] 块内，不要重复创建 [plugins]。

[plugins."io.containerd.grpc.v1.cri".registry]
  # ... 其他已有配置 ...

  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
      endpoint = [
        "https://docker.m.daocloud.io",
        "https://docker.1panel.live", 
        "https://docker.1ms.run",
        "https://docker.xuanyuan.me"
      ]
    # K8s 镜像仓库加速
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."registry.k8s.io"]
      endpoint = ["https://registry.aliyuncs.com/google_containers"]
    # 私有仓库
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.wang.org"]
      endpoint = ["https://harbor.wang.org"]

  [plugins."io.containerd.grpc.v1.cri".registry.configs]
    [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.wang.org".tls]
      insecure_skip_verify = true
    [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.wang.org".auth]
      username = "admin"
      password = "123456"

验证与生效

无论使用哪种方法，配置完成后都最好重启 containerd 服务。
使用hosts.toml这种方式可以不重启服务。

sudo systemctl restart containerd

config_path = “/etc/containerd/certs.d”
只对 k8s/cri 生效
不对 ctr 命令生效,需要指定加上 --hosts-dir /etc/containerd/certs.d

验证拉取：

• 使用 crictl (K8s 环境推荐):

  # 测试 Docker Hub
  crictl pull docker.io/library/nginx:latest
  # 测试 K8s 官方镜像
  crictl pull registry.k8s.io/pause:3.10.1
  

• 使用 ctr:

  sudo ctr images pull --hosts-dir /etc/containerd/certs.d/ docker.io/library/nginx:latest
  

如果配置成功，镜像拉取速度应有明显提升。