镜像已拉取完成，却提示 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 pull 提示 manifest unknown 怎么办？
- • docker pull 提示 no matching manifest 怎么办？
- • Docker pull 时 HTTPS / TLS 证书验证失败怎么办？
- • Docker pull 时 DNS 解析超时或连不上仓库怎么办？
- • Docker 拉取出现 410 Gone 怎么办？
- • 出现 402 或「流量用尽」提示怎么办？
- • Docker 拉取提示 UNAUTHORIZED（401）怎么办？
- • 遇到 429 Too Many Requests（请求太频繁）怎么办？
- • docker login 提示 Cannot autolaunch D-Bus，还算登录成功吗？
- • 为什么会出现「单层超过 20GB」或 413，无法加速拉取？
本文由「轩辕镜像」维护
轩辕镜像 | Docker 镜像高效稳定拉取服务
内容基于轩辕镜像真实用户使用与实测整理