怎样排查linux overlay故障

在 Linux 中，Overlay（overlayfs）常用于容器（Docker、Kubernetes）、Live CD、只读根文件系统等场景。排查 overlay 故障可以从内核、挂载、存储驱动、权限、磁盘、容器层几个方面入手。

下面给你一套系统化的排查思路 + 常用命令。

一、确认是否使用了 overlay

1. 查看挂载情况

mount | grep overlay

或

cat /proc/mounts | grep overlay

示例：

overlay on /var/lib/docker/overlay2/xxx/merged type overlay (rw,relatime,...)

2. 查看 Docker 使用的存储驱动

docker info | grep -i storage

常见：

overlay2（推荐）
overlay（老版本）

二、常见 overlay 故障分类

1️⃣ 挂载失败（mount: overlay failed）

常见原因：

lowerdir / upperdir / workdir 不存在
workdir 和 upperdir 在同一文件系统但配置错误
内核不支持 overlay

排查步骤

dmesg | tail

或

journalctl -k | tail

典型错误：

overlayfs: missing 'lowerdir'
overlayfs: workdir and upperdir must be on same fs
overlayfs: filesystem not supported

检查目录

ls -ld /lower /upper /work /merged

overlay 要求：

upperdir 和 workdir 在同一文件系统
workdir 不能是 upperdir 的子目录

2️⃣ 写文件失败（Read-only / Operation not permitted）

常见原因：

底层是只读镜像（ISO、squashfs）
upperdir 所在磁盘满了
SELinux / 权限问题

检查磁盘

df -h

检查 overlay 是否只读

mount | grep overlay

看到 ro 说明只读。

权限问题

ls -ld /upper /work

需要：

upper/work 可写
进程 UID 有权限

3️⃣ 文件“看不到”或“改了没生效”

overlay 特性：

上层（upper）覆盖下层（lower）
删除文件是 whiteout（c—）

查看 whiteout 文件

ls -la /upper

白文件示例：

c--------- 1 root root 0, 0 whiteout

判断是否被覆盖

stat /merged/file

4️⃣ Docker / Kubernetes 中 overlay 故障

查看容器存储位置

docker inspect <container> | grep -i merged

查看 overlay2 目录

ls /var/lib/docker/overlay2/

容器写不进去

df -h /var/lib/docker

三、内核 & 模块检查

1. 内核是否支持 overlay

cat /proc/filesystems | grep overlay

或

lsmod | grep overlay

2. 手动加载模块

modprobe overlay

3. 内核版本建议

overlay2：≥ 4.0（推荐 ≥ 4.19）

四、手动复现 overlay 挂载（调试神器）

mkdir -p /tmp/lower /tmp/upper /tmp/work /tmp/merged
echo "lower" > /tmp/lower/a.txt
mount -t overlay overlay \
  -o lowerdir=/tmp/lower,upperdir=/tmp/upper,workdir=/tmp/work \
  /tmp/merged

失败立刻看：

dmesg | tail

五、典型问题速查表

现象	可能原因
mount overlay 失败	目录不存在 / workdir 错
容器启动失败	storage-driver 不支持
写文件报错	磁盘满 / 只读
删除文件还在	whiteout 没生效
性能差	多层 overlay / 机械盘

六、建议的最佳实践

✅ 使用 overlay2（不是 overlay）
✅ upper/work 放 SSD
✅ 定期清理 /var/lib/docker
✅ 避免 overlay 嵌套（overlay on overlay）

如果你愿意，可以告诉我：

是 Docker / K8s / 自定义 overlay
具体 报错信息
内核版本

我可以给你针对你环境的精准排查步骤。