Produktupdates ohne manuelle Nacharbeit

Workspace führt bei einem unterstützten Update alle sicheren, produktbesessenen Übergänge selbst aus. Sie müssen keine Datenbankspalten, Systemartefakte, Taskstream-Sources oder Revisionsanker einzeln prüfen und keine Apply-Befehle aus Release-Notizen ableiten.

Vor jedem Update erstellt die gestagte Zielversion einen read-only DeploymentPlan. Er bindet Quell- und Ziel-Baseline, Zielartefakt, Backup, Übergangsklasse und den Point of No Return. Erst ein bereiter Plan erlaubt die Aktivierung.

Muss ich nach einem fehlgeschlagenen Update eine andere Version laden?

Nicht allein wegen eines 503, einer sichtbaren Loginseite oder retry_wait. Entscheiden Sie anhand des persistierten Übergangszustands:

Ein Schema-Upgrade kann erfolgreich gewesen sein, obwohl Product Release danach fehlschlägt. Der Gesamtstart ist dann nicht erfolgreich, die Datenbankänderung ist aber real. Starten Sie deshalb nie testweise eine ältere Binary. Prüfen Sie schemaTransitionClass, pointOfNoReturnAt, minimumRuntimeBaseline und rollbackAfterSchemaTransition, bevor Sie über Recovery entscheiden.

Betriebsform wählen

Entscheiden Sie vor dem Update, welche Verfügbarkeit Ihre Installation erreichen muss:

Ein unterbrechungsfreies Rolling-Update setzt voraus, dass die laufende Quellversion im unterstützten Mixed-Version-Fenster der Zielversion liegt. Der DeploymentPlan muss dafür transitionClass: compatible_expand und eine zur Quellversion passende minimumRuntimeBaseline melden. Ein forward_only-Übergang benötigt ein Wartungsfenster. Workspace hält kompatible alte Knoten während der Reconciliation im Serving-Zustand. Inkompatible Knoten nehmen keine neue Arbeit mehr an und wechseln kontrolliert in drained.

Point of No Return verstehen

Die physische Schema-Baseline beschreibt den Datenbankstand. Die minimumRuntimeBaseline nennt die älteste Server-Baseline, die diesen Stand noch öffnen darf.

Zielversion vorab prüfen

Stagen oder pullen Sie die Zielversion, ohne sie zu aktivieren. Erstellen Sie danach ein vollständiges Backup mit echtem Restore-Test. Starten Sie die Ziel-Binary getrennt vom Load Balancer im Modus deployment-preflight. Dieser Modus öffnet nur den Diagnoseendpunkt, setzt PostgreSQL für alle Verbindungen auf default_transaction_read_only=on und meldet sich nie als betriebsbereite Workspace-Instanz:

nucleus deployment-preflight \
  --config /pfad/zur/nucleus.config.enc \
  --listen 127.0.0.1:8444 \
  --target-digest sha256:<digest> \
  --backup-evidence /sicher/backup-evidence.json

nucli \
  --host https://workspace.example.com \
  --tenant system \
  system update doctor \
  --target-url https://127.0.0.1:8444 \
  --target-digest sha256:<digest> \
  --json

nucli liest den autoritativen Quellzustand vom laufenden Server und vergleicht ihn mit dem von der Ziel-Binary gelesenen Datenbankzustand. Es bindet Release, Manifest, Schema-Baseline, Ziel-Digest und System-Tenant in eine kurzlebige Evidenz. Der Befehl verändert keine Daten.

Der gemeldete updateMode ist rolling, maintenance_required, bridge oder offline. --watch wartet nur auf bereits laufende, vorübergehende Product-Release-Arbeit. Ein Preflight-Prozess wird niemals zur normalen Serverinstanz hochgestuft. Stoppen Sie ihn und starten Sie danach exakt dieselbe Binary beziehungsweise denselben OCI-Digest im normalen Modus.

Wenn der laufende Server nicht erreichbar ist, verwenden Sie numin deployment plan aus exakt dem Zielartefakt als privilegierten Offline-Fallback. Verwenden Sie numin nicht, um Authentisierung oder die serverseitigen Verträge eines erreichbaren Servers zu umgehen.

