Backup und Wiederherstellung

Sobald Ihre Instanz in Gebrauch ist, erstellen Sie ein Backup vor Upgrades oder dem Umzug von Servern. Erster Antrag.

SubLane kann eine laufende Instanz exportieren, ein Backup verifizieren und in ein neues Verzeichnis wiederherstellen. Systemeinstellungen → Backup und Wiederherstellung Verwenden Sie die gleiche Archivvalidierung und Wiederherstellungsimplementierung. Recovery überschreibt niemals die laufende Instanz; der Wechsel zu wiederhergestellten Daten ist ein expliziter Neustart des Operators.

Was ist inbegriffen

Neue Backups sind binäre, passwortverschlüsselte age-Dateien. Nach dem Entschlüsseln enthält das gzip/Tar-Archiv:

• sublane.db: eine konsistente SQLite Snapshot, einschließlich engagierter WAL-Daten.
• credentials.key: der übereinstimmende Verschlüsselungsschlüssel für Abonnement-Anmeldeinformationen und wiederherstellbare Gateway-Schlüssel.
• manifest.json: Formatversion, Erstellungszeit, SubLane Build-Version, Schema-Version, Dateigrößen und SHA-256 Prüfsummen.

Benutzer, Passwort-Hashes, API Schlüssel, Abonnementkonten, Pools, Berechtigungen, Kataloge, Einstellungen, Anforderungsdatensätze, Nutzungszusammenfassungen, Cooldowns und Affinitätsdatensätze sind enthalten. Browsersitzungen werden im Backup erfasst, aber in einem wiederhergestellten Verzeichnis gelöscht. Browser-lokale Themen-/Sprachauswahl, Prozessumgebung, Bereitstellungsdateien und ausstehende In-Memory-Dateien OAuth Versuche sind nicht enthalten.

Neue Exporte benötigen ein Passwort mit 12–128 Zeichen. SubLane speichert es nicht. Bewahren Sie es getrennt auf; bei Verlust lässt sich das verschlüsselte Backup nicht wiederherstellen. Ältere unverschlüsselte .tar.gz-Archive bleiben ohne Passwort lesbar, enthalten aber lesbare Schlüssel und müssen privat aufbewahrt werden.

Befehlszeile

Führen Sie die Befehle aus einem Verzeichnis mit genügend freiem Speicherplatz für den Datenbank-Snapshot und das komprimierte Archiv aus:

mkdir -p backups
./bin/sublane backup --password-stdin --output ./backups/team.sublane-backup.tar.gz.age < /secure/backup-password
./bin/sublane backup verify --password-stdin --input ./backups/team.sublane-backup.tar.gz.age < /secure/backup-password
./bin/sublane restore --password-stdin --input ./backups/team.sublane-backup.tar.gz.age --data-dir ./data-restored < /secure/backup-password

backup Lesewerte SUBLANE_DATA_DIR oder ./data, mit einer optionalen --data-dir Übersteuern. restore Es wird immer ein explizites neues Verzeichnis benötigt, sogar ein vorhandenes leeres Verzeichnis wird abgelehnt. Das übergeordnete Verzeichnis muss vorhanden sein. Bestehende Archivdateien und Wiederherstellungsverzeichnisse werden nie ersetzt. Erfolgreiche Befehle drucken ein JSON resultieren mit den Metadaten Operation, Pfad und Backup. sublane --help listet die Befehle auf.

Wartungsbefehle starten nicht die HTTP Server, SDK Vollstrecker, OAuth, oder automatische Freigabeprüfungen, und nicht abhängig von Server-Adresse / Public-URL-Konfiguration. Sie haben eine fünfzehnminütige Frist und reagieren auf SIGINT / SIGTERM. Datenbank-Snapshots sind auf 4 GiB begrenzt und Archiv-IO verwendet begrenzte Puffer. Lassen Sie Speicherplatz für Extraktion und Migrationen bei der Überprüfung oder Wiederherstellung, zusätzlich zum Archiv selbst.

Nach erfolgreicher Wiederherstellung:

1. Stoppen Sie den Strom SubLane Dienst.
2. Behalten Sie das ursprüngliche Datenverzeichnis intakt.
3. Beginn SubLane mit dem wiederhergestellten Verzeichnis:

SUBLANE_DATA_DIR=./data-restored ./bin/sublane

4. Melden Sie sich erneut an und überprüfen Sie die erwarteten Benutzer, Pools, Schlüssel und Kontozustände, bevor Sie den Teamverkehr wieder aufnehmen.

