Wiederherstellung · Dokumentation

Erst eine Wiederherstellungsübung macht aus „wir haben Backups“ ein „wir können wiederherstellen“. Führen Sie eine vor dem Produktivstart durch und erneut nach jeder Schlüsselrotation.

Einen Satz prüfen

Führen Sie php artisan vaultigen:backup:verify /path/to/completed-set mit den ursprünglichen Wiederherstellungsvoraussetzungen und derselben Datenbank-Engine aus. Der Befehl authentifiziert das Manifest, validiert Format und Pfade und prüft jede Datei und Prüfsumme ohne Wiederherstellung. Format 2 prüft außerdem die ursprünglichen Werte von APP_KEY, Audit-/Passkey-Geheimnissen und benötigten KEKs. Format 1 bleibt unterstützt, kann aber nicht alle Geheimniswerte vorab prüfen; bewahren Sie die exakten Originale auf und führen Sie eine Wiederherstellungsübung durch.

Zwei Fehlersignale bedeuten „diesen Satz nicht wiederherstellen, einen anderen nehmen“:

ein Manifest-MAC-Fehler: Der Satz wurde nach dem Schreiben verändert;
ein Prüfsummenfehler: Eine der Dateien ist beschädigt.

Versuchen Sie nicht, einen Satz zu reparieren.

Die Wiederherstellungsübung

Bereiten Sie einen sauberen Host vor oder eine Wegwerf-Installation mit derselben Vaultigen-Version. Üben Sie nie auf dem Produktivsystem.
php artisan down ausführen und Web, Queue-Worker und Scheduler stoppen. Alle Dienste müssen während der Wiederherstellung offline bleiben; nur ein Host darf auf diese Installation zugreifen.
Stellen Sie die passenden Wiederherstellungsvoraussetzungen bereit: dieselbe installation.json (Installations-ID, Audit-Schlüssel, Passkey-Geheimnis), dieselbe kek.json, dieselbe backup.json und denselben APP_KEY. Auf dem Ziel keine Initialisierung, Schlüsselerzeugung, Testdaten oder Migrationen einer neueren Version ausführen. Leere Datenbank und privaten Dateispeicher mit derselben Engine und ursprünglichen Identität vorbereiten; der Snapshot liefert das Schema.
Kopieren Sie den Backup-Satz auf den Host und führen Sie aus (für Docker Compose siehe unten):
```
php artisan vaultigen:restore /path/to/backup-set --services-stopped
```
--services-stopped bestätigt, dass alle anderen Anwendungsprozesse gestoppt sind; Laravel muss ebenfalls offline sein. Ohne --force gibt der Befehl eine Zusammenfassung aus, einschließlich der benötigten Schlüsselkennungen, und fragt nach einer Bestätigung. Lesen Sie sie.
Nach erfolgreicher Wiederherstellung php artisan up ausführen, Dienste starten und testen: anmelden, einen Tresor öffnen, ein Login anzeigen, einen Anhang herunterladen, eine ältere Revision wiederherstellen und in der Aktivität nach dem Ereignis restore.completed suchen.
Notieren Sie, wie lange es gedauert hat und was Sie überrascht hat.

Vorbereitung und Fehler

Die Wiederherstellung bereitet verschlüsselte Dateien privat vor und entschlüsselt/prüft den Snapshot vor dem Datenbankaustausch. Sie prüft Zielrechte und Speicherplatz, lehnt unsichere Pfade/Links sowie inkompatible Engines ab, kopiert Anhänge und aufbewahrte Importquellen an ihre ursprünglichen privaten Speicherpfade und gleicht das Datenbankinventar mit dem Manifest ab. Datenbankzeilen stellen auch Bilder/Icons wieder her. Bei PostgreSQL, MySQL und MariaDB entfernt sie zuvor alle Tabellen der Zieldatenbank, damit Tabellen eines neueren Schemas einen Rückschritt auf einen älteren Satz nicht überdauern; nur auf die eigene Datenbank dieser Installation anwenden. Alte Jobs, Sitzungen, Caches und Operationszustände werden erst nach erfolgreicher Dateiwiederherstellung zurückgesetzt; anschließend wird restore.completed protokolliert.

