让 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 无法访问外链，可打开说明文档复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。

镜像已拉取完成，却提示 invalid tar header 或 failed to register layer 怎么办？

一句话结论

invalid tar header /failed to register layer不是单一故障。最常见是两类：旧 Docker 解压兼容性问题，或把 AI 模型镜像当普通容器镜像执行了 docker pull。

先做 2 步判断（30 秒内）

确认你拉取的是普通容器镜像，还是 AI 模型镜像（路径常含 /ai/）。
若是 AI 模型镜像，优先排查命令是否用错；若是普通容器镜像，再排查 Docker 版本兼容性。

分流流程图

docker pull 后出现 invalid tar header / failed to register layer
  ↓
判断目标对象
  ├─ 普通容器镜像（homeassistant、n8n 等）
  │    → 走“场景 A：Docker 兼容性排查”
  └─ AI 模型镜像（例如 .../ai/qwen3-embedding-vllm:0.6B）
       → 走“场景 B：模型命令与插件排查”

场景 A：普通容器镜像（Docker 兼容性问题）

当镜像是普通容器镜像，且日志已显示层下载完成后才报错，常见根因是旧 Docker（如 20.10.3、20.10.6）在本地 ApplyLayer 解压阶段与新层格式兼容性不足。

处理顺序：先升级 Docker；暂时无法升级时，改用较旧且仍维护的镜像 tag，再观察是否恢复。

场景 B：AI 模型镜像（命令使用错误）

你提供的典型日志如下（已精简）：

docker pull docker.xuanyuan.run/ai/qwen3-embedding-vllm:0.6B ... failed to register layer: archive/tar: invalid tar header

该对象属于 AI 模型镜像，不应直接按普通容器镜像方式使用。请改用：

docker model pull docker.xuanyuan.run/ai/qwen3-embedding-vllm:0.6B

拉取后请通过 Ollama、vLLM、SGLang 等推理程序加载模型。模型标签参考：

https://xuanyuan.cloud/r/ai/qwen3-embedding-vllm/tags

如果出现 docker: unknown command: docker model

这说明当前 Docker 安装未包含 Docker Model / AI 扩展能力。请升级到支持该能力的版本，或安装对应插件后再执行模型拉取命令。

最小排查命令清单

docker --help

docker info

docker version

先用 docker --help 看是否存在model 子命令；再用docker info /docker version 判断版本与运行时环境。

仍无法定位时，工单请附带 4 项信息：完整命令、完整报错、docker version 输出、目标镜像 tags 链接。这样可快速判断属于场景 A 还是场景 B。

若你的报错是 manifest unknown，请改看这篇 FAQ。

你可能还会遇到：

本文由「轩辕镜像」维护
轩辕镜像 | Docker 镜像高效稳定拉取服务
内容基于轩辕镜像真实用户使用与实测整理