如何调试ubuntu overlay

调试 Ubuntu 下的 OverlayFS（overlay） 通常出现在这些场景：

• Docker / containerd 使用 overlay2 存储驱动
• 手动 mount -t overlay 做根文件系统合并
• Live CD / 系统恢复 / 只读根文件系统 + 可写层

下面按常见问题 → 排查方法 → 实用命令来讲。

一、先确认你用的是哪种 overlay

1. 查看挂载情况

mount | grep overlay
cat /proc/mounts | grep overlay

典型 Docker：

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

2. 查看 overlay 参数

cat /proc/mounts | grep overlay

重点关注：

• lowerdir
• upperdir
• workdir
• index=off（有时是坑）

二、最常见问题及调试方法

问题 1：overlay 挂载失败（mount: invalid argument）

✅ 检查 4 个目录是否存在：

ls -ld lowerdir upperdir workdir merged

⚠️ 要求：

• upperdir 和 workdir 必须在同一文件系统
• workdir 不能是被挂载点本身
• lowerdir 可以是多个，用 : 分隔

✅ 正确示例：

mount -t overlay overlay \
  -o lowerdir=/lower,upperdir=/upper,workdir=/work \
  /merged

问题 2：修改文件没生效 / 文件“消失”

原因通常是：

• 文件在 lowerdir 是只读
• 实际写入到了 upperdir

✅ 排查：

ls -l /upper/somefile
ls -l /lower/somefile

✅ 查看白障文件（whiteout）：

ls -l /upper/somefile  # 如果是 c 字符设备 0,0，说明被删除

问题 3：Docker overlay2 性能差 / 报错

✅ 确认文件系统支持：

df -T /var/lib/docker

推荐：

• ext4
• xfs（开启 ftype=1）

❌ 不支持：

• overlay on overlay
• NFS / CIFS 做 upperdir

✅ 检查 xfs 是否支持：

xfs_info / | grep ftype

应为：

ftype=1

问题 4：inode 用尽（Docker 常见）

✅ 查看 inode：

df -i /var/lib/docker

✅ 清理：

docker system prune -a

三、调试技巧（非常实用）

1. 打开内核调试信息

dmesg | tail

overlay 报错一般会在这里。

2. 使用 strace 看 mount 失败原因

strace mount -t overlay overlay -o ... /merged

3. 手动模拟 Docker overlay

mkdir -p /tmp/{lower,upper,work,merged}
echo hello > /tmp/lower/a
mount -t overlay overlay \
  -o lowerdir=/tmp/lower,upperdir=/tmp/upper,workdir=/tmp/work \
  /tmp/merged

四、Docker 专项调试

查看存储驱动

docker info | grep -i storage

查看容器 overlay 路径

docker inspect <容器> | grep MergedDir

直接进入 merged 目录

cd /var/lib/docker/overlay2/<id>/merged

五、常见坑总结

如果你能告诉我：

• 是 Docker 还是 手工 overlay
• Ubuntu 版本
• 具体报错信息

我可以直接帮你定位并给出命令级解决方案。