containerd 镜像加速配置指南 (适用于 containerd 1.5 及以上版本)

1. 引言

1.1 为什么需要配置镜像加速？

在使用 containerd 拉取 Docker Hub 或其他公共镜像仓库的镜像时，由于网络延迟和带宽限制，经常会遇到镜像拉取缓慢甚至失败的问题。特别是在国内环境中，直接访问国外镜像仓库的速度往往不理想。

为了解决这一问题，我们可以通过配置镜像加速器来提升镜像拉取速度。镜像加速器通常由云服务商提供，它们在全球各地部署了镜像缓存服务器，能够就近提供镜像服务，显著提升镜像拉取速度。

1.2 镜像加速原理

镜像加速器的工作原理如下：

1. 当用户请求拉取某个镜像时，请求首先发送到镜像加速器
2. 镜像加速器检查本地是否已有该镜像的缓存
3. 如果有缓存且未过期，则直接返回缓存镜像
4. 如果没有缓存或缓存已过期，则从原始镜像仓库拉取镜像，缓存后再返回给用户

这种方式大大减少了跨地域网络传输的延迟，提高了镜像拉取效率。

2. 配置前准备

2.1 确认 containerd 版本

首先确认已安装 containerd 及其版本：

containerd --version

注意：本文档适用于 containerd 1.5 及以上版本。对于 1.5 之前的版本，配置方式有所不同。

2.2 检查现有配置

查看当前 containerd 配置文件：

cat /etc/containerd/config.toml

如果配置文件不存在，需要先生成默认配置：

sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml

3. 配置镜像加速器（containerd 1.5 及以上版本）

3.1 常用镜像加速服务

国内常用的镜像加速服务包括：

• Docker 中国官方镜像：https://registry.docker-cn.com
• 腾讯云容器镜像服务：https://mirror.ccs.tencentyun.com
• 中科大镜像站：https://docker.mirrors.ustc.edu.cn
• 网易云镜像：https://hub-mirror.c.163.com
• DaoCloud 镜像站：https://docker.m.daocloud.io

3.2 修改主配置文件

编辑 containerd 配置文件：

sudo vim /etc/containerd/config.toml

找到 [plugins."io.containerd.grpc.v1.cri".registry] 部分，添加 config_path 配置项：

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

注意：在 containerd 1.5 及以上版本中，mirrors 配置已经被弃用，取而代之的是基于目录结构的配置方式。

3.3 创建镜像仓库配置目录

创建配置目录：

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

为需要加速的镜像仓库创建各自的配置目录：

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

3.4 配置各镜像仓库的加速地址

在每个仓库目录下创建 hosts.toml 文件，以 docker.io 为例：

sudo tee /etc/containerd/certs.d/docker.io/hosts.toml <<-'EOF'
server = "https://registry-1.docker.io"

[host."https://registry.docker-cn.com"]
  capabilities = ["pull", "resolve"]

[host."https://hub-mirror.c.163.com"]
  capabilities = ["pull", "resolve"]

[host."https://mirror.ccs.tencentyun.com"]
  capabilities = ["pull", "resolve"]
EOF

为其他镜像仓库创建类似的配置文件：

gcr.io 配置：

sudo tee /etc/containerd/certs.d/gcr.io/hosts.toml <<-'EOF'
server = "https://gcr.io"

[host."https://gcr.mirrors.ustc.edu.cn"]
  capabilities = ["pull", "resolve"]
EOF

k8s.gcr.io 配置：

sudo tee /etc/containerd/certs.d/k8s.gcr.io/hosts.toml <<-'EOF'
server = "https://k8s.gcr.io"

[host."https://gcr.mirrors.ustc.edu.cn"]
  capabilities = ["pull", "resolve"]
EOF

registry.k8s.io 配置：

sudo tee /etc/containerd/certs.d/registry.k8s.io/hosts.toml <<-'EOF'
server = "https://registry.k8s.io"

[host."https://k8s.m.daocloud.io"]
  capabilities = ["pull", "resolve"]
EOF

3.5 配置私有仓库（可选）

如果需要配置私有仓库，可以在对应目录下创建 hosts.toml 文件：

sudo mkdir -p /etc/containerd/certs.d/your-private-registry.com
sudo tee /etc/containerd/certs.d/your-private-registry.com/hosts.toml <<-'EOF'
server = "https://your-private-registry.com"

[host."https://your-private-registry.com"]
  capabilities = ["pull", "resolve", "push"]
  skip_verify = false
  
[host."http://your-private-registry.com"]
  capabilities = ["pull", "resolve", "push"]
  skip_verify = true
EOF

4. 重启服务并验证

4.1 重启 containerd 服务

修改配置后，需要重启 containerd 服务使配置生效：

sudo systemctl restart containerd

4.2 验证配置是否生效

可以通过以下方式验证配置是否生效：

1. 查看 containerd 状态：

sudo systemctl status containerd

2. 尝试拉取镜像：

