numin für lokale Offline-Administration

numin ist das lokale Wartungswerkzeug für Betreiber einer selbst gehosteten Workspace-Installation. Nutzen Sie es, wenn der Server für eine unterstützte Pre-Start-, Datenbank- oder Recovery-Aufgabe nicht verfügbar sein muss. Nach der Prüfung kennen Sie den lokalen Schema- oder Projektionszustand und können eine freigegebene Änderung kontrolliert anwenden.

Nutzen Sie für einen laufenden Server und tenantgebundene API-Aufgaben stattdessen nucli. numin besitzt keinen Remote-Login, öffnet keinen Listener und ersetzt keine Serverberechtigung.

Voraussetzungen

Verwenden Sie numin nur in einer privilegierten Betriebsumgebung. Sie benötigen:

• dieselbe numin-Version wie das zu prüfende Laufzeit- oder Zielartefakt,
• Zugriff auf die verschlüsselte Serverkonfiguration und ihren Config-Key,
• eine lokale Verbindung zur Workspace-PostgreSQL-Datenbank,
• für Site-Vertragsupgrades zusätzlich Zugriff auf den Storage-Root,
• eine aktuelle Sicherung und eine dokumentierte Freigabe vor Änderungen.

Geben Sie Config-Key, Datenbankpasswort und neue Administratorpasswörter nie in Logs, Tickets oder Befehlsargumenten aus.

Wählen Sie den Config-Key über seinen geschützten Dateipfad, bevor Sie die folgenden Beispiele ausführen:

export NUCLEUS_KEY_FILE=/data/nucleus-key

Bereitstellung prüfen

Das Workspace-Server-Image enthält numin unter /bin/numin. DEB, RPM und das Serverarchiv enthalten ebenfalls das versionsgleiche Binary. Verwenden Sie immer das Werkzeug aus demselben Laufzeit- oder Zielartefakt.

Prüfen Sie zuerst die Version:

/bin/numin version

Im Containerbetrieb können Sie den Befehl im vorhandenen Server-Container ausführen:

docker exec <workspace-container> /bin/numin version

Die angezeigte Version muss zur eingesetzten Serverversion passen.

Das richtige Werkzeug wählen

Schema und Baseline prüfen

Übergeben Sie den Pfad zur verschlüsselten Serverkonfiguration mit --config:

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

Die Befehle verändern keine Daten. Exit-Code 0 bestätigt einen erfolgreichen Zustand ohne Befund. Exit-Code 1 zeigt einen erfolgreich ermittelten Handlungsbedarf. Beheben Sie keinen Drift mit ad-hoc SQL.

schema migrations status --json meldet unter preflightFindings auch ungültige Werte des Vertrags fulfillment_follow_up_mode_contract. Der Befund enthält die Gesamtzahl, höchstens 500 nach Tenant- und Varianten-ID sortierte Identitäten sowie truncated. Er enthält keine Rohwerte und verändert nichts. Korrigieren Sie die betroffenen Produktvarianten über die tenantgebundene PIM-Pflege auf manual oder automatic und führen Sie den Befehl nach jeder Korrekturrunde erneut aus. Für diesen Befund gibt es keinen --apply- oder direkten Datenbankpfad.

schema migrations preflight --json prüft vor einem Update auch die Zeitfenster von Absenderprofil-Revisionen. Unter senderProfileRevisionWindow stehen der Status, die Anzahl ungültiger Fenster und die Anzahl überlappender Paare. Die Ausgabe nennt keine Tenant-, Profil- oder Revisionskennungen. Ein Status blocked verhindert die Schema-Transition. Stoppen Sie das Update und klären Sie eine unterstützte Korrektur der Bestandsdaten, bevor Sie den Preflight wiederholen. Verwenden Sie weder ad-hoc SQL noch einen numin --apply-Pfad; für diesen Befund gibt es keinen.

Datenbanken unterhalb der unterstützten Mindest-Baseline müssen zuerst über den dokumentierten Zwischenstand aktualisiert werden. Aktuelle Binaries enthalten keine historischen Direkt-Upgrader für beliebig alte Datenbanken.

