镜像里明明有网站程序，添加一条目录挂载后，容器里的目录却空了；去掉挂载重新启动，文件又出现。这样的现象通常与路径遮蔽有关：挂载内容覆盖了该路径的可见视图，原有文件未必被删除。
不过，“被遮住”不能用来解释所有数据异常。挂载到了错误的宿主机目录、换了一个新数据卷、入口脚本执行了初始化，也可能让人误以为文件消失。处理前需要先确认当前看到的是哪份数据，避免把空目录反向同步到原目录。
本文以 Docker Engine 的 Linux 容器为主，涉及 Docker Compose 的地方会单独说明。以下路径均为示例，没有在读者服务器上实测。涉及数据库和业务文件时，先准备可恢复备份，再安排受控检查。
挂载后，目标路径展示的是挂载源
假设镜像里 /opt/app 原本包含应用文件，将宿主机 /srv/app 绑定到 /opt/app 后，容器看到的这个路径主要反映 /srv/app 的内容。如果宿主机目录为空，容器里看起来也会是空目录。
这与把文件逐个复制到容器里不同。挂载建立了一层文件系统视图，下面原有的镜像文件或容器可写层内容被遮住，不会因为挂载这个动作自动移进外部目录。
Docker 官方文档说明，绑定挂载遮蔽已有内容后，通常需要重建一个不带该挂载的容器来重新看到底层文件。不要在生产容器内尝试强行卸载挂载点，以免改变运行环境或误操作宿主机资源。
还需要区分文件原本在哪里。如果是镜像内置文件，可以通过同一镜像的独立检查容器查看；如果是旧容器运行期间写进可写层的文件，新建容器不会带上它们。未备份前不要删除旧容器。
绑定挂载与空数据卷的初始行为不同
绑定挂载将一个宿主机路径直接映射到容器目标。它不会默认把目标已有文件复制到源目录。宿主机路径错了，即使容器成功启动，也可能展示一份意外的目录。
Docker 管理的数据卷则有不同的初始化规则：默认情况下，将空卷挂载到容器已有内容的目录时，Docker 会把该目录的已有内容复制进空卷。使用 volume-nocopy 等选项可以关闭这一行为。
已经有内容的卷挂载后，会遮蔽目标原有内容；更换镜像也不会自动把卷内应用文件升级成新镜像版本。因此，镜像已更新而程序仍旧，有时是旧卷遮住了新镜像目录。
这不代表应该删除卷重新初始化。卷里可能同时存放上传文件、配置或数据库数据。应先确定哪些内容该由镜像提供，哪些内容需要持久化，再设计迁移。
先读取实际 Mounts，不凭 Compose 文件猜
运行中的容器才是本次排查对象。配置文件可能已经改过，现有容器却尚未重建，也可能使用了不同项目名或覆盖文件。
# app 为占位容器名，请替换。
docker inspect --format '{{json .Mounts}}' app
docker inspect --format 'ImageID={{.Image}} ImageRef={{.Config.Image}}' app
重点检查每项挂载的 Type、Source、Destination、RW，数据卷还应关注卷名。输出可能包含宿主机敏感路径，不要原样公开。
对于绑定挂载，Source 指向 Docker daemon 所在主机的路径。使用远程 context 或远程 Engine 时，它不一定是当前终端电脑的目录。Docker Desktop 还存在主机路径共享与虚拟机环境边界，需结合产品机制确认。
如果 Mounts 中目标路径正确，但源目录不对，应继续核实 Compose 文件位置、相对路径基准、项目参数及实际运行命令。不要因为目录名字相同就认定数据来源相同。
-v 拼错路径可能创建一个空目录
对于绑定挂载，-v 的宿主机路径不存在时，Docker 会创建该路径，且创建为目录；--mount type=bind 在源路径不存在时默认会报错。这是排查“明明挂上了却没有文件”的重要区别。
例如，把文件路径拼错后当作绑定源传给 -v，可能得到一个新目录。后续的报错或内容异常往往来自文件与目录类型不匹配。
Compose 的短语法也可能为了兼容而自动创建缺失的宿主机目录。检查现有配置前，不要重复运行带错路径的创建命令，避免制造更多空目录。
在支持相应 Compose 规范的版本中，可以采用更明确的长语法，并关闭源路径自动创建：
services:
web:
image: your-app:tested-tag
volumes:
- type: bind
source: /srv/site/uploads
target: /opt/app/uploads
bind:
create_host_path: false
这是配置片段，镜像与目录均为占位。修改前先检查本机版本支持，用 docker compose config 查看解析结果；其输出可能包含环境变量值，应在本机受控查看。
用只读检查区分路径错误与权限问题
确认实际 Source 后，在 daemon 所在主机上查看目录类型、内容和权限。对于本机 Linux Engine，可以按实际权限运行：
stat /srv/site/uploads
ls -ld /srv/site/uploads
列目录时控制输出范围，避免遍历庞大业务目录。不要使用递归 chmod 或 chown 来试探。权限不足通常会产生拒绝访问，也可能被应用转成默认页面，必须结合日志判断。
如果是 SELinux 环境，标签与挂载选项也可能影响访问。但路径错误、权限错误和内容遮蔽是不同问题，应先确认数据位置，再判断授权。
对于命名卷，可以先用 docker volume inspect 核实驱动和挂载信息。不要直接进入 Docker 内部管理目录修改内容；非本地驱动的数据位置和访问方式也可能不同。
容器内的 /opt/app 看起来为空，不代表宿主机上所有同名目录都为空。整个排查过程中，应给每条记录标注主机、容器、源路径和目标路径。
检查镜像内容时，不要运行生产入口
想确认镜像是否真的包含程序，可以使用原容器记录的镜像 ID，在隔离环境创建一个不带业务挂载的检查容器。优先只创建、不启动，避免默认入口执行初始化、连接数据库或发送外部请求。
需要提取镜像文件时，可在确认路径和授权后，通过 Docker 支持的复制方式将检查容器中的目标内容保存到独立临时目录；不要覆盖现有业务目录。检查容器的自动声明卷及镜像配置也需核实，避免再次被挂载视图误导。
这一步只能证明该镜像版本的内容。旧容器可写层中运行时生成的文件，需要另行保留和提取；数据库文件则应优先通过数据库原生一致性备份或受控停机备份处理，不能把运行中的目录复制当成可靠恢复点。
检查结束后，按明确对象清理临时容器和临时数据，不执行全局 prune，也不顺手删除未确认用途的卷。
恢复时按数据来源选择路径
如果只是绑定源拼错，先找到正确源目录，确认内容与备份，然后在维护窗口修正配置并重建目标服务。挂载配置变更通常不能仅靠容器 restart 生效。
如果想把镜像中的默认文件放进宿主机目录，应先复制到独立暂存位置，对照内容并检查属主权限，再按部署流程迁移。不能期待绑定挂载自动填充文件。
如果旧卷遮住了新版本程序，应拆分应用代码与持久化数据，让代码随镜像发布、业务数据按应用文档挂载到专用目录。已有混合目录需要规划迁移，不能直接去掉卷后启动。
重建前记录镜像 ID、挂载关系、卷名、配置和回滚步骤，保留旧容器及相关备份。不要执行 docker compose down -v 或 docker volume prune 来“恢复默认文件”，这可能删除仍需要的数据。
仅在应用明确支持的情况下共享写入卷。多个进程同时修改文件或数据库目录可能造成损坏，即使挂载路径看上去完全正确。
验收要检查读写落点和下一次重建
恢复后重新读取 Mounts，确认源与目标、读写模式及卷名符合预期。然后通过应用本身验证已有文件可读，新产生的数据落在预定持久化位置。
只读资源不要为了测试写入而修改。可写目录可在测试环境使用无副作用的标记验证，业务系统则应使用受控测试流程，避免在生产目录随意创建或删除文件。
最后在测试环境验证重启与重建后的行为：默认文件是否仍存在，上传是否保留，镜像升级后代码版本是否正确。重启成功只能说明当前容器恢复，无法证明下次重新创建也不会换一份空卷。
记录最终的数据边界，比单纯记住一条挂载命令更有用。哪些文件来自镜像、哪些来自旧容器可写层、哪些位于外部持久化存储，都应能够说清楚。
参考资料
核验日期：2026-11-04。以下为 Docker 官方文档；Compose 配置与挂载选项请结合实际 Engine、Compose 版本和操作系统确认。