Technische Problemlösung
Häufig auftretende Symptome / Fehler und Lösungen. Schnelle Klassifizierung → detaillierter Lösungsablauf.
status.sh— Container + Port + API + app.properties Kernschlüssel in einer Zeile zusammengefassthealth.sh— Umfassender Healthcheck basierend auf Exit-Codes (für cron geeignet)doctor.sh— Diagnose-Sammel-Tarball (api / docker / systemd / 7 Komponenten-Logs / config redacted / Host-Metriken) → Support-Eskalation/api/v1/system/health— Status-Map für 8 Komponenten + 503-Verzweigung (sofortige Identifikation, welche Komponente DOWN ist)- Betrieb im Container-Modus — Störungsbehebung + Befehls-Cheat-Sheet
Index nach Symptomen
| Symptom | Mögliche Ursache |
|---|---|
| App stoppt beim Booten | Cassandra-Verbindungsfehler, DDL-Anwendungsfehler |
/api/v1/edge Antwort ist started=false | Collector-Initialisierungsfehler (Treiber / Cache-Problem) |
Nur bestimmte OPC connection_status=DISCONNECTED | PLC-Netzwerk / Authentifizierung / Adressformat |
| Alle OPC fallen gelegentlich gleichzeitig aus | OPCUAServerManager vollständiger Neustart durch Hinzufügen/Ändern von OPC |
| MQTT-Publish funktioniert nicht | mqtt.enable=false oder Broker-Authentifizierungsfehler |
| Sparkplug-Topics werden nicht veröffentlicht | sparkplug.enable=false oder Jar fehlt |
| Bildschirm lädt langsam | opcList() N+1-Abfragen + kumulierte Sleeps |
| OPC-Start dauert jeweils 5 Sekunden | Thread.sleep Auswirkung (Zielgruppe Phase A1) |
Booten / Initialisierung
Cassandra-Verbindungsfehler
Caused by: com.datastax.oss.driver.core.exceptions.NoHostAvailableException
| Prüfung | Bestätigung |
|---|---|
| Cassandra läuft | nodetool status |
| Port erreichbar | telnet <app.db.host> 9042 |
| Keyspace vorhanden | cqlsh -u cassandra -p cassandra dann DESCRIBE KEYSPACE pe; |
app.db.* und oltp.cassandra.* stimmen überein | app.properties beide Einträge prüfen |
app.sql.path ist ein Tippfehler in resouces
Der resouces in app.sql.path = classpath:resouces/sql von app.properties ist ein Tippfehler, aber das Verzeichnis wird unter demselben Namen beibehalten, sodass es funktioniert. Wenn ein Fehler auftritt, dass SQL-Ressourcen nicht gefunden werden, prüfen Sie, ob der WEB-INF/resouces/sql/-Pfad tatsächlich existiert.
OPC / Treiber
Bestimmte OPC-Verbindung nicht möglich
| Protokoll | Erste Prüfung |
|---|---|
| OPCUA | opc_agent_port erreichbar, discovery=true versuchen, Benutzer/Passwort |
| Modbus TCP | Port 502 erreichbar, holding-register:... Format |
| MELSEC | MC-Protokoll aktiv, controller-type=Q_L Übereinstimmung |
| S7 | rack/slot Übereinstimmung, "PUT/GET" aktiv |
| LS | Bei NetUtils.isReachable-Fehler ICMP-Blockierung vermuten, Port 2004 |
| EIP | rack/slot, Port 44818 |
Zuerst die Tabelle "Häufige Fehler + Lösungen" auf der jeweiligen Treiberseite beachten.
LS-PLC Ping failed
Der LS-Treiber prüft die Erreichbarkeit vor dem connect per ICMP-Ping. Wenn ICMP im Firmennetz blockiert ist, wird auch eine normale PLC als fehlgeschlagen angezeigt.
Lösung:
- ICMP in der Firewall erlauben
- Oder Ping-Prüfung in
LSDriver.connect()optional deaktivierbar machen (aktuell ist eine Code-Änderung erforderlich)
32-bit / 64-bit Wert inkonsistent
Meistens ist format nicht angegeben die Ursache.
| Protokoll | Falsches Muster → Korrektes Muster |
|---|---|
| LS | D00600 + Integer (wird als 16-bit gelesen) → D00600 + Integer + format=DW |
| Modbus | holding-register:1 (16-bit) → holding-register:1:DINT |
| S7 | %DB1.DBW0 + Float → %DB1.DBD0 + format=REAL |
32-bit float Wert ist NaN / große Zahl
Byte-Order (Endianness)-Problem. Byte/Word-Swap-Richtlinie von Slave / Master prüfen:
- Modbus →
:UDINT_LSWORD_FIRSTetc., PLC4j-Optionen verwenden - Andere Protokolle mit Formel nachbearbeiten
Übertragung (MQTT / Sparkplug)
MQTT-Publish funktioniert nicht
# broker 도달 확인
MQTT_USER="${MQTT_USER:-edge}"
MQTT_PASSWORD="$(tr -d '\r\n' < /run/secrets/mqtt-password)"
mosquitto_pub -h <mqtt.server.host> -p 1883 -u "$MQTT_USER" -P "$MQTT_PASSWORD" -t /edge/point -m '{"test":1}'
Checkliste:
mqtt.enable=truemqtt.server.host/port/user/passwordkorrekt- Broker erlaubt Publish-ACL vom Client
- In catalina.out nach
MQTT connectedoder Reconnection-Log suchen
Sparkplug-Topics nicht sichtbar
| Prüfung | Methode |
|---|---|
sparkplug.enable=true aktiv | properties prüfen + Neustart erforderlich |
| Jar in lib vorhanden | ls WebContent/WEB-INF/lib/tahu-core*.jar |
| Gleicher Broker | mqtt.server.* und SPB identisch |
| SPB-Topic-ACL des Brokers | spBv1.0/# Veröffentlichungsberechtigung |
NDEATH scheint zweimal veröffentlicht zu werden
Das ist normales Verhalten. Bei normalem Herunterfahren explizite Veröffentlichung + (da auch ein Will registriert ist) kann der Broker, wenn er den Verbindungsabbruch nicht als Will-Bypass erkennt, zusätzlich den Will veröffentlichen. In diesem Fall muss die Host-Seite so implementiert sein, dass NDEATH mit derselben bdSeq nur einmal verarbeitet wird.
Leistung / Reaktionsfähigkeit
OPC start/stop Antwort dauert 5 Sekunden
Das liegt an der beabsichtigten Thread.sleep von ConnectService (zur Gewährleistung des Collector-Warmups).
- Vorübergehende Umgehung: Antwort per Bildschirm-Reload über Polling prüfen
- Dauerhafte Lösung:
REFACTORING_PLAN.mdPhase A1 (Thread.sleepentfernen /CountDownLatch) in nachfolgendem PR anwenden
Langsames erstes Laden des Bildschirms
Durch opcList() N+1-Abfragen + LastValueMap-Lookup-Verteilung kann eine zusätzliche Verzögerung von 1–2 Sekunden auftreten.
- Verbesserung geplant mit Phase B1 (IN-Batch-Select) und B2 (einzelnes Facade)
Änderung einer OPC unterbricht vorübergehend andere OPC
Das liegt daran, dass OPCUAServerManager.restart() ein vollständiger Neustart ist (Zielgruppe Phase A2 — partielles Reload).
Notfall-Umgehung: OPC-Änderungen außerhalb der Betriebszeiten durchführen.
Daten / Cassandra
Tombstone-Akkumulationswarnung
Beim Löschen mehrerer OPCs im Betrieb kann die tombstone-Metrik von nodetool cfstats pe.app_tag vorübergehend ansteigen.
- Nicht kritisch, da die Anzahl der OPC/Tags dieses Gateways normalerweise ≤ 1000 ist
- Die Zeitreihe (
TM_TAG_POINT) liegt nicht in der Verantwortung dieses Gateways, sondern vonplantpulse-timeseries-engine
tag not found: <id>
Tritt häufig bei PUT /api/v1/tag/{tagId} oder beim Lesen auf.
Ursache:
tag_idTippfehlerAPP_TAG.xmlR03derALLOW FILTERING-Abfrage, daher Partition-Key nicht angegeben. tag_id muss korrekt sein.
Prüfung:
cqlsh -u cassandra -p cassandra -k pe -e "SELECT tag_id FROM app_tag;"
tag write not supported for opc_type=... beim Schreiben von Werten
Für andere Protokolle als HTTP ist Write derzeit nicht unterstützt.
- Nur
HTTPDriver.bind()implementiert - Write für andere Protokolle erfordert SPI-Erweiterung zusammen mit Sparkplug Phase 3 (NCMD/DCMD)
Sicherheit / Betrieb
/api/* ohne Authentifizierung exponiert
Designbedingt wird von einem Firmennetz ausgegangen (SecurityFilter check-pattern enthält /api/* nicht). Bei externer Exposition vor einem Reverse-Proxy mTLS / API-Key / Basic-Auth verwenden.
CSRF
Nur *_.do-Muster sind CSRF-geschützt. v1-Mutations-Endpunkte sind davon ausgenommen. Bei externer Exposition zusammen prüfen.
Anleitung zur Log-Erfassung
Bei der Meldung eines Problems fügen Sie Folgendes bei, um die Analyse zu beschleunigen.
# 환경
curl -s http://localhost:8080/api/v1/edge
# OPC 상태
curl -s http://localhost:8080/api/v1/opc
# 시스템 메트릭
curl -s http://localhost:8080/api/v1/monitoring
# 최근 로그
tail -n 500 $CATALINA_HOME/logs/catalina.out
Passwörter in app.properties bitte maskiert beifügen.