如何排查centos overlay配置错误

CentOS 上排查 Overlay 配置错误的实用流程

一 快速定位思路

• 明确场景：是直接使用 OverlayFS 挂载，还是在 Docker 使用 overlay2 存储驱动。
• 分层检查：先看 内核与模块，再看 底层文件系统 d_type，随后核对 挂载参数与目录权限，最后查看 日志与资源。
• 最小化复现：用最简命令或最小化容器验证，逐步排除配置与环境因素。

二 内核与模块检查

• 检查内核是否支持 OverlayFS：在 CentOS 7 上建议使用 3.10.0-514 及以上内核以获得较好的 overlay2 支持；执行 uname -r 查看版本。
• 确认模块已加载：执行 lsmod | grep overlay，若未加载，可启用开机加载：
  • 创建文件：/etc/modules-load.d/overlay.conf，内容为 overlay，然后 systemctl restart systemd-modules-load 或重启。
• 注意区分：容器网络中的 “overlay 网络” 与文件系统 “OverlayFS” 不是同一概念，网络问题请先确认是否误把网络问题当作文件系统问题。

三 底层文件系统与 Docker 存储驱动

• 检查底层文件系统是否支持 d_type（OverlayFS 强依赖）：
  • 若使用 XFS：执行 xfs_info /var/lib/docker | grep ftype，应看到 ftype=1；若为 0，需重新格式化：mkfs.xfs -n ftype=1 /dev/your_device（操作前务必备份数据）。
• 核对 Docker 存储驱动：
  • 查看：docker info | grep -i 'storage driver'，推荐为 overlay2。
  • 配置：编辑 /etc/docker/daemon.json
    • 示例：{ "storage-driver": "overlay2" }（仅在确认内核与文件系统均满足时设置）。
  • 重启：systemctl restart docker 并再次核对。
• 如仅为验证或临时绕过内核检查（不建议生产）：可在 daemon.json 中加入 "storage-opts": ["overlay2.override_kernel_check=true"]，验证通过后应移除该选项并恢复合规配置。

四 OverlayFS 挂载与权限排查

• 核对 /etc/fstab 或手工 mount 的挂载选项：
  • 示例：overlay /mnt/overlay overlay defaults,lowerdir=/lower,upperdir=/upper,workdir=/work 0 0
  • 要点：lowerdir、upperdir、workdir 必须存在且可访问，且 workdir 必须是空目录。
• 检查目录权限与属主：确保参与挂载的目录对相应用户/进程可读写（如 ls -ld /lower /upper /work）。
• 查看是否已挂载及参数是否正确：mount | grep overlay。
• 资源与一致性：
  • 空间：df -h 检查 可用空间 与 inode 是否充足。
  • 健康：如怀疑底层文件系统异常，先卸载相关挂载后执行 fsck 修复，再重新挂载。
• 故障处置：修正参数或修复后执行 mount -o remount /mnt/overlay 或重新 mount。

五 日志与常见错误速查

• 日志定位：
  • 系统日志：journalctl -xe、grep -i overlay /var/log/messages 或 /var/log/syslog，关注挂载失败、权限拒绝、找不到目录等关键报错。
• 常见错误与处理要点：
  • 存储驱动不兼容或目录非空：Docker 初始化 graphdriver 失败，确认 /var/lib/docker 所在文件系统为 XFS ftype=1，清理或迁移后重启 Docker。
  • SELinux 拒绝：可临时 setenforce 0 验证，若解决请用 semanage fcontext/restorecon 做最小权限策略放行，而非长期关闭 SELinux。
  • 模块未加载：lsmod | grep overlay 无输出时，按上文启用 overlay 模块加载。
  • 挂载参数错误：提示 lowerdir/workdir 不存在或参数非法时，核对目录路径、权限与 fstab 选项拼写。
  • 空间不足：镜像/容器层写入失败或只读，先 df -h 清理不必要数据再重试。