让 AI 帮你使用轩辕镜像？ · 展开查看说明 · 点击收起说明
如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。
只需在 AI 对话中先发送下面这句话即可：
请先完整阅读并严格遵守以下文档中的全部规则与要求：
https://xuanyuan.cloud/agents.md
在未充分阅读并理解该文档前，不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。查看 agents.md 用法指南与完整示范。国内用户首推 元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。 若 AI 无法访问外链，可 打开说明文档 复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。
Containerd Docker 镜像源配置教程
教程简介
适用场景
1适用版本
本手册适用于以下 containerd 版本，请先确认您的版本：
| 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 配置文件的目录路径：
⚠️重要：此配置是必需的，否则 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 为例：
⚠️重要提示：对于 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）：
gcr.io 的配置（文件路径：/etc/containerd/certs.d/gcr.io/hosts.toml）：
注意：对于其他镜像仓库（如 registry.k8s.io、ghcr.io、mcr.microsoft.io 等），请按照相同的方式创建对应的目录和 hosts.toml 文件，并修改 server 和 host 字段为对应的仓库地址和您的专属域名。
5TLS 配置（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常见问题
- config.toml 配置无效或路径错误
- config.toml 配置中没有配置对应的仓库
- 专属域名没有流量
- 确认文件路径和语法，或重建配置文件
- journalctl -u containerd -f 观察报错信息，看看具体是哪个仓库链接不上，配置到 config.toml 中
- 前往充值页面充值流量包
- hosts.toml 文件路径错误或不存在
- hosts.toml 配置语法错误
- 未为对应的镜像仓库创建 hosts.toml 文件
- 使用了错误的配置方式（v2.x 不能使用 v1.x 的 config.toml 配置）
- 确认 hosts.toml 文件路径正确
- 检查 hosts.toml 文件语法是否正确
- 为每个需要访问的镜像仓库创建对应的目录和 hosts.toml 文件
- 确认使用的是 v2.x 配置方式，参考上方的 v2.x 配置指南
- 使用了 v1.x 的 config.toml 配置方式（v2.x 不支持）
- hosts.toml 文件路径或格式错误
- 确认 containerd 版本，v2.x 必须使用 hosts.toml 配置
- 参考上方的 v2.x 配置指南重新配置
镜像拉取常见问题
功能
错误码
用户好评
来自真实用户的反馈，见证轩辕镜像的优质服务
oldzhang
运维工程师
Linux服务器
"Docker访问体验非常流畅，大镜像也能快速完成下载。"