大型 Docker 开发镜像磁盘排查：containerd、缓存与容量规划

摘要：给出大型开发镜像的磁盘排查顺序，区分 containerd 镜像数据、snapshot、BuildKit cache、导出归档和源码构建输出。

在这里插入图片描述

@[toc]

当一个二十多 GiB 的开发镜像运行在 Docker Engine 29+ 新主机上时，磁盘问题往往比容器运行问题更早出现。

例如根分区只有约 80 GiB，却同时存在：

大型开发镜像
containerd content
unpacked snapshot
BuildKit cache
源码 build 输出
镜像导出归档

这时如果只看到：

1	/dev/sdaX 90%

然后立刻运行 docker system prune -a，很容易删掉重新构建代价很高的开发镜像。

更好的方式是先回答：

空间到底被哪一类数据占用了？

1. 第一层先看文件系统

df -h /

它回答的是：

1	整个根文件系统还剩多少空间？

它不会告诉你 Docker 哪个对象在占空间。

如果镜像归档放在其他分区，还要分别看：

1	df -h /path/to/archive

大型镜像导出时，Docker 数据和归档文件可能位于不同文件系统，不能只检查一个路径。

2. 第二层看宿主机真实目录

containerd image store 环境下，至少检查：

1	sudo du -sh /var/lib/containerd /var/lib/docker

这回答的是宿主机目录实际占用。

Docker 当前文档说明，containerd image store 下的 image contents 和 container snapshots 默认在：

1	/var/lib/containerd

所以新 Docker 环境中只看 /var/lib/docker 已经不够。

3. 第三层看 Docker 逻辑对象

1	docker system df

需要更详细时：

1	docker system df -v

它让你从 Docker 对象视角看：

Images
Containers
Local Volumes
Build Cache

du 和 docker system df 不要求数字完全一致。

一个是文件系统目录视角，一个是 Docker 对象和共享关系视角。

4. 构建过大镜像以后单独看 BuildKit cache

如果刚执行过大型 docker buildx build，再看：

1	docker buildx du

大型 SDK 构建经常产生很大的 BuildKit cache。

它和“最终镜像本身”不是同一个对象：

Build Cache
    构建阶段复用

Final Image
    docker run 使用

如果 cache 明确可回收，可以：

1	docker builder prune

这通常是大型镜像构建完成后的第一类清理对象。

5. 为什么 builder prune 不会把 50 GiB 镜像变成 27 GiB

如果当前 containerd image store 需要同时保存：

1 2	image content unpacked snapshot

那么它们属于最终镜像运行体系。

执行：

1	docker builder prune

只会处理 BuildKit cache。

所以即使清掉 20 GiB 构建缓存，最终镜像相关的几十 GiB 仍然可能存在。

这不是 prune 失败，而是你清理的是不同对象。

6. inactive 不等于“不需要”

大型开发镜像有一个危险特点：平时不一定有常驻容器。

所以 Docker 可能显示：

ACTIVE 0

但这只说明现在没有容器使用它，不代表镜像应该删除。

一个 20+ GiB 开发镜像可能构建几个小时，甚至需要重新复制大型 SDK。

因此看到 inactive 后不要直接：

1	docker system prune -a

更合理的是先确定：

1
2
3

这个镜像是否是正式开发环境？
是否已经有可靠离线备份？
是否能快速重新构建？

7. image prune 和 system prune 的范围不同

较温和：

1	docker image prune

更激进：

1	docker image prune -a

范围更广：

1	docker system prune -a

越往后，自动判断“未使用”的对象范围越大。

对于普通 CI 临时环境，这可能很方便；对于手工制作的大型 SDK 镜像，应该更保守。

建议先：

1	docker system df -v

确认对象，再做针对性清理。

8. 不要直接删除 `/var/lib/containerd`

即使：

1	sudo du -sh /var/lib/containerd

显示几十 GiB，也不要执行：

1	sudo rm -rf /var/lib/containerd/*

containerd 的 content、metadata 和 snapshot 之间存在引用关系。

绕过 Docker/containerd 管理层手工删除，可能导致：

镜像 metadata 仍然存在
底层 blob 已损坏
snapshot 引用不一致
容器无法启动

清理应优先通过 Docker CLI 或明确的官方迁移流程完成。

9. 导出归档经常是被忽略的一大块

例如你为了迁移镜像，在：

~/images/

放了：

1 2	cross-dev.tar cross-dev.tar.zst

如果原始 TAR 没删，可能同时多占：

1
2
3

20+ GiB TAR
+
10+ GiB 压缩归档

它们完全不属于 Docker，因此：

1	docker system df

不会显示。

这就是为什么排查不能只看 Docker CLI。

可以检查：

1 2	du -sh ~/images find ~/images -maxdepth 1 -type f -size +1G -ls

大型镜像场景里，“导出文件忘了删”非常常见。

10. 源码 build 目录也可能很大

如果开发容器使用 bind mount：

1	宿主机源码 -> /workspace

那么容器生成的：

build/
*.o
*.a
*.so
打包产物

都可能实际写在宿主机项目目录。

这些也不属于 Docker image store。

所以完整排查还应该看：

1 2	du -sh ~/work/demo-app du -sh ~/work/demo-app/build

不要看到“是容器编译产生的”就认为一定在 /var/lib/docker。

11. data-root 迁走后为什么根分区还可能增长

Docker 常见配置：

1
2
3

{
  "data-root": "/mnt/docker-data"
}

但 Docker 当前官方文档明确说明：在 containerd image store 下，data-root 不会自动改变 containerd image contents 和 snapshots 的位置。

于是可能变成：

1 2	/mnt/docker-data Docker 其他数据 /var/lib/containerd 镜像内容和 snapshot

如果你的目标是彻底把大型镜像数据迁出根分区，就必须把 containerd 数据位置也纳入设计，而不是只修改 Docker data-root。

这类存储迁移涉及 daemon 停止、数据复制和配置一致性，不建议在磁盘快满时临时手工移动目录；应按 Docker/containerd 官方数据目录配置方式操作。

12. 一个 80 GiB 根分区为什么很容易不够

假设：

系统自身              15 GiB
开发镜像相关数据       45~55 GiB
BuildKit cache         10 GiB
源码和 build            5 GiB

总量已经可能达到：

75~85 GiB

如果这时还在根分区导出：

1	cross-dev.tar.zst 10+ GiB

很容易直接失败。

因此对超大型开发镜像，磁盘规划应该比“镜像 SIZE + 5 GiB”保守得多。

13. 更实用的容量规划方式

可以按几类数据分别估算：

A. 操作系统和普通工具
B. containerd image content
C. unpacked snapshots
D. BuildKit cache 峰值
E. 源码和构建产物
F. 镜像导出归档

其中 F 最适合放到另一块盘或网络存储，因为它只在迁移时需要。

如果这台机器长期维护大 SDK 镜像，更合理的硬件布局是：

系统根分区
    放 OS 和普通工具

大容量数据分区
    放 Docker/containerd 数据
    或至少放离线镜像归档

14. 推荐的排查顺序

以后遇到 Docker 把磁盘吃满，可以按下面顺序：

flowchart TD
    A["df -h：文件系统还剩多少"] --> B["du：/var/lib/containerd 与 /var/lib/docker"]
    B --> C["docker system df -v：镜像/容器/volume"]
    C --> D["docker buildx du：BuildKit cache"]
    D --> E["检查导出归档和源码 build"]
    E --> F["针对确认对象清理或迁移"]

对应命令：

df -h /
sudo du -sh /var/lib/containerd /var/lib/docker
docker system df -v
docker buildx du
du -sh ~/images ~/work/demo-app/build 2>/dev/null

这五步基本能把“大空间去哪了”分成明确类别。

15. 最后再决定处理策略

如果主要是 BuildKit cache：

1	docker builder prune

如果是明确不需要的旧镜像：

1	docker image rm <image>

如果是离线归档：

1 2	转移到移动硬盘 / NAS 或确认备份后删除本地副本

如果是 containerd image store 的最终镜像本身：

它不是“垃圾缓存”

此时真正的解决方式可能是扩大数据分区、迁移 containerd 数据位置，或者重新评估是否必须长期保留如此巨大的完整 SDK 镜像。

关键原则只有一句：

先确认数据身份，再清理；不要用最激进的 prune 去替代诊断。

参考资料

Docker Docs：containerd image store with Docker Engine — https://docs.docker.com/engine/storage/containerd/
Docker Docs：Docker daemon data directory — https://docs.docker.com/engine/daemon/
Docker Docs：Storage drivers — https://docs.docker.com/engine/storage/drivers/

文章作者: Liya Huang

文章链接: https://wdfk-prog.space/posts/d837d65a/

docker

赞助

微信
支付寶

相关推荐

2026-09-03

01-Docker开发环境容器化：从基本概念到Ubuntu20

Docker 开发环境容器化：从基本概念到 Ubuntu 20.04 安装排查摘要：从 Image、Container、Dockerfile 和挂载建立 Docker 心智模型，并结合 Ubuntu 20.04 的安装冲突说明为什么要把旧开发环境容器化。 @[toc]学习 Docker 最容易走偏的方式，是先背几十条命令，再去想这些命令解决什么问题。对于开发环境容器化，更合理的顺序正好相反：先明确工程为什么需要 Docker，再理解 Image、Container、Dockerfile、挂载和权限这些概念，最后才把命令放进实际场景。本文从一个典型的嵌入式交叉编译环境出发：旧工程长期依赖 Ubuntu 20.04、厂商 Yocto SDK、固定 CMake、代码生成工具和若干宿主机软件。旧机器能稳定构建，但一旦换电脑、升级系统或让其他开发者接手，就很难准确复刻环境。 Docker 在这里的目标不是“把 Linux 再装一遍”，而是：把构建环境固定成可重复生成的镜像，把日常修改的源码继续留在宿主机。 1. 为什么开发环境值得容器化传统开发机往往随着项目迭代逐渐变成这样...

2026-09-03

02-大型SDK开发镜像工程化：BuildKit、Buildx与项目脚本

大型 SDK 开发镜像工程化：BuildKit、Buildx 与项目脚本摘要：以约 25 GiB 的交叉编译 SDK 为例，解释 BuildKit、Buildx、named context、镜像层，以及 Dockerfile、Compose 和配套脚本怎样组成完整开发环境。 @[toc] 普通 Docker 教程经常从一个几十 MB 的源码目录开始：写 Dockerfile、COPY . .、执行 docker build，几秒钟就能看到结果。但真实嵌入式开发环境可能完全不是这个规模。假设已有一套厂商 Yocto SDK，展开后约 25 GiB，还需要固定版本的 CMake、host 侧代码生成工具以及一套 UID/GID 兼容逻辑。此时问题已经从“会不会写 Dockerfile”变成了： 25 GiB SDK 怎样进入 Image；怎样避免为了构建镜像再制造一个巨大的 SDK 压缩包； BuildKit 和 Buildx 分别负责什么；为什么使用额外 build context；为什么源码不和 SDK 一起做进 Image；为什么需要 entry...

2026-09-03

03-交叉编译开发容器故障排查：从CMakeCache到目标库链接

交叉编译开发容器故障排查：从 CMakeCache 到目标库链接摘要：按真实首次失败点复盘旧 CMakeCache、host/target Thrift、SDK 权限、编译参数冲突和目标库链接，说明怎样沿证据链逐层收敛问题。 @[toc] Docker 能启动、交叉编译器能执行，只能证明环境最外层入口正常。历史 C/C++ 工程仍可能依次暴露旧 CMake 缓存、宿主工具、目标库、权限和编译参数策略。这次排查最重要的原则是：围绕当前第一次失败收集证据，证明后再继续向后。最终故障链可以概括为： 1234567flowchart TD Cache["旧 CMakeCache\n编译器路径属于旧 Host"] -->|干净 build tree| Compiler["交叉 GCC 正确识别"] Compiler --> Thrift["host Thrift 查找失败"] Thrift -->|确认 host generator| Header["...

2026-09-03

04-Docker常用语法与命令：CLI、Dockerfile与Compose速查

# Docker 常用语法与命令：CLI、Dockerfile 与 Compose 速查摘要：用开发环境场景整理 Docker CLI、Dockerfile、Buildx、Bind Mount、Compose、镜像迁移与磁盘清理的常用语法，重点解释参数改变了什么。 @[toc] 这一篇把前面频繁出现的 Docker 语法集中成开发机速查表，不穷举全部参数，只保留最常用对象和命令结构。 1. Docker CLI 先按“对象 + 动作”理解现代 Docker CLI 很多命令可以读成： 1docker <object> <command> [options] 例如： 123456docker image lsdocker image inspect arm64-dev:20.04docker container lsdocker container rm demodocker volume lsdocker network ls 同时 Docker 仍保留大量短写： 1234docker imagesdocker psdocker rmdoc...

2026-09-04

05-Docker开发镜像跨主机迁移：从Ubuntu20

Docker 开发镜像跨主机迁移：从 Ubuntu 20.04 到 24.04 摘要：说明如何把已验证的 Ubuntu 20.04 开发镜像迁移到 Ubuntu 24.04，并逐层验证 Docker、镜像、源码挂载和真实构建。 @[toc]旧开发机长期使用 Ubuntu 20.04，交叉编译 SDK、CMake 和各种依赖已经调通；新机器升级到 Ubuntu 24.04 后，最稳妥的做法往往不是重装整套依赖，而是继续运行已经验证过的开发镜像。 1. 宿主机升级，不等于容器也升级假设我们已经有一张镜像： 1cross-dev:20.04 它内部包含： 123456Ubuntu 20.04 用户空间Yocto SDK交叉编译器CMake / Make / Python代码生成工具entrypoint 把它迁移到 Ubuntu 24.04 后，结构是： 123456flowchart TB Host["Ubuntu 24.04 宿主机"] --> Engine["Docker Engine"] Engine --&g...

2026-09-04

06-Docker开发环境到底要交付什么：镜像、源码与运行脚本

Docker 开发环境到底要交付什么：镜像、源码与运行脚本摘要：从团队交付角度区分 Docker 镜像、bind mount 源码、entrypoint、Compose 和 dev.sh，明确哪些需要随镜像一起交给使用者。 @[toc]开发镜像自己能运行以后，下一个问题往往不是“怎么构建”，而是：我要把这套环境给另一个开发者，他到底需要拿到哪些文件？最容易产生误解的是 entrypoint.sh、compose.yaml 和 dev.sh。它们看起来都和“启动容器”有关，但所处层次完全不同。 1. 先把开发环境分成三层可以先用一张图建立边界： 123456flowchart TB User["开发者"] --> Dev["dev.sh"] Dev --> Compose["compose.yaml / docker run 参数"] Compose --> Image["Docker Image"] Image --> Entry[&...

大型 Docker 开发镜像磁盘排查：containerd、缓存与容量规划

1. 第一层先看文件系统

2. 第二层看宿主机真实目录

3. 第三层看 Docker 逻辑对象

4. 构建过大镜像以后单独看 BuildKit cache

5. 为什么 builder prune 不会把 50 GiB 镜像变成 27 GiB

6. inactive 不等于“不需要”

7. image prune 和 system prune 的范围不同

8. 不要直接删除 /var/lib/containerd

9. 导出归档经常是被忽略的一大块

10. 源码 build 目录也可能很大

11. data-root 迁走后为什么根分区还可能增长

12. 一个 80 GiB 根分区为什么很容易不够

13. 更实用的容量规划方式

14. 推荐的排查顺序

15. 最后再决定处理策略

参考资料

8. 不要直接删除 `/var/lib/containerd`