Das Originalverzeichnis steht zum Rollback zur Verfügung, indem es anhält SubLane und Schalten SUBLANE_DATA_DIR Zurück. Führen Sie nicht zwei Gateway-Instanzen im selben Datenverzeichnis aus. Die Wiederherstellung führt den gesamten gespeicherten Zustand in den Snapshot zurück: spätere Schlüsselentzüge, Passwortänderungen und neue Datensätze sind nicht enthalten. Ein Abonnementanbieter hat möglicherweise ältere Aktualisierungstoken seit der Sicherung ungültig gemacht; betroffene Konten bei Bedarf erneut autorisieren. Die Überprüfung überprüft die Entschlüsselung und lokale Integrität, ohne den Anbieter zu kontaktieren.

Web-Schnittstelle

Mutationen erfordern den genauen Browser-Ursprung und exportieren die Administratorsitzung nach der Vorbereitung der Datei erneut.

• Download Backup erstellt und lädt ein vollständiges Archiv herunter, während die Instanz verfügbar bleibt.
• Verifizieren Sie Backup überprüft die ausgewählte Datei und zeigt deren Erstellungszeit an, SubLane Version und Datenbankgröße.
• Vorbereitung der Wiederherstellung Uploads und Validierung der Datei erneut, dann erstellt <current data directory>/restore-ready. Die Seite zeigt den vollständigen Pfad und die Neustartanweisungen an. Die aktuelle Instanz läuft mit ihren Originaldaten weiter, bis der Operator die Verzeichnisse wechselt.

Eine bestehende restore-ready Der Pfad blockiert eine andere Vorbereitung. Überprüfen Sie sie auf dem Server oder verwenden Sie die CLI mit einem anderen neuen Ziel. Kein Verzeichnis kann über das Web überschrieben werden. APIWenn Wiederherstellungsdaten erstellt wurden, der Live-Audit-Schreiben jedoch fehlgeschlagen ist, wird das Verzeichnis beibehalten und die Seite meldet den Auditfehler; überprüfen Sie es, bevor Sie es erneut versuchen.

Web-Uploads und -Downloads sind auf 256 MiB komprimierter Daten begrenzt; größere Backups erfordern die CLI. Ein Export-/Verifizierungs-/Wiederherstellungsvorgang läuft gleichzeitig pro Server. Upload, Verarbeitung und Download haben begrenzte Fristen. Temporäre Dateien werden nach Abschluss, Ausfall oder normaler Kündigung entfernt. Ein erzwungener Prozessabbruch oder Stromausfall kann einen privaten Prozess verlassen .sublane-backup-* Verzeichnis; entfernen Sie übrig gebliebene Staging-Verzeichnisse nur, wenn kein Backup-Vorgang ausgeführt wird.

Exporte und vorbereitete Wiederherstellungen werden geprüft, ohne Archivinhalte, Dateinamen, Dateisystempfade oder Anmeldeinformationen aufzuzeichnen. Cache-Control: no-storeDie Seite streamt Uploads aus der ausgewählten Datei; der Browser erhält das heruntergeladene Archiv als temporären Blob und gibt seine URL nach dem Start des Downloads frei.

Beispiel Browser-Backup und Wiederherstellung Kontrollen:

Docker Compose

Exportieren und Verifizieren innerhalb des laufenden Containers:

docker compose -f docker.compose.yaml exec sublane sh -c 'mkdir -p /data/backups'
docker compose -f docker.compose.yaml exec -T sublane sublane backup --password-stdin --output /data/backups/team.sublane-backup.tar.gz.age < /secure/backup-password
docker compose -f docker.compose.yaml exec -T sublane sublane backup verify --password-stdin --input /data/backups/team.sublane-backup.tar.gz.age < /secure/backup-password
docker compose -f docker.compose.yaml cp sublane:/data/backups/team.sublane-backup.tar.gz.age ./team.sublane-backup.tar.gz.age

Kopieren Sie für die Wiederherstellung ein Backup in einen privaten beschreibbaren Speicherort, der innerhalb des Containers sichtbar ist, und erstellen Sie dann ein separates Verzeichnis:

docker compose -f docker.compose.yaml exec -T sublane sublane restore --password-stdin --input /data/backups/team.sublane-backup.tar.gz.age --data-dir /data/restore-ready < /secure/backup-password

Die Web-Restore-Aktion erzeugt das gleiche Ziel. Compose Override, z.B. docker.compose.restore.yaml:

services:
  sublane:
    environment:
      SUBLANE_DATA_DIR: /data/restore-ready

Stoppen Sie dann den ursprünglichen Prozess und beginnen Sie mit dem Override:

docker compose -f docker.compose.yaml stop sublane
docker compose -f docker.compose.yaml -f docker.compose.restore.yaml up -d

Für einen bereits angehaltenen Container verwenden docker compose -f docker.compose.yaml run --rm --no-deps sublane ... anstelle von exec Um Wartungsbefehle gegen das benannte Datenvolumen auszuführen, behalten Sie die ausgewählte Überschreibung in nachfolgenden Bereitstellungsbefehlen bei, entfernen Sie das benannte Volumen während dieses Vorgangs nicht.

