overlayfs因空间写满引发的“镜像破损”本质是运行态异常，需协同修复存储空间、overlay结构及inode状态：先用df -i和du -sh /var/lib/docker/overlay2定位根因，再清理 dangling 层、重建挂载点并配置存储配额预防复发。
当底层联合文件系统（如 OverlayFS、AUFS）因空间写满而引发镜像破损异常时，问题本质不是镜像文件本身损坏，而是容器或系统运行时因无可用空间导致元数据错乱、inode耗尽、overlay 工作层（workdir）或上层（upperdir）无法写入，进而触发挂载失败、invalid argument、no space left on device 或 overlay: failed to mount 等错误。这类“镜像破损”实际是运行态异常，需从存储空间、overlay 结构、inode 状态三方面协同修复。
MiniMax 图片理解 + 网络搜索 MCP 工具。适配 Docker 环境（极空间等），支持图片 OCR 识别、图像内容理解、网络搜索。API Key 安全存储在本地 credentials 文件，不暴露在代码中。
立即释放 overlay 存储空间
OverlayFS 依赖底层存储（通常是 /var/lib/docker/overlay2 或 /var/lib/containers/storage/overlay）中的 upperdir、workdir 和 merged 目录。空间写满后，即使磁盘 df -h 显示仍有余量，也可能因 inode 耗尽或 overlay 元数据碎片化而失效。
- 查看 overlay 使用情况：
du -sh /var/lib/docker/overlay2/*/diff | sort -hr | head -10
- 清理已停止但未自动删除的容器层：
docker system prune -f docker builder prune -f
- 强制清理 dangling layer（不被任何镜像或容器引用的层）：
docker system prune -a -f --volumes
检查并修复 inode 耗尽问题
OverlayFS 对 inode 敏感，小文件堆积极易耗尽 inode。df -i 若显示 /var/lib/docker 分区 Use% 接近 100%，即为根因。
- 列出 inode 占用大户：
find /var/lib/docker/overlay2 -xdev -type f | cut -d/ -f1-4 | sort | uniq -c | sort -nr | head -10
- 清理临时构建缓存、重复日志、未命名镜像层：
# 删除所有构建缓存（谨慎） docker builder prune --filter "until=24h" -f # 清空容器日志（若使用 json-file 驱动） truncate -s 0 /var/lib/docker/containers/*/*-json.log 2>/dev/null
重建损坏的 overlay 挂载点
若 mount | grep overlay 显示某 overlay 实例状态异常（如 failed, invalid argument），说明该实例元数据已不一致，不能仅靠重启恢复。
- 卸载异常 overlay 实例（先停相关容器）：
docker stop <container-id> umount /var/lib/docker/overlay2/<id>/merged 2>/dev/null</id></container-id>
- 删除对应工作目录（仅在容器已停且无重要数据时）：
rm -rf /var/lib/docker/overlay2/<id></id>
- 重启 dockerd 重建挂载树：
systemctl restart docker
预防性配置优化
避免再次写满的关键在于限制与监控：
- 在
/etc/docker/daemon.json中启用磁盘配额（需 overlay2 + kernel ≥ 5.11）：{ "storage-driver": "overlay2", "storage-opts": ["overlay2.size=20G"] } - 设置容器级存储限制（适用于 rootless 或 podman）：
podman run --storage-opt size=10G ...
- 添加定时清理任务（例如每日凌晨清理 7 天前的构建缓存）：
echo "0 3 * * * root docker builder prune --filter 'until=168h' -f" >> /etc/crontab
不复杂但容易忽略——真正起效的修复，往往始于 df -i 和 du -sh /var/lib/docker/overlay2 这两行命令。
