Diagnose und Readiness

Diese Seite beschreibt öffentliche Diagnosewege für Administratoren und Betreiber. Nutzen Sie zuerst redigierte Status- und Readiness-Ausgaben, bevor Sie Logs oder Rohdaten weitergeben.

Für CLI-Diagnosen brauchen Sie einen lokalen nucli-Tenant-Alias und eine gültige Session im Zielmandanten. Die Grundlagen zu Installation, Profilen, Tenant-Alias und Tenant-ID stehen unter nucli.

Erreichbarkeit prüfen

Prüfen Sie nach Start, Update oder Ingress-Änderung zuerst den technischen Ping:

curl -sk https://<workspace-url>/api/v1/ping

Prüfen Sie danach die Administrationsoberfläche im Browser und melden Sie Fehler mit Zeitpunkt, betroffener Umgebung, angemeldetem Kontext und reproduzierbaren Schritten.

CLI-Diagnose nutzen

Prüfen Sie vor jeder Diagnose zuerst, welches lokale Profil und welcher aktive Tenant verwendet werden:

nucli profiles
nucli --tenant <tenant-alias> whoami
nucli --tenant <tenant-alias> --tenant-id <tenant-id> doctor

--tenant <tenant-alias> wählt ein lokales nucli-Profil. --tenant-id prüft die serverseitige Tenant-UUID. Der Guard ist besonders wichtig in Skripten, CI-Jobs und Supportabläufen, weil er bei einem falschen Profil abbricht.

Nutzen Sie die Diagnosebefehle in dieser Reihenfolge:

nucli doctor prüft Profil, Host, Tokenstore, Session, Mandantenkontext und öffentliche Discovery. Der Befehl gibt keine Tokenwerte, Cookie-Namen, Tokenquellen, Identitäts-IDs oder Scope-Listen aus.

nucli --tenant <tenant-alias> doctor
nucli --tenant <tenant-alias> --tenant-id <tenant-id> doctor
nucli --tenant <tenant-alias> doctor --json

nucli diagnose ruft die tenantgebundene Diagnose-API ab. Die Ausgabe enthält kuratierte Status- und Zählwerte, aber keine Tokenwerte, SMTP-Secrets, Empfängerlisten, Mail-Inhalte, Queue-Payloads, Personen- oder Adressdaten.

nucli --tenant <tenant-alias> diagnose
nucli diagnose --all-tenants --json

Nutzen Sie --all-tenants nur für lokal konfigurierte Profile mit gespeicherter Session. Ein globaler NUCLI_TOKEN wird dabei nicht über alle Profile ausgerollt. Der Befehl ruft keine serverseitige Tenant-Liste ab; er arbeitet nur die Profile ab, die auf Ihrem Rechner existieren.

Beispiel für zwei Mandanten:

nucli --tenant shop-prod --host https://workspace.example.com login --email admin@example.com
nucli --tenant shop-stage --host https://stage-workspace.example.com login --email admin@example.com

nucli --tenant shop-prod whoami --json
nucli --tenant shop-stage whoami --json
nucli diagnose --all-tenants

Wenn die Mail-Queue ein bekanntes aktuelles Finding meldet, bestätigen Sie es mit Pflichtgrund:

nucli --tenant <tenant-alias> findings list --source mail_queue
nucli --tenant <tenant-alias> findings acknowledge <fingerprint> --source mail_queue --reason "<Grund>"

Eine Bestätigung repariert den Mail-Job nicht. Requeue oder fachliche Bereinigung bleiben separate Wartungsaktionen.

Typische CLI-Fehler einordnen

Site-Domain-Readiness prüfen

Prüfen Sie nach Domain-Verifikation, Site-Domain-Bindung, Build oder Ingress-Änderung die konkrete Site. Nach einem erfolgreichen Lauf ist die Site öffentlich auslieferbar und web wait meldet operations readiness: ready.

nucli --tenant <tenant-alias> web readiness <site-id>
nucli --tenant <tenant-alias> web wait <site-id> --timeout 5m

web readiness liefert stabile Check- und Detail-Schlüssel. Die Ausgabe nennt keine internen Edge-URLs, Dial-Adressen, Node-Namen, Provider-Referenzen, SQL-Details oder Proxy-Ziele.

Behandeln Sie fehlende Edge-Veröffentlichungen nicht durch Einträge in System Domains (CSV). Öffentliche Website-Hosts gehören in den Zielmandanten, nicht in den Systemmandanten.

Operative Findings in der Oberfläche bestätigen

Nutzen Sie die Oberfläche, wenn Sie ein bekanntes Mail-Queue-Finding nicht weiter als offenen Handlungsbedarf sehen möchten:

