Gitlab CI/CD中Docker跨架构构建无法复用前置阶段缓存的问题

问题背景 #

• 环境：GitLab CI/CD + 自托管AMD64、ARM64架构Runner（禁用架构模拟，模拟速度过慢）
• 构建方案：两阶段构建
  1. 第一阶段：分别构建对应架构镜像并推送到缓存仓库
  2. 第二阶段：拉取缓存构建多架构镜像并推送到最终仓库
• 核心问题：push阶段未完全复用缓存，部分步骤重新执行，甚至在yarn global add gatsby-cli步骤出现架构相关失败

当前配置 #

.gitlab-ci.yml #

image: docker:20

variables:
    GROUP_NAME: "group"
    PROJECT_NAME: "project"
    BRANCH_NAME: "main"

    LATEST_NAME: "$PROJECT_NAME:latest"
    REGISTRY_LATEST_NAME: "$CI_REGISTRY/$GROUP_NAME/$PROJECT_NAME/$LATEST_NAME"
    REGISTRY_CACHE_NAME_PREFIX: "$CI_REGISTRY/$GROUP_NAME/$PROJECT_NAME/$PROJECT_NAME:cache"
    CACHE_AMD64: "$REGISTRY_CACHE_NAME_PREFIX-amd64"
    CACHE_ARM64: "$REGISTRY_CACHE_NAME_PREFIX-arm64"

    BACKEND_URL: "$BACKEND_URL" # 构建所需环境变量

services:
    - docker:20-dind

before_script:
  - docker context create builder-context
  - docker buildx create --name builderx --driver docker-container --bootstrap --use builder-context
  - docker login $CI_REGISTRY -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD

stages:
  - build
  - push

build_amd64:
  stage: build
  script:
    - docker buildx build --build-arg BACKEND_URL="${BACKEND_URL}" --build-arg BUILDKIT_INLINE_CACHE=1 --cache-from="$CACHE_AMD64" --tag "$CACHE_AMD64" --push --platform=linux/amd64 .
  tags:
    - amd64

build_arm64:
  stage: build
  script:
    - docker buildx build --build-arg BACKEND_URL="${BACKEND_URL}" --build-arg BUILDKIT_INLINE_CACHE=1 --cache-from="$CACHE_ARM64" --tag "$CACHE_ARM64" --push --platform=linux/arm64 .
  tags:
    - arm64

push:
  stage: push
  script:
    - docker buildx build --build-arg BACKEND_URL="${BACKEND_URL}" --build-arg BUILDKIT_INLINE_CACHE=1 --cache-from="$CACHE_AMD64" --cache-from="$CACHE_ARM64" --tag "$REGISTRY_LATEST_NAME" --push --platform=linux/amd64,linux/arm64 .

Dockerfile #

# NOTE: 拆分为3个阶段尝试保证确定性，但可能存在问题

### Dependencies Installer Stage ###
FROM node:18-bullseye as installer

WORKDIR /app/admin
COPY yarn.lock /app/admin/
COPY package.json /app/admin/
RUN yarn global add gatsby-cli # <--- Push阶段常在此失败，与Runner架构相关
RUN yarn install --silent --frozen-lockfile
### --- ###

### Builder stage ###
FROM node:18-bullseye as builder 

WORKDIR /app/admin
COPY . .
RUN rm -rf node_modules

COPY --from=installer /app/admin /app/admin
COPY --from=installer /usr/local/bin/ /usr/local/bin/
COPY --from=installer /usr/local/share/.config/yarn/global /usr/local/share/.config/yarn/global

# 静态站点生成后无法读取环境变量，需提前注入
ARG BACKEND_URL
ENV GATSBY_BACKEND_URL $BACKEND_URL
RUN gatsby build
### --- ###

### Serve stage ###
FROM nginx:stable-alpine
EXPOSE 80 
COPY ./nginx/nginx.conf /etc/nginx/conf.d/default.conf 
COPY --from=builder /app/admin/public /usr/share/nginx/html
ENTRYPOINT ["nginx", "-g", "daemon off;"]
### --- ###

问题根源分析 #