Der Austausch von Datenbank und Dateien ist nicht atomar. Schlägt die Anwendung des Backups fehl, alle Dienste offline lassen. Klartext-Arbeitsdateien werden immer gelöscht; storage/framework/restore-in-progress.json markiert die unvollständige Wiederherstellung. Ursache beheben und denselben vollständigen Satz mit Originalschlüsseln erneut anwenden oder mit einem sauberen Ziel neu beginnen. Bei teilweiser Wiederherstellung kein artisan up ausführen. Nach Erfolg MFA, Revisionen, Bilder, Importquellen sowie die Audit-Kette in Aktivität als Teil der Übung prüfen.

Im Ernstfall wiederherstellen

Das Vorgehen ist dasselbe. Zusätzlich:

Stellen Sie den neuesten Satz wieder her, dem Sie vertrauen. Nach einer vermuteten Kompromittierung wählen Sie einen Satz von vor der Kompromittierung.
Stellen Sie sicher, dass während der Wiederherstellung nur ein Prozess in die Datenbank schreibt.
Prüfen Sie danach den Installationsstatus und erstellen Sie ein frisches Backup.

Docker Compose

Auf einen neuen Server wiederherstellen

Das ist zugleich die Wiederherstellungsübung und die echte Wiederherstellung nach dem Verlust eines Servers. Sie brauchen:

einen abgeschlossenen Backup-Satz (den Ordner backups/<id>),
Ihre Schlüsselkopie (vaultigen-keys.tar.gz mit dem Ordner keys/),
die ursprüngliche .env und compose.proxy.yaml, falls Sie sie verwendet haben.

Verwenden Sie einen frischen Server mit Docker und die compose.yaml der Version, mit der das Backup erstellt wurde (siehe Download). Behalten Sie VAULTIGEN_IMAGE_TAG und DB_PASSWORD aus der ursprünglichen .env. Für eine Übung ändern Sie nur VAULTIGEN_DOMAIN auf einen Test-Hostnamen; üben Sie nie gegen das Produktivsystem.

umask 077
mkdir -p ~/vaultigen/data ~/vaultigen/backups && cd ~/vaultigen
curl -fLO https://raw.githubusercontent.com/vaultigen/vaultigen/v1.0.0/scripts/docker/compose.yaml
# die ursprüngliche .env hierher kopieren, dann:
tar -xzf ~/vaultigen-keys.tar.gz -C ~/vaultigen/data
# den Backup-Ordner nach ~/vaultigen/backups/BACKUP_ID kopieren, dann:
docker compose up -d --wait database
docker compose run --rm --no-deps setup restore /backups/BACKUP_ID
docker compose up -d --wait

Der Wiederherstellungscontainer übergibt die Ordner an den Anwendungsbenutzer, prüft den Satz gegen Ihre Schlüssel, zeigt eine Zusammenfassung, fragt nach einer Bestätigung und stellt dann Datenbank und Dateien bei offline geschalteter Anwendung wieder her. Er erzeugt nie zuerst Schlüssel, legt keinen Administrator an und führt vorher keine Migrationen aus. Führen Sie den letzten Befehl erst aus, wenn die Wiederherstellung Erfolg meldet.

Melden Sie sich danach mit einem bestehenden Konto und seinem Authenticator an, zeigen Sie einen bekannten Eintrag an, laden Sie seinen Anhang herunter und suchen Sie restore.completed in der Aktivität. Stellen Sie DNS erst auf den neuen Server um, wenn der alte offline ist.