sudo ctr images pull docker.io/library/nginx:latest

3. 查看镜像列表：

sudo ctr images list

5. 不同环境下的配置示例

5.1 阿里云环境配置

如果您使用阿里云服务器，可以使用阿里云提供的镜像加速器：

sudo tee /etc/containerd/certs.d/docker.io/hosts.toml <<-'EOF'
server = "https://registry-1.docker.io"

[host."https://<your_code>.mirror.aliyuncs.com"]
  capabilities = ["pull", "resolve"]
EOF

注意：需要将 <your_code> 替换为您在阿里云容器镜像服务中获取的专属加速地址。

5.2 腾讯云环境配置

腾讯云用户可以使用腾讯云镜像加速器：

sudo tee /etc/containerd/certs.d/docker.io/hosts.toml <<-'EOF'
server = "https://registry-1.docker.io"

[host."https://mirror.ccs.tencentyun.com"]
  capabilities = ["pull", "resolve"]
EOF

5.3 多镜像源配置

为了提高可用性，可以配置多个镜像源：

sudo tee /etc/containerd/certs.d/docker.io/hosts.toml <<-'EOF'
server = "https://registry-1.docker.io"

[host."https://registry.docker-cn.com"]
  capabilities = ["pull", "resolve"]
  priority = 10

[host."https://hub-mirror.c.163.com"]
  capabilities = ["pull", "resolve"]
  priority = 20

[host."https://mirror.ccs.tencentyun.com"]
  capabilities = ["pull", "resolve"]
  priority = 30
EOF

containerd 会按优先级顺序尝试这些镜像源，priority 值越小优先级越高。

6. 故障排除

6.1 配置不生效

如果配置后镜像拉取速度没有改善，请检查：

1. 确认 containerd 版本是否为 1.5 及以上
2. 确认配置文件路径正确：/etc/containerd/config.toml 和 /etc/containerd/certs.d/
3. 确认服务已重启：sudo systemctl restart containerd
4. 检查配置文件语法是否正确

6.2 镜像拉取失败

如果配置镜像加速后出现镜像拉取失败，可以尝试：

1. 检查镜像加速器地址是否正确
2. 尝试更换其他镜像加速器
3. 检查网络连接是否正常
4. 确认镜像名称是否正确

6.3 回滚配置

如果配置出现问题需要回滚，可以：

1. 备份当前配置：

sudo cp -r /etc/containerd/certs.d /etc/containerd/certs.d.backup

2. 恢复默认配置：

sudo containerd config default | sudo tee /etc/containerd/config.toml
sudo rm -rf /etc/containerd/certs.d
sudo systemctl restart containerd

7. containerd 1.5版本前后的配置差异

7.1 旧版本配置方式（1.5 之前）

在 containerd 1.5 之前的版本中，镜像加速配置直接写在 config.toml 文件中：

[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
    endpoint = ["https://registry.docker-cn.com", "https://hub-mirror.c.163.com"]

7.2 新版本配置方式（1.5 及以上）

从 containerd 1.5 开始，推荐使用基于目录结构的配置方式，通过 config_path 指定配置目录：

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

然后在 /etc/containerd/certs.d/ 目录下为每个镜像仓库创建独立的配置文件。

7.3 两种配置方式的对比

特性	旧版本配置	新版本配置
配置位置	config.toml 文件中	独立的 hosts.toml 文件
重启要求	需要重启 containerd	无需重启（热加载）
灵活性	较低	更高，支持更多选项
可维护性	较差，所有配置集中在一个文件	更好，配置分散在多个文件中

8. 最佳实践建议

8.1 选择合适的镜像加速器

不同地区的用户应选择就近的镜像加速器，以获得最佳性能。

8.2 定期检查配置

建议定期检查镜像加速配置的有效性，确保加速器正常工作。

8.3 多源配置提高可用性

配置多个镜像源可以提高镜像拉取的可靠性，避免单点故障。

8.4 监控镜像拉取性能

可以通过监控工具跟踪镜像拉取时间，评估镜像加速效果。

8.5 使用新版配置方式

对于 containerd 1.5 及以上版本，强烈推荐使用基于 hosts.toml 文件的新配置方式，它提供了更好的灵活性和可维护性。

9. 总结

通过配置镜像加速器，可以显著提升 containerd 拉取镜像的速度，特别是在网络环境较差的情况下。正确配置镜像加速不仅能提高工作效率，还能改善容器化应用的部署体验。

对于 containerd 1.5 及以上版本，配置过程主要包括：

1. 选择合适的镜像加速服务
2. 修改 containerd 主配置文件，指定 config_path
3. 为每个需要加速的镜像仓库创建独立的配置目录和 hosts.toml 文件
4. 重启服务使配置生效
5. 验证配置结果

建议根据实际使用环境选择合适的镜像加速器，并定期检查配置的有效性。对于 containerd 1.5 及以上版本，使用新的基于 hosts.toml 文件的配置方式可以获得更好的配置管理体验。