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=gha | type=registry | type=local + actions/cache | |
|---|---|---|---|
| Einrichtung | Zwei Zeilen | Login und ein Cache-Tag | Zusätzlicher Verschiebeschritt |
| Speicherlimit | Teilt sich 10 GB Repo-Cache | Ihr Registry-Kontingent | Teilt sich 10 GB Repo-Cache |
| Wird mit Laptops geteilt | Nein | Ja | Nein |
| Pull-Kosten | Cache-Dienst | Registry-Egress, oft innerhalb der Region | Cache-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_DATEvor 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: truegegen 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.
Verwandt
- Docker-Build in der CI langsam? Ursache finden und behebenDocker-Build in CI zu langsam? Build-Kontext, .dockerignore, Layer-Reihenfolge, Cache-Misses und BuildKit prüfen und zuerst das größte Problem beheben.
- Caching in GitHub Actions: Schlüssel, Limits, BeispieleWie actions/cache, setup-*-Caching und restore-keys funktionieren: mit sofort einsetzbarem YAML, Cache-Geltungsbereich, Größenlimits und typischen Fehlern.
- Docker Pull Rate Limit in GitHub Actions: Lösungen"toomanyrequests: You have reached your pull rate limit" in GitHub Actions beheben: Docker-Hub-Limits, docker/login-action, Mirrors und GHCR-Alternativen.
- Docker Build GitHub Actions Workflow VorlageFertiger GitHub-Actions-Workflow zum Bauen von Docker-Images mit Buildx, GitHub-Cache-Layern und einem Push zu GHCR auf main, mit minimalen Berechtigungen.