Betrieb / Admin

Backup und Restore

Datenbank, Schlüssel und Vektordaten sichern und Wiederherstellung üben.

25 Min. Lesezeit · Zuletzt aktualisiert:

Status dieser Funktion

Betrieb: On-prem-Profil für Kundeninfrastruktur Vorschau

Status 2026-10-01 auf preview gesetzt: nur auf k3d erprobt, noch nicht auf einem echten Kundenhost. Auf k3d erprobt; install-k3s auf echtem Host noch nicht durchgespielt. Der Upgrade-Test nutzt denselben Build unter neuem Tag (prüft den Upgrade-Ablauf, keine Schemaänderung zwischen zwei Releases); Air-Gap-Import und echte lokale Inferenz noch nicht durchgespielt; eine Replika; Release-Images für db-migrate und same-origin web müssen gebaut werden.

1. Umfang klären

Das On-Prem-Backup enthält Dumps von oap und keycloak, verschlüsselten State, einen vollständigen Qdrant-Snapshot, Helm-Werte und ein Manifest mit Prüfsummen. Der State enthält generierte Secrets und Schlüssel. Ohne diese lassen sich gespeicherte Zugangsdaten nicht entschlüsseln.

Mandantenexport ist kein vollständiges Datenbankbackup. Zusätzliche externe Objektspeicher und Anbieterzustände müssen nach ihrer eigenen Betriebsanleitung gesichert werden.

2. Backup erstellen

Stelle BACKUP_PASSPHRASE sicher über die Prozessumgebung bereit. Schreibe die Passphrase nicht in gemeinsam genutzte Shell-Verläufe oder Dokumentation.

bash
infra/onprem/scripts/backup.sh

Mit --upload kann ein konfiguriertes S3-kompatibles Backupziel verwendet werden. Prüfe Ziel, Zugang und erfolgreichen Upload. Kontrolliere Manifest, Prüfsummen und Lesbarkeit des Archivs; verwahre die Passphrase getrennt.

3. Wiederherstellung vorbereiten

Plane einen Test auf einem isolierten Ziel. Bei einem neuen Host zuerst den verschlüsselten State in ~/.oap-onprem/<site>/ wiederherstellen, dann den Bootstrap ausführen, damit die bestehenden Schlüssel wiederverwendet werden. Prüfe Standort und Archivpfad.

4. Restore und Prüfung

Ersetze den Beispielpfad durch das geprüfte Archivverzeichnis:

bash
infra/onprem/scripts/restore.sh /secure/backups/oap-backup-SITE-ZEIT

Der Ablauf führt Migrationen aus, startet Dienste wieder und verifiziert. Prüfe danach Anmeldung, Daten und einen synthetischen Gesprächsablauf. Notiere Ergebnis, Dauer und fehlende Bestandteile. Die k3d-Tests sind kein Nachweis eines Restore im Kundenkonto. Anbieterabhängige kontinuierliche CNPG-Backups und PITR brauchen eigene Konfiguration und Wiederherstellungsprüfung.

Grundlage im Repository
  • infra/onprem/README.md
  • docs/pilot/betrieb.md

Deployment / Admin

Backup and restore

Back up databases, keys and vector data, and practise recovery.

25 min read · Last updated:

Feature status

Deployment: on-prem customer-infrastructure profile Preview

Status set to preview on 2026-10-01: proven on k3d only, not yet on a real customer host. Proven on k3d; real-host install-k3s not yet exercised. The upgrade smoke re-tags the same build (proves the upgrade mechanics, not a schema change between two releases); the air-gap import and real local inference not yet exercised; single replica; release images for db-migrate and same-origin web must be built.

1. Confirm the scope

The on-premises backup contains dumps of oap and keycloak, encrypted state, a complete Qdrant snapshot, Helm values and a manifest with checksums. The state contains generated secrets and keys. Without these, stored credentials cannot be decrypted.

A tenant export is not a complete database backup. Additional external object stores and provider state must be backed up according to their own operating instructions.

2. Create a backup

Provide BACKUP_PASSPHRASE securely through the process environment. Do not write the passphrase into shared shell histories or documentation.

bash
infra/onprem/scripts/backup.sh

Use --upload to send the backup to a configured S3-compatible destination. Check the destination, access and successful upload. Verify the manifest, checksums and readability of the archive; store the passphrase separately.

3. Prepare recovery

Plan a test on an isolated target. On a new host, first restore the encrypted state to ~/.oap-onprem/<site>/, then run the bootstrap so that the existing keys are reused. Check the site and archive path.

4. Restore and verify

Replace the example path with the verified archive directory:

bash
infra/onprem/scripts/restore.sh /secure/backups/oap-backup-SITE-ZEIT

The procedure runs migrations, restarts services and performs verification. Afterwards, check sign-in, data and a synthetic conversation flow. Record the result, duration and any missing components. The k3d tests do not demonstrate a restore in a customer account. Provider-specific continuous CNPG backups and PITR require their own configuration and recovery testing.

Repository sources
  • infra/onprem/README.md
  • docs/pilot/betrieb.md