Ungültige Fulfillment-Follow-up-Modi korrigieren

Stoppen Sie das Update. Der Doctor meldet in diesem Fall den Check fulfillment_follow_up_mode_contract mit der Aktion update_fulfillment_follow_up_mode_invalid. Aus Sicherheitsgründen nennt der Remote-Preflight nur affectedCount, aber keine Mandanten oder Produktvarianten.

Führen Sie die lokale, read-only Diagnose mit der numin-Version aus dem gestagten Zielartefakt aus:

numin --config /data/nucleus.config.enc schema migrations status --json

Die Ausgabe unter preflightFindings enthält die Gesamtzahl und bis zu 500 deterministisch sortierte Tenant-/Varianten-IDs. truncated: true signalisiert weitere betroffene Datensätze. Korrigieren Sie ausschließlich die aufgeführten Produktvarianten über die bestehende tenantgebundene PIM-Pflege auf manual oder automatic. Einen --apply-Pfad bietet numin dafür bewusst nicht.

Rufen Sie nach jeder Korrekturrunde zuerst die lokale Diagnose und danach nucli system update doctor erneut auf; die Zielversion dürfen Sie erst aktivieren, wenn der Befund verschwunden ist und der Remote-Preflight wieder Exit-Code 0 liefert.

Rolling- oder Blue/Green-Update durchführen

1. Erstellen Sie die für Ihre Betriebsform vorgesehene Sicherung.
2. Stellen Sie sicher, dass der Load Balancer ausschließlich Instanzen mit erfolgreichem /health/ready-Check für Business-Traffic verwendet.
3. Führen Sie den Ziel-Preflight aus und verlangen Sie Exit-Code 0 sowie updateMode: rolling.
4. Stoppen Sie den Preflight. Starten Sie exakt denselben Digest neben mindestens einer kompatiblen, weiterhin bereiten alten Instanz. Beenden Sie die alte Instanz noch nicht.
5. Beobachten Sie den geschützten Status der neuen Instanz:

   nucli --tenant system system product-release status --watch

1. Warten Sie, bis die neue Instanz auf /health/ready mit HTTP 200 antwortet.
2. Nehmen Sie die neue Instanz in den Business-Traffic auf. Entfernen Sie die alte Instanz erst danach.

Einzelinstanz aktualisieren

1. Stagen Sie die Zielversion, ohne sie zu aktivieren.
2. Erstellen Sie die vorgesehene Sicherung und prüfen Sie die Wiederherstellung.
3. Führen Sie den Ziel-Preflight aus und verlangen Sie Exit-Code 0.
4. Beginnen Sie erst bei einem bereiten Plan das geplante Updatefenster.
5. Aktivieren Sie exakt das geprüfte Zielartefakt.
6. Beobachten Sie den geschützten Status:

   nucli --tenant system system product-release status --watch

1. Geben Sie die Installation erst frei, wenn /health/ready mit HTTP 200 antwortet.

Die Release-Bundles automatisieren diese Reihenfolge:

# Docker Compose
./start.sh backup
./start.sh update git.schukai.me/releases/nucleus@sha256:<digest>

# DEB oder RPM: Paketinstallation staged nur
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

# Kubernetes
./update.sh \
  git.schukai.me/releases/nucleus@sha256:<digest> \
  /sicher/backup-evidence.json

Docker und Kubernetes verlangen einen unveränderlichen Image-Digest. Der native Paketmanager startet die neue Version nicht und migriert beim Installieren keine Datenbank.

Während Workspace den Releasevertrag abgleicht, bleibt /health/live erreichbar. /health/ready antwortet bis zur vollständigen Verifikation mit HTTP 503. /health/product-release zeigt den begrenzten Release-Zustand. Alle drei Endpunkte bleiben nach der Trafficfreigabe erreichbar; /health/ready und /health/product-release antworten dann mit HTTP 200 und melden den verifizierten Release-Status succeeded.

Browser können in dieser Zeit weiterhin bereits veröffentlichte öffentliche Sites und die Anmeldeseite der Administrationsoberfläche laden. Workspace liefert dabei ausschließlich das veröffentlichte Live-Artefakt über GET und HEAD aus. Preview-Modi, Builds, Analytics-Aufzeichnung, APIs und schreibende Funktionen bleiben geschlossen. Eine nicht auflösbare Site zeigt eine lokalisierte Wartungsseite mit HTTP 503. Explizite JSON-Clients erhalten weiterhin den begrenzten Maintenance-Status.

