使用 GitHub Actions 进行缓存管理

目录

本页包含在使用 GitHub Actions 时使用缓存存储后端的示例。

注意

有关缓存存储后端的更多详细信息，请参阅缓存存储后端。

Inline 缓存

在大多数情况下，您会希望使用inline 缓存导出器。然而，请注意 inline 缓存导出器仅支持 min 缓存模式。要使用 max 缓存模式，请使用带有 cache-to 选项的 registry 缓存导出器单独推送镜像和缓存，如registry 缓存示例所示。

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: user/app:latest
          cache-from: type=registry,ref=user/app:latest
          cache-to: type=inline

镜像仓库缓存

您可以使用registry 缓存导出器从 registry 上的缓存清单或（特殊）镜像配置导入/导出缓存。

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: user/app:latest
          cache-from: type=registry,ref=user/app:buildcache
          cache-to: type=registry,ref=user/app:buildcache,mode=max

GitHub 缓存

缓存后端 API

可用性： 实验性

GitHub Actions 缓存导出器后端使用GitHub 缓存服务 API来获取和上传缓存块。这就是为什么您只应在 GitHub Action 工作流程中使用此缓存后端的原因，因为 url ($ACTIONS_RESULTS_URL) 和 token ($ACTIONS_RUNTIME_TOKEN) 属性仅在工作流程上下文中填充。

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: user/app:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

重要

从2025 年 4 月 15 日开始，将仅支持 GitHub 缓存服务 API v2。

如果在构建过程中遇到以下错误

ERROR: failed to solve: This legacy service is shutting down, effective April 15, 2025. Migrate to the new service ASAP. For more information: https://gh.io/gha-cache-sunset

您可能正在使用仅支持旧版 GitHub 缓存服务 API v1 的过期工具。根据您的使用情况，您需要升级到的最低版本如下

  • Docker Buildx >= v0.21.0
  • BuildKit >= v0.20.0
  • Docker Compose >= v2.33.1
  • Docker Engine >= v28.0.0（如果您使用启用了 containerd 镜像存储的 Docker 驱动程序进行构建）

如果您在 GitHub 托管的 Runner 上使用 docker/build-push-action 或 docker/bake-action 进行构建，Docker Buildx 和 BuildKit 已是最新版本，但在自托管的 Runner 上，您可能需要自行更新。或者，您可以使用 docker/setup-buildx-action Action 来安装最新版本的 Docker Buildx

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

如果您使用 Docker Compose 进行构建，可以使用 docker/setup-compose-action Action

- name: Set up Docker Compose
  uses: docker/setup-compose-action@v1
  with:
   version: latest

如果您使用启用了 containerd 镜像存储的 Docker Engine 进行构建，可以使用 docker/setup-docker-action Action

-
  name: Set up Docker
  uses: docker/setup-docker-action@v4
  with:
    version: latest
    daemon-config: |
      {
        "features": {
          "containerd-snapshotter": true
        }
      }

缓存挂载

BuildKit 默认不保留 GitHub Actions 缓存中的缓存挂载。如果您希望将缓存挂载放入 GitHub Actions 缓存并在构建之间重用，可以使用reproducible-containers/buildkit-cache-dance提供的解决方案。

此 GitHub Action 会创建临时容器，以便在 Docker 构建步骤中提取和注入缓存挂载数据。

以下示例展示了如何在 Go 项目中使用此解决方案。

build/package/Dockerfile 中的示例 Dockerfile

FROM golang:1.21.1-alpine as base-build

WORKDIR /build
RUN go env -w GOMODCACHE=/root/.cache/go-build

COPY go.mod go.sum ./
RUN --mount=type=cache,target=/root/.cache/go-build go mod download

COPY ./src ./
RUN --mount=type=cache,target=/root/.cache/go-build go build -o /bin/app /build/src
...

示例 CI Action

name: ci

on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

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

      - name: Docker meta
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: user/app
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Go Build Cache for Docker
        uses: actions/cache@v4
        with:
          path: go-build-cache
          key: ${{ runner.os }}-go-build-cache-${{ hashFiles('**/go.sum') }}

      - name: Inject go-build-cache
        uses: reproducible-containers/buildkit-cache-dance@4b2444fec0c0fb9dbf175a96c094720a692ef810 # v2.1.4
        with:
          cache-source: go-build-cache

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          cache-from: type=gha
          cache-to: type=gha,mode=max
          file: build/package/Dockerfile
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          platforms: linux/amd64,linux/arm64

有关此解决方案的更多信息，请参阅GitHub 仓库。

本地缓存

警告

目前，旧的缓存条目不会被删除，因此缓存大小会持续增长。以下示例使用 Move cache 步骤作为解决方案（有关更多信息，请参阅moby/buildkit#1896）。

您还可以利用GitHub 缓存，结合使用actions/cache和local cache exporter 与此 action。

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

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

      - name: Cache Docker layers
        uses: actions/cache@v4
        with:
          path: ${{ runner.temp }}/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-buildx-

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: user/app:latest
          cache-from: type=local,src=${{ runner.temp }}/.buildx-cache
          cache-to: type=local,dest=${{ runner.temp }}/.buildx-cache-new,mode=max

      - # Temp fix
        # https://github.com/docker/build-push-action/issues/252
        # https://github.com/moby/buildkit/issues/1896
        name: Move cache
        run: |
          rm -rf ${{ runner.temp }}/.buildx-cache
          mv ${{ runner.temp }}/.buildx-cache-new ${{ runner.temp }}/.buildx-cache
页面选项