docker-buildx-clean

命令

清理 Docker Buildx 构建缓存

docker-buildx-clean

清理 Docker Buildx 构建缓存

补充说明

docker buildx 是 Docker 的扩展构建工具，支持多平台镜像构建、高级构建选项和构建缓存管理。本文覆盖 Buildx 缓存清理的完整操作，以及 Buildx 节点元数据索引错乱（No such container: buildx_buildkit_mybuilder00）的彻底修复方案。

Buildx 节点错乱修复（适配 FnOS）

一、问题现象

当前系统存在 Buildx 元数据与实际容器不匹配的顽固 Bug：

docker buildx prune -f / docker buildx du 报错：No such container: buildx_buildkit_mybuilder00
实际运行容器名为 buildx_buildkit_mybuilder0（多出一个 0 后缀，索引错乱）
无法删除 builder、无法正常清理缓存、缓存统计失效
切换默认构建器清理正常，切回自定义 builder 必报错

二、问题根因

Docker Buildx 在异常重启 / 强制删除容器后：

本地配置缓存残留了错误节点名称 mybuilder00
实际创建的容器节点为正常 mybuilder0
docker-container 驱动的 buildx 会强制读取错误元数据，导致找不到容器报错

核心结论：服务是好的，只是 buildx 本地索引数据库错乱。

三、临时安全清理方案（日常使用 | 推荐）

无需重建、不破坏现有多架构构建器、永久规避报错，日常清理缓存固定使用这套流程：

# 1. 切换到系统默认内置构建器（无独立容器、无错乱bug）
docker buildx use default

# 2. 安全清理所有无引用构建缓存（不删除正在使用的层）
docker buildx prune -f

# 3. 切回你的多架构构建器，正常编译镜像
docker buildx use mybuilder

✅ 实测有效：清理无报错、缓存清零、不影响构建环境。

四、彻底根治修复方案（重置错乱索引）

如需彻底修复异常索引，以后 buildx prune 无需切换默认，执行完整重置流程：

# 1. 切换默认构建器
docker buildx use default

# 2. 删除损坏的自定义构建器
docker buildx rm mybuilder 2>/dev/null

# 3. 强制清理所有残留 buildkit 容器
docker rm -f $(docker ps -a --filter "name=^buildx_buildkit_" -q) 2>/dev/null

# 4. 全新创建干净无错乱的 buildx 构建器
docker buildx create --name mybuilder --driver docker-container --use

# 5. 初始化启动 BuildKit
docker buildx inspect mybuilder --bootstrap

# 6. 正常清理缓存（彻底无报错）
docker buildx prune -f

五、万能替代清理命令（绕开所有 Buildx Bug）

Docker 原生清理命令，不依赖 buildx 索引，100% 不会报错：

# 安全清理：仅删除未使用的构建缓存（推荐日常使用）
docker builder prune -f

# 深度清理：清空所有悬空/未引用缓存（适合磁盘爆满）
docker builder prune -a -f

# 清理当前 builder 全部缓存
docker buildx prune --all -f

六、最佳使用规范（后续永久不报错）

结合环境，固定工作流：

编译镜像：使用 mybuilder 多架构构建器
日常清理缓存：优先 docker builder prune -f
需要精准清理 buildx 缓存：切 default 清理再切回

七、当前环境状态总结

Buildx 服务：正常运行
BuildKit 容器：正常在线
故障类型：本地元数据索引错乱（软件 Bug，非环境损坏）

查看构建缓存使用情况

查看缓存大小

# 查看所有 Buildx 缓存的磁盘使用情况（推荐第一步操作）
docker buildx du

输出示例：

TYPE            TOTAL     ACTIVE    SIZE      DESCRIPTION
builder         1         0         78B       dockerfile build record
build-cache     2         0         256MB     build cache
Total:          3         0         256MB

详细查看缓存内容

# 查看更详细的缓存信息，包含构建记录
docker buildx du --verbose

# 过滤查看特定 builder 的缓存
docker buildx du --builder default

安全清理（推荐）

安全清理只删除无引用的缓存，已使用的构建层会被保留，后续构建仍能复用有效层。这是日常维护的首选方式。

删除无引用缓存

# 安全清理 — 删除所有无引用的构建缓存（不删除正在使用的层）
docker buildx prune -f

说明：

-f / --force：跳过确认提示，直接执行
不会删除当前或近期构建使用的缓存层
适合作为定时清理任务，对正在进行的 CI/CD 影响最小

带过滤条件的清理

# 只清理 24 小时前的无引用缓存（更安全，保留近期缓存）
docker buildx prune -f --filter "until=24h"

# 清理 7 天前的缓存
docker buildx prune -f --filter "until=168h"

# 清理超过 1GB 的缓存（阈值清理）
docker buildx du  # 先查看大小，再决定是否清理
docker buildx prune -f --filter "max-size=1g"

一次性全部清空

执行后所有构建缓存将被删除，后续构建必须完全重新拉取依赖、逐层编译，构建速度会明显变慢。请确认无重要缓存需要保留。

删除全部构建缓存

# 清空所有 Buildx 构建缓存（包含所有无引用和已引用缓存）
docker buildx prune -a -f

警告：

-a / --all：删除所有构建缓存，包括可复用的层
后续镜像构建无法复用历史缓存层
重新构建会完全重新拉取和编译，耗时大幅增加

