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:

bash

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:

bash

/bin/numin version

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

bash

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

Die angezeigte Version muss zur eingesetzten Serverversion passen.

Das richtige Werkzeug wählen

Situation	Vorgehen
Der Server läuft und Sie prüfen Benutzer, Mandant, Ressourcen oder Findings	Verwenden Sie `nucli`.
Der Server startet wegen eines lokalen Schema-Contract- oder Baseline-Befunds nicht	Prüfen Sie mit `numin schema`.
Ein Produktupdate bleibt im Maintenance-Gate	Prüfen Sie read-only mit `numin product-release status --json`.
Sie planen eine Erstinstallation oder ein Update	Prüfen Sie Zielartefakt, Backup und Schemaübergang mit `numin deployment plan`.
Sie gleichen Inventory-Ledger und Bestandsaggregate ab	Starten Sie `numin inventory reconcile` ohne `--apply`.
Sie aktualisieren den lokalen Source-Vertrag einer Site	Prüfen Sie zuerst `numin site upgrade-contract` ohne `--apply`.
Sie bereiten den dokumentierten Taskstream-Attempt-Cutover vor	Frieren Sie die alte Runtime ein und prüfen Sie `numin taskstream attempt-cutover` ohne `--apply`.
Ein dokumentierter historischer Recovery-Fall betrifft Taskstream-Producer-Sources	Prüfen Sie `numin taskstream producer-sources status --json`; normale Produktupdates legen fehlende Sources automatisch an.
Sie haben den initialen System-Admin-Zugang verloren	Verwenden Sie den expliziten stdin-Passwortreset.
Ein dokumentierter `numin`-Befehl deckt die Aufgabe nicht ab	Stoppen Sie. Erfinden Sie keinen direkten Datenbank-Repair.

Schema und Baseline prüfen

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

bash

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 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.

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

bash

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.

Installation oder Update planen

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

bash

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:

json

{
  "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:

bash

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.

Inventory-Projektion abgleichen

Prüfen Sie zuerst alle Ledgergruppen und Bestandsaggregate:

bash

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

Grenzen Sie die Prüfung bei Bedarf ein:

bash

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:

bash

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:

bash

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:

bash

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:

bash

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

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

bash

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:

bash

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:

bash

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.

Site-Vertrag aktualisieren

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

bash

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:

bash

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:

bash

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

Exit-Code	Bedeutung
`0`	Der Befehl war erfolgreich; bei Prüfungen besteht kein offener Befund.
`1`	Die Prüfung war erfolgreich und hat Handlungsbedarf erkannt.
`2`	Aufruf, Konfiguration, Verbindung oder Ausführung ist fehlgeschlagen.

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.