Overlay配置中常见的错误有哪些

Overlay配置常见错误与排查要点

一 存储驱动 OverlayFS 的常见错误

• 内核或模块问题：未加载 overlay 内核模块或内核版本过低（如 CentOS 7 要求 ≥ 3.10.0-514）。处理：执行 lsmod | grep overlay 检查，必要时在 /etc/modules-load.d/overlay.conf 写入 overlay 并重启。
• 文件系统与 d_type：使用 XFS 时未启用 ftype=1，会导致 Docker 无法使用 overlay2。处理：xfs_info /var/lib/docker | grep ftype 验证，若为 ftype=0 需备份后按 -n ftype=1 重新格式化。
• 挂载参数错误：lowerdir/upperdir/workdir 路径不存在、顺序错误或权限不足。处理：核对目录存在且可访问，必要时修正权限或以正确用户执行。
• 配置与版本不兼容：在 /etc/docker/daemon.json 中错误使用或不兼容的选项（如随意设置 overlay2.override_kernel_check）。处理：优先使用默认配置，确需覆盖时仅在特定版本按官方指引设置，变更后重启 Docker。
• 空间与 Inode 耗尽：/var/lib/docker/overlay2 所在分区空间或 Inode 用尽。处理：df -h、df -i 检查，清理无用镜像/容器/卷（如 docker system prune -a）。
• 日志与诊断：忽视系统日志导致难以定位。处理：查看 /var/log/syslog、journalctl -xe 与 docker info、dockerd 日志。

二 Docker Swarm Overlay 网络的常见错误

• 端口未放行：未开放 TCP 2377（集群管理）、TCP/UDP 7946（节点发现）、UDP 4789（VXLAN 数据面）。处理：在防火墙/安全组放行上述端口（示例：ufw allow 2377/tcp 等）。
• 网络未正确创建或驱动不匹配：未以 --driver overlay 创建网络，或服务未加入同一网络。处理：docker network create --driver overlay <name>，docker service create --network <name> ...。
• 节点与引擎状态异常：Docker 服务未运行、节点 NotReady、或网络插件异常。处理：systemctl status docker、docker network ls、kubectl get nodes（K8s 场景）排查。
• 连通性验证缺失：未在服务间做实际连通性测试。处理：在同一 Overlay 网络中创建服务并用 ping/curl 验证，或 docker service logs 查看错误。

三 容器运行时与权限的常见错误

• SELinux 限制：SELinux enforcing 可能阻止 Overlay 挂载点创建或写入。处理：优先调整策略（如 setsebool -P docker_overlay2_rw 1），临时排障可用 setenforce 0，不建议长期关闭。
• 权限与属主：挂载点或工作目录属主/权限不当导致容器读写失败。处理：用 chown/chmod 统一属主与权限，确保运行 Docker 的用户具备必要权限。
• 配置文件语法错误：/etc/docker/daemon.json、docker-compose.yml、K8s 清单等存在语法或字段错误。处理：使用 JSON/YAML 校验工具，核对字段名与缩进。
• 节点与网络插件：集群节点未就绪、网络插件未启用或异常。处理：确认 kubelet/kube-proxy 正常，必要时重装/启用相应网络插件。

四 容易混淆的非 OverlayFS 配置错误

• 前端开发 devServer 的 overlay 选项：在 Vue CLI/webpack-dev-server 的 devServer.overlay 并非所有版本都支持，错误配置会触发 ValidationError。处理：升级到支持该选项的版本，或移除/注释该字段。

五 快速排查清单

• 环境核对：内核 ≥ 3.10.0-514；lsmod | grep overlay；uname -r。
• 文件系统：XFS 且 ftype=1；xfs_info /var/lib/docker | grep ftype。
• 资源与权限：df -h、df -i；目录存在且权限正确。
• 配置与日志：/etc/docker/daemon.json 合法；journalctl -xe、/var/log/syslog、docker info。
• Swarm 网络：端口 2377/TCP、7946/TCP/UDP、4789/UDP 放行；docker network ls/inspect；服务连通性测试。