1. Öffnen Sie System > Mail Server.
2. Wechseln Sie in den Tab Queue-Übersicht.
3. Prüfen Sie die Kennzahlen Offene Findings und Bestätigte Findings.
4. Klicken Sie in der betroffenen Zeile auf Bestätigen.
5. Tragen Sie unter Grund für die Bestätigung ein, warum das Finding aktuell akzeptiert ist.

Bestätigte Findings bleiben in der Queue sichtbar, zählen aber nicht mehr als offener Handlungsbedarf im Dashboard. Öffnen Sie ein Finding wieder, sobald es erneut aktiv bearbeitet werden soll: Klicken Sie in der Zeile auf Wieder öffnen und geben Sie einen Grund für das Wiederöffnen an.

Die Aktionen erscheinen nur mit der erforderlichen Wartungsberechtigung für die Mail-Queue. Ohne diese Berechtigung können Sie den Queue-Zustand einsehen, aber keine Findings bestätigen, wieder öffnen oder Jobs neu einreihen.

Storefront-Detailseiten überwachen

Produktdetailseiten können aus einer dynamischen Site-Page und vorgerenderten Product-Snippets bestehen. Wenn ein Required-Snippet für Tenant, Variante, Locale und Sales Channel fehlt, liefert die öffentliche Detailseite 503 Service Unavailable mit Retry-After. Workspace meldet diesen Zustand als kritischen Telemetry-Fehler mit der Quelle server.storefront.product_detail.snippet_missing.

Prüfen Sie den Befund in dieser Reihenfolge:

1. Öffnen Sie die Telemetry-Fehlergruppe oder die daraus erzeugte Aufgabe.
2. Prüfen Sie in den Telemetry-Instanzen Route, Variante, Site, Locale, Sales Channel und die fehlenden Snippet-Namen.
3. Prüfen Sie, ob nach Inhalts-, Medien- oder Template-Änderungen ein Snippet-Rebuild gelaufen ist.
4. Prüfen Sie die Produkt-Route und den freigegebenen Produktinhalt im Zielkanal.
5. Starten Sie den Rebuild oder korrigieren Sie die Snippet-Vorlage.
6. Rufen Sie die öffentliche Detail-URL erneut ab und erwarten Sie 200 OK.

Behandeln Sie den Fehler als umsatzrelevanten Betriebsbefund. Verweisen Sie Besucher nicht auf interne PIM- oder Admin-Daten und deaktivieren Sie den Telemetry-Alert nicht, solange die öffentliche Detailseite noch 503 liefert.

Workflow-Owned-Repair sicher verwenden

Workflow-Owned-Datensätze steuern Statuswechsel über eine Workflow-Instanz. Wenn diese Instanz fehlt, bleiben Workflow-Aktionen gesperrt. Reparieren Sie solche Datensätze nur über den expliziten Workflow-Owned-Repair. Normales Speichern, Listenaufrufe und Detailaufrufe reparieren keine fehlenden Workflow-Instanzen.

Arbeiten Sie immer in dieser Reihenfolge:

1. Prüfen Sie das Finding oder den Diagnosehinweis in der Oberfläche.
2. Führen Sie einen Dry-Run aus.
3. Kontrollieren Sie die geplanten Ziele: Entity-Typ, ID, Anzeigename, Workflow-Key und Startstatus.
4. Starten Sie die Reparatur erst, wenn die geplanten Ziele fachlich passen.
5. Prüfen Sie danach dieselbe Finding-Quelle erneut.

Der Dry-Run verändert keine Daten:

printf '{"dryRun":true,"entityType":"product_variant"}' | nucli --tenant <tenant-alias> api POST /api/v1/workflow-owned/repair --input -

Die Reparatur schreibt die fehlende Workflow-Bindung und erzeugt ein Audit-Ereignis:

printf '{"dryRun":false,"entityType":"product_variant"}' | nucli --tenant <tenant-alias> api POST /api/v1/workflow-owned/repair --input -

Begrenzen Sie gezielte Reparaturen mit entityIds, wenn Sie nur einzelne Datensätze bearbeiten möchten:

printf '{"dryRun":true,"entityType":"product_variant","entityIds":["<variant-id>"]}' | nucli --tenant <tenant-alias> api POST /api/v1/workflow-owned/repair --input -

entityIds darf höchstens 100 UUIDs enthalten. Für größere Korrekturen nutzen Sie die offene Finding-Liste und den unselektierten Dry-Run, statt große ID-Listen zu senden.

Aktuell unterstützt der generische Repair diesen Entity-Typ:

Wenn ein anderer entityType gemeldet wird, brechen Sie ab. Dafür muss zuerst ein eigener Entity-Adapter umgesetzt und freigegeben werden.

PIM-Varianten mit fehlendem Workflow-Lifecycle behandeln

Wenn eine Produktvariante ohne Workflow-Lifecycle geöffnet wird, zeigt das Varianten-Detail einen Diagnosehinweis. Workflow-Aktionen bleiben deaktiviert, und normales Speichern repariert den Datensatz nicht.

Gehen Sie so vor:

1. Kopieren Sie im Varianten-Detail die Diagnose. Die Diagnose enthält PIM_VARIANT_WORKFLOW_LIFECYCLE_MISSING, Varianten-ID, SKU, Name, Geschäftstyp und Workflow-Key.
2. Geben Sie die Diagnose an einen PIM-Admin oder Operations-Admin weiter.
3. Prüfen Sie als PIM-Admin die Admin-Seite PIM > Varianten & Preise > Lifecycle-Integrität.
4. Prüfen Sie alternativ per CLI die offenen Findings:

nucli --tenant <tenant-alias> findings list --source workflow_owned_integrity

Die Finding-Zeilen enthalten Variant-ID, SKU, Name, Familie, Workflow-Key, Lifecycle-Zeilenstatus, Workflow-Instanzstatus und Fingerprint. Die API und Oberfläche zeigen keine rohen SQL- oder Treiberfehler an.

Führen Sie vor jeder Reparatur einen Dry-Run aus:

printf '{"dryRun":true,"entityType":"product_variant"}' | nucli --tenant <tenant-alias> api POST /api/v1/workflow-owned/repair --input -

Der Dry-Run verändert keine Daten. Er zeigt, welche Varianten betroffen sind und welcher Workflow zugeordnet würde. Starten Sie den Fix erst, wenn die geplanten Varianten korrekt sind:

printf '{"dryRun":false,"entityType":"product_variant"}' | nucli --tenant <tenant-alias> api POST /api/v1/workflow-owned/repair --input -

Prüfen Sie danach erneut:

nucli --tenant <tenant-alias> findings list --source workflow_owned_integrity

Die Reparatur läuft über den generischen Workflow-Owned-Repair mit entityType=product_variant und benötigt pim_variant_lifecycle:repair. Die Diagnose benötigt pim_variant_lifecycle:diagnose. Die ältere Finding-Quelle pim_variant_lifecycle bleibt für bestehende Automationen kompatibel. PIM-Pfleger sehen den Hinweis im Varianten-Detail, reparieren aber nicht direkt über den normalen Pflegefluss.

System-Readiness prüfen

System-Readiness läuft über den System-Mandanten, weil diese Checks systemweite Betreiberverträge prüfen und nicht zu einem einzelnen Arbeitsmandanten gehören. Öffnen Sie System > Betriebsbereitschaft, um die redigierten systemweiten Checks in der Oberfläche zu prüfen. Nutzen Sie diese Sicht nach Setup, Updates und Tenant Init, bevor Sie fachliche Funktionen produktiv nutzen.

nucli readiness ruft GET /api/v1/system/readiness auf, filtert Checks und führt keine lokalen Provider aus.

nucli --tenant system readiness summary
nucli --tenant system readiness list --status pending
nucli --tenant system readiness wait --domain <domain> --check <check> --timeout 30s

Exitcodes:

Storage-Diagnose prüfen

Der Storage-Doctor stellt redigierte Systemdiagnose bereit:

• GET /api/v1/system/doctor/storage
• POST /api/v1/system/doctor/storage/probe

Der GET-Aufruf ist passiv. Er prüft keine Schreibrechte und verändert keine Daten. Der POST-Aufruf führt eine explizite Write/Delete-Probe aus und entfernt das technische Probe-Artefakt wieder.

Die Antwort enthält nur Vertrag, Zeitpunkt, Gesamtstatus und Checks. Sie enthält keine Dateipfade, Dateinamen, Store-Listen, ACL-Details, Secrets, Key-IDs, rohe Fehlertexte oder Stacktraces.

Wichtige Checks:

Ausgaben sicher weitergeben

Nutzen Sie für Supportfälle bevorzugt zusammengefasste oder redigierte CLI-Ausgaben:

nucli api GET /api/v1/meta/discovery --summary
nucli api GET /api/v1/meta/privacy --redact --save diagnostics-redacted.json

Prüfen Sie jede Datei vor der Weitergabe. Auch redigierte Diagnose kann Organisationsnamen, öffentliche URLs oder interne Betriebsinformationen enthalten.