Produktrelease prüfen

numin --config /data/nucleus.config.enc product-release status --json

Der Befehl ist read-only. Exit-Code 0 bestätigt den vollständig verifizierten Releasevertrag. Exit-Code 1 meldet einen blockierten, fehlgeschlagenen oder noch nicht abgeschlossenen Lauf. Ein normales Update besitzt keinen zugehörigen --apply-Befehl: Die offizielle Server-Binary führt ausschließlich ihre buildgebundenen sicheren Übergänge selbst aus.

Historische System-Root-Rollenbindung prüfen

Dieser einmalige Offline-Vertrag gilt für 7.30-Quellzustände, deren früherer Bootstrap die kanonische Gruppe System Root noch an die globale Rolle System Owner gebunden hat. Verwenden Sie vor dem geschützten Zielbinary-Doctor numin aus exakt dem gestagten Zielartefakt:

numin --config /data/nucleus.config.enc \
  iam system-root-role-binding --json

Exit-Code 0 mit status: ready bestätigt, dass keine Korrektur offen ist. Nur Exit-Code 1 mit status: repair_required, checked: 1, repairable: 1 und blockers: 0 beschreibt den exakt unterstützten Altzustand. Stoppen Sie vor dem Apply alle Server- und Worker-Prozesse, prüfen Sie das restore-getestete Backup und holen Sie eine ausdrückliche Betriebsfreigabe ein:

numin --config /data/nucleus.config.enc \
  iam system-root-role-binding --apply --json

Bei status: blocked, einem anderen Report oder Exit-Code 2 bleibt die Installation unverändert; untersuchen Sie den Zustand manuell. Nach einem erfolgreichen Apply starten Sie dieselbe Quellversion erneut, wiederholen den Dry-Run und erstellen ein neues vollständiges Backup mit Restore-Test. Erst diese Post-Repair-Evidenz darf der folgende Zielbinary-Doctor verwenden. Release- und Serverpfad führen den Apply niemals automatisch aus.

Installation oder Update planen

deployment plan verbindet den vorhandenen Datenbankstand mit dem buildgebundenen Vertrag der gestagten Zielversion. Der Befehl verändert keine Daten:

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

Verwenden Sie für <sha256> den Digest des exakten Ziel-Binarys oder OCI-Artefakts. Die Backup-Evidenz besitzt diesen Vertrag:

{
  "createdAt": "2026-07-31T10:00:00Z",
  "database": true,
  "storage": true,
  "config": true,
  "restoreTestedAt": "2026-07-31T10:15:00Z"
}

Die Datei enthält keine Passwörter und keine Backup-Inhalte. Exit-Code 0 meldet ready: true. Exit-Code 1 meldet stabile Aktionen, zum Beispiel ein fehlendes Zielartefakt, einen fehlenden Restore-Nachweis oder eine inkompatible Schema-Baseline. Der Plan akzeptiert die Evidenz höchstens 24 Stunden nach createdAt; erstellen und testen Sie bei einem späteren Aktivierungszeitpunkt ein neues Backup.

Beachten Sie transitionClass, minimumRuntimeBaseline, pointOfNoReturnReached, rollbackBefore und rollbackAfter. forward_only erlaubt nach dem Point of No Return keinen Start der alten Binary. Reparieren Sie mit der Zielversion vorwärts oder stellen Sie PostgreSQL, Storage, verschlüsselte Konfiguration und Runtime-Key gemeinsam wieder her.

Emergency-Manifest prüfen

Verwenden Sie diese Variante ausschließlich nach externer Signaturprüfung eines OCI-Manifests mit stateChangeClass: runtime_only:

numin --config /data/nucleus.config.enc deployment plan \
  --artifact-digest <ziel-digest> \
  --emergency-manifest /secure/emergency-release.json \
  --json