1. 跨架构层哈希不匹配：不同架构的基础镜像（如node:18-bullseye）底层层哈希不同，导致后续依赖安装、命令执行的层哈希无法统一
2. 缓存匹配逻辑模糊：push阶段未明确指定缓存与架构的对应关系，buildx无法精准匹配对应架构的缓存层
3. Dockerfile层设计不合理：COPY --from=installer /app/admin /app/admin覆盖整个目录，易引入不必要的层变化；全局安装gatsby-cli的路径在不同架构下存在隐性差异，导致层哈希不一致

修复方案 #

一、重构Dockerfile，保证跨架构层一致性 #

### 全局依赖安装阶段 ###
FROM node:18-bullseye as global-deps
# 指定全局安装路径，避免架构相关路径差异
RUN yarn global add gatsby-cli --prefix /usr/local

### 项目依赖安装阶段 ###
FROM node:18-bullseye as installer
WORKDIR /app/admin
COPY yarn.lock package.json ./
RUN yarn install --silent --frozen-lockfile

### 构建阶段 ###
FROM node:18-bullseye as builder 
WORKDIR /app/admin
# 先复制全局依赖、项目依赖，再复制代码，最大化缓存复用
COPY --from=global-deps /usr/local /usr/local
COPY --from=installer /app/admin/node_modules ./node_modules
COPY --from=installer /app/admin/yarn.lock /app/admin/package.json ./
COPY . .

ARG BACKEND_URL
ENV GATSBY_BACKEND_URL $BACKEND_URL
RUN gatsby build

### 部署阶段 ###
FROM nginx:stable-alpine
EXPOSE 80 
COPY ./nginx/nginx.conf /etc/nginx/conf.d/default.conf 
COPY --from=builder /app/admin/public /usr/share/nginx/html
ENTRYPOINT ["nginx", "-g", "daemon off;"]

关键优化点：

• 拆分全局依赖与项目依赖安装，隔离架构敏感操作
• 全局安装时指定--prefix /usr/local，强制统一路径
• 分步骤复制文件，避免全目录覆盖引发的层哈希变化

二、调整GitLab CI配置，优化缓存匹配 #

1. 明确缓存与架构的对应关系
   修改push阶段的buildx命令，指定每个架构对应的缓存源：

push:
  stage: push
  script:
    - docker buildx build 
        --build-arg BACKEND_URL="${BACKEND_URL}" 
        --build-arg BUILDKIT_INLINE_CACHE=1 
        --cache-from type=registry,ref=$CACHE_AMD64,platform=linux/amd64 
        --cache-from type=registry,ref=$CACHE_ARM64,platform=linux/arm64 
        --tag "$REGISTRY_LATEST_NAME" 
        --push 
        --platform linux/amd64,linux/arm64 .

2. 配置多架构兼容的buildx builder
   在before_script中指定builder支持的平台：

before_script:
  - docker context create builder-context
  - docker buildx create --name builderx --driver docker-container --bootstrap --use builder-context --platform linux/amd64,linux/arm64
  - docker login $CI_REGISTRY -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD

3. push阶段使用多架构Runner
   避免在单架构Runner上执行push阶段导致的架构模拟，可配置一个支持多架构的Runner，或不指定架构标签让GitLab自动分配兼容Runner。

调试方法 #

1. 查看详细构建日志
   在build命令中添加--progress=plain参数，查看每层的缓存复用情况：

docker buildx build --progress=plain --platform linux/amd64,linux/arm64 .

日志中标记为CACHED的层是复用的，无标记则为重新构建，可定位问题步骤。

2. 检查缓存镜像层信息
   使用buildx imagetools inspect查看缓存镜像的层哈希：

docker buildx imagetools inspect $CACHE_AMD64
docker buildx imagetools inspect $CACHE_ARM64

对比两个镜像的层哈希，找到不一致的层对应的Dockerfile步骤。

3. 本地验证跨架构层一致性
   本地分别构建两种架构的镜像，对比层历史：

# 构建AMD64镜像并查看层历史
docker buildx build --platform linux/amd64 --tag cache-amd64 .
docker history cache-amd64

# 构建ARM64镜像并查看层历史
docker buildx build --platform linux/arm64 --tag cache-arm64 .
docker history cache-arm64

对比哈希不同的层，定位问题根源。

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