BuildKit 取消构建后缓存一直 in-use、磁盘占满怎么处理

先确认没有正在运行的构建，再判断是否命中取消 RUN 阶段后的引用泄漏，最后安排受控重启释放空间

直接答案：如果 CI 在 Dockerfile 的 RUN 步骤执行中被取消，随后 docker system df -v 显示构建缓存持续为 in use，而 docker builder prune 回收 0B，先不要反复执行更激进的清理命令。先确认同一 builder 没有活动构建，并记录 Docker、Buildx 和实际 BuildKit daemon 版本；若现象符合 BuildKit 上游 Issue #7206，目前可验证的恢复动作是安排维护窗口重启对应 daemon，然后再清理已经变为可回收的缓存。

只读检查不会删除镜像或数据。重启 Docker 或独立 BuildKit daemon 会中断该节点正在运行的构建；执行 prune 会删除可回收构建缓存，使后续构建重新下载依赖并增加时间、流量和存储读写。生产节点应先停止接收新任务，等待现有任务结束，再操作。本文核验日期为 2026-10-05；该上游问题当时仍是开放状态，不能把临时恢复写成已经发布的永久修复。

先确认磁盘是不是被构建缓存占用

在实际执行构建的节点上运行下面的只读命令。使用远程 builder 时，不要只检查发起命令的 CI 容器；先用 Buildx 列表找到带星号的当前 builder 和节点。

docker buildx ls
docker buildx inspect --bootstrap
docker system df -v
df -h

docker buildx inspect 用来确认 driver、节点和 BuildKit 版本；docker system df -v 用来查看 Docker 对构建缓存的统计；df -h 用来确认实际文件系统剩余空间。若只是镜像、停止容器或日志占满磁盘，应转到相应对象处理，不要套用本文的 daemon 重启路径。

检查结果	判断	下一步
有构建正在运行	缓存显示 in-use 可能正常	等待构建结束后重新取证，不要重启
没有构建，缓存可回收空间大于 0	属于常规未使用缓存	先做 builder 专用 prune
没有构建，缓存持续 in-use，prune 回收 0B	可能命中取消构建后的引用未释放	核对取消时间、版本和 daemon 日志
Docker 统计不大，但根分区仍满	原因可能是容器日志、系统日志或其他目录	按 Linux 磁盘占用路径继续检查

确认是否在 RUN 步骤中取消过构建

Issue #7206 描述的触发点不是“所有构建失败”，而是构建在 RUN 步骤执行时被取消。检查 CI 任务历史、取消策略和同一时刻的 builder 日志。常见现场是新提交到达后自动取消上一条流水线，或者人工按下取消按钮。

对于 docker-container driver，先从 Buildx 找到实际容器名，再只读查看近期日志。下面的过滤只帮助定位时间，不代表看到 cancel 就能直接断定根因。

docker ps --format '{{.Names}}\t{{.Image}}' | grep buildx_buildkit
docker logs --since 24h <BUILDKIT_CONTAINER> 2>&1 | grep -Ei 'cancel|context canceled|exec'

把 <BUILDKIT_CONTAINER> 换成上一条命令返回的真实容器名。若使用的是 Docker driver，BuildKit 由 Docker Engine 管理，应查看 journalctl -u docker；若是独立 buildkitd，查看对应 systemd 服务或容器日志。

先做一次范围最小的常规清理验证

确认没有活动构建后，可以先预览并执行 builder 专用清理。不要直接使用带 --volumes 的 docker system prune；它的影响范围更大，且不会解决仍被标为使用中的引用。

docker builder prune
docker system df -v

第一条命令会先列出并要求确认可删除的构建缓存。若回收量符合预期，问题属于常规缓存积累，到这里即可停止。若命令显示没有可回收对象或回收 0B，而相同记录仍为 in-use，继续进入维护窗口处理。

在维护窗口重启正确的 daemon

重启前先暂停 CI runner 或把节点从调度池摘除，确认没有构建任务，再记录 builder 配置和磁盘数据。不要在仍承载业务容器的 Docker Engine 上直接照抄重启命令；重启影响取决于容器重启策略和宿主机配置。

Docker driver 由 Docker Engine 管理，在使用 systemd 的 Linux 主机上由管理员执行：

sudo systemctl restart docker
sudo systemctl is-active docker

如果是 docker-container driver，应在确认 builder 名称后重启对应 BuildKit 容器，或由维护者重建该 builder；独立服务则重启实际的 buildkitd 服务。关键是重启持有引用的 daemon，不是随意重启发起构建的 CI 容器。

重启后如何清理和验收

daemon 恢复后先确认 builder 可用，再检查先前记录是否已从 in-use 变为可回收。确认无任务后才执行清理。

docker buildx inspect --bootstrap
docker system df -v
docker builder prune
docker system df -v
df -h

验收需要同时满足三点：builder 状态正常；原来无法回收的缓存不再持续占用；文件系统可用空间实际增加。随后只放行一条可信构建，确认镜像能够完成且缓存行为正常，再恢复全部 CI 流量。

失败分支与回退

• 重启后仍无法回收：保存 docker system df -v、Buildx inspect、daemon 版本与取消时间，检查是否重启了错误节点；不要循环重启。
• builder 起不来：继续保持节点摘除状态，查看 daemon 日志；使用事先记录的 builder 配置恢复，不要删除仍可能需要的本地缓存目录。
• 业务容器受影响：按原有容器编排和健康检查恢复上一稳定状态，构建节点继续隔离。以后应把共享 CI builder 与业务容器拆分故障域。
• 磁盘很快再次增长：检查流水线是否仍频繁“取消旧任务”，并为构建节点设置磁盘告警。GC 只能处理可回收记录，不能替代触发条件治理。

怎样降低再次占满磁盘的概率

在上游明确发布修复版本前，优先减少同一长生命周期 builder 上的中途取消。可以让即将完成的构建自然结束，或把高频取消的分支放到可替换的隔离 builder。外部缓存可降低节点重建后的冷启动成本，但缓存后端可能产生对象存储、仓库流量或容量费用，启用前应到实际平台账单页核对。

常规容量治理可参考 Docker no space left on device 排查和 Linux 磁盘满排查。如果问题恰好发生在主动清理之后、表现为下一次构建完全不命中缓存，应改看 Buildx prune 后缓存失效。需要核对 BuildKit 版本安全边界时，再看 BuildKit 超大构建定义内存耗尽。

官方与上游依据

• BuildKit Issue #7206：取消 RUN 后缓存引用持续 in-use（需求与缺陷现场，2026-10-05 核验）
• Docker Docs：docker buildx inspect（builder 与节点检查）
• Docker Docs：Build garbage collection（GC 与清理边界）
• Docker Docs：docker system prune（删除范围与风险）

常见问题

可以直接执行 docker system prune -a --volumes 吗？

不建议。它会扩大到未使用镜像、网络、停止容器和匿名卷；而被标为 in-use 的构建缓存仍可能不会被删除。先确认对象类型，再用范围最小的命令。

重启 Docker 一定能永久修复吗？

不能这样承诺。上游 Issue 说明重启会释放进程生命周期内持有的引用，但截至核验日问题仍开放。重启是恢复动作，后续仍需控制取消策略并关注上游修复。

本稿需要黑鲨云确认业务事实吗？

本稿未发现需要补充确认的黑鲨云业务事实。文章只提供 Docker/BuildKit 运维判断，不把黑鲨云写成 Docker 官方，也不承诺固定修复版本或恢复时效。