如何调试debian overlay配置

在 Debian（以及一般的 Linux 系统）里，“overlay 配置”通常指 OverlayFS（联合文件系统），常用于 Live CD、容器（Docker）、initramfs、或者自定义根文件系统。下面按常见使用场景和调试方法系统说明。

一、确认你用的是哪种 overlay

先明确你在调试哪一种：

Docker / 容器 overlay2
initramfs 中的 overlay（Live 系统）
手动 mount -t overlay
systemd 挂载单元（.mount）
dracut / mkinitcpio 的 overlay

不同场景调试入口不同。

二、通用调试方法（所有 overlay 都适用）

1. 确认内核支持 overlay

cat /proc/filesystems | grep overlay
# 或
lsmod | grep overlay

如果没有：

modprobe overlay

Debian 默认内核已支持。

2. 手动挂载测试（最重要）

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

✅ 成功说明配置逻辑没问题
❌ 失败会直接报错误（见下）

3. 常见挂载错误对照表

错误信息	原因
`mount: wrong fs type`	内核不支持 overlay
`upperdir and workdir must be on same fs`	upper 和 work 不在同一文件系统
`workdir is not empty`	workdir 必须为空
`lowerdir missing`	路径写错或不存在
`permission denied`	SELinux / 权限 / 只读文件系统

三、调试 Live / initramfs overlay（Debian Live）

1. 查看启动参数

cat /proc/cmdline

常见参数：

boot=live union=overlay

2. 查看实际挂载

mount | grep overlay
findmnt -t overlay

3. 调试 initramfs 脚本

Debian Live 使用：

/usr/share/initramfs-tools/scripts/live

重新生成 initramfs：

update-initramfs -u

调试建议：

加 debug 到内核参数
在脚本中加 set -x

四、调试 Docker overlay2

1. 查看存储驱动

docker info | grep Storage

2. 查看 overlay 挂载

mount | grep overlay

路径通常在：

/var/lib/docker/overlay2/xxx/merged

3. 常见问题

/var/lib/docker 在 ext4/xfs 上
不要在 NFS / ZFS / tmpfs 上用 overlay2
磁盘满会导致 overlay 写失败

五、systemd overlay 挂载调试

示例 /etc/systemd/system/root-overlay.mount：

[Unit]
Description=Overlay Root

[Mount]
What=overlay
Where=/mnt/merged
Type=overlay
Options=lowerdir=/mnt/lower,upperdir=/mnt/upper,workdir=/mnt/work

调试：

systemctl status mnt-merged.mount
journalctl -u mnt-merged.mount

⚠️ 注意：

unit 名必须是 路径转义格式
workdir 必须为空

六、调试技巧合集

1. 看内核日志

dmesg | grep overlay

2. 用 strace（高级）

strace -f mount -t overlay overlay -o ... /mnt

3. 检查文件系统类型

df -T /upper /work

upper 和 work 必须同类型且同设备

七、如果你愿意，我可以更具体地帮你

你可以补充：

Debian 版本（cat /etc/debian_version）
使用场景（Live / Docker / 嵌入式 / 自定义 rootfs）
报错信息原文
你的 overlay 配置（mount 命令或 unit 文件）

我可以直接帮你逐行分析配置并定位问题。