清理 BuildKit 共享状态

# 清理 BuildKit 的共享内存和元数据（辅助彻底清理）
docker buildx prune -a -f --filter "all"

# 清理临时的构建输出文件
docker buildx prune -f --keep-storage 10GB  # 保留 10GB 缓存后再清理剩余

Windows PowerShell 脚本示例

# === 查看当前 Buildx 缓存大小 ===
Write-Host "=== Buildx 缓存使用情况 ===" -ForegroundColor Cyan
docker buildx du

# === 安全清理（保留有效层）===
Write-Host "`n=== 执行安全清理（仅删除无引用缓存）===" -ForegroundColor Yellow
docker buildx prune -f
docker buildx du

# === 确认清理结果 ===
Write-Host "`n=== 清理完成，当前缓存 ===" -ForegroundColor Green
docker buildx du

Linux/macOS 脚本示例

#!/bin/bash
# === docker-buildx-clean.sh ===
# Docker Buildx 构建缓存清理脚本

set -e

echo "=== Buildx 缓存使用情况 ==="
docker buildx du

echo ""
echo "=== 执行安全清理 ==="
docker buildx prune -f

echo ""
echo "=== 清理完成，当前缓存 ==="
docker buildx du

# 添加执行权限
chmod +x docker-buildx-clean.sh

# 手动执行
./docker-buildx-clean.sh

# 或添加到 crontab 定时执行（每周日凌晨 3 点）
# 0 3 * * 0 /path/to/docker-buildx-clean.sh >> /var/log/docker-buildx-clean.log 2>&1

CI/CD 中的使用

GitHub Actions

# .github/workflows/cleanup.yml
name: Cleanup Buildx Cache

on:
  schedule:
    - cron: '0 3 * * 0'  # 每周日凌晨 3 点
  workflow_dispatch:       # 允许手动触发

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: View cache size
        run: docker buildx du

      - name: Safe prune
        run: docker buildx prune -f

      - name: Verify cleanup
        run: docker buildx du

GitLab CI

# .gitlab-ci.yml
stages:
  - cleanup

cleanup-buildx:
  stage: cleanup
  image: docker:24-cli
  services:
    - docker:24-dind
  script:
    - docker buildx du
    - docker buildx prune -f
    - docker buildx du
  only:
    - schedule

命令	作用范围	是否保留有效层	适用场景
`docker buildx prune -f`	Buildx 无引用缓存	✅ 保留	日常维护首选
`docker buildx prune -a -f`	Buildx 所有缓存	❌ 全部删除	彻底重置磁盘空间
`docker builder prune`	Classic builder 缓存	部分保留	非 Buildx 构建环境
`docker system prune`	Docker 所有未用资源	部分保留	系统级清理
`docker system prune -a`	Docker 所有未用资源	❌ 全部删除	全面重置

常见问题

Q: docker buildx prune 和 docker builder prune 有什么区别？

A: docker buildx prune 清理 Buildx（BuildKit 后端）的缓存，存储在 buildx 目录；docker builder prune 清理传统 Docker builder 的缓存。推荐使用 Buildx 的项目使用 buildx prune。

Q: 清理后构建速度变慢了？

A: 这是正常现象。缓存被清理后，构建需要重新执行每一步。如果不想完全禁用缓存，可以设置保留阈值：docker buildx prune -f --keep-storage 5GB，保留 5GB 缓存空间。

Q: 如何防止清理正在 CI 中使用的缓存？

A: 使用时间过滤保留近期缓存：docker buildx prune -f --filter "until=48h"，只清理 48 小时前的无引用缓存。

Q: Windows 上缓存路径在哪里？

A: %LOCALAPPDATA%\Docker\buildx，也可以通过 docker buildx du --verbose 查看具体路径。

Q: 清理报错 "permission denied"？

A: 需要管理员/root 权限。在 Linux 上使用 sudo，或确保当前用户在 docker 用户组中。

Q: 报错 "No such container: buildx_buildkit_mybuilder00"？

A: Buildx 元数据索引错乱。实际容器为 mybuilder0 但本地缓存误记为 mybuilder00。使用临时方案：docker buildx use default && docker buildx prune -f && docker buildx use mybuilder。如需根治，执行彻底修复方案（见上方第四节）。

Q: docker buildx du 一直转圈不显示结果？

A: BuildKit 容器可能未正常运行。先执行 docker buildx inspect mybuilder --bootstrap 确认容器在线，然后重试。如果仍然卡住，说明 builder 元数据损坏，需重建 builder。

docker-buildx-clean

docker-buildx-clean

补充说明

Buildx 节点错乱修复（适配 FnOS）

一、问题现象

二、问题根因

三、临时安全清理方案（日常使用 | 推荐）

四、彻底根治修复方案（重置错乱索引）

五、万能替代清理命令（绕开所有 Buildx Bug）

六、最佳使用规范（后续永久不报错）

七、当前环境状态总结

查看构建缓存使用情况

查看缓存大小

详细查看缓存内容

安全清理（推荐）

删除无引用缓存

带过滤条件的清理

一次性全部清空

删除全部构建缓存

清理 BuildKit 共享状态

Windows PowerShell 脚本示例

Linux/macOS 脚本示例

CI/CD 中的使用

GitHub Actions

GitLab CI

相关命令对比

常见问题