ubuntu overlay怎么排查错误

在 Ubuntu 上使用 OverlayFS（overlay） 时，常见场景包括：

• Docker 存储驱动（overlay2）
• 手动 mount -t overlay
• 系统启动用的 initramfs / livecd overlay
• Kubernetes / 容器运行时

下面按排查思路 + 常见错误 + 工具命令来说明。

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

mount | grep overlay

或

cat /proc/mounts | grep overlay

常见形式：

• overlay on /var/lib/docker/overlay2/...
• overlay on / type overlay（live 系统）
• 手动挂载的 overlay

二、Overlay 基本原理（排查前必须知道）

Overlay 挂载至少需要：

• lowerdir（只读层，可多个，用 : 分隔）
• upperdir（可写层）
• workdir（临时工作目录，必须和 upperdir 同文件系统）

典型挂载：

mount -t overlay overlay \
  -o lowerdir=/low,upperdir=/up,workdir=/work \
  /merged

三、常见错误与排查方法

1. mount: wrong fs type / options / bad superblock

典型报错：

mount: /merged: mount(2) system call failed: Invalid argument.

✅ 检查点：

# 1. 目录是否存在
ls -ld /low /up /work /merged

# 2. upperdir 和 workdir 是否同文件系统
df -h /up /work

# 3. workdir 是否为空
ls -A /work

❌ 常见错误：

• workdir 非空
• upperdir 和 workdir 不在同一分区
• lowerdir 不存在

2. permission denied

可能原因：

• upperdir 权限不足
• SELinux / AppArmor
• 容器场景下 user namespace

排查：

namei -l /up
ls -ld /up

Docker 场景：

sudo systemctl status docker
journalctl -u docker

3. 文件“消失”或不可见（白障文件）

Overlay 用 whiteout 文件 表示删除：

ls -la /up
# 看到 c--------- 文件

排查：

find /up -type c

说明：

• lowerdir 有文件
• upperdir 有 whiteout → 看起来像删除了

4. Docker overlay2 报错

常见：

failed to mount overlay: invalid argument

排查步骤：

# Docker 存储驱动
docker info | grep Storage

# 内核支持
cat /proc/filesystems | grep overlay

# 检查 overlay2 目录
ls /var/lib/docker/overlay2

修复示例：

sudo systemctl stop docker
sudo rm -rf /var/lib/docker/overlay2
sudo systemctl start docker

（⚠️ 会删除容器数据，仅测试环境）

5. dmesg / 内核日志（非常重要）

dmesg | tail -n 50

Overlay 错误通常会在这里打印：

overlayfs: upperdir is in-use
overlayfs: workdir and upperdir must be same fs

四、调试与诊断命令汇总

# 查看挂载参数
cat /proc/mounts | grep overlay

# 查看 inode
stat /merged /up /low

# 文件系统类型
df -T

# 内核模块
lsmod | grep overlay
modprobe overlay

五、Live CD / Ubuntu 启动 overlay 问题

如果是启动阶段：

journalctl -b | grep overlay

检查：

• casper 层
• overlayroot
• /etc/overlayroot.conf

六、快速自检清单 ✅

• [ ] lowerdir 存在
• [ ] upperdir 存在且可写
• [ ] workdir 为空
• [ ] upper/work 同文件系统
• [ ] 内核支持 overlay
• [ ] dmesg 无报错

如果你能贴出：

• 具体报错信息
• mount 命令或 Docker 配置
• Ubuntu 版本 & 内核版本

我可以直接帮你定位到具体原因。