Updates und Rollback

Planen Sie jeden Versionswechsel in einer Self-Hosting-Umgebung als kontrollierten Ablauf mit nachvollziehbaren Prüfungen und vorbereitetem Rollback. Am Ende läuft die neue Version produktiv oder Sie können den vorgesehenen Recovery-Pfad sicher ausführen.

Ein erfolgreiches Update bedeutet

  • neue Version installiert,
  • Anmeldung funktioniert,
  • Kernfunktionen funktionieren,
  • Recovery-Pfad entspricht dem DeploymentPlan,
  • Änderungen sind dokumentiert.

Vor dem Update

  • [ ] Release ausgewählt.
  • [ ] SHA256SUMS geprüft.
  • [ ] Datenbank gesichert.
  • [ ] Storage gesichert.
  • [ ] verschlüsselte Konfiguration gesichert.
  • [ ] NUCLEUS_KEY verfügbar.
  • [ ] Rollback-Version vorhanden.
  • [ ] Schema-Status, Schema-Baseline und Schema-Drift geprüft.
  • [ ] Wartungsfenster geplant.
  • [ ] Kommunikationsweg für betroffene Nutzer geklärt.

Artefakte prüfen

Prüfen Sie heruntergeladene Dateien vor Installation oder Rollout:

bash
sha256sum -c SHA256SUMS

Bewahren Sie manifest.txt, SHA256SUMS, Release-Hinweise und installierte Version gemeinsam mit Ihrem Betriebsprotokoll auf.

Schema-Status vor dem Update prüfen

Prüfen Sie vor dem Versionswechsel, ob die Datenbank zur geplanten Serverversion passt. Workspace führt automatische Strukturmigrationen nur bis zur unterstützten Schema-Baseline aus. Sehr alte Datenbanken müssen Sie zuerst über eine unterstützte Zwischenversion oder ein ausdrücklich dokumentiertes Upgrade-Tool anheben.

Führen Sie die Prüfung mit dem versionsgleichen lokalen Offline-Administrationswerkzeug numin auf dem Server oder in derselben Betriebsumgebung aus, in der die Serverkonfiguration verfügbar ist:

bash
numin schema status
numin schema migrations status
numin schema drift

Nutzen Sie für ein Betriebsprotokoll die JSON-Ausgabe:

bash
numin schema status --json
numin schema migrations status --json
numin schema drift --json

Die Prüfung ist erfolgreich, wenn:

  • schema status keinen Upgrade-Bedarf und keine neuere Datenbankversion meldet,
  • schema migrations status die Datenbank-Baseline als unterstützt meldet und fingerprintAligned nicht false, driftStatus ok und driftCheckError false ist,
  • schema drift keine blockierenden Fehler meldet,
  • keine Meldung auf ein explizites Upgrade-Tool oder eine Zwischenversion verweist.
MeldungBedeutungNächster Schritt
Datenbank-Baseline ist unterstütztDie geplante Binary kann den vorhandenen Strukturstand öffnen.Update im Wartungsfenster fortsetzen.
Struktur-Fingerprint passt nicht oder Schema-Drift ist vorhandenDie physische Datenbankstruktur passt nicht vollständig zum erwarteten Strukturvertrag der Binary.Update nicht fortsetzen, Drift-Report sichern und den dokumentierten Reconcile-, Zwischenversions- oder Upgrade-Pfad ausführen.
Datenbank ist unterhalb der Mindest-BaselineDie neue Binary unterstützt den alten Strukturstand nicht direkt.Erst auf eine unterstützte Zwischenversion aktualisieren oder das dokumentierte Upgrade-Tool nutzen.
Datenbank ist neuer als die BinaryDie Binary ist älter als der Datenbankstand.Nicht starten. Verwenden Sie die passende neuere Binary oder stellen Sie aus einem kompatiblen Backup wieder her.
Explizites Upgrade erforderlichEin harter Schema-Contract braucht einen Operator-Schritt.Runbook zum genannten Upgrade-Tool lesen, Dry-Run ausführen und erst danach --apply im Wartungsfenster nutzen.

Zielversion gegen die reale Datenbank prüfen

