OverlayFS 白化文件怎样影响容器层

我第一次认真追踪容器层里的“删除”时，最容易误判的一点是：看到下层目录里还有文件，就以为删除没有生效。OverlayFS 的设计恰好相反——它通常不改写 lowerdir，而是在 upperdir 记录一个白化标记，让合并视图不再返回下层的同名路径。

所以，白化文件影响的是可见性和层叠结果，不是把基础层的原文件直接擦掉。如果你同时在看 OCI 镜像层 tar 和已经挂载的 OverlayFS，上面出现的标记形式还不一样：前者常见的是 .wh.，后者可能是 0/0 字符设备或带 xattr 的零字节文件。

白化文件到底挡住了哪一层

先把三个对象分开：lowerdir 是只读的下层目录，upperdir 保存当前层的新增、修改和删除痕迹，merged view 是应用最终看到的合并目录。当同一个名字同时存在于上下层时，OverlayFS 优先呈现上层对象；当上层出现 whiteout 时，下层同名对象会被忽略，whiteout 自己也不会出现在合并视图中。

这也解释了一个常见现象：删除基础镜像中的大文件，当前层可能只增加一个很小的删除标记，基础层的字节仍然留在镜像历史里。白化文件解决的是“最终根文件系统看不到它”，不是“历史层立刻变小”。

单个文件删除和目录整体遮蔽不是一回事

Linux 内核文档把这两种语义分得很清楚。单个 lower 对象被删除时，upperdir 可以放置 whiteout；如果 upperdir 中的目录被标记为 opaque，那么 lowerdir 中同名目录的内容整体不再合并。目录整体遮蔽会覆盖子目录和后代条目，范围比一个文件名更大。

最后一行很关键：whiteout 不是“任何 rm 都会留下的隐藏文件”。只有删除动作需要继续对下层表达时，白化标记才有意义。

从 OCI 层文件名读回内核标记

容器镜像层通常以 tar changeset 表达文件的新增、修改和删除。OCI Image Spec 规定，删除单个路径时使用空的特殊文件名 .wh.；例如 etc/.wh.config.yml 表示应用这一层时隐藏父层的 etc/config.yml。如果要隐藏一个目录在下层的全部子项，则使用该目录下的 .wh..wh..opq。

这里不能把 tar 里的白化文件当作普通文件直接解压。层应用器要识别它的特殊名字，再对父层执行“隐藏”语义；白化文件本身最终也必须不可见。OCI 规范还特别说明，whiteout 只作用于 lower/parent layers，同层后来出现的普通文件不能被同层白化文件反向隐藏。

映射到 Linux OverlayFS 时，内核支持的表示包括 0/0 字符设备，以及带 trusted.overlay.whiteout xattr 的零字节普通文件。目录整体遮蔽则使用 trusted.overlay.opaque=y。这就是为什么你从镜像 tar 里看到的是点号文件名，而在运行时上层目录里看到的可能是设备节点或扩展属性。

排查时先确认“层”和“范围”

我在排查这类问题时，会先把“看不到”拆成两个问题：目标路径原本来自哪一层，当前标记作用于单个名字还是整个目录。不要先假设白化文件等同于普通的空文件，也不要只在 merged view 中搜索它——正确的标记本来就应该被合并视图隐藏。

# 查看挂载目标和 lowerdir、upperdir、workdir 的关系
findmnt -t overlay -o TARGET,FSTYPE,OPTIONS

# 在已取得权限且文件系统支持 xattr 时，查看上层目录的 OverlayFS 标记
getfattr -R -m 'trusted\.overlay\.(whiteout|opaque)' -d /path/to/upperdir

# 查找可能的 0/0 字符设备；这里只用于定位候选项，不把所有字符设备都当成白化文件
find /path/to/upperdir -type c -print

这些命令的用途是建立“路径归属—标记范围—合并结果”的对应关系，不是直接证明某个容器运行时一定采用了某一种内部布局。不同运行时和存储驱动可能负责把 OCI 层格式转换成不同的上层表示，因此取证时要同时说明你查看的是 tar 层、upperdir 还是 merged view。

最容易踩的三个判断坑

把 whiteout 当成可以清理的垃圾文件

在 upperdir 或镜像层 changeset 中，白化标记承担的是删除语义。随意删除它，可能让 lowerdir 的原路径重新出现在合并结果中。只有在你明确重建层、改变父层关系并同步更新索引时，才有理由处理这些标记。

看到基础层文件还在，就认为删除失败

基础层是不可变历史的一部分，保留原文件并不矛盾。要判断删除是否生效，应观察层应用后的 merged view 或按 OCI 规则解释 changeset，而不是直接把 lowerdir 的目录列表当成最终根文件系统。

用单文件白化推断目录整体已清空

.wh.config.yml 只指向一个名字；.wh..wh..opq 才表达同一目录下层子项整体不参与合并。两者的影响范围不同，排障记录中应把“目标路径”和“目录边界”一起写清楚。

给迁移和打包流程留下的清单

1. 先标明正在看的对象是 OCI layer tar、OverlayFS upperdir，还是 merged view。
2. 单路径删除使用与目标 basename 对应的 whiteout，目录整体遮蔽使用 opaque 语义，不要混用。
3. 确认白化标记只是在遮蔽 lower/parent layer，而不是误以为它会清除历史层数据。
4. 重打包或搬迁层时保留 whiteout 的特殊语义，不能把 .wh.* 当成普通配置文件发布。
5. 复查时同时检查标记范围和最终合并视图，避免只看某个底层目录就下结论。

一句话总结：OverlayFS 白化文件是“对下层路径的否定记录”。在 OCI 层里，它以特殊 tar 文件名表达删除范围；在 Linux upperdir 里，它以 whiteout 或 opaque xattr 表达合并规则。理解这条转换链，就能解释为什么原文件还在基础层、但容器里已经看不到它。

相关问题

白化文件会让镜像体积立刻变小吗？

不会。它主要改变最终视图，历史层中的原始数据仍可能占据镜像存储；体积是否减少取决于后续的层组织、重建和清理策略。

为什么在 merged view 中找不到 whiteout？

因为 whiteout 的职责就是隐藏下层同名路径和自身。需要分析标记时，应查看对应的 OCI 层 changeset 或 upperdir，而不是只搜索合并目录。

.wh..wh..opq 能只删除目录中的一个子目录吗？

不能。它表达的是同名目录的子项整体不再从下层合并；只删除一个子目录时应使用对应 basename 的显式 whiteout。

资料来源

Linux 内核文档：https://kernel.org/doc/html/latest/filesystems/overlayfs.html

OCI Image Spec Layer：https://github.com/opencontainers/image-spec/blob/main/layer.md