让 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
2配置文件路径（v1.x）
containerd 的默认配置文件为：
/etc/containerd/config.toml
如未生成此文件，可使用以下命令初始化默认配置：
containerd config default > /etc/containerd/config.toml
3镜像源配置示例（v1.x）
请在 config.toml 中添加以下配置（位于 plugins."io.containerd.grpc.v1.cri".registry.mirrors 节点）：
💡重要提示：请将配置中的 *** 替换为您的专属域名前缀。例如，如果您的专属域名为 123abc.xuanyuan.run，则应将 *** 替换为 123abc。
说明：多个 endpoint 可按优先级排列，containerd 会依次尝试，直到成功。
最佳实践：docker.io 的配置中，我们添加了 https://registry-1.docker.io 作为 fallback endpoint。这样即使专属域名配置有误或不可用，containerd 仍可回退到官方源，确保服务不会中断。
注意：以上配置已包含常用镜像仓库，如果您的项目使用其他镜像仓库，请参考上述格式自行添加配置。
扩展配置示例：
4TLS 注意事项（v1.x）
如果因偶发情况触发证书验证失败。可使用以下配置忽略 TLS 校验：
[plugins."io.containerd.grpc.v1.cri".registry.configs."***.xuanyuan.run".tls] insecure_skip_verify = true
可针对不同域名分别设置。
5应用配置（v1.x）
配置修改完成后，需重启 containerd：
sudo systemctl restart containerd
建议重启后使用 journalctl -u containerd -f 观察是否有报错信息。
6验证配置是否生效（v1.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访问体验非常流畅，大镜像也能快速完成下载。"