让 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 无法访问外链，可 打开说明文档 复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。
为什么会出现「单层超过 20GB」或 413，无法加速拉取？
本文适用于：
- • 拉取镜像时出现 413 或「该镜像存在超过 20GB 的单层」相关报错
- • 镜像体积巨大（几十 GB）、单层特别大的冷门镜像
- • 通过轩辕镜像加速拉取时速度极慢或频繁失败
⚠️ 重要说明
轩辕镜像对镜像总体积不设限，但单层（单分片）超过 20GB 的镜像不在缓存与加速范围内。此类镜像通过加速源拉取容易失败或极慢，建议直接从 Docker Hub 官方源拉取。
常见报错示例：
您好，该镜像存在超过 20GB 的单层，当前不支持加速拉取。请选择其他镜像或联系管理员。参考文档：https://xuanyuan.cloud/faq/413-single-layer-25gb-error
为什么单层过大的镜像不适合走加速？
单层几十 GB 的镜像属于「超大单分片」场景，和普通镜像的拉取逻辑不同：
- 传输易中断：单层文件过大，下载过程中更容易因网络波动中断或失败，一旦失败往往需要重新开始。
- 缓存成本高：加速节点通常不会长期缓存这类冷门、超大分片，多数情况下需要回源拉取，速度难以保证。
- 行业共性：即便在 Docker Hub 官方源拉取，这类镜像也常出现速度慢、中途失败的情况，并非轩辕镜像独有。
推荐做法
✅ 单层超过 20GB 的镜像
建议不要通过轩辕镜像加速域名拉取，改为直接从 Docker Hub 官方源拉取（例如使用原始镜像名 docker.io/命名空间/镜像名:标签）。在官方源拉取时若仍出现速度慢或中途失败，多为镜像体积与网络环境导致，可尝试在网络稳定时段多次重试。
若您经常需要拉取此类超大镜像，可提交工单说明使用场景，我们会根据实际情况给予建议。
总结：镜像总体积不限制，但单层超过 20GB 不在轩辕镜像加速与缓存范围内。遇到 413 或相关提示时，建议改用 Docker Hub 官方源拉取，并在网络稳定时多试几次。
你可能还会遇到：
本文由「轩辕镜像」维护
轩辕镜像 | Docker 镜像高效稳定拉取服务
内容基于轩辕镜像真实用户使用与实测整理