Docker 镜像层损坏 file corrupt 速查：拉取中断、overlay 修复与重拉重建

更新时间：2026-10-24。FAQ 速查页，面向 docker pull 卡在半途、解压层时报 file corrupt、或容器起不来提示层文件缺失的同学。镜像层损坏的本质是「分层文件系统 × 内容寻址校验」链条上某一环对不上：层是按 digest（内容摘要）寻址的 tar 包，下载中断会得到截断的层，磁盘抖动会改写本地 overlay 里的层文件，registry 侧的层被覆盖会让客户端缓存与服务端不一致。病因收敛在六根轴上：拉取中断导致层不完整、digest 校验失败、本地 overlay2 目录文件损坏、graph driver 元数据错乱、registry 服务端层不一致、磁盘满写入截断。顺一遍基本必中。如果是拉取被限流而不是层损坏，转 Docker 拉取限流速查。

本文要回答的问题

• unexpected EOF 或 file corrupt 是网络问题还是镜像本身坏了？
• 重试 docker pull 为什么总是从同一个层失败，缓存是不是帮倒忙？
• layer verification failed 的 digest 校验在防什么，能绕过吗？
• 本机 overlay2 目录里的层文件坏了，能不能只修一个层？
• 私有 registry 推上去的镜像，别人拉就报损坏，是谁的问题？

一、报错原文与典型现象

层损坏的报错分散在三处：拉取阶段、解压阶段、运行阶段（registry 一律以 registry.example.com 占位，路径以 /proj/demo 占位）：

# 拉取/解压阶段：层数据流被截断
failed to register layer: unexpected EOF
# 或
rpc error: code = Unknown desc = file corrupt

# digest 校验失败：下载内容与原摘要不一致
filesystem layer verification failed for digest
sha256:9f86d0...8a1b2c

# 运行阶段：overlay 挂载时发现层文件缺失
error creating overlay mount to /var/lib/docker/overlay2/<id>/merged:
no such file or directory

读现象先分三段：下载途中 unexpected EOF 多为传输截断；verification failed 是内容对不上摘要，比截断更严重；运行期才报的 no such file or directory 说明拉取当时是「成功」的，坏的是本地已经落盘的 overlay 层。三段修法不同，先定性。

二、病因处置速查表

报错现象 / 场景	可能原因	快速验证	处置
pull 解压时报 unexpected EOF	网络中断，层 tar 流被截断	重 pull 观察是否总在同一层断	清该层缓存后重拉；换稳定网络/代理
file corrupt 反复出现在同一层	本地缓存的损坏层被反复复用	docker system df 看缓存占用	docker rmi 删掉镜像再 pull
layer verification failed	下载内容 digest 与原摘要不符	对比 registry 端 manifest 摘要	不绕过校验；让推送方重新推送该层
运行时报 overlay 层文件缺失	本地 overlay2 目录被误删/磁盘坏块	对照 image inspect 的层列表找缺失	删镜像重拉，不做手工修补
私有 registry 推完别人拉就坏	推送中断产生不完整 blob 被引用	registry 侧查 blob 与实际大小	重推镜像；registry 开垃圾回收清理孤儿 blob
拉取与构建频繁截断	磁盘满，写入层时被截断	df -h 看 /var/lib/docker 所在盘	清理磁盘与 docker system prune 后重试

三、排查决策图

下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。

读这张图抓分水岭：报错出现在哪一段决定走哪支——下载/解压段的 unexpected EOF 走左支重拉验证断点是否固定；verification failed 走右支对摘要，那是内容被改写的信号，重拉解决不了就轮到推送方重推。运行期才爆的缺层，一律删镜像重拉，别去手工补文件。

四、逐条排查展开

下载截断是最常见、也最容易误诊的一条。 unexpected EOF 的字面意思是 tar 流读到一半没了：网络抖动、代理超时、registry 限流都可能造成。误诊点在于 Docker 会复用已下载的层——损坏的半截层一旦进了本地缓存，之后每次重试都从这层继续报错，看起来「怎么重试都没用」。处置：docker images 找到该镜像，docker rmi 删掉（连带清掉坏层），再重新 pull；网络不稳的环境配镜像加速器或重试次数更大的代理。