Worker, Analytics-, SFTP- und SMTP-Laufzeiten sowie APIs und schreibende Business-Routen starten erst nach der Verifikation. Eine sichtbare Administrationsoberfläche bedeutet deshalb noch nicht, dass Workspace bereits schreibbereit ist. Verwenden Sie /health/ready als Freigabekriterium. Bereits veröffentlichte Sites und die Anmeldeseite bleiben sichtbar, aber eine Einzelinstanz ist in diesem Zeitraum nicht arbeitsfähig.

Ein normaler Updateablauf benötigt kein numin ... --apply, kein system-init apply, keinen direkten Datenbankzugriff und keine aus Release-Notizen erratene Reihenfolge von Wartungsschritten.

Vorübergehende Betriebsfehler zeigt der geschützte Status als retry_wait; Workspace wiederholt den gefenceten Release-Lauf automatisch mit begrenztem Backoff. blocked meldet einen fachlichen Konflikt, failed einen Vertragsfehler der gestarteten Binary. Diese terminalen Zustände benötigen eine Korrektur und werden nicht durch endlose Wiederholungen verdeckt.

Was Workspace automatisch prüft

Der mit der Binary ausgelieferte Releasevertrag bindet das unterstützte Schema- und Vertragsfenster, globale Systemartefakte, die Workflow-Bibliothek, den Taskstream-Katalog, Executor, Scheduler, Producer-Sources sowie positive Tenant- und IAM-Revisionsanker. Er prüft zudem alle gepinnten Workflow-Versionen, verwalteten Bindings, aktiven Tenant-Overrides und effektiv verwendbaren System-Fallbacks aller nicht gelöschten Tenants. Damit kann ein fehlerhafter Workflow nicht erst beim ersten Geschäftsvorgang auffallen. Übersprungene Zwischenreleases spielen keine Rolle, wenn die Ziel-Binary den letzten vollständig verifizierten Quellrelease und dessen vollständige Schema-Übergangskette ausdrücklich im Katalog führt. Unbekannte oder nicht veröffentlichte Quellstände blockieren geschlossen.

Workspace plant zuerst den gesamten Übergang. Erst wenn dieser Preflight keine Konflikte findet, wendet der Server die als automatic_safe deklarierten Schritte an. Jeder Schritt ist persistent, idempotent sowie durch Lease und Fence-Token gegen parallele Instanzen geschützt. Mehrere Instanzen teilen denselben Tenant-Snapshot und denselben Release-Run. Inkompatible alte Instanzen beenden neue Arbeit, warten laufende Taskstream- und Workflow-Artefaktversuche ab und wechseln vor der Mutation in drained.

Eine neue Workflows-Modulversion aktualisiert bestehende Mandanten nicht im Hintergrund. Soll ein bestehender Mandant die aktuelle verwaltete Workflowauswahl erhalten, starten Sie den dafür angebotenen Provisionierungslauf ausdrücklich. Workspace bindet den Lauf an sein aktuelles Modulziel. Ein alter, bereits abgeschlossener Lauf wird dadurch weder umgeschrieben noch still fortgesetzt.

Einen blockierten Updatezustand prüfen

Vorhandene ungültige Revisionen, inaktive Producer-Sources, unbekannte persistierte Taskstream-Typen, nicht kompilierbare Workflows und inkompatible kundeneigene Overlays bleiben absichtlich unverändert.

nucli --tenant system system product-release status --json

Der geschützte Status-Endpunkt bleibt auch während des Product-Release-Gates erreichbar. Er zeigt Run, Retry-Zeitpunkt, Tenant-Snapshot, Komponenten, Runtime-Evidenz und Blocker mit verantwortlichem Bereich und nächster Aktion. Er zeigt zusätzlich schemaBaseline, minimumRuntimeBaseline, schemaTransitionClass, schemaTransitionManifestDigest, pointOfNoReturnAt und rollbackAfterSchemaTransition. Die Antwort enthält keine SQL-, Pfad-, Treiber- oder Secret-Details. numin bleibt die lokale, read-only Diagnose für eine privilegierte Betriebsumgebung; für einen erreichbaren Server verwenden Sie nucli.

