413 错误：单层超过 20GB 的镜像不支持加速拉取
本文适用于：
- • 拉取镜像时出现 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 镜像高效稳定拉取服务
内容基于轩辕镜像真实用户使用与实测整理