Monorepo中GitHub Actions结合Docker Buildx构建镜像遇权限问题

我有一个包含3个应用的monorepo，通过GitHub Actions执行测试。使用docker build时配置正常，但切换到docker buildx（用于镜像缓存）后出现权限错误，无法拉取本地构建的base:latest镜像。

配置详情 #

根目录package.json脚本 #

"build:docker.base": "docker buildx build . -f ./Dockerfile.base -t 'base:latest' --cache-from=type=gha --cache-to=type=gha,mode=max",
"prebuild:docker": "npm run build:docker.base",
"build:docker": "docker images && npx lerna run build:docker",

各应用package.json脚本 #

"build:docker": "APP_NAME=timer && docker buildx build . --build-arg APP_NAME=\"$APP_NAME\" -t \"superior/$APP_NAME:latest\" -f .././docker/Dockerfile.app --cache-from=type=gha --cache-to=type=gha,mode=max",

GitHub Actions Workflow #

- uses: docker/setup-buildx-action@v3

- name: Build docker images
    run: npm run build:docker

曾尝试使用docker/build-push-action@v5，但该Action仅支持单个Dockerfile，不符合多应用场景需求。

错误日志 #

> superior/timer:"build:docker"

> superior/timer@0.7.9 build:docker
> APP_NAME=timer && docker buildx build . --build-arg APP_NAME="$APP_NAME" -t "superior/$APP_NAME:latest" -f .././docker/Dockerfile.app --cache-from=type=gha --cache-to=type=gha,mode=max

#0 building with "builder-d54732d8-cdc2-43ef-ac94-230f778ffefa" instance using docker-container driver

#1 [internal] load build definition from Dockerfile.app
#1 transferring dockerfile: 1.26kB done
#1 DONE 0.0s

#2 [internal] load metadata for docker.io/library/node:21.7.2
#2 DONE 0.1s

#3 [internal] load metadata for docker.io/superior/base:latest
#3 ERROR: 拉取权限被拒绝，仓库不存在或需要授权：服务器消息：权限范围不足：授权失败
------
 > [internal] load metadata for docker.io/superior/base:latest:
------
警告：使用docker-container驱动未指定输出，构建结果仅保留在构建缓存中。如需推送到镜像仓库请使用--push，如需加载到Docker请使用--load
Dockerfile.app:21
--------------------
 19 |     COPY --from=superior/base:latest /app/apps/${APP_NAME}/src/schema src/schema
 20 | >>> COPY --from=superior/base:latest /app/node_modules/swagger-ui-dist node_modules/swagger-ui-dist
 21 |     
 22 |     COPY --from=superior/base:latest app/esbuild-dist/${APP_NAME} ${APP_NAME}
--------------------
错误：构建失败：superior/base:latest: 无法解析docker.io/superior/base:latest的源元数据：拉取权限被拒绝，仓库不存在或需要授权：服务器消息：权限范围不足：授权失败
npm ERR! Lifecycle脚本`build:docker`执行失败：
npm ERR! 错误：命令执行失败
npm ERR!   工作区：superior/timer@0.7.9
npm ERR!   位置：/home/runner/work/superior/superior/apps/timer

1. Buildx驱动隔离问题：Docker Buildx默认使用docker-container驱动，构建环境独立于本地Docker daemon。你构建的base:latest仅存在于Buildx的构建缓存中，未加载到本地Docker镜像列表，也未推送到远程仓库。应用构建时，Buildx会尝试从Docker Hub拉取superior/base:latest，但该镜像不存在于公共仓库，触发权限错误。
2. 镜像标签不匹配：根目录脚本给base镜像打的标签是base:latest，但应用Dockerfile中引用的是superior/base:latest，标签不一致导致无法匹配本地镜像。

方案1：将Base镜像加载到本地Docker #

在构建base镜像的命令中添加--load参数，让Buildx将镜像加载到本地Docker daemon，同时统一镜像标签：

修改根目录package.json的build:docker.base脚本：

"build:docker.base": "docker buildx build . -f ./Dockerfile.base -t 'superior/base:latest' --load --cache-from=type=gha --cache-to=type=gha,mode=max",

方案2：使用Buildx本地镜像协议引用 #

在应用Dockerfile的COPY --from指令中，通过docker-image://协议指定本地镜像，确保Buildx直接从构建缓存中读取：

修改应用Dockerfile中的引用：

COPY --from=docker-image://superior/base:latest /app/apps/${APP_NAME}/src/schema src/schema
COPY --from=docker-image://superior/base:latest /app/node_modules/swagger-ui-dist node_modules/swagger-ui-dist
COPY --from=docker-image://superior/base:latest app/esbuild-dist/${APP_NAME} ${APP_NAME}

同时确保base镜像的标签为superior/base:latest，且所有构建使用同一个Buildx实例。

方案3：推送Base镜像到私有仓库（适合团队协作） #

若需要团队共享base镜像，可推送到私有仓库（如GitHub Container Registry）：

1. 在GitHub Actions中登录私有仓库：

- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

2. 修改base镜像标签并添加--push参数：

"build:docker.base": "docker buildx build . -f ./Dockerfile.base -t 'ghcr.io/your-username/superior/base:latest' --push --cache-from=type=gha --cache-to=type=gha,mode=max",

3. 修改应用Dockerfile中的引用：

COPY --from=ghcr.io/your-username/superior/base:latest /app/apps/${APP_NAME}/src/schema src/schema

修改后，可在GitHub Actions的docker images步骤中查看是否存在superior/base:latest镜像，确认base镜像已成功加载到本地。

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