容器与云原生 / 系统课时
排查数据写入失败
排查数据写入失败
容器写文件失败时,不要先改权限或直接重建容器。最有效的顺序是先确认实际写入路径,再检查挂载是否可写、进程用户是否有权限,以及目标文件系统是否仍有容量,最后用一次最小写入测试验证修复。
学习目标
- 能从挂载、只读模式、用户权限和磁盘空间四个方向定位写入失败
- 能使用
docker inspect、docker exec和docker system df收集关键证据 - 能在修复后通过最小写入测试确认问题确实消失
先把故障缩小到四类原因
常见现象包括 Permission denied、Read-only file system、No space left on device,以及应用声称写入成功但宿主机找不到文件。它们分别指向权限、只读挂载、空间不足或路径与挂载目标不一致。

排查时应以“容器实际看到的状态”为准。仅检查宿主机目录并不够,因为容器可能写到了另一个路径,也可能被 --read-only、只读 bind mount 或文件系统层限制。
一次收集挂载、权限和容量证据
下面假设容器名为 my-app,应用写入目录为 /data。如果你的应用写入其他目录,只修改 TARGET 即可。
CONTAINER=my-app
TARGET=/data
docker inspect "$CONTAINER" --format '{{json .Mounts}}'
docker exec "$CONTAINER" sh -c "id; if test -w '$TARGET'; then echo writable; else echo not-writable; fi; df -h '$TARGET'; df -i '$TARGET'"
docker system df预期输出:
[{"Type":"bind","Source":"<PATH>","Destination":"/data","Mode":"","RW":true,"Propagation":"rprivate"}]
uid=<ID>(<VALUE>) gid=<ID>(<VALUE>) groups=<VALUE>
writable
Filesystem Size Used Avail Use% Mounted on
<VALUE> <VALUE> <VALUE> <VALUE> <VALUE> /data
Filesystem Inodes IUsed IFree IUse% Mounted on
<VALUE> <VALUE> <VALUE> <VALUE> <VALUE> /data
TYPE TOTAL ACTIVE SIZE RECLAIMABLE
Images <VALUE> <VALUE> <VALUE> <VALUE>
Containers <VALUE> <VALUE> <VALUE> <VALUE>
Local Volumes <VALUE> <VALUE> <VALUE> <VALUE>实际数值会因主机和镜像不同而变化。重点看 .Mounts 中的 Destination 是否就是应用写入目录、RW 是否为 true,以及 test -w、磁盘可用空间和 inode 是否正常。
按证据修复而不是盲目 chmod
如果 Destination 不对,修正 docker run -v、--mount 或 Compose 中的目标路径;如果 RW 为 false,去掉只读挂载选项,确认没有使用 :ro。容器以非 root 用户运行时,宿主机 bind mount 的目录属主或权限必须允许该 UID/GID 写入。
若 df -h 显示容量耗尽,应清理目标文件系统或扩容;若 df -i 的 inode 使用率接近 100%,即使仍有磁盘容量也无法创建新文件。docker system df 只能帮助判断 Docker 对象占用,执行 docker system prune 前必须确认不会删除仍需保留的未使用对象。
用最小写入测试完成验证
修复后不要只看应用日志,直接在目标目录创建、读取并删除一个临时文件。这个测试同时验证目录可写、文件可创建以及基本读写链路正常。
CONTAINER=my-app
TARGET=/data
docker exec -e TARGET="$TARGET" "$CONTAINER" sh -c 'tmp="$TARGET/.write-test-$$"; printf "ok\n" > "$tmp" && cat "$tmp" && rm "$tmp"'预期输出:
ok如果最小测试成功而应用仍失败,问题通常已经从 Docker 挂载层缩小到应用自身,例如应用配置使用了另一个路径、文件名冲突、配额限制或应用内部权限控制;此时应回到应用日志继续定位,而不是继续修改 Docker 文件权限。