linux overlay常见错误有哪些

Linux 的 OverlayFS（overlay） 常用于容器（Docker、Kubernetes）、Live CD、只读根文件系统等场景。下面按常见错误类型 + 原因 + 解决办法来梳理。

一、挂载相关错误

1. mount: wrong fs type, bad option, bad superblock

原因

• 内核未开启 OverlayFS 支持
• 挂载参数写错（lowerdir / upperdir / workdir）
• workdir 和 upperdir 在同一文件系统但配置不当

排查

cat /proc/filesystems | grep overlay

没有输出说明内核不支持。

解决

• 使用支持 overlay 的内核（≥3.18，推荐 ≥4.×）
• 检查挂载命令：

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

2. workdir and upperdir must be on same filesystem

原因

• upperdir 和 workdir 不在同一个文件系统

解决

df -h /upper /work

确保二者同盘同文件系统。

3. lowerdir is not a directory / upperdir must be empty

原因

• lowerdir 不存在或不是目录
• upperdir 非空（首次挂载必须为空）

解决

mkdir -p /upper /work /lower

upperdir 和 workdir 必须为空目录。

二、权限与 SELinux 问题

4. Permission denied

常见原因

• upperdir / workdir 权限不足
• SELinux 阻止（常见于 RHEL/CentOS）

解决

chmod 700 /upper /work

SELinux：

setenforce 0
# 或加 context
semanage fcontext -a -e /var/lib/docker /upper

三、容器场景（Docker / Kubernetes）

5. Docker 启动失败：overlay2: the backing xfs filesystem is formatted without d_type support

原因

• XFS 文件系统未开启 ftype=1

检查

xfs_info /var/lib/docker | grep ftype

应为 ftype=1

解决

• 重新格式化磁盘：

mkfs.xfs -n ftype=1 /dev/sdX

6. could not find any free loop device

原因

• overlay 上层使用 loop 设备过多
• Docker 存储驱动配置错误

解决

losetup -a

减少 loop 使用或调整 Docker storage driver。

7. Docker 报 overlay2: no such file or directory

原因

• 容器层损坏
• 被手动删除 overlay 目录

解决

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

（会丢失容器数据）

四、写时复制（CoW）与文件问题

8. 文件修改未生效 / 修改后消失

原因

• 修改的是 lowerdir（只读层）
• 上层覆盖未正确挂载

解决

• 确认修改发生在 merged 目录
• 检查 mount 点：

mount | grep overlay

9. 删除文件后仍在 lowerdir

原因

• overlay 删除只在上层创建 whiteout 文件
• lowerdir 本身不可写

说明 这是正常行为，不是错误。

五、内核 / 性能问题

10. 内核 BUG / 崩溃（老内核）

表现

• overlay 死锁
• rename 失败

解决

• 升级内核
• 避免 overlay 上使用某些 fs（如 NFS 作 lower）

六、典型正确挂载示例

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

七、快速排查清单

uname -r
cat /proc/filesystems | grep overlay
mount | grep overlay
df -h
xfs_info /var/lib/docker | grep ftype

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

• 是 Docker / K8s / 手动挂载
• 具体 错误日志
• 内核版本

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