Fahren Sie nur bei ready: true, releaseMode: runtime_only und rollbackToSource.allowed: true fort. numin validiert den Binary-, Manifest- und Datenbankvertrag. Es bestätigt nicht die Signatur seines eigenen Images. Nutzen Sie dafür vorher den separat vertrauten Verifier unter Kritische Laufzeitfehler sicher beheben.

Historische Absenderprofile umstellen

Führen Sie diesen Cutover vor dem Start der Zielversion aus, wenn ein Bestandsupdate noch historische Absenderdaten meldet. Stoppen Sie alle Server- und Worker-Prozesse, prüfen Sie die aktuelle Sicherung und verwenden Sie numin aus genau dem Zielartefakt, das Sie danach starten.

Prüfen Sie zuerst den Zustand ohne Schreibzugriff:

numin --config /data/nucleus.config.enc \
  sender-profiles legacy-cutover status --json

Exit-Code 1 meldet Handlungsbedarf. Die Ausgabe enthält die betroffenen Profil-IDs, vorgeschlagene Senderprofil-IDs und die zulässigen Kandidaten für jedes Commerce-Profil. Sie enthält keine historischen Absenderinhalte.

Wählen Sie für jedes gemeldete Commerce-Profil ausdrücklich einen der angezeigten Kandidaten und erzeugen Sie den Plan in einem geschützten Pfad:

numin --config /data/nucleus.config.enc \
  sender-profiles legacy-cutover plan \
  --commerce-default <commerce-profile-id>=<sender-profile-id> \
  --output /secure/sender-profile-cutover.plan.json

Wiederholen Sie --commerce-default bei mehreren Commerce-Profilen. numin leitet keinen Standardabsender ab. Document- und Notification-Absender werden konservativ aus den vorhandenen Daten in den Plan übernommen. Die Plandatei ist 15 Minuten gültig und an Ziel-Binary sowie Datenbankzustand gebunden.

Prüfen Sie die Auswahl und wenden Sie genau diesen Plan nach der betrieblichen Freigabe an:

numin --config /data/nucleus.config.enc \
  sender-profiles legacy-cutover apply \
  --plan /secure/sender-profile-cutover.plan.json \
  --apply \
  --json

Der Apply-Lauf ist transaktional. Er setzt nur die geplanten Profile, Revisionen und Bindings, löscht keine historischen Felder und hebt die Schema-Baseline nicht an. Ein abgelaufener oder nicht mehr zum Zustand passender Plan wird abgelehnt. Führen Sie danach status --json erneut aus. Starten Sie die Zielversion erst, wenn ready: true mit Exit-Code 0 gemeldet wird.

Inventory-Projektion abgleichen

Prüfen Sie zuerst alle Ledgergruppen und Bestandsaggregate:

numin --config /data/nucleus.config.enc inventory reconcile --json

Grenzen Sie die Prüfung bei Bedarf ein:

numin --config /data/nucleus.config.enc inventory reconcile \
  --tenant-id <tenant-uuid> \
  --warehouse-id <warehouse-uuid> \
  --variant-id <variant-uuid> \
  --json

Die Ausgabe unterscheidet fehlende, verwaiste und mengenabweichende Bestandsaggregate. numin verändert dabei keine Ledgerbuchung.

Wenden Sie den Projektions-Rebuild nur nach Prüfung und Freigabe an:

numin --config /data/nucleus.config.enc inventory reconcile --apply --json

Die Aufgabe ist abgeschlossen, wenn ein anschließender Dry-Run keine Findings mehr meldet.

Taskstream auf persistierte Attempts umstellen

Nutzen Sie diesen Befehl nur für den dokumentierten Offline-Cutover auf den persistierten Taskstream-Delivery- und Producer-Source-Vertrag. Der Befehl ist keine laufende Wartungsfunktion. Stoppen Sie vorher alle alten Server-, Scheduler- und Worker-Prozesse und sperren Sie deren Datenbankzugang.

Prüfen Sie den eingefrorenen Bestand:

numin --config /data/nucleus.config.enc taskstream attempt-cutover --json

