多节点Docker Buildx缓存存储与GC配置问题咨询

我正在远程arm64平台使用Buildkit构建Docker镜像，已通过以下步骤配置buildx构建器：

$ docker buildx install
$ docker buildx create --name=multiarch --driver=docker-container
$ docker buildx create --name=multiarch --append --node=arm-docker --platform=linux/arm64 ssh://username@arm64.hostname.com
$ docker buildx use multiarch

配置正常后，执行docker buildx build --platform=linux/arm64 /path/to/mydockerfile/构建linux/arm64镜像：首次构建耗时较长，立即再次构建时缓存生效，但等待数分钟后再次构建，缓存失效；而直接在远程arm64节点构建时，缓存可长期保留。通过docker buildx prune确认缓存存储在本地主机。现咨询：

1. Buildkit层缓存是否确实存储在本地主机而非远程节点？
2. Buildkit缓存的存储目录是什么？
3. 如何查看缓存垃圾回收（GC）的活动记录（如日志）？
4. 如何配置Buildkit缓存GC以延长缓存有效期？
   同时需解答：多节点Docker构建中，层缓存的存储位置及缓存垃圾回收触发时机。

问题解答 #

1. Buildkit层缓存是否确实存储在本地主机而非远程节点？ #

是的，当使用docker-container驱动的buildx构建器时，Buildkit的缓存默认存储在本地主机的Buildkit容器中，而非远程构建节点。远程节点仅负责执行构建任务，构建产生的层会被传输回本地Buildkit容器进行缓存存储。这也是远程节点直接构建时缓存能长期保留的原因——此时缓存属于远程节点本地Docker引擎的缓存，和buildx跨节点缓存机制完全独立。

2. Buildkit缓存的存储目录是什么？ #

使用docker-container驱动时，Buildkit缓存存储在Buildkit容器的内部文件系统中，对应的本地主机目录取决于Docker的存储驱动配置：

• 默认情况下，Docker容器数据卷存储在/var/lib/docker/volumes/下，可通过以下命令定位对应Buildkit容器的卷：

  # 查找Buildkit容器名称
  docker ps --filter "name=buildx_buildkit_multiarch"
  # 查看容器挂载的卷信息
  docker inspect <buildkit-container-id> | grep -A 10 "Mounts"
  

• 若使用docker驱动（而非docker-container），Buildkit会直接复用本地Docker引擎的缓存，存储在/var/lib/docker/的镜像层目录中。

3. 如何查看缓存垃圾回收（GC）的活动记录（如日志）？ #

可通过查看Buildkit容器的日志获取GC活动记录：

# 查看对应buildx构建器的Buildkit容器日志
docker logs buildx_buildkit_multiarch_1

日志中会包含GC相关条目，比如清理触发时间、清理的层数量等。可通过过滤命令缩小范围：

docker logs buildx_buildkit_multiarch_1 | grep "gc"

4. 如何配置Buildkit缓存GC以延长缓存有效期？ #

Buildkit的GC行为可通过构建器创建参数或修改Buildkit配置调整：

• 创建构建器时指定GC参数：在docker buildx create命令中添加--buildkitd-flags设置阈值，例如设置缓存保留7天、最大占用100GB：

  docker buildx create --name=multiarch --driver=docker-container \
    --buildkitd-flags '--gc.keepduration 168h --gc.keepstorage 100GB'
  

  • --gc.keepduration：设置缓存保留时长，超过该时长的缓存会被清理
  • --gc.keepstorage：设置缓存最大占用空间，超出后触发GC
• 修改现有构建器的Buildkit配置：
  1. 通过docker inspect找到Buildkit容器对应卷的本地路径
  2. 编辑卷内的buildkitd.toml文件，添加GC配置：

     [gc]
       keepduration = "168h0m0s"
       keepstorage = "100GB"
     

  3. 重启Buildkit容器生效：

     docker restart buildx_buildkit_multiarch_1
     

多节点Docker构建：层缓存存储位置及GC触发时机 #

缓存存储位置 #

• 使用docker-container驱动的多节点buildx构建器时，所有构建节点的层缓存最终都会汇总存储在本地主机的Buildkit容器中，远程节点不会留存构建产生的缓存层（除非在远程节点单独执行构建）。
• 若使用kubernetes等分布式驱动，缓存可能存储在共享存储（如PVC）中，但默认docker-container驱动仍采用本地存储。

GC触发时机 #

Buildkit的GC默认在以下场景触发：

1. 构建完成后自动触发：每次构建结束后检查缓存占用，若超过阈值则启动GC
2. 定时触发：默认每小时运行一次GC（可通过配置修改）
3. 手动触发：执行docker buildx prune命令手动清理缓存
4. 缓存空间不足时触发：当缓存占用达到--gc.keepstorage设置的上限时，立即触发GC

你的场景中，等待数分钟后缓存失效，大概率是Buildkit默认GC在构建结束后或定时任务中清理了短期未被使用的缓存；而远程节点本地构建的缓存属于Docker引擎本地缓存，其GC策略（默认基于磁盘空间）更为宽松，因此能长期保留。

内容的提问来源于stack exchange，提问作者Régis B.