容器与云原生 / 系统课时

排查数据写入失败

排查数据写入失败

容器写文件失败时,不要先改权限或直接重建容器。最有效的顺序是先确认实际写入路径,再检查挂载是否可写、进程用户是否有权限,以及目标文件系统是否仍有容量,最后用一次最小写入测试验证修复。

学习目标

  • 能从挂载、只读模式、用户权限和磁盘空间四个方向定位写入失败
  • 能使用 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 即可。

bash
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

预期输出:

text
[{"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 前必须确认不会删除仍需保留的未使用对象。

用最小写入测试完成验证

修复后不要只看应用日志,直接在目标目录创建、读取并删除一个临时文件。这个测试同时验证目录可写、文件可创建以及基本读写链路正常。

bash
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"'

预期输出:

text
ok

如果最小测试成功而应用仍失败,问题通常已经从 Docker 挂载层缩小到应用自身,例如应用配置使用了另一个路径、文件名冲突、配额限制或应用内部权限控制;此时应回到应用日志继续定位,而不是继续修改 Docker 文件权限。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查数据写入失败

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通