digest 校验失败不要想着绕过。 镜像层是内容寻址的：每个层的 digest 就是它内容的摘要，客户端下载完会重新算一遍，对不上就拒收。verification failed 意味着「我下载到的东西不是推送者发布的东西」——可能是传输中被中间设备改写，也可能是 registry 侧 blob 本身就被覆盖过。正确处置是让推送方重新构建推送，或换一个 tag 重推；绕过校验等于主动引入一个不可信的层，供应链安全上是大忌。

本地 overlay 层损坏只删不修。 运行期报 overlay2/<id>/merged: no such file or directory，常见成因是有人手工进 /var/lib/docker 目录「清理空间」、或磁盘出现坏块。overlay2 的层之间有严格引用关系，手工补一个文件进去几乎不可能恢复一致性，反而会让 graph driver 的元数据更乱。标准处置：docker rm 掉相关容器 → docker rmi 删镜像 → 重新 pull。若大面积层损坏，怀疑文件系统层面问题，先 dmesg 看磁盘报错，必要时备份后重建整个 /var/lib/docker。

registry 一致性：推一半也是坏。 私有 registry（如 registry.example.com 上的 Harbor 或 distribution）在推送中断时，可能留下「manifest 引用了但 blob 不完整」的半成品。之后任何人拉这个 tag 都会在固定层失败。处置：推送方重推（同名 tag 覆盖即可），registry 侧跑垃圾回收清理孤儿 blob；有能力的团队给 CI 推送步骤加「推完立刻 pull 回验」的闭环。

磁盘满是隐形截断手。 /var/lib/docker 所在分区写满时，层写入被静默截断，报错的措辞千奇百怪。df -h 一眼就能确认，配合 docker system df 看 Docker 自身占用，docker system prune 清理悬挂层与停止的容器。把磁盘水位监控接进告警，比事后排查省事得多。

重拉之前的两个判断能省一半时间。 一是断点是否固定：重试两三次，若总在同一个层、同一个百分比断，本地缓存坏层或 registry 半成品 blob 的嫌疑大，直接删镜像重拉；若断点随机漂移，多为网络质量，先换通道再拉。二是是否全员中招：同一 registry 上的同一 tag，只有某台机器拉坏是本地问题，所有机器都拉坏是 registry 或推送侧问题——这个二分直接决定工单开给谁。另外注意 containerd 作为运行时的集群节点与 dockerd 的本地缓存是两套体系，在一侧清缓存不影响另一侧，别搞混了战场。

五、规范做法与预防

• 拉取/推送加回验闭环：CI 推完镜像立刻在干净环境 pull 一次并启动冒烟，坏镜像不出门。
• 磁盘水位监控：/var/lib/docker 分区超过八成即告警，定期 docker system prune 进定时任务。
• 不可靠网络配加速器：跨境或弱网环境一律走镜像加速/registry 代理，减少长连接截断概率。
• registry 垃圾回收常态化：推送中断产生的孤儿 blob 定期回收，避免半成品被引用。
• 禁止手工动 /var/lib/docker：清理空间只用 docker 命令，overlay2 目录是只读黑盒。
• tag 不可变纪律：release 镜像用不可变 tag，坏了重推新 tag，杜绝「同名不同内容」的一致性灾难。

这一篇在知识体系里的位置

本篇是 Docker 排错速查簇的镜像完整性入口篇，定位「层数据可信」：拉得动但被限流卡住看 Docker 拉取限流速查；镜像拉下来了但磁盘写不进看 Docker 磁盘写满速查；层完整但容器起不来崩在运行期看 Docker 容器崩溃速查。「报错定段 → 下载段重拉、校验段对摘要、运行段删了重拉」这条主线对一切层完整性报错通用。

一句话总结

Docker 镜像层损坏先按报错出现的位置定段：下载/解压段的 unexpected EOF 多为传输截断，删镜像清缓存重拉、换稳定网络可解；verification failed 是内容对不上摘要，绝不能绕过校验，要让推送方重推并让 registry 回收半成品 blob；运行期才报的 overlay 层缺失说明坏在本地落盘层，一律 docker rmi 重拉，绝不手工补 /var/lib/docker 里的文件。磁盘满是隐形截断手，水位监控和定期 prune 是最便宜的预防；CI 推送加「推完回拉验证」闭环，坏镜像根本出不了门。