Validierungs- und Fehlerverhalten

Die Überprüfung überprüft genaue Archiveinträge und -größen, SHA-256 Digests, Gzip-Integrität, die unterstützte konsolidierte Schemaversion, SQLite Integrität und Fremdschlüssel, Begrenzte Anmeldedatensätze und Entschlüsselung von Kontodaten und verschlüsselt API Validationsverbindungen begrenzen auch einzelne SQLite Symlinks, Pfad-Traversal, Duplicate/Unerwartete Dateien, fehlende Dateien, verkürzte Archive und unbekannte zukünftige Schemata werden abgelehnt. Ältere Entwicklungsschemata werden von diesem Prerelease-Build nicht akzeptiert.

Wiederherstellen schließt und synchronisiert seine vorbereitete Datenbank/Schlüssel vor der Veröffentlichung des gesamten neuen Verzeichnisses mit einer atomaren No-Replace-Operation. Linux und macOS benötigen für diese Operation Dateisystemunterstützung; eine nicht unterstützte Operation schlägt fehl, ohne auf ein Überschreiben zurückzugreifen. SQLite Die Snapshot-Erstellung nutzt die SQLite Online Backup API durch den angehefteten Go-Treiber, anstatt eine Live-Datenbankdatei zu kopieren.

Verwendung application/gzip oder application/octet-stream Ungültige Archive geben 400, ein vorhandenes Ziel 409, übergroße Uploads 413 und ein belegter Operationsschlitz 429 mit Retry-AfterSpeicher- und andere Betriebsfehler geben sanierte 503-Fehler zurück.

credentials.key · Backup-Passwort

Bestehende Instanzen zuerst stoppen und den bisherigen Schlüssel an einen privaten Ort außerhalb des Datenverzeichnisses kopieren. Rechte für den Dienstbenutzer setzen. Erst nach erfolgreichem Start und geprüftem verschlüsseltem Backup die alte Kopie entfernen.

SUBLANE_CREDENTIALS_KEY_FILE: Optionale private Schlüsseldatei außerhalb des Datenverzeichnisses; ohne Angabe bleibt der bisherige Pfad.

Bei getrennter Schlüsselablage verschieben Sie die wiederhergestellte credentials.key vor dem Neustart an einen neuen privaten Ort außerhalb des Datenverzeichnisses und aktualisieren SUBLANE_CREDENTIALS_KEY_FILE. Überschreiben Sie den Schlüssel der ursprünglichen Instanz nicht.

Verwenden Sie 12–128 Zeichen. Bewahren Sie das Passwort separat auf; bei Verlust kann es nicht zurückgesetzt werden. Für verschlüsselte Backups erforderlich. Für ältere unverschlüsselte Archive leer lassen.

--key-file FILE · --password-stdin · scrypt: 18 (~256 MiB)

Lesen Sie das Passwort mit --password-stdin aus einer privaten einzeiligen Datei mit Modus 0600; verwenden Sie keine Kommandozeilenargumente oder Umgebungsvariablen für das Passwort.

Die Oberfläche sendet multipart/form-data, zuerst password, dann file. Historische rohe Uploads bleiben ohne Passwort möglich.

Automatische Compose-Schlüsselmigration

Das Anwendungsrepository stellt scripts/separate-key.sh für bestehende Compose-Installationen mit SubLane v0.12.0+ bereit. Speichern und prüfen Sie das Skript vor der Ausführung auf dem Docker-Host. Exportieren und verifizieren Sie zuerst ein passwortverschlüsseltes Wiederherstellungsbackup.

sudo bash scripts/separate-key.sh --dir /srv/sublane --key-dir /srv/sublane-secrets

--dir bezeichnet das bestehende Deployment mit docker.compose.yaml und optionaler .env. --key-dir muss ein neuer absoluter Pfad auf persistentem Host-Speicher außerhalb des tatsächlichen Daten-Mounts und des Wiederherstellungsverzeichnisses sein; das übergeordnete Verzeichnis muss existieren. Übliche ASCII-Pfade einschließlich Leerzeichen werden unterstützt. Erforderlich sind lokales Linux mit rootful Docker ohne userns-Remapping oder SELinux, Compose, Bash, jq und GNU coreutils. Der gesunde Dienst muss sublane heißen und sein Datenverzeichnis als beschreibbaren Bind-Mount oder benanntes Volume direkt am Mount-Wurzelverzeichnis einbinden. Compose muss die Dienste mit zwei Leerzeichen einrücken und eine Block-Zuordnung für environment sowie eine Block-Liste für volumes verwenden. Nicht unterstützte Strukturen werden vor dem Dienststopp abgelehnt.

