Ein GitLab-Backup, das Sie nicht wiederherstellen können, ist nur eine große Datei

Die meisten selbst gehosteten GitLab-Instanzen haben einen nächtlichen Backup-Job, und die meisten, die ihn eingerichtet haben, haben nie daraus wiederhergestellt. Das ist ein Problem, denn das Archiv, das GitLab erzeugt, ist absichtlich unvollständig. Stellen Sie es auf einem frischen Server ohne die Dateien wieder her, die es auslässt, und Ihre Repositories kommen zurück, während Ihre CI-Variablen, Zwei-Faktor-Einstellungen und Runner-Registrierungen zu unlesbaren Daten werden. Hier ist, was ein vollständiges GitLab-Backup enthält, wie Sie es bewegen, ohne Ihre Sicherheit zu schwächen, und wie Sie beweisen, dass es funktioniert.

Was der Backup-Task enthält und was er auslässt

Bei einer Paketinstallation (Omnibus) lautet der Backup-Task:

sudo gitlab-backup create STRATEGY=copy

Er schreibt ein einzelnes tar-Archiv in das Backup-Verzeichnis, üblicherweise /var/opt/gitlab/backups. Dieses Archiv enthält die Datenbank, die Git-Repositories, Uploads, LFS-Objekte, Artefakte der CI-Jobs, Pages, Packages und, falls aktiviert, die Container Registry. STRATEGY=copy kopiert die Daten, bevor es sie archiviert, was Fehler vermeidet, wenn sich Dateien während eines langen Backups auf einer stark genutzten Instanz ändern.

Was es absichtlich nicht enthält:

• /etc/gitlab/gitlab-secrets.json, die Schlüssel, mit denen sensible Spalten in der Datenbank verschlüsselt werden.
• /etc/gitlab/gitlab.rb, Ihre Konfiguration.
• TLS-Zertifikate und Schlüssel unter /etc/gitlab/ssl, falls Sie sie dort aufbewahren.
• Die SSH-Host-Keys in /etc/ssh, die die Clients Ihrer Entwickler bereits gespeichert haben.

GitLab lässt diese aus, damit ein einzelnes gestohlenes Archiv nicht sowohl die verschlüsselten Daten als auch den Schlüssel enthält, der sie entschlüsselt. Das ist eine vernünftige Überlegung, und sie überträgt Ihnen die Aufgabe, diese Dateien separat zu sichern.

Warum die Secrets-Datei so wichtig ist

CI/CD-Variablen, Registrierungs-Tokens der Runner, Seeds der Zwei-Faktor-Authentifizierung, Passwörter von Integrationen und etliche weitere Werte werden in der Datenbank mit Schlüsseln aus gitlab-secrets.json verschlüsselt. Stellen Sie die Datenbank ohne die passende Secrets-Datei wieder her, und GitLab startet, die Repositories sind da, und dann schlagen Pipelines fehl, Benutzer mit Zwei-Faktor-Authentifizierung können sich nicht anmelden, und Runner müssen neu registriert werden.

Sichern Sie das Konfigurationsverzeichnis als eigenes Artefakt:

sudo gitlab-ctl backup-etc --backup-path /var/opt/gitlab/config-backups

Das erzeugt ein tar von /etc/gitlab, einschließlich der Secrets-Datei. Bewahren Sie es an einem anderen Ort als das Datenarchiv auf, mit strengerem Zugriff, und halten Sie zusammengehörige Paare in Ihrer Aufbewahrungsrichtlinie zusammen. Ein Datenarchiv von Montag und eine Secrets-Datei von Donnerstag passen möglicherweise nicht zueinander, wenn dazwischen etwas rotiert wurde.

Bei Container-Installationen sind die Befehle dieselben, ausgeführt im Container, und /etc/gitlab ist das Volume, das Sie darauf gemappt haben. Stellen Sie sicher, dass dieses Volume Teil dessen ist, was Sie sichern. Es passiert leicht, nur das Daten-Volume zu sichern.

Holen Sie das Backup ab, schieben Sie es nicht

Das übliche Muster ist ein Cron-Job auf dem GitLab-Server, der das Archiv auf einen Backup-Host kopiert. Das bedeutet, der GitLab-Server hält Zugangsdaten, die in Ihre Backups schreiben können. Wird GitLab kompromittiert, ist es auch der Weg, die Backups zu erreichen und zu löschen.

Drehen Sie die Richtung um. Der Backup-Host verbindet sich mit GitLab und holt die Dateien ab. GitLab hält keine Zugangsdaten für den Backup-Host und hat keinen Netzwerkpfad zu ihm. Auf der GitLab-Seite begrenzen Sie, was der Schlüssel des Backup-Hosts tun kann, mit einem Forced Command in authorized_keys:

