Buildkit Cache Repository 镜像文档

一、镜像概述

Buildkit Cache Repository 镜像是一个基于 Buildkit 的缓存服务镜像，专为 GitHub Actions 环境设计，用于存储和管理 Docker 构建过程中的中间层缓存。通过持久化构建缓存，该镜像可有效减少重复构建步骤（如依赖下载、编译过程等）的执行频率，显著提升 GitHub Actions 中 Docker 镜像构建的效率。

二、核心功能与特性

2.1 核心功能

• 构建层缓存管理：存储 Docker 构建过程中产生的中间层（layer）缓存，避免重复构建相同层。
• GitHub Actions 原生集成：支持与 GitHub Actions 工作流无缝对接，通过环境变量和卷挂载实现缓存持久化。
• 多存储后端支持：兼容本地文件系统、网络存储（如 NFS）及对象存储（如 S3），灵活适配不同存储需求。

2.2 关键特性

• 轻量级设计：基于 Alpine 或精简基础镜像，镜像体积小，启动速度快。
• 缓存策略可配置：支持缓存模式（如 min/max）、有效期设置，平衡缓存效率与存储占用。
• 跨构建会话共享：缓存可在同一仓库的多次构建或不同分支间共享，进一步提升复用率。

三、使用场景与适用范围

3.1 适用环境

• GitHub Actions 构建流程：作为 CI/CD 流程的一部分，加速 Docker 镜像构建步骤。
• 本地开发环境：辅助本地 Docker 构建，减少重复依赖安装或编译耗时。

3.2 典型场景

• 频繁构建项目：如每日多次提交的活跃项目，避免重复执行耗时构建步骤。
• 多阶段构建项目：缓存中间阶段产物（如编译后的二进制文件、依赖包），缩短最终镜像构建时间。
• 依赖密集型构建：如前端 npm/yarn 依赖、后端 Maven/Gradle 依赖下载，通过缓存大幅减少网络请求耗时。

四、使用方法与配置说明

4.1 快速启动（Docker Run）

通过 docker run 命令直接启动缓存服务，默认使用本地文件系统存储缓存：

docker run -d \
  --name buildkit-cache \
  -v /path/to/local/cache:/cache \  # 本地缓存目录挂载（持久化缓存）
  -e BUILDKIT_CACHE_REPO=local:///cache \  # 缓存仓库地址（本地路径）
  -e CACHE_MODE=max \  # 缓存模式（max：保留所有层；min：仅保留最终层）
  -p 8080:8080 \  # 可选：暴露缓存服务端口（如需远程访问）
  myregistry/buildkit-cache-repo:latest

4.2 GitHub Actions 集成示例

在 GitHub Actions 工作流中，通过卷挂载或服务依赖方式集成缓存服务，以下为典型 workflow 配置：

# .github/workflows/build.yml
name: Build Docker Image with Cache

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    services:
      buildkit-cache:
        image: myregistry/buildkit-cache-repo:latest
        volumes:
          - buildkit-cache-volume:/cache  # 使用命名卷持久化缓存
        env:
          BUILDKIT_CACHE_REPO: local:///cache
          CACHE_MODE: max

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          driver-opts: |
            image=myregistry/buildkit-cache-repo:latest
            cache-repo=local:///cache  # 指向缓存服务的本地路径（需与服务卷一致）

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: false
          cache-from: type=registry,ref=local:///cache  # 从缓存仓库拉取缓存
          cache-to: type=registry,ref=local:///cache,mode=max  # 推送缓存到仓库

volumes:
  buildkit-cache-volume:  # 命名卷用于跨 job 持久化缓存（GitHub Actions 中卷生命周期与 runner 一致）

4.3 Docker Compose 配置示例

通过 docker-compose.yml 定义缓存服务及构建环境，适用于本地开发或自托管 CI 环境：

# docker-compose.yml
version: '3.8'

services:
  buildkit-cache:
    image: myregistry/buildkit-cache-repo:latest
    volumes:
      - ./buildkit-cache:/cache  # 本地目录挂载（相对路径）
    environment:
      - BUILDKIT_CACHE_REPO=local:///cache
      - CACHE_MODE=max
      - CACHE_TTL=7d  # 缓存有效期（默认无限制，可选：7d=7天，30m=30分钟）
    restart: unless-stopped

  builder:
    image: docker:dind
    depends_on:
      - buildkit-cache
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./:/app  # 项目代码挂载
    environment:
      - DOCKER_BUILDKIT=1  # 启用 Buildkit
      - BUILDKIT_CACHE_REPO=local:///cache  # 指向缓存服务的缓存目录
    command: sh -c "cd /app && docker build --cache-from=type=registry,ref=local:///cache --cache-to=type=registry,ref=local:///cache,mode=max -t myapp:latest ."

五、配置参数详解

5.1 环境变量配置

5.2 卷挂载配置

六、注意事项

1. 缓存清理：如未设置 CACHE_TTL，缓存将持续累积，建议定期清理过期缓存或配置自动清理策略（如通过 cron 任务）。
2. 存储容量：根据项目构建频率和缓存模式（max 模式缓存体积较大），确保存储后端有足够容量。
3. 兼容性：需配合 Buildkit 构建工具使用（Docker 18.09+ 内置 Buildkit，或通过 docker buildx 启用）。
4. 安全性：如使用远程存储（如 S3），确保访问密钥权限最小化，避免缓存数据泄露。