镜像已拉取完成，却提示 invalid tar header 或 failed to register layer 怎么办？
本文适用于：
- • 群晖 DSM 自带 Docker、或其它 Docker 20.10.x 较旧补丁版本（如 20.10.3、20.10.6）
- •
docker pull已显示层拉取完成 / Status: Downloaded，但随后报错 - • 日志中出现
archive/tar: invalid tar header、failed to register layer或ApplyLayer exit status 1 - • 典型镜像：较新的 homeassistant/home-assistant、n8nio/n8n 等大体积、多层镜像
- • 需要与「manifest unknown」（清单不存在）区分
重要：多数情况下不是「镜像没拉下来」
镜像层已从 Registry 下载完成，错误发生在本地容器运行时（containerd/overlay2）解压镜像层阶段。轩辕镜像侧拉取链路正常时，你在本机用 docker pull 也能看到各层 Pull complete；问题出在当前 Docker 版本与镜像层打包格式的兼容性。
快速判断流程
docker pull 显示层已下载 / Downloaded ↓ 随后报错 invalid tar header / failed to register layer ↓ 优先怀疑：Docker 版本偏旧 + 新版镜像层格式 ↓ 处理：升级 Docker（推荐）或 换用较旧镜像 tag
下面给出典型错误形态、群晖与 Linux 实测场景，以及升级 Docker / 降级镜像版本的可行做法。
错误示例
形态一：Synology（群晖）Docker 拉取 Home Assistant
环境示例：DSM 7.1.1，Docker 套件版本 20.10.3-1308。通过专属域名拉取镜像后，在「映像」界面导入或拉取时出现：
形态二：拉取 n8n 等新版本镜像（Linux 等）
环境示例：Docker 20.10.6，CentOS 7（内核 3.10 等较老环境）。拉取 n8nio/n8n:2.5.0 时，下载完成后解压阶段报错：
原因说明
较新的官方镜像往往层数多、打包方式随上游构建链更新。部分旧补丁版本的 Docker（尤其 20.10.3、20.10.6 等早期 20.10 小版本）在本地 ApplyLayer时与某些层格式存在已知兼容性问题，会在解压阶段抛出 invalid tar header，与镜像是否从加速源成功拉取无关。
我们已在服务端验证：同一镜像在支持的客户端上 docker pull 可完整拉取；若你仅在特定设备解压失败，请优先从本机 Docker 版本与镜像 tag两侧排查。
推荐处理步骤
步骤 1：确认当前 Docker 与内核
在终端执行：
关注 Server Version、Kernel Version。群晖用户可在「套件中心」或官方说明中查看当前 Docker 套件版本是否可升级。
步骤 2：升级 Docker（推荐）
在可升级的前提下，将 Docker 提升至较新的 20.10 补丁版本（社区经验上 20.10.10 及以上）或更高主版本，可缓解部分解压兼容性问题。群晖请以 Synology 官方提供的 Docker 套件更新为准。
Linux 服务器可参考：
Linux Docker 安装与升级教程步骤 3：暂时无法升级 Docker 时——降级镜像版本
若设备无法升级 Docker（例如群晖套件长期停留在 20.10.3），可改用维护周期内较旧、体积与层结构更保守的 tag，例如：
- • Home Assistant：避免使用与当前套件不兼容的
stable/ 最新线，改查上游文档或 Docker Hub 上较旧且仍受支持的标签。 - • n8n：若
2.5.0解压失败，可尝试2.0.x等上一稳定线（如2.0.1），待环境升级后再试新版本。
拉取命令仍使用你的专属域名或 docker.xuanyuan.run 前缀，仅替换镜像 tag。
总结：出现 invalid tar header / failed to register layer 且拉取日志显示层已下载时，请按升级 Docker / 降级镜像版本处理，并与「清单不存在」类错误区分。若仍无法判断，可携带 docker info 与完整报错提交工单。
你可能还会遇到：
- • 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 镜像高效稳定拉取服务
内容基于轩辕镜像真实用户使用与实测整理