Zum Inhalt springen

Docker-Layer-Caching in der CI mit Buildx

Zuletzt aktualisiert am

CI-Runner starten leer, daher beginnt jeder docker build ohne Layer und baut alles neu. Bei einem typischen App-Image bedeutet das, dass bei jedem Push alle Abhängigkeiten erneut installiert werden. Layer-Caching behebt das, indem der Build-Cache zwischen den Läufen gespeichert wird. Dieser Leitfaden zeigt die beiden Backends, die in GitHub Actions wichtig sind, und wie Sie ein Dockerfile schreiben, das den Cache tatsächlich trifft.

Zuerst das Dockerfile anpassen

Ein Cache ist nur nützlich, wenn die Layer zwischen den Builds identisch bleiben. Docker invalidiert einen Layer und alle nachfolgenden Layer, sobald sich die Anweisung oder die kopierten Dateien ändern. Setzen Sie selten veränderte Inhalte nach oben:

FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-slim
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
CMD ["node", "dist/server.js"]

Der Layer npm ci wird wiederverwendet, bis sich das Lockfile ändert. Wenn Sie COPY . . vor der Installation geschrieben haben, würde jede Quellcode-Änderung alles neu installieren. Fügen Sie eine .dockerignore mit .git, node_modules und Build-Ausgaben hinzu, damit unabhängige Dateien den Cache nicht ungültig machen.

Für Paketmanager halten BuildKit-Cache-Mounts den Download-Cache auch dann bereit, wenn der Layer neu gebaut wird:

RUN --mount=type=cache,target=/root/.npm npm ci

Beachten Sie, dass Cache-Mounts im BuildKit-Builder liegen und nicht im Layer-Cache. Deshalb brauchen sie in CI eine eigene Behandlung (siehe unten).

Backend 1: der GitHub Actions Cache (type=gha)

Die einfachste Einrichtung nutzt build-push-action von Docker und den GitHub-Cache-Dienst:

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    context: .
    push: false
    tags: myapp:ci
    cache-from: type=gha
    cache-to: type=gha,mode=max

mode=max exportiert alle Layer, einschließlich der Layer von Zwischenstufen in einem Multi-Stage-Build. Der Standard, mode=min, exportiert nur die Layer des finalen Images, was für Multi-Stage-Dockerfiles schlecht passt. Verwenden Sie max und akzeptieren Sie den größeren Cache.

Abwägungen, auf Basis der Limits in der GitHub-Dokumentation: Der Cache zählt zu den 10 GB Cache-Speicher des Repositorys, Einträge, die 7 Tage nicht genutzt wurden, werden entfernt, und es gilt die Branch-Begrenzung wie bei jedem Actions-Cache. Große Images können das Kontingent schnell füllen und Ihre anderen Caches verdrängen. Verwenden Sie einen scope pro Image, wenn ein Repository mehrere baut:

cache-from: type=gha,scope=api
cache-to: type=gha,scope=api,mode=max

Backend 2: ein Registry-Cache (type=registry)

Speichern Sie den Cache als Image in Ihrer Registry (GHCR, ECR, Docker Hub). Er wird nicht auf das Actions-Cache-Kontingent angerechnet, bleibt länger erhalten und lässt sich mit Entwickler-Rechnern und anderen CI-Systemen teilen:

- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
    cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache
    cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache,mode=max

Der Job benötigt permissions: packages: write, um nach GHCR zu pushen. Für ECR verwenden Sie in cache-to die Option image-manifest=true,oci-mediatypes=true, da ECR für Cache-Manifeste OCI-Medientypen verlangt. Prüfen Sie die Dokumentation von AWS und Docker für Ihre Registry, die Unterstützung variiert.

Welches Backend Sie wählen sollten

type=ghatype=registrytype=local + actions/cache
EinrichtungZwei ZeilenLogin und ein Cache-TagZusätzlicher Verschiebeschritt
SpeicherlimitTeilt sich 10 GB Repo-CacheIhr Registry-KontingentTeilt sich 10 GB Repo-Cache
Wird mit Laptops geteiltNeinJaNein
Pull-KostenCache-DienstRegistry-Egress, oft innerhalb der RegionCache-Dienst

Für die meisten Teams: Beginnen Sie mit type=gha und wechseln Sie zu type=registry, wenn die Images groß sind oder Sie auch außerhalb von GitHub bauen.

Cache-Mounts in CI

Daten aus RUN --mount=type=cache werden von cache-to nicht exportiert. Wenn Sie für Paket-Downloads auf Cache-Mounts setzen, können Sie diese mit einem Hilfswerkzeug wie reproducible-containers/buildkit-cache-dance persistieren. Alternativ verzichten Sie in CI auf Mounts und verlassen sich auf das Layer-Caching des Installationsschritts. Für die meisten Apps ist die zweite Option einfacher.

Prüfen, ob es funktioniert

Im Build-Log sind gecachte Schritte mit CACHED markiert. Wenn Ihr Installations-Layer jedes Mal läuft, achten Sie auf diese Ursachen:

  • Ein COPY . . vor dem Installationsschritt.
  • Ein Build-Argument oder Zeitstempel, der sich pro Lauf ändert (ARG BUILD_DATE vor der Installation).
  • Fehlende .dockerignore, sodass sich der Kontext-Hash durch unabhängige Dateien ändert.
  • Ein mode=min-Cache bei Multi-Stage-Builds.
  • Ein Basis-Image-Tag wie node:22-slim, das sich verschoben hat. Das ist korrektes Verhalten, invalidiert aber alles danach. Fixieren Sie das Image über den Digest, wenn Sie vorhersagbare Cache-Treffer wollen, und aktualisieren Sie es mit Dependabot.

Weitere Beschleunigungen für Image-Builds

  • Bauen Sie in CI nur eine Plattform, sofern Sie keine Multi-Arch-Images ausliefern. Emulierte arm64-Builds unter QEMU sind um ein Vielfaches langsamer als native; verwenden Sie für diesen Job einen nativen arm64-Runner, wenn Sie beides benötigen.
  • Verwenden Sie ein schlankes oder distroless Basis-Image, um Pushes und Pulls zu verkleinern.
  • Führen Sie Tests in einem späteren Job mit load: true gegen das gebaute Image aus, anstatt es neu zu bauen.

FAQ

Bietet GitHub integriertes Docker-Layer-Caching?

GitHub-gehostete Runner speichern Docker-Layer nicht zwischen Jobs. Sie exportieren und importieren den Cache mit Buildx, wie oben beschrieben.

Kann ich Layer-Caching auch ohne Buildx nutzen?

Der klassische Builder kann einen Cache nicht auf dieselbe Weise aus einem Remote-Speicher importieren. Verwenden Sie BuildKit über docker buildx oder build-push-action.

Warum ist mein Cache größer als mein Image?

mode=max speichert jede Stage und jeden Zwischen-Layer. Das ist erwartet.

Ist der Registry-Cache für Forks sicher?

Pull Requests aus Forks erhalten keinen Schreibzugriff auf Ihre Registry oder Secrets. Verwenden Sie cache-from nur für diese Runs und schreiben Sie den Cache aus main.

Nächste Schritte

Im Artikel So beschleunigen Sie GitHub Actions finden Sie Hinweise zur restlichen Pipeline, und mit dem Kostenrechner wandeln Sie eingesparte Minuten in Euro um. Wenn Ihre Image-Builds CPU-gebunden sind, führt der Vergleichsmodus von compiler.dev denselben Job auf einer größeren Maschine aus, sodass Sie Zeit und Preis pro Run vergleichen können.

Führen Sie diesen Docker-Build auf compiler.dev aus Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen