Logo

菜单

Administrator
Administrator
发布于 2026-10-28 / 0 阅读
0
0

Docker 故障排查（13）：not a directory：挂载配置文件时，为什么源路径变成了目录

适用：使用 systemd 的 Linux 服务器、常规 rootful Docker Engine；Compose 示例使用 docker compose V2。本文为教学故障场景，错误文本和结果为示意，具体输出以现场为准。

一、遭遇情况：明明挂的是配置文件，却提示不是目录

部署 Nginx 时，命令写着把 nginx.conf 挂进容器，但报错包含：

not a directory
Are you trying to mount a directory onto a file (or vice-versa)?

本篇案例中，宿主机文件名拼错了。运维人员使用 -v，Docker 在不存在的源路径处创建了一个目录；随后尝试把这个目录覆盖到容器里的配置文件位置，出现类型冲突。

这与“应用读取配置后发现语法错”不同：容器可能还没真正运行应用，应该先检查挂载路径，而不是先研究 Nginx 指令。

二、原因分析：后缀名不决定文件类型

Linux 中，叫 nginx.conf 的对象也可以是目录。文件名有 .conf，不证明它就是普通文件，必须看 stat 或 ls -ld。

-v /源路径:/目标路径 与 --mount type=bind,... 对源路径缺失的默认处理不同：传统 -v 会创建缺失的源目录，--mount 默认直接报源不存在。后者更容易在路径拼错时尽早暴露问题。

配置文件挂载的源路径与目标路径检查

绑定挂载的源路径位于 daemon 所在主机。如果你通过远程 context 部署，本地电脑存在这个文件，也不代表服务器上存在。

三、排查思路：先确认源，再确认目标

假设配置预期位于 /srv/myweb/nginx.conf：

pwd
ls -ld /srv/myweb/nginx.conf
stat /srv/myweb/nginx.conf
docker inspect web --format '{{json .Mounts}}'
docker inspect web --format '{{.State.Error}}'

检查实际部署命令里使用的路径是否与这里相同，注意相对路径、工作目录、文件名大小写和环境变量展开。Compose 的相对路径通常按项目与配置文件规则解析，不要凭当前终端 pwd 猜最终路径。

若挂载阻止容器启动，可使用同一镜像、不带问题挂载的临时容器，读取目标类型：

docker run --rm --entrypoint sh nginx:stable-alpine -c 'ls -ld /etc/nginx/nginx.conf /etc/nginx/conf.d'

这里应能区分配置文件与配置目录。如果某镜像没有 shell，需使用该镜像支持的其他诊断方式，不能把 shell 不存在当作文件不存在。

四、实践：复现缺失源路径变成目录

在同一个 Bash 会话中创建专用实验目录：

lab_dir=$(mktemp -d /tmp/dt13.XXXXXX)
docker run --name dt13-wrong -v "${lab_dir}/nginx-missing.conf:/etc/nginx/nginx.conf:ro" nginx:stable-alpine
ls -ld "$lab_dir/nginx-missing.conf"

预期运行失败，宿主机的 nginx-missing.conf 却是目录。错误出现的具体阶段与运行时版本有关，但源对象类型可以直接验证。

不要为了继续部署直接 rm -rf。先确认这是刚才误建、没有业务内容的目录，再用只删除空目录的 rmdir 处理：

sudo rmdir "$lab_dir/nginx-missing.conf"

如果提示目录非空，停止这一步，先确认内容来源。错误目录里可能已经有其他操作写入的数据。

五、修复实践：准备真实文件，并让缺失直接失败

在实验目录创建一个实际配置文件：

cat > "$lab_dir/nginx.conf" <<'EOF'
events {}
http {
    server {
        listen 80;
        location / { return 200 "mount-ok\n"; }
    }
}
EOF

test -f "$lab_dir/nginx.conf"
docker run --rm --mount "type=bind,src=$lab_dir/nginx.conf,dst=/etc/nginx/nginx.conf,readonly" nginx:stable-alpine nginx -t
docker run -d --name dt13-fixed -p 127.0.0.1:18093:80 --mount "type=bind,src=$lab_dir/nginx.conf,dst=/etc/nginx/nginx.conf,readonly" nginx:stable-alpine
curl --max-time 5 http://127.0.0.1:18093/

配置预检应通过，HTTP 请求应得到 mount-ok。若 test -f 不通过，不应继续后面的部署步骤；它是人工操作中的检查点，不是整段脚本自动具备了分支保护。

在 Compose 长语法中，可以明确不自动创建源路径：

services:
  web:
    image: nginx:stable-alpine
    volumes:
      - type: bind
        source: ./nginx.conf
        target: /etc/nginx/nginx.conf
        read_only: true
        bind:
          create_host_path: false

部署前检查当前 Compose 版本支持该字段，并运行 docker compose config。语法检查通过也不能完全代替服务器源文件的存在与类型检查。

六、验证与总结

核对源文件是普通文件、容器 Mounts 指向正确路径、应用配置预检通过、业务请求符合新配置。对比配置内容时，注意文件级 bind mount 在原子替换文件后可能仍指向旧对象；需要按部署方式重新创建或重新挂载，不能只凭宿主机新文件内容判断容器已经读取。

这类故障应从两端对象类型和路径解析入手。把“文件名看起来对”换成“源对象、目标对象和内容都已验证”，比不断加冒号选项更有效。

参考资料

上一篇 · 系列目录 · 下一篇

Docker 故障排查（12）：挂...
Docker 故障排查（14）：C...

评论