Ein Agent liest den verbindlichen Ablauf mit nucli skills show deployment. Ein MCP-Client kann danach nucleus_deployment_assess mit normalisierten, nicht geheimen Statusfeldern aufrufen. Das lokale Assessment nennt versionAction, recoveryMode, nächste Schritte und Stop-Bedingungen, nimmt aber keine Freigabe vor und verändert weder Pin noch Datenbank. Übergeben Sie keine Tokens, Passwörter, Credential-Dateien oder ungefilterten Logs.

Bei der Erstinstallation ist noch keine Login-Session verfügbar. Verwenden Sie den im Logblock SYSTEM INITIALIZED ausgegebenen System-API-Key ausschließlich über stdin:

read -r -s NUCLEUS_BOOTSTRAP_TOKEN
printf '%s\n' "$NUCLEUS_BOOTSTRAP_TOKEN" |
  nucli \
    --host https://workspace.example.com \
    --tenant system \
    system product-release status \
    --watch \
    --token-stdin
unset NUCLEUS_BOOTSTRAP_TOKEN

--token-stdin überspringt Login und optionale Discovery, speichert den Token nicht und verwendet weiterhin die serverseitige System-Tenancy und Diagnoseberechtigung.

Beheben Sie den gemeldeten fachlichen Konflikt über den vorgesehenen Produktvertrag und starten Sie dieselbe Binary erneut. Der Release-Run setzt an seinen verifizierten Checkpoints fort.

Wenn Login oder Serverstatus nicht erreichbar sind, verwenden Sie lokal das versionsgleiche Zielwerkzeug:

/pfad/zur/zielversion/numin \
  --config /pfad/zur/nucleus.config.enc \
  deployment plan --artifact-digest <sha256> \
  --backup-evidence /sicher/backup-evidence.json --json
/pfad/zur/zielversion/numin \
  --config /pfad/zur/nucleus.config.enc \
  schema migrations status --json

Verwenden Sie dafür niemals das numin einer älteren Installation.

Kritische reine Laufzeitfehler

Ein signiertes OCI-Hotfix-Image darf den schnelleren Emergency-Pfad nur verwenden, wenn sein Manifest stateChangeClass: runtime_only deklariert und Product Release, Schema, Konfiguration sowie Storage unverändert bleiben. Signaturprüfung, Canary und Produktionsfreigabe sind getrennte Gates. Der Emergency-Pfad gilt nicht für DEB, RPM oder Standalone-Binaries.

Folgen Sie Kritische Laufzeitfehler sicher beheben, um Image und Manifest zu prüfen, den Ziel-DeploymentPlan auszuführen, frische API- und Browser- Sessions zu testen und den exakten Rückweg zu bestätigen.

Neue Tenants

Neue Tenants verwenden automatisch standard.v1 mit iam, workflows, crm, localization, commerce, pim und forum. Workspace legt positive Autorisierungsanker vor dem ersten Producer- oder Job-Artefakt an. Business- Routen bleiben gesperrt, bis alle Profilschritte verifiziert wurden.

POST /api/v1/system/tenants legt Tenant, Eigentümerbindung und Provisionierungs-Run atomar an. Senden Sie für Automatisierungen einen Idempotency-Key. Workspace antwortet mit HTTP 202, Location, Retry-After, Tenant, Run und Status-URL. Derselbe Schlüssel mit demselben normalisierten Request liefert denselben Run; ein anderer Request mit diesem Schlüssel liefert HTTP 409.

Systemadministratoren lesen den Zustand mit nucli --tenant system system tenant-provisioning status <tenant-id> oder unter GET /api/v1/system/tenants/{tenant-id}/provisioning. Unterbrochene Läufe werden paginiert, mit dauerhaftem Backoff und auf demselben Run fortgesetzt. GET /api/v1/system/tenants?include=provisioning ergänzt den jeweils letzten Zustand für eine paginierte Tenant-Liste mit einer einzigen Batch-Abfrage. Business-Routen bleiben bis succeeded gesperrt.