Die Statusbefehle oben bewerten die Datenbank aus Sicht der aktuell installierten Binary. Vor der Aktivierung muss zusätzlich numin aus genau dem gestagten Zielartefakt prüfen, welche Struktur- und Datenübergänge diese Installation tatsächlich benötigt:

bash
numin --config /data/nucleus.config.enc schema migrations preflight --json
numin --config /data/nucleus.config.enc deployment plan \
  --artifact-digest <sha256> \
  --backup-evidence /secure/backup-evidence.json \
  --json

Der Schema-Preflight ist der maßgebliche Vergleich zwischen Zielversion und Bestandsdatenbank. Prüfen Sie insbesondere:

FeldAussage
sourceBaseline, targetBaselineAusgangs- und Zielbaseline des geplanten Übergangs.
expectedColumns, existingColumns, conversionColumnsUmfang einer anstehenden UUID-Strukturumstellung. Eine nicht leere Konvertierungsliste ist allein noch kein Fehler.
findingsBlockierende Werte, Typen, Abhängigkeiten oder PostgreSQL-Voraussetzungen.
senderProfileRevisionWindow.statusGesamtstatus der Absenderprofil-Zeitfenster.
invalidWindowCount, overlapCountAnzahl ungültiger Fenster und überlappender aktiver Revisionspaare.
transitionClass, requiresMaintenanceWartungs- und Recovery-Vertrag des Übergangs.

Ein erfolgreicher Canary oder eine zweite Installation ersetzt diese Prüfung nicht. Selbst bei derselben Quell- und Zielversion können Bestandsdaten, Schema-Baseline und PostgreSQL-Konfiguration voneinander abweichen.

Fahren Sie nur fort, wenn der Schema-Preflight status: ready ohne Findings meldet, beide Absenderprofil-Zähler 0 sind und der Deployment-Plan mit Exit-Code 0 ready: true ausgibt. Nach jeder Datenkorrektur müssen Sie den Preflight wiederholen und eine neue, restore-getestete Backup-Evidenz erzeugen. Die Fehlerzuordnung steht unter Update-Preflight-Fehler einordnen.

IAM-Sicherheitsvertrag beim Rollout erhalten

Aktuelle Workspace-Versionen führen einen datenbankgestützten Berechtigungsstand ein. PostgreSQL erhöht diesen Stand gemeinsam mit autorisierungswirksamen Rollen-, Gruppen- und Mitgliedschaftsänderungen. So erkennen alle Server einen Rechteentzug ohne eine zusätzliche Ereigniszustellung.

Rollen Sie alle Workspace-Server in einem koordinierten Wartungsfenster auf denselben kompatiblen Stand. Betreiben Sie keine ältere Binary parallel, wenn sie Berechtigungs-Caches noch ohne diesen Datenbankvertrag verwenden kann. Prüfen Sie nach dem Start, dass die Schema- und Readiness-Prüfungen erfolgreich sind. Ein fehlender oder veränderter PostgreSQL-Trigger ist Schema-Drift und darf nicht durch eine aktuelle Baseline verdeckt werden.

Serverpaket aktualisieren

Die Paketinstallation staged die neue Version, startet sie aber nicht. Erstellen Sie danach einen geprüften Backup-Nachweis und aktivieren Sie die Zielversion mit ihrem versionsgleichen numin-Preflight:

bash
sudo apt install ./nucleus-server_<version>-1_amd64.deb
# oder: sudo rpm -Uvh nucleus-server-<version>-1.x86_64.rpm
sudo nucleus-server-backup
sudo nucleus-server-update \
  --target-version <version> \
  --backup-evidence /var/lib/nucleus/backups/<evidence>.json

Wenn Sie das Archivformat verwenden, ersetzen Sie das Binary kontrolliert und starten Sie den Dienst erst, nachdem das numin des Zielarchivs deployment plan mit ready: true abgeschlossen hat.

Container aktualisieren

Verwenden Sie einen unveränderlichen Image-Digest. Der Wrapper sichert PostgreSQL, Storage, Konfiguration und Runtime-Key, prüft den Restore und führt den Ziel-Preflight vor der Aktivierung aus:

bash
./start.sh update git.schukai.me/releases/nucleus@sha256:<digest>