Der Plan ist nur anwendbar, wenn:

• Quell- und Ziel-Schema-Contract dem erwarteten Altvertrag entsprechen,
• kein Job queued oder running ist,
• noch keine Control-, Occurrence- oder Attempt-Historie existiert,
• Jobs mit demselben tenantlokalen Concurrency-Key kein widersprüchliches Limit besitzen.

Der Plan zeigt zusätzlich erwartete, aktive, fehlende, inaktive und ungültige Producer-Sources sowie die Taskstream-Autorisierungs-Revisionsanker aller aktiven Tenants. Fehlende Anker halten complete auf false, dürfen aber mit dem freigegebenen Apply als Revision 1 initialisiert werden. Eine vorhandene Revision 0 oder kleiner ist ungültig und setzt applyEligible auf false.

Bei einem bereits angewendeten Attempt-Cutover kann alreadyApplied: true zusammen mit einer fehlenden Source- oder Revisionsanker-Phase und applyEligible: true erscheinen. Der Apply holt dann nur die unvollständige Phase nach. Brechen Sie bei applyEligible: false und complete: false ab. Korrigieren Sie keinen Befund mit ad-hoc SQL und starten Sie --apply nicht automatisiert als Teil eines Deployments.

Führen Sie den Cutover erst nach dokumentierter Betriebsfreigabe aus:

numin --config /data/nucleus.config.enc taskstream attempt-cutover \
  --apply \
  --json

Der Apply-Lauf legt die technischen Tabellen, Controls, ausschließlich fehlende kataloggebundene Producer-Sources und ausschließlich fehlende Taskstream-Autorisierungs-Revisionsanker transaktional an. Ein Basisanker erteilt keine Berechtigung und ersetzt keine aktuelle Permission-Prüfung. Der Lauf verändert weder vorhandene Revisionen noch vorhandene Sources und reaktiviert keinen Tombstone. Er erfindet keine alte Ausführungshistorie. Bestandsjobs bleiben prüfpflichtig und inaktiv, bis ein Operator sie einzeln neu autorisiert. Beim erstmaligen Cutover hebt der letzte Schreibschritt den Schema-Contract als Downgrade-Sperre an.

Der Cutover ist abgeschlossen, wenn ein erneuter Dry-Run complete: true, producerSourcesComplete: true und authorizationRevisionAnchorsComplete: true meldet und ausschließlich kompatible neue Server-Binaries mit einer neuen Datenbank-Credential-Generation starten. Inaktive Sources bleiben dabei bewusst inaktiv. Starten Sie nach --apply kein altes Binary mehr. Ein Rollback erfolgt nur durch erneuten Freeze und ein vorwärtskompatibles korrigiertes Binary, nicht durch das Löschen der neuen Tabellen, Controls, Sources oder Revisionsanker.

Taskstream-Producer-Sources freigeben

Neue Installationen legen die aktuell katalogisierten internen Producer-Sources beim ersten globalen Bootstrap automatisch an. Bei einer bestehenden Installation kann ein Update neue Sources hinzufügen. Der Server bleibt dabei verfügbar; nur die betroffene Funktion bleibt blockiert.

Prüfen Sie zuerst den read-only Status:

numin --config /data/nucleus.config.enc \
  taskstream producer-sources status --json

Erzeugen Sie für fehlende Sources einen 15 Minuten gültigen Plan:

numin --config /data/nucleus.config.enc \
  taskstream producer-sources plan \
  --output /secure/path/taskstream-producer-sources.plan.json

Eine bewusst deaktivierte oder ungültige Source bleibt unangetastet. Geben Sie ihre exakte ID nur nach fachlicher Prüfung erneut frei:

numin --config /data/nucleus.config.enc \
  taskstream producer-sources plan \
  --reapprove nucleus.crm.lead.company_research \
  --output /secure/path/taskstream-producer-sources.plan.json

Prüfen Sie die Plan-Datei und wenden Sie exakt diesen Plan an:

numin --config /data/nucleus.config.enc \
  taskstream producer-sources apply \
  --plan /secure/path/taskstream-producer-sources.plan.json \
  --apply \
  --json

apply lehnt einen abgelaufenen Plan, ein anderes Binary und einen inzwischen geänderten Datenbank- oder Katalogzustand ab. Erzeugen Sie dann einen neuen Plan. Bearbeiten Sie Sources nicht mit SQL und starten Sie keinen Seeder. Prüfen Sie anschließend erneut den Status und nucli readiness.

CMS-Quelllayout aktualisieren

Stoppen Sie vor einem Upgrade auf das atomare Quelllayout alle Serverprozesse und CMS-SFTP-Worker. Prüfen Sie das Storage-Backup und führen Sie für jede Site zuerst einen Dry-Run aus:

numin --config /data/nucleus.config.enc site upgrade-source-layout \
  --site <site-uuid> \
  --json

Exit-Code 1 zeigt an, dass ein Eingriff erforderlich ist. Nach der Prüfung führen Sie denselben Befehl mit --apply aus. Legacy-Quellen werden zuerst in eine vollständige Generation kopiert und erst danach atomar aktiviert. Bei einem bereits aktuellen Layout entfernt die Offline-Wartung ältere Generationen und behält den aktuellen sowie den unmittelbaren Vorgänger.

numin --config /data/nucleus.config.enc site upgrade-source-layout \
  --site <site-uuid> \
  --apply \
  --json

Der Abschluss-Dry-Run muss state: current und actionRequired: false melden. Das Werkzeug ändert keine Datenbankdaten, Builds oder Releases. Starten Sie anschließend ausschließlich die versionsgleichen Server- und Worker-Binaries. Ein Downgrade auf eine Version ohne Generationenlayout wird nicht unterstützt.

Site-Vertrag aktualisieren

Prüfen Sie den lokalen Source-Vertrag einer Site:

numin --config /data/nucleus.config.enc site upgrade-contract \
  --site <site-uuid> \
  --target 2 \
  --json

Prüfen Sie Plan, Warnungen und Zielversion. Wenden Sie den Plan erst danach an:

numin --config /data/nucleus.config.enc site upgrade-contract \
  --site <site-uuid> \
  --target 2 \
  --apply \
  --json

Die Aktualisierung ist abgeschlossen, wenn der erneute Dry-Run keine offenen Änderungen mehr zeigt. Verwenden Sie nucli weiterhin für normale Site-Inspektion, Dateien, Builds und Veröffentlichung.

Initiales System-Admin-Passwort zurücksetzen

Der Passwortreset ist eine unmittelbare Recovery-Aktion und besitzt keinen --apply-Schalter. Übergeben Sie das neue Passwort ausschließlich über stdin:

read -rsp 'Neues Passwort: ' NEW_PASSWORD
printf '%s\n' "$NEW_PASSWORD" \
  | numin --config /data/nucleus.config.enc admin reset-password \
      --password-stdin \
      --email admin@system.nucleus
unset NEW_PASSWORD

numin setzt nur das initiale System-Admin-Credential zurück und widerruft zugehörige Sitzungen beziehungsweise Bootstrap-Freigaben. Die Ausgabe enthält das Passwort nicht. Melden Sie sich anschließend neu an und prüfen Sie den Zugang mit nucli whoami.

Exit-Codes auswerten

Behandeln Sie Exit-Code 1 nicht als Verbindungsfehler. Lesen Sie den strukturierten Befund und entscheiden Sie danach über den nächsten Schritt.

Nächste Schritte

• Nutzen Sie nucli für autorisierte Remote-Diagnose und tenantgebundene Administration.
• Ordnen Sie die lokale Blob-v2-Root-Key-Inventur unter Blob-v2-Schlüsselinventur ein. Erfinden Sie dafür keinen nicht dokumentierten numin-Befehl.
• Planen Sie Serverupdates mit Updates und Rollback.
• Prüfen und veröffentlichen Sie Sites über Sites und CMS.