command="/usr/local/bin/backup-send",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAA... backup-puller

wobei backup-send ein kleines Skript ist, das nichts anderes tut, als das neueste Datenarchiv und sein passendes Konfigurationsarchiv zu streamen. Auf dem Backup-Host holt der Job beide ab, prüft ihre Größen und Prüfsummen und alarmiert, wenn eines fehlt oder älter ist als erwartet.

Setzen Sie die Richtung dann an der Firewall durch: Der Backup-Host darf Verbindungen zu GitLab öffnen, nichts im Netzwerk von GitLab darf Verbindungen zum Backup-Host öffnen.

Restore-Regeln, die Sie kennen sollten, bevor Sie sie brauchen

Ein GitLab-Backup lässt sich nur auf dieselbe GitLab-Version und Edition wiederherstellen, die es erzeugt hat. Schreiben Sie die Version zum Backup-Zeitpunkt in den Archivnamen oder in eine Begleitdatei:

sudo gitlab-rake gitlab:env:info > gitlab-env-$(date +%F).txt

Verlieren Sie den Server und der einzige Installer, den Sie finden, ist neuer, installieren Sie zuerst die alte Version, stellen wieder her und aktualisieren dann entlang des unterstützten Pfads. Das vorher zu wissen macht aus einer langen Nacht ein geplantes Verfahren.

Der Restore selbst, auf einer frischen Installation der passenden Version:

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
# put gitlab-secrets.json and gitlab.rb back into /etc/gitlab first
sudo gitlab-ctl reconfigure
sudo gitlab-backup restore BACKUP=<archive-id>
sudo gitlab-ctl restart
sudo gitlab-rake gitlab:check SANITIZE=true
sudo gitlab-rake gitlab:doctor:secrets

Der letzte Befehl ist der, der zählt. gitlab:doctor:secrets geht die verschlüsselten Spalten durch und meldet alle, die es nicht entschlüsseln kann. Meldet es Fehler, gehören Ihre Secrets-Datei und Ihr Datenarchiv nicht zusammen.

Beweisen Sie es nach Plan

Ein Restore, den Sie nicht getestet haben, ist eine Hoffnung. Machen Sie ihn zur Routine:

1. Bauen Sie eine Wegwerf-VM in einem isolierten Netzwerk ohne Route zur Produktion.
2. Installieren Sie die GitLab-Version, die mit dem Backup festgehalten wurde.
3. Stellen Sie das neueste Paar aus Konfiguration und Daten wieder her.
4. Führen Sie gitlab:check und gitlab:doctor:secrets aus.
5. Klonen Sie ein bekanntes Repository, vergleichen Sie seinen letzten Commit-Hash mit der Produktion und öffnen Sie die Seite mit den CI-Variablen eines Projekts.
6. Halten Sie das Ergebnis und die benötigte Zeit fest, dann zerstören Sie die VM.

Stoppen Sie auch die Zeit. Die Dauer des Restores ist Ihre tatsächliche Wiederherstellungszeit, und sie ist auf einer großen Instanz meist länger, als man schätzt.

Eine zweite, unabhängige Kopie des Codes

Das vollständige Backup schützt die gesamte Anwendung. Für die Repositories selbst gibt Ihnen ein einfacher Mirror eine zweite Kopie, die überhaupt nicht von den Werkzeugen von GitLab abhängt:

git clone --mirror git@gitlab.example.com:group/project.git
git -C project.git remote update --prune

Führen Sie das von der Backup-Seite aus für die Repositories aus, deren Verlust Sie sich nicht leisten können. Es stellt keine Issues oder Merge Requests wieder her, aber es bedeutet, dass Ihre Quellcode-Historie selbst ein Backup-Archiv überlebt, das Sie nicht lesen können.

Die Kurzfassung

• gitlab-backup create ist ein halbes Backup. gitlab-ctl backup-etc ist die andere Hälfte.
• Halten Sie Secrets und Daten in zusammengehörigen Paaren, getrennt gespeichert, mit strengerem Zugriff auf die Secrets.
• Die Backup-Seite holt ab. GitLab hat keinen Pfad zu seinen eigenen Backups.
• Halten Sie die GitLab-Version bei jedem Archiv fest.
• Stellen Sie nach Plan wieder her, und führen Sie jedes Mal gitlab:doctor:secrets aus.

So schützen wir die GitLab-Instanzen, die wir für Kunden in unseren eigenen Rechenzentren betreiben. Wenn Sie Ihren eigenen Restore-Pfad prüfen lassen möchten, helfen wir gern.

Mit einem Ingenieur sprechen

related line: Verwandt: Managed Source Control auf GitLab · Managed Office-Dokumente auf Nextcloud

footer line: Veröffentlicht am 22. Oktober 2026. Alle Notizen aus der Praxis