Containerd Docker 镜像源配置教程

教程简介

适用于使用 containerd 的系统,如 Kubernetes(k3s / cri-o)或自建 containerd 环境,支持通过配置专属镜像域名专属域名提升镜像拉取速度、可控性与可用性。本教程同时支持 containerd v1.x 和 v2.x 版本,请根据您的版本选择对应的配置方式。

适用场景

适用于 Kubernetes、Containerd 等场景。

1
适用版本

本手册适用于以下 containerd 版本,请先确认您的版本:

< 1.4
不支持(语法不同)
1.4 ~ 1.7.x
配置方式:config.toml
完全支持(见下方 v1.x 配置)
≥ 1.7.x (v1.x)
配置方式:config.toml
推荐使用(见下方 v1.x 配置)
≥ 2.0 (v2.x)
配置方式:hosts.toml
配置方式不同(见下方 v2.x 配置)

请使用以下命令查看版本:

containerd --version

1
配置 config.toml(v2.x)

首先,需要在 /etc/containerd/config.toml 中配置 config_path,指定 hosts.toml 配置文件的目录路径:

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

⚠️重要:此配置是必需的,否则 containerd 无法识别 /etc/containerd/certs.d 目录下的 hosts.toml 配置文件。配置完成后需要重启 containerd 服务。

2
配置文件路径(v2.x)

containerd v2.x 版本使用独立的 hosts.toml 文件进行配置,每个镜像仓库需要创建对应的目录和配置文件:

/etc/containerd/certs.d/<registry_host>/hosts.toml

例如,对于 docker.io,配置文件路径为:

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

3
创建配置目录和文件(v2.x)

首先,为每个镜像仓库创建对应的目录和配置文件。以 docker.io 为例:

1. 创建配置目录:

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

2. 创建 hosts.toml 配置文件:

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

4
镜像源配置示例(v2.x)

在 hosts.toml 文件中添加以下配置内容。以 docker.io 为例:

server = "https://registry-1.docker.io"

[host."https://***.xuanyuan.run"]
  capabilities = ["pull", "resolve"]
  skip_verify = false

⚠️重要提示:对于 docker.io,server 字段必须使用 https://registry-1.docker.io,不能使用 https://docker.io。因为 docker.io 是命名空间,而 registry-1.docker.io 才是实际的 registry 地址。containerd 会严格校验,docker.io 下没有 /v2/ API,这可能导致配置失败。

💡重要提示:请将配置中的 *** 替换为您的专属域名前缀。例如,如果您的专属域名为 123abc.xuanyuan.run,则应将 *** 替换为 123abc。

其他镜像仓库配置示例:

quay.io 的配置(文件路径:/etc/containerd/certs.d/quay.io/hosts.toml):

server = "https://quay.io"

[host."https://***-quay.xuanyuan.run"]
  capabilities = ["pull", "resolve"]
  skip_verify = false

gcr.io 的配置(文件路径:/etc/containerd/certs.d/gcr.io/hosts.toml):

server = "https://gcr.io"

[host."https://***-gcr.xuanyuan.run"]
  capabilities = ["pull", "resolve"]
  skip_verify = false

注意:对于其他镜像仓库(如 registry.k8s.io、ghcr.io、mcr.microsoft.io 等),请按照相同的方式创建对应的目录和 hosts.toml 文件,并修改 server 和 host 字段为对应的仓库地址和您的专属域名。

5
TLS 配置(v2.x)

如果遇到证书验证失败的问题,可以在 hosts.toml 中设置 skip_verify = true:

server = "https://registry-1.docker.io"

[host."https://***.xuanyuan.run"]
  capabilities = ["pull", "resolve"]
  skip_verify = true

可针对不同仓库的 hosts.toml 文件分别设置。

6
应用配置(v2.x)

首次配置:修改了 config.toml 文件后,需要重启 containerd 服务使配置生效:

sudo systemctl restart containerd

建议重启后使用 journalctl -u containerd -f 观察是否有报错信息。

后续更新:首次配置完成后,后续如果只需要修改 /etc/containerd/certs.d/ 目录下的 hosts.toml 文件,不需要重启 containerd 服务。containerd 会自动检测并加载新的配置。

7
验证配置是否生效(v2.x)

配置完成后,尝试拉取镜像验证配置是否生效:

sudo crictl pull docker.io/library/nginx:alpine

或使用 nerdctl:

sudo nerdctl pull nginx:alpine

若配置生效,镜像将从您设置的专属域名拉取,而非默认 registry-1.docker.io。

7
常见问题

镜像拉取仍走官方源
可能原因(v1.x):
  • config.toml 配置无效或路径错误
  • config.toml 配置中没有配置对应的仓库
  • 专属域名没有流量
解决方法(v1.x):
  • 确认文件路径和语法,或重建配置文件
  • journalctl -u containerd -f 观察报错信息,看看具体是哪个仓库链接不上,配置到 config.toml 中
  • 前往充值页面充值流量包
镜像拉取仍走官方源(v2.x)
可能原因:
  • hosts.toml 文件路径错误或不存在
  • hosts.toml 配置语法错误
  • 未为对应的镜像仓库创建 hosts.toml 文件
  • 使用了错误的配置方式(v2.x 不能使用 v1.x 的 config.toml 配置)
解决方法:
  • 确认 hosts.toml 文件路径正确
  • 检查 hosts.toml 文件语法是否正确
  • 为每个需要访问的镜像仓库创建对应的目录和 hosts.toml 文件
  • 确认使用的是 v2.x 配置方式,参考上方的 v2.x 配置指南
containerd v2.x 配置后验证错误
可能原因:
  • 使用了 v1.x 的 config.toml 配置方式(v2.x 不支持)
  • hosts.toml 文件路径或格式错误
解决方法:
  • 确认 containerd 版本,v2.x 必须使用 hosts.toml 配置
  • 参考上方的 v2.x 配置指南重新配置
TLS 证书校验失败
v1.x 见 TLS 注意事项(v1.x),v2.x 在 hosts.toml 中设置 skip_verify = true
拉取失败报错 no matching endpoint
可能原因:
endpoint 拼写错误或域名不可访问
解决方法:
检查域名可用性与拼写正确性
专业版 · 高速稳定拉取镜像
50GB 仅 ¥8/年
高速镜像下载在线技术支持专业版保障服务可用付费会员免广告