UnionFS不支持直接写入只读层，挂载持久化卷时若与镜像层路径重叠或挂载顺序冲突，会导致启动失败、文件不可见或写入丢弃；需隔离路径、明确挂载优先级、调整传播模式或改用其他存储驱动。
UnionFS 本身不支持直接写入底层只读层，当容器使用 UnionFS 作为存储驱动（如 aufs、overlay2）并挂载了持久化数据卷（如 bind mount 或 volume）时，若卷路径与 UnionFS 的镜像层路径发生重叠或权限/挂载顺序冲突，会导致容器启动失败、文件不可见、写入静默丢弃等问题。关键在于明确挂载优先级、隔离路径空间、避免层间覆盖。
确认挂载层级与冲突点
运行 mount | grep $(docker info | grep "Docker Root Dir" | awk '{print $4}') 查看实际挂载树，重点关注 overlay2 的 merged、upper、work 和 volumes 的 bind 挂载是否出现在同一父目录下。常见冲突场景包括：
- 容器内将宿主机目录 /data/app 以 bind mount 方式挂载到 /app，而镜像中 /app 已由 UnionFS 提供（含默认配置文件）；
- 使用 named volume 并指定 --mount source=myvol,target=/config，但 Docker daemon 配置的 data-root 下恰好存在同名子路径被 UnionFS 自动管理。
规避路径重叠：强制分离挂载目标
确保持久化卷挂载点与镜像层内容路径无交集：
- 不要将 volume 或 bind mount 目标设为镜像中已存在的非空目录（如 /etc、/usr/bin），优先选择镜像中为空或专用于挂载的路径（如 /mnt/data、/var/lib/myapp）；
- 构建镜像时，在 Dockerfile 中用 VOLUME 显式声明挂载点，并保持该路径下无初始文件（仅 mkdir，不 COPY）；
- 对已有镜像，可通过 docker run -v /host/path:/mnt/external:rw 绕过原路径，再在容器内用符号链接或启动脚本映射逻辑路径。
调整挂载顺序与传播模式
Bind mount 默认为 rprivate，可能被 UnionFS 层遮蔽。需显式设置挂载传播以确保可见性：
- 启动容器时添加 --mount type=bind,source=/host/data,target=/app,data-propagation=rslave（适用于 overlay2 + Linux 4.15+）；
- 若使用 docker-compose，可在 service 下配置：
volumes:
- type: bind
source: ./data
target: /app
bind:
propagation: rslave
- 确保宿主机对应目录不在 Docker 根目录（如 /var/lib/docker）内部，否则 overlay2 可能拒绝挂载。
替代方案：改用 volume 驱动或移除 UnionFS 依赖
对强一致性或复杂挂载需求，可绕过 UnionFS 限制：
- 使用 local-persist 或 lvm2 类 volume 插件，由外部驱动管理路径，与 UnionFS 解耦；
- 在支持的环境中切换存储驱动为 zfs 或 btrfs，它们原生支持快照与写时复制，对 bind mount 更友好；
- 若仅为开发测试，启用 dockerd --storage-driver=overlay2 --no-submounts（部分版本支持），禁用自动子挂载干预。