Schlägt die Wiederherstellung fehl oder brechen Sie die Bestätigung ab, bleibt die Installation im Wartungsmodus. Beheben Sie das gemeldete Problem und führen Sie denselben Befehl mit demselben Satz und den ursprünglichen Schlüsseln erneut aus. Starten Sie die Anwendungsdienste nicht zwischendurch, und führen Sie auf einem Server, der eine bestehende Installation erhalten soll, nie setup ohne restore aus.

Die ganze Installation kopieren

Weil die Installation ein einziges Verzeichnis ist, können Sie sie auch genau so sichern oder umziehen, wie sie ist. Das erfordert eine kurze Ausfallzeit; die Kopie einer laufenden Datenbank ist nicht gültig:

cd ~/vaultigen
docker compose stop
sudo tar -czpf ~/vaultigen-full.tar.gz -C ~ vaultigen
docker compose up -d --wait

Entpacken Sie das Archiv auf dem neuen Server mit sudo tar -xzpf vaultigen-full.tar.gz -C ~ und führen Sie in ~/vaultigen docker compose up -d --wait aus. Führen Sie keine Einrichtung aus. Die Option -p erhält Besitzer und Berechtigungen, die die Container brauchen.

Dieses Archiv enthält Ihre Schlüssel und Ihre Daten, unverschlüsselt: Wer es besitzt, kann Ihre Tresore lesen. Verschlüsseln Sie es, bevor es den Server verlässt (zum Beispiel gpg --symmetric vaultigen-full.tar.gz), und bewahren Sie die Passphrase getrennt auf. Für den täglichen Schutz verlassen Sie sich auf die verschlüsselten Backup-Sätze.

Eine manuelle Installation zu Docker Compose umziehen

Der Compose-Stack verwendet PostgreSQL. Eine manuelle Installation auf PostgreSQL zieht mit einer normalen Wiederherstellung um und behält Installationsidentität, Schlüssel, Konten und Daten. Installationen auf SQLite, MySQL oder MariaDB bleiben bei der manuellen Einrichtung, weil sich ein Backup nur in dieselbe Datenbank-Engine wiederherstellen lässt.

Aktualisieren Sie die manuelle Installation auf die Version, die Sie mit Docker betreiben werden, führen Sie php artisan vaultigen:backup aus, stoppen Sie dann Webserver, Queue-Worker und Scheduler und lassen Sie sie offline.
Folgen Sie auf dem Docker-Server den Schritten 1 bis 3 der Installation mit derselben Version, aber führen Sie keine Einrichtung aus. Übernehmen Sie die Zeile APP_KEY=… der manuellen Installation in die neue .env, dazu Einstellungen, die Sie noch brauchen, etwa Mail- oder Lizenzwerte. Behalten Sie das erzeugte DB_PASSWORD.
Kopieren Sie installation.json, kek.json und backup.json aus storage/app/private/ der manuellen Installation nach ~/vaultigen/data/keys/ und den Backup-Ordner nach ~/vaultigen/backups/.
Starten Sie die Datenbank und führen Sie den Wiederherstellungsbefehl aus Auf einen neuen Server wiederherstellen aus.

Behalten Sie die Zeile APP_KEY danach in .env und nehmen Sie .env in Ihre Schlüsselkopie auf.

Wiederherstellung und Schlüsselrotation

Nach einer Rotation des Installations-KEK brauchen alte Backup-Sätze weiterhin die alten KEK-Schlüssel. Behalten Sie sie im Schlüsselbund, solange Sie diese Sätze aufbewahren.
Nach einer Rotation eines Tresorschlüssels erstellen Sie ein neues Backup; behalten Sie das Backup von vor der Rotation, bis Sie sicher sind, dass Sie es nicht mehr brauchen.
Nach einer Rotation des Backup-Schlüssels mit --retire-old-keys sind Offline-Kopien, die nicht neu verschlüsselt wurden, nicht mehr lesbar.

Siehe Schlüsselverwaltung.