使用--cache-from时Docker Build未复用缓存层问题排查求助

以下是针对你的场景（SemaphoreCI + BuildKit + 多阶段Dockerfile）的具体排查步骤：

1. 验证缓存镜像的有效性 #

• 检查拉取的缓存镜像是否包含BuildKit缓存元数据：在Semaphore构建步骤中添加命令

  docker inspect gcr.io/test-app/test-app-img:active | grep -A 15 "BuildKit"
  

  若输出中没有Cache相关字段，说明该镜像构建时未添加--build-arg BUILDKIT_INLINE_CACHE=1，导致无法作为缓存源。
• 确认active标签指向的是正确的镜像：执行docker images gcr.io/test-app/test-app-img:active，查看镜像ID是否与之前正常复用缓存时的ID一致，避免标签被意外覆盖。

2. 确认BuildKit环境配置正确 #

• 验证Semaphore环境中BuildKit是否启用：添加命令

  echo $DOCKER_BUILDKIT && docker buildx version
  

  确保DOCKER_BUILDKIT值为1，且docker buildx版本支持内联缓存功能（建议Docker版本≥19.03）。
• 检查生成缓存镜像的原始命令：必须确保第一次构建active镜像时就添加了--build-arg BUILDKIT_INLINE_CACHE=1，否则镜像不会携带缓存元数据，后续--cache-from无效。

3. 排查Dockerfile层的隐性变更 #

• 检查基础镜像是否更新：执行docker inspect ruby:3.1.3 --format '{{.Id}}'，对比当前构建与之前正常构建时的基础镜像ID。若官方ruby:3.1.3镜像被更新（即使tag不变），所有基于它的层都会失效。
• 检查RUN命令的细微差异：比如你的apt-get install命令中libpq-dev和npm之间有两个空格，若之前的Dockerfile是单个空格，会导致层哈希变化，缓存失效。逐行对比RUN命令的字符内容，包括换行符、空格、命令参数。
• 多阶段构建的缓存复用：base阶段的RUN命令与build阶段完全重复，需确认缓存镜像中是否包含base阶段的层。BuildKit默认会复用同阶段的缓存，但跨阶段需确保缓存源镜像包含对应阶段的构建元数据。

4. 排查SemaphoreCI环境的变化 #

• 检查Docker权限与镜像拉取完整性：添加docker pull --verbose gcr.io/test-app/test-app-img:active，查看拉取过程是否有报错（如权限不足、镜像损坏），确保镜像完整拉取到Semaphore环境中。
• 确认Semaphore的Docker daemon配置：若使用Docker-in-Docker（DinD），检查DinD版本是否变更，或者是否开启了缓存清理策略，导致临时缓存无法被利用（不过你使用的是远程缓存镜像，此点优先级较低）。

5. 分析构建日志细节 #

• 启用详细构建日志：修改构建命令为

  DOCKER_BUILDKIT=1 docker build --progress=plain --cache-from "gcr.io/test-app/test-app-img:active" -t "gcr.io/test-app/test-app-img:$SEMAPHORE_GIT_SHA" --build-arg BUILDKIT_INLINE_CACHE=1 .
  

  查看每个步骤的哈希值，对比缓存镜像中的对应层哈希，确定哪一步开始缓存失效。
• 查找日志中的CACHED标记：若没有任何步骤显示CACHED，说明BuildKit完全无法匹配缓存源；若部分步骤未缓存，重点排查对应步骤的内容变化。

内容的提问来源于stack exchange，提问作者usha