Prüfen Sie danach, ob der neue Serverstand und die eingebettete Administrationsoberfläche aktiv sind.

Nach dem Update prüfen

Führen Sie nach jedem Update technische und fachliche Smoke-Tests aus.

Technische Prüfungen

  • Ping-Endpunkt erreichbar,
  • Login funktioniert,
  • Administrationsoberfläche lädt den erwarteten Stand,
  • numin schema status, numin schema migrations status und numin schema drift melden einen unterstützten, driftfreien Stand,
  • im System-Mandanten ist kein offener Schema-Readiness-Handlungsbedarf sichtbar,
  • nucli doctor meldet keine blockierenden Kontextfehler,
  • relevante System-Readiness-Checks sind ok oder fachlich erklärbar.

Basisprüfung:

bash
curl -fsS https://<workspace-url>/api/v1/ping
curl -fsS https://<workspace-url>/health/ready

Wenn der Server wegen Schema-Drift in den Maintenance-Modus geht, bleibt /health/live erreichbar, aber /health/ready und normale Routen liefern 503 mit einem stabilen Fehlercode. Dadurch bleibt Monitoring wach, ohne SMTP, Worker, Storage, Buchhaltung oder andere Business-Pfade auf einer inkompatiblen Datenbank zu starten.

Für detaillierte Diagnoseinformationen nutzen Sie Diagnose und Readiness.

Fachliche Prüfungen

  • Anmeldung mit typischen Rollen möglich,
  • Kernprozesse der Umgebung funktionieren,
  • Integrationen erreichbar,
  • Exporte und Importe funktionieren,
  • betroffene Arbeitsbereiche lassen sich öffnen.

Dokumentieren Sie Version, Artefakt, Prüfsumme, Startzeit, Prüfergebnis und offene Auffälligkeiten.

Rollback vorbereiten

Ein Binary- oder Image-Rollback allein macht keine Datenmigration rückgängig. Stimmen Sie Rollback-Schritte immer mit Ihrem Backup- und Restore-Konzept ab. Prüfen Sie im DeploymentPlan und geschützten Product-Release-Status transitionClass, minimumRuntimeBaseline, pointOfNoReturnAt und rollbackAfterSchemaTransition.

KomponenteFür Rollback erforderlich
Binary oder ImageJa
PostgreSQLMöglicherweise, abhängig von Schema-Baseline und Migrationen
StorageMöglicherweise, abhängig von geänderten Daten
KonfigurationJa
NUCLEUS_KEYJa

Rollback durchführen

Rollen Sie nur vor dem Point of No Return oder nach einem ausdrücklich kompatiblen compatible_expand-Übergang durch einen Binary-Wechsel zurück. Nach forward_only bleibt die Zielversion ausgewählt. Reparieren Sie mit ihr vorwärts oder stellen Sie Datenbank, Storage, verschlüsselte Konfiguration und Runtime-Key gemeinsam aus dem passenden Backup wieder her.

Ein Rollback auf einen Stand, der Berechtigungs-Caches nicht gegen den aktuellen Datenbankstand prüft, ist kein sicherer Binary-Rollback. Verwenden Sie in diesem Fall eine ausdrücklich kompatible Rollback-Version oder stellen Sie das zum alten Stand gehörende Datenbank-Backup wieder her. Prüfen Sie anschließend mit Testkonten, dass entzogene Rollen, Mitgliedschaften und Schlüssel weiterhin abgelehnt werden.

Prüfen Sie nach dem Rollback dieselben Punkte wie nach einem Update. Halten Sie fest, ob Daten wiederhergestellt wurden und welcher Stand jetzt produktiv läuft.

Nächste Schritte

  • Prüfen Sie Betrieb und Readiness mit Diagnose und Readiness.
  • Prüfen Sie Self-Hosting-Grundlagen mit Self-Hosting, wenn Backup, Storage oder Erstzugang betroffen sind.
  • Prüfen Sie Container-Ingress mit Container und Ingress, wenn das Update über Images oder orchestrierte Rollouts läuft.
  • Prüfen Sie TLS und Reverse Proxy mit TLS und Reverse Proxy, wenn öffentliche Erreichbarkeit nach dem Update auffällt.