Das Skript prüft Projekt, Image, Daten-Mount, private Rechte, die Größe von 32 Byte und den Hash des bisherigen Schlüssels. Compose-Text und Variableninterpolation bleiben erhalten; die normalisierte Konfiguration wird verglichen. Das neue Host-Verzeichnis bleibt im Besitz von root mit Modus 0700. Nur die Schlüsseldatei mit 0600 und der UID/GID des Dienstes wird schreibgeschützt eingebunden. Die Dienstrechte werden nicht erhöht.

Vor dem Wechsel, danach und nach dem Entfernen des alten Schlüssels erstellt und prüft das Skript ein temporäres verschlüsseltes Backup mit jeweils neuem Zufallspasswort. Der Prüfbereich liegt außerhalb des Datenverzeichnisses und wird anschließend gelöscht. Planen Sie ausreichend Speicherplatz und Arbeitsspeicher für die Backup-KDF ein. Diese Prüfungen bewahren kein Wiederherstellungsbackup auf. Erst nach erfolgreicher Prüfung von Konfiguration, Zustand, Schlüsselhash und Zugangsdaten wird die alte Kopie entfernt; erneutes Erstellen und Prüfen bestätigt die Unabhängigkeit von der alten Datei.

Ab Beginn des Wechsels lösen abfangbare Fehler oder Signale einen Rollback-Versuch aus. Auch nach erfolgreicher Migration ist ein expliziter Rollback möglich:

sudo bash scripts/separate-key.sh --dir /srv/sublane --rollback

Private Wiederherstellungsunterlagen bleiben in /srv/sublane/.key-migration. Der Rollback stellt die ursprüngliche Konfiguration und den passenden Schlüssel wieder her, erstellt den ursprünglichen Dienst neu und prüft ihn. Spätere Konfigurations-/Umgebungsänderungen oder andere Schlüssel werden nicht überschrieben; Image und Datenbank werden nie herabgestuft. Externer Schlüssel und Unterlagen bleiben nach dem Rollback privat erhalten. Eine erneute Migration überschreibt weder bestehende Unterlagen noch Ziele. Archivieren Sie verifizierte Unterlagen sicher und wählen Sie vor einem neuen Versuch ein neues Schlüsselverzeichnis.

Das Skript teilt .update-lock mit dem Installer; führen Sie keine anderen Deployment-Aktionen parallel aus. Prüfen Sie nach erzwungenem Prozessende oder Stromausfall, dass keine Migration und kein Update läuft. Entfernen Sie nur die verwaiste leere .update-lock und führen Sie dann --rollback aus. Ist der Rollback nicht verifizierbar, bleiben Wiederherstellungsschlüssel und die private operation.log erhalten. Bewahren Sie Wiederherstellungs- und Schlüsselverzeichnis bis zum Abschluss auf. Für dauerhaft aufbewahrte Backups und getrennt verwahrte Passwörter bleiben Sie selbst verantwortlich.

Automatische verschlüsselte Backups

Mit den folgenden Deployment-Einstellungen aktivieren. Zielverzeichnis: privat (0700). Das separate Passwort mit 12–128 Zeichen gehört in eine private reguläre Datei (0600, kein Symlink), getrennt von Daten und Backups. Es wird bei jedem Lauf neu gelesen.

export SUBLANE_BACKUP_DIR=/srv/sublane-backups
export SUBLANE_BACKUP_PASSWORD_FILE=/secure/sublane/backup-password
export SUBLANE_BACKUP_INTERVAL=24h
export SUBLANE_BACKUP_KEEP=7

Ein Lauf startet beim Prozessstart, danach beginnt das Intervall nach jedem Versuch. Erst nach vollständiger Prüfung werden reservierte scheduled--Dateien rotiert; manuelle Archive und das neue geprüfte Archiv bleiben erhalten. Ergebnisse stehen im Dienstprotokoll. Kein Remote-Upload oder Browser-Zeitplan; im Demo-Modus deaktiviert.

SUBLANE_BACKUP_INTERVAL: 1h–720h (default 24h). SUBLANE_BACKUP_KEEP: 1–365 (default 7).

Verwenden Sie ein eigenes Backup-Ziel für jede Instanz.

Optional sendet SUBLANE_BACKUP_WEBHOOK_URL an eine öffentliche HTTPS-Adresse pro fehlgeschlagenem Versuch ein zeitlich begrenztes backup_failure-JSON-Ereignis. Dieses Betreiberziel gilt für die Instanz, getrennt von Workspace-Alarmen; Zustellfehler werden protokolliert.

Für Docker Containerpfade verwenden und private Passwortdatei sowie beschreibbares eigenes Backup-Verzeichnis per lokalem Compose-Override einbinden; der Dienstbenutzer braucht Zugriff. Das voreingestellte /tmp-tmpfs hat 64 MiB. Größere Prüfungen benötigen einen eigenen privaten beschreibbaren Mount und TMPDIR im Override.