Updates und Rollback

Diese Anleitung beschreibt den empfohlenen Ablauf für Updates von Workspace in Self-Hosting-Umgebungen. Ziel ist ein kontrollierter Versionswechsel mit nachvollziehbarer Prüfung und vorbereitetem Rollback.

Nutzen Sie diese Seite vor jedem Versionswechsel von Workspace. Nach Abschluss läuft die neue Version produktiv und ein Rollback ist vorbereitet.

Ein erfolgreiches Update bedeutet

  • neue Version installiert,
  • Anmeldung funktioniert,
  • Kernfunktionen funktionieren,
  • Rollback bleibt möglich,
  • Ä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.

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

Installieren Sie das passende Paketformat für Ihre Umgebung:

bash
sudo dpkg -i nucleus-server_<version>-1_amd64.deb
bash
sudo rpm -Uvh nucleus-server-<version>-1.x86_64.rpm

Wenn Sie das Archivformat verwenden, ersetzen Sie das Binary kontrolliert und starten Sie den Dienst danach über Ihren Service-Manager neu.

Container aktualisieren

Beziehen Sie das neue Image mit explizitem Versionstag und starten Sie die Laufzeit neu:

bash
docker pull git.schukai.me/releases/nucleus:<version>
docker compose up -d

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.

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 auf eine Version zurück, deren Artefakte, Konfiguration und Datenverträglichkeit für Ihre Umgebung geklärt sind. Verwenden Sie das vorherige Serverpaket oder den vorherigen Image-Tag und stellen Sie bei Bedarf Datenbank und persistenten Speicher 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.