Werkspur Docs
Zur Website

Integration: Fehlersuche

Sicherer Diagnosebeginn

Arbeiten Sie von innen nach außen: zuerst Prozess und Kernabhängigkeiten, dann Sitzung und Konfiguration, zuletzt das externe Protokoll. So vermeiden Sie Tests mit echten Zugangsdaten, solange die Anwendung selbst noch nicht bereit ist.

Die Beispiele verwenden eine absichtlich nicht erreichbare Platzhalteradresse und ein Platzhaltertoken:

export WERKSPUR='https://werkspur.internal.invalid'
export WERKSPUR_SESSION='<SESSION_TOKEN>'

Ersetzen Sie beides nur in einer lokalen Shell. Schreiben Sie weder Sitzungstoken noch Secret-Werte in ein Ticket, eine Dokumentationsdatei oder ein gemeinsam genutztes Skript.

Prüfen Sie zuerst Liveness und Readiness. Beide Endpunkte brauchen keine Anmeldung:

curl -sS "$WERKSPUR/healthz"
curl -sS "$WERKSPUR/readyz"

Prüfen Sie danach die Sitzung und Rolle:

curl -sS \
  -H "Authorization: Bearer $WERKSPUR_SESSION" \
  "$WERKSPUR/api/sessions/current"

401 bedeutet fehlende oder ungültige Sitzung. 403 bedeutet gültige Sitzung mit zu niedriger Rolle. Die Konfigurationsendpunkte in diesem Kapitel brauchen admin.

Für eine Compose-Installation lesen Sie zuletzt die Anwendungsprotokolle im relevanten Zeitraum:

docker compose -f deploy/docker-compose.yml logs --since 10m werkspur

Teilen Sie nur die Korrelations-ID, den Zeitstempel und die bereinigte Fehlermeldung. Entfernen Sie Tokens, Secret-Werte, interne Adressen und Nutzdaten.

REST und SOAP

  1. Öffnen Sie „Zielsysteme“ oder lesen Sie die Definitionen über die Admin-API:

    curl -sS \
  -H "Authorization: Bearer $WERKSPUR_SESSION" \
  "$WERKSPUR/api/destinations"

  2. Prüfen Sie kind, base_url und die Trennung von Basisadresse und Aktionspfad. REST und SOAP verlangen http:// oder https:// mit Host.

  3. Prüfen Sie bei Authentifizierung nur, ob auth.header und der Name in auth.secret gesetzt sind. Lassen Sie den Secret-Wert verborgen. Fehlt der referenzierte Secret-Name, sendet WERKSPUR den Aufruf nicht ohne Authentifizierung.

  4. Prüfen Sie bei SOAP die gespeicherte WSDL-Zusammenfassung, Operation, SOAPAction und XPath-Ausdrücke. Ein SOAP-Fault wird als fehlgeschlagener externer Aufruf behandelt.

  5. Ordnen Sie den Aktionsstatus ein: 422 weist meist auf Definition oder Eingabe, 502 auf den externen Aufruf. Verwenden Sie die X-Correlation-ID der Antwort, um denselben Lauf im Protokoll zu finden.

Es gibt keinen allgemeinen REST- oder SOAP-Test-Endpunkt. Lösen Sie nicht auf Verdacht eine mutierende Produktionsaktion aus. Verwenden Sie nur eine ausdrücklich dafür angelegte, lesende Testaktion und eine freigegebene Testgegenstelle. Ohne eine solche Gegenstelle endet die sichere Diagnose bei Definition, Namensauflösung, Netzwerkpfad und bereinigtem Fehlerprotokoll.

OPC UA

  1. Öffnen Sie „OPC-UA-Ziele“ oder lesen Sie die Ziele über GET /api/opcua-targets:

    curl -sS \
  -H "Authorization: Bearer $WERKSPUR_SESSION" \
  "$WERKSPUR/api/opcua-targets"

  2. Prüfen Sie endpoint, node, type und mode. opcua.read braucht read oder read-write; opcua.write braucht write oder read-write.

  3. Prüfen Sie den security-Block als Einheit. Sign und SignAndEncrypt brauchen eine Policy. Benutzer-, Zertifikats- und Schlüsselwerte stehen nur als Secret-Namen in der Definition.

  4. Bei der Live-Anzeige lesen Sie den Snapshot ohne externes OPC-UA-Passwort:

    curl -sS \
  -H "Authorization: Bearer $WERKSPUR_SESSION" \
  "$WERKSPUR/api/telemetry?machine=<MACHINE_ID>"

    Eine leere Liste kann eine fehlende Telemetriebindung, ein unbekanntes Ziel oder einen noch nie empfangenen Wert bedeuten. quality: "bad" zeigt einen zuvor vorhandenen Wert mit gestörter Zielverbindung.

  5. Unterscheiden Sie die Pfade. Ein benanntes OPC-UA-Ziel mit Telemetriebindung versorgt das Live-Widget. Eine OPC-UA-Maschinenbindung versorgt den historischen Telemetrie- und Regelpfad. Ein funktionierender Pfad beweist den anderen nicht.

Für einen Schreibtest gibt es keinen generischen Ziel-Endpunkt. Verwenden Sie nur eine freigegebene Aktion und einen sicheren Testknoten. Ein 502 bei opcua.read oder opcua.write verweist auf Verbindung, Sicherheit, Knoten, Typ oder Modus.

MQTT

  1. Prüfen Sie in der Deployment-Umgebung, ob FOUNDRY_MQTT_URL nicht leer ist. Die Zuordnungs-API schaltet die Bridge nicht ein und ändert ihre Broker-Adresse nicht.

  2. Lesen Sie die Zuordnungen:

    curl -sS \
  -H "Authorization: Bearer $WERKSPUR_SESSION" \
  "$WERKSPUR/api/mqtt-mappings"

  3. Vergleichen Sie das veröffentlichte Topic Zeichen für Zeichen mit topic. + und # sind nicht erlaubt. Prüfen Sie außerdem enabled: true, machine_id und metric.

  4. Berücksichtigen Sie den Abgleich von bis zu 30 Sekunden nach einer Änderung.

  5. Prüfen Sie das Payloadformat. Zulässig sind eine Zahl oder ein JSON-Objekt mit numerischem value. Ungültige Payloads werden verworfen und erscheinen nur als Warnung im Anwendungsprotokoll.

  6. Prüfen Sie, ob Punkte gespeichert wurden:

    curl -sS \
  -H "Authorization: Bearer $WERKSPUR_SESSION" \
  "$WERKSPUR/api/telemetry?machine=<MACHINE_ID>&metric=<METRIC>&window=1h"

    Keine Punkte bei fehlerfreiem MQTT-Empfang lenken die Prüfung auf NATS und den Telemetry Ingest. Ein Readiness-Fehler für nats hat Vorrang.

  7. Prüfen Sie Zustandsregeln über GET /api/rules. Namen, Operator, Grenzwert, for_seconds, Zielzustand und enabled müssen passen. Eine Haltezeit braucht weitere passende Messpunkte; bloßes Warten ohne neue Samples löst nichts aus.

Veröffentlichen Sie nur dann eine Testnachricht, wenn Ihnen ein freigegebenes Test-Topic und die dafür vorgesehenen Broker-Zugangsdaten vorliegen. Diese Dokumentation enthält bewusst kein Broker-Passwort und keinen Befehl gegen eine reale Infrastruktur.

AMQP

  1. Prüfen Sie, ob FOUNDRY_AMQP_URL nicht leer ist. Der Wert ist nur der Einschalter für die eingehende Bridge und nicht die tatsächlich verwendete Broker-Adresse.

  2. Lesen Sie Zielsysteme und Listener getrennt:

    curl -sS \
  -H "Authorization: Bearer $WERKSPUR_SESSION" \
  "$WERKSPUR/api/destinations"

curl -sS \
  -H "Authorization: Bearer $WERKSPUR_SESSION" \
  "$WERKSPUR/api/amqp-listeners"

  3. Prüfen Sie am Zielsystem kind: "amqp", base_url, username und den vorhandenen Namen in auth.secret. Prüfen Sie am Listener ausschließlich name, destination, queue und event_type.

  4. Berücksichtigen Sie bis zu 30 Sekunden für Listener-Änderungen. Verbindungsabbrüche versucht die Bridge nach zwei Sekunden erneut.

  5. Prüfen Sie die Payload. Mehr als 256 KiB oder ungültiges JSON landet ohne Domain-Ereignis in <queue>.dlx. Eine gültige JSON-Nachricht wird erst nach dauerhaftem Anhängen bestätigt; ein Fehler löst ein Requeue aus.

  6. Prüfen Sie den nachgelagerten Trigger. match.event_type muss exakt event_type des Listeners entsprechen. Ein Feld ${event.data.reference} verlangt ein gleichnamiges Feld im JSON-Objekt.

  7. Wenn das Ereignis gespeichert ist, aber kein Trigger läuft, prüfen Sie die NATS-Readiness, den Triggerstatus enabled, den Aktionsnamen und run_as. Der AMQP-Listener ruft die Aktion nicht direkt auf.

WERKSPUR bietet keinen allgemeinen Endpunkt zum Veröffentlichen von AMQP-Nachrichten oder zum Prüfen einer Queue. Prüfen Sie die Dead-Letter-Queue mit den freigegebenen Werkzeugen Ihres Broker-Betriebs, ohne die Nachricht oder Zugangsdaten in ein Ticket zu kopieren.

Webhooks

Ein Webhook verwendet kein Sitzungstoken. Testen Sie mit einem eigens dafür vorgesehenen Secret-Wert und einem neutralen JSON-Body:

curl -sS -X POST "$WERKSPUR/api/hooks/<WEBHOOK_NAME>" \
  -H 'Authorization: Bearer <WEBHOOK_SECRET_VALUE>' \
  -H 'Content-Type: application/json' \
  -d '{"reference":"<TEST_REFERENCE>"}'

Die Statusfolge grenzt die Ursache ein:

Ein beliebiger gültiger JSON-Body mit der Zeichenfolge ${body. ist nicht von sich aus ein Fehler. Entscheidend sind ausschließlich die Platzhalter in der gespeicherten Triggerdefinition und ob sie gegen Felder im Body aufgelöst werden können.

KI ist deaktiviert oder nicht konfiguriert

KI-Funktionen sind optional. Fehlt der konfigurierte Client, ist der Not-Aus-Schalter aktiv oder wurde ein Monatslimit ausgelöst, bleiben Fertigung, Buchungen und Integrationen nutzbar. Nur KI-Aufrufe werden blockiert.

Admins lesen den Zustand ohne einen Anbieter-Schlüssel offenzulegen:

curl -sS \
  -H "Authorization: Bearer $WERKSPUR_SESSION" \
  "$WERKSPUR/api/ai/settings"

curl -sS -X POST \
  -H "Authorization: Bearer $WERKSPUR_SESSION" \
  "$WERKSPUR/api/ai/ping"

/api/ai/ping antwortet bei deaktivierter KI mit 200 und {"status":"disabled"}. Generierungsendpunkte antworten in diesem Zustand mit 503 und {"error":"AI is unavailable"}. /readyz prüft KI nicht. Schalten Sie den Not-Aus-Schalter erst nach geklärter Freigabe aus. Die Anmeldung beim Anbieter gehört in die Bereitstellungsumgebung und nicht in einen API-Body.

Abschlussprüfung

Nach einer Korrektur wiederholen Sie nur die kleinste betroffene Stufe: Konfiguration lesen, einen neutralen Testdatensatz senden, Speicherung prüfen und erst danach Trigger oder Aktion beobachten. Dokumentieren Sie Status, Korrelations-ID, Zeitstempel und bereinigtes Ergebnis. Echte Zugangsdaten und fachliche Produktionsdaten bleiben außerhalb des Diagnoseprotokolls.

ZurückAPI & Authentifizierung WeiterInstallation & Betrieb