Containerd镜像仓库配置实战：用hosts.toml解决加速、认证难题-优快云博客

Containerd 2.x镜像仓库配置实战：用 hosts.toml 解决加速、认证难题

从1.35的k8s版本起，强制要求containerd升级为2.x，今天为大家带来2.x的配置文件新语法。主要是代理仓库配置文件迁移至hosts.toml文件，文件的书写格式和语法有变化。

一、先搞懂：hosts.toml 是干嘛的？

Containerd 作为容器运行时的「核心引擎」，负责镜像拉取、容器启停等工作。而hosts.toml就是它的「镜像仓库通讯录」—— 通过这个文件，我们可以：

给 Docker Hub 配置国内加速源（告别龟速拉取）；
对接私有仓库（比如企业内部的 Harbor），配置用户名 / 密码认证；
限制仓库权限（比如只允许拉取，禁止推送，防止误操作）；
处理 TLS 证书（自签名证书、双向认证都能搞定）。

它的默认存放路径有两个关键位置：

针对单个仓库：/etc/containerd/certs.d/<仓库域名>/hosts.toml

（比如 Docker Hub 对应/etc/containerd/certs.d/``docker.io/hosts.toml）
全局通用配置：/etc/containerd/certs.d/_default/hosts.toml

（所有仓库都生效，适合统一限制权限，比如测试环境禁止推送）

二、看个完整示例：hosts.toml 长这样

先放一个包含「加速源、认证、自定义请求头」的完整配置，后面我们逐段拆解：

# 全局配置：对应当前仓库（这里是Docker Hub）

server = "https://registry-1.docker.io"  # 官方主地址

capabilities = \["pull", "push"]          # 允许拉取和推送

default = \["https://mirror.docker-cn.com", "https://registry-1.docker.io"]  # 优先试国内加速源

# 单个主机配置：国内加速源（mirror.docker-cn.com）

[host."https://mirror.docker-cn.com"]

  capabilities = \["pull"]  # 加速源通常只支持拉取，禁用推送

  skip\_verify = false      # 生产环境必须开启TLS验证（true=跳过，危险！）

  ca = "/etc/containerd/certs.d/docker.io/ca.pem"  # 自定义CA证书（如有）


 # 私有仓库认证（示例：若加速源需要登录）

 [host."https://mirror.docker-cn.com".auth]

   username = "my-name"

   password = "\${REG\_PASSWORD}"  # 用环境变量存密码，避免明文泄露

  # token = "jwt-token"  # 更安全的方式：用JWT令牌替代账号密码


# 自定义请求头（比如传递企业内部标识）
[host."https://mirror.docker-cn.com".header]

  "X-Enterprise-ID" = "dev-team-01"

   "X-Pull-Priority" = \["high"]

三、核心配置字段：逐个搞懂不踩坑

3.1 全局配置（针对当前仓库）

字段名	作用说明
`server`	仓库的「主地址」，比如 Docker Hub 官方是`https://registry-1.docker.io`
`capabilities`	权限开关：`pull`（允许拉镜像）、`push`（允许推镜像），不配置则默认全支持
`default`	拉取 / 推送时的「重试列表」，按顺序尝试，前一个失败就换下一个（比如先试加速源）

3.2 单个主机配置（针对某一个仓库源）

比如上面示例中针对mirror.docker-cn.com的配置，核心字段分三类：

① 基础访问配置

字段名	作用说明
`capabilities`	优先级高于全局配置！比如全局允许`push`，但加速源可单独设为只允许`pull`
`skip_verify`	是否跳过 TLS 证书验证？⚠️ 生产环境必须设为`false`，否则有被劫持的风险
`ca`	自定义 CA 证书路径（仓库用自签名证书时必须配，否则会报证书错误）
`cert/key`	客户端证书和私钥（企业级私有仓库可能要求「双向认证」，就需要配这两个）

② 认证配置（对接私有仓库）

在[host."<地址>".auth]下配置，支持两种方式：

账号密码：username+password（推荐用环境变量，如${REG_PASSWORD}）；
令牌认证：token（更安全，比如 JWT 令牌，适合生产环境）。

③ 自定义请求头

在[host."<地址>".header]下配置，比如：

传递企业内部身份标识："X-Team" = "backend"；
配置拉取优先级："X-Pull-Level" = "high"。

四、3 个实战场景：直接抄作业

场景 1：Docker Hub 拉取慢？国内加速源安排

需求：拉镜像时先试国内加速源，失败再回退到官方源。

操作步骤：

创建配置目录：mkdir -p /var/lib/containerd/certs.d/``docker.io
新建hosts.toml：

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

default = \["https://mirror.docker-cn.com", "https://registry-1.docker.io"]  # 先加速源后官方

[host."https://mirror.docker-cn.com"]

  capabilities = \["pull"]  # 加速源通常只支持拉取

  skip\_verify = false

场景 2：对接企业私有 Harbor 仓库（带认证）

需求：访问harbor.example.com，需账号密码认证，且仓库用自签名 CA。

操作步骤：

创建目录：mkdir -p /var/lib/containerd/certs.d/``harbor.example.com
把自签名 CA 证书放到目录：cp harbor-ca.pem /var/lib/containerd/certs.d/``harbor.example.com/
新建hosts.toml：

server = "https://harbor.example.com"

capabilities = \["pull", "push"]  # 允许拉和推

[host."https://harbor.example.com"]

  skip\_verify = false

  ca = "/var/lib/containerd/certs.d/harbor.example.com/harbor-ca.pem"  # 配置CA证书


[host."https://harbor.example.com".auth]

  username = "harbor-admin"

  password = "\${HARBOR\_PASSWORD}"  # 环境变量存密码，避免明文

场景 3：测试环境禁止推送镜像？全局限制

需求：所有仓库只允许拉取，禁止推送（防止误操作把测试镜像推到生产）。

操作步骤：

创建全局配置目录：mkdir -p /var/lib/containerd/certs.d/_default
新建hosts.toml：

capabilities = \["pull"]  # 全局只允许拉取，所有仓库默认继承

五、配置生效与问题排查

1. 让配置生效

修改完hosts.toml后，必须重启 Containerd：

# 重启服务

systemctl restart containerd

# 验证服务是否正常

systemctl status containerd  # 看到active(running)就对了

2. 验证配置是否好用

用 Containerd 自带的ctr命令拉个镜像试试：

注意：配置ca证书依然可能拉取不了，原因在于ctr有可能不能完全读取配置文件，containerd官方更加推荐使用nerdctl工具来进行命令行操作，此外也可以试试k8s的crictl进行操作，但是它功能较为基础。

# 测试Docker Hub加速（场景1）

ctr image pull docker.io/library/nginx:alpine

# 测试私有Harbor（场景2）

ctr image pull harbor.example.com/my-project/my-app:v1

3. 拉取失败？看日志找问题

如果拉镜像报错，用下面的命令看 Containerd 日志，通常能定位到问题（比如证书错、认证失败）：

journalctl -u containerd -f  # 实时查看日志

六、这些坑千万别踩！

安全红线：生产环境绝对不能把skip_verify设为true！跳过 TLS 验证会导致请求被劫持，泄露镜像或认证信息。
密码安全：别在hosts.toml里写明文密码！用环境变量（如${REG_PASSWORD}）或外部密钥工具（比如 K8s Secrets）。
路径正确：配置文件必须放在/var/lib/containerd/certs.d/<仓库域名>/下，否则 Containerd 找不到！
版本兼容：header自定义请求头这些字段，需要 Containerd 1.4.0 及以上版本，先确认版本：containerd --version。