文档首页/ 容器镜像服务 SWR/ 最佳实践（基础版）/ containerd配置镜像加速器
更新时间：2026-09-11 GMT+08:00
查看PDF
分享

containerd配置镜像加速器

场景描述

在虚拟机场景下使用containerd作为容器运行时，拉取Docker Hub等境外镜像仓库的镜像时，常因网络延迟导致拉取缓慢甚至超时失败。本实践指导您通过配置镜像加速器解决此问题，涵盖containerd 1.x与2.x版本。

版本差异

containerd 1.x与2.x的配置思路一致，核心区别仅在于CRI插件配置路径名称不同。推荐使用config_path + hosts.toml方式，该方式为containerd官方推荐， 1.5+与2.x通用。registry.mirrors直接配置方式已被官方标记为DEPRECATED，2.x中不再推荐。

表1 containerd 1.x与2.x配置差异

项目

containerd 1.x

containerd 2.x

CRI插件配置路径

plugins."io.containerd.grpc. v1.cri"

plugins."io.containerd.cri.v1. images"

registry.mirrors

支持（1.5前主流方式）

已废弃，不推荐

config_path +hosts.toml

1.5+支持（推荐）

支持（推荐）

前提条件

  • 已安装containerd且服务正常运行。
  • 已获取可用的镜像加速器地址（登录SWR控制台"镜像加速器"页面获取）。
  • 虚拟机与镜像加速器之间网络可达。

版本判断

不同版本的配置路径不同，操作前请先执行以下命令确认版本：

containerd --version

回显示例：

containerd github.com/containerd/containerd v1.6.32
#或
containerd github.com/containerd/containerd v2.0.2

根据版本号选择对应配置：

  • v1.x：使用io.containerd.grpc.v1.cri插件路径
  • v2.x：使用io.containerd.cri.v1.images插件路径

操作步骤（推荐方式）

本方式使用config_path + hosts.toml配置镜像加速器，适用于containerd 1.5+及2.x版本，为官方推荐方式。

  1. 备份原有配置文件。 

    sudo cp /etc/containerd/config.toml /etc/containerd/config.toml.bak

  2. 编辑配置文件。 

    sudo vi /etc/containerd/config.toml

  3. 根据containerd版本，搜索是否存在以下配置项，若配置项不存在，则在配置文件中添加以下配置。若配置项已存在，则跳过本步骤，执行下一步操作。

    • Containerd 1.x（1.5+） 
      [plugins."io.containerd.grpc.v1.cri".registry]
  config_path = "/etc/containerd/certs.d"
    • Containerd 2.x 
      [plugins."io.containerd.cri.v1.images".registry]
 config_path = "/etc/containerd/certs.d"

  4. 创建镜像仓库配置目录。 

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

  5. 创建并编辑hosts.toml文件。 

    sudo vi /etc/containerd/certs.d/docker.io/hosts.toml

    写入以下内容，将加速器地址替换为实际地址。

    server = "https://docker.io"
[host."https://<加速器地址>"]
capabilities = ["pull","resolve"]
    表2 hosts.toml配置项说明

    配置项

    说明

    server

    原始上游镜像仓库地址，所有加速器不可用时回退至该地址。

    [host."加速器地址"]

    镜像加速器地址，可配置多个，containerd按顺序依次尝试。

    capabilities

    加速器支持的能力：pull（拉取镜像）、resolve（解析manifest）

  6. 重启containerd容器引擎。 

    sudo systemctl restart containerd
sudo systemctl enable containerd

  7. 拉取测试镜像，观察速度是否明显提升。 

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

  8. （可选）查看日志确认加速器使用情况。 

    sudo journalctl -u containerd -n 50 | grep -i mirror

常见问题处理

  1. config_path与mirrors同时存在。
    1. 问题现象：配置了镜像加速器，但拉取镜像仍然缓慢，配置看似正确。
    2. 问题原因：当config.toml中同时存在config_path和registry.mirrors配置时，config_path优先级更高，registry.mirrors配置将被完全忽略。
    3. 典型错误配置： 
      [plugins."io.containerd.grpc.v1.cri".registry]
config_path = "/etc/containerd/certs.d"        #非空，mirrors被忽略

[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
endpoint = ["https://<加速器地址>"]           #实际不生效

      此时若/etc/containerd/certs.d/目录下没有对应的hosts.toml文件，containerd将直接访问原始仓库，表现为拉取缓慢但配置看似正确。

    4. 处理方法：二选一，不要同时保留两种配置。
      表3 冲突处理方案

      方案

      操作

      方案A（推荐）

      保留config_path，删除所有registry.mirrors段落，在certs.d目录下配置hosts.toml。

      方案B

      将config_path设为空字符串，保留registry.mirrors配置。
    5. 验证方法： 
      grep config_path /etc/containerd/config.toml
      • 返回非空路径：走hosts.toml，mirrors失效
      • 返回空字符串：走mirrors，旧配置生效
  2. 私有仓库需认证。
    1. 问题现象：加速器或私有仓库需要用户名密码认证，拉取时返回401。
    2. 处理方法：在hosts.toml对应[host."..."]段落下添加认证信息： 
      [host."https://<私有仓库地址>"]
capabilities = ["pull", "resolve"]
[host."https://<私有仓库地址>".auth]
username = "<用户名>"
password = "<密码>"

      明文密码存在安全风险，建议使用token或其他安全认证方式。

      请确保hosts.toml文件权限仅限root用户访问。

      sudo chmod 600 /etc/containerd/certs.d/docker.io/hosts.toml

旧版配置方式（仅1.4及更早）

registry.mirrors直接配置方式仅适用于containerd 1.4及更早版本， 2.x中已废弃。如需使用，步骤如下：

  1. 编辑配置文件。 

    sudo vi /etc/containerd/config.toml

    添加registry.mirrors配置。

     version = 2
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
 endpoint = ["https://<加速器地址>", "https://registry-1.docker.io"]

  2. 重启containerd。 

    sudo systemctl restart containerd

相关文档