Fehlerbehebung
Häufige Symptome / Fehler und deren Behebung. Schnelle Einordnung → detaillierter Lösungsablauf.
status.sh— Container + Ports + API + Kernschlüssel aus app.properties als Einzeiler-Zusammenfassunghealth.sh— umfassender Health-Check auf Basis von Exit-Codes (für cron geeignet)doctor.sh— Diagnose-Sammel-Tarball (api / docker / systemd / Logs der 7 Komponenten / config redacted / Host-Metriken) → Support-Eskalation/api/v1/system/health— Status-Map je Komponente (8 Stück) + 503-Verzweigung (sofortige Identifikation, welche Komponente DOWN ist)- Im Kasten
/opt/kopens/install/RUNBOOK.md— Matrix mit 5 Szenarien (A–E) + Befehls-Cheatsheet
Index nach Symptom
| Symptom | Mögliche Ursache |
|---|---|
| App bleibt beim Start hängen | Cassandra-Verbindung fehlgeschlagen, DDL-Anwendung fehlgeschlagen |
/api/v1/edge antwortet mit started=false | Collector-Initialisierung fehlgeschlagen (Treiber- / Cache-Problem) |
Nur bestimmte OPC connection_status=DISCONNECTED | PLC-Netzwerk / Authentifizierung / Adressformat |
| Alle OPC brechen gelegentlich gleichzeitig ab | Kompletter Restart des OPCUAServerManager durch Hinzufügen/Ändern von OPC |
| MQTT publish funktioniert nicht | mqtt.enable=false oder Broker-Authentifizierung fehlgeschlagen |
| Sparkplug-Topics werden nicht publiziert | sparkplug.enable=false oder fehlendes JAR |
| Oberfläche lädt langsam | opcList() N+1-Queries + kumulierte Sleeps |
| OPC-Start dauert jeweils 5 Sekunden | Auswirkung von Thread.sleep (Gegenstand von Phase A1) |
Boot / Initialisierung
Cassandra-Verbindung fehlgeschlagen
Caused by: com.datastax.oss.driver.core.exceptions.NoHostAvailableException
| Prüfpunkt | Kontrolle |
|---|---|
| Cassandra läuft | nodetool status |
| Port erreichbar | telnet <app.db.host> 9042 |
| Keyspace vorhanden | cqlsh -u cassandra -p cassandra danach DESCRIBE KEYSPACE pe; |
app.db.* und oltp.cassandra.* stimmen überein | Einträge auf beiden Seiten von app.properties prüfen |
app.sql.path ist ein Tippfehler für resouces
Das resouces in app.sql.path = classpath:resouces/sql von app.properties ist ein Tippfehler, das Verzeichnis wurde jedoch
unter demselben Namen beibehalten und funktioniert. Bei Fehlern, dass SQL-Ressourcen nicht gefunden werden, prüfen, ob der Pfad WEB-INF/resouces/sql/
tatsächlich existiert.
OPC / Treiber
Bestimmte OPC verbinden nicht
| Protokoll | Erste Prüfung |
|---|---|
| OPCUA | opc_agent_port erreichbar, discovery=true versuchen, Benutzer/Passwort |
| Modbus TCP | Port 502 erreichbar, Format holding-register:... |
| MELSEC | MC-Protokoll aktiv, controller-type=Q_L stimmt überein |
| S7 | rack/slot stimmen überein, "PUT/GET" aktiviert |
| LS | bei Fehlschlag von NetUtils.isReachable ICMP-Blockierung vermuten, Port 2004 |
| EIP | rack/slot, Port 44818 |
Vorrangig die Tabelle "Häufige Fehler + Lösung" auf der jeweiligen Treiberseite konsultieren.
LS-PLC Ping failed
Der LS-Treiber prüft vor dem Connect die Erreichbarkeit per ICMP-Ping. Wird ICMP im Firmennetz blockiert, werden auch funktionierende PLC als fehlerhaft angezeigt.
Lösung:
- ICMP in der Firewall freigeben
- oder die Ping-Prüfung in
LSDriver.connect()per Folgeänderung optional abschaltbar machen (aktuell Codeänderung erforderlich)
32-Bit-/64-Bit-Werte inkonsistent
Meist ist fehlende Angabe von format 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-Werte sind NaN / sehr große Zahlen
Problem mit der Byte-Reihenfolge (Endianness). Byte-/Word-Swap-Richtlinie von Slave / Master prüfen:
- Modbus → PLC4j-Optionen wie
:UDINT_LSWORD_FIRSTverwenden - bei anderen Protokollen per 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- ob die Broker-ACL Publish durch den Client erlaubt
MQTT connectedoder Reconnection-Logs in catalina.out
Sparkplug-Topics sind nicht sichtbar
| Prüfpunkt | Vorgehen |
|---|---|
ob sparkplug.enable=true | Properties prüfen + Neustart erforderlich |
| ob das JAR in lib liegt | ls WebContent/WEB-INF/lib/tahu-core*.jar |
| ob derselbe Broker | mqtt.server.* und SPB identisch |
| SPB-Topic-ACL des Brokers | Publish-Berechtigung für spBv1.0/# |
NDEATH scheint zweimal publiziert zu werden
Das ist normales Verhalten. Explizite Publikation bei regulärem Shutdown + (da auch ein Will registriert ist) kann zusätzlich das Will publiziert werden, wenn der Broker den Verbindungsabbau nicht als Will-Bypass erkennt. In diesem Fall muss die Host-Seite so implementiert sein, dass NDEATH mit derselben bdSeq nur einmal verarbeitet wird.
Performance / Reaktionszeit
OPC start/stop antwortet erst nach 5 Sekunden
Ursache ist der bewusste Thread.sleep in ConnectService (Sicherstellung des Collector-Warmups).
- Übergangslösung: Polling-Antwort durch Reload der Oberfläche prüfen
- Dauerhafte Lösung: Folge-PR nach Umsetzung von
REFACTORING_PLAN.mdPhase A1 (Entfernung vonThread.sleep/CountDownLatch)
Erstes Laden der Oberfläche ist langsam
Durch N+1-Queries in opcList() + verteilte LastValueMap-Lookups kann es zu 1–2 Sekunden zusätzlicher Verzögerung kommen.
- Verbesserung ist mit Phase B1 (Sammel-SELECT via IN) und B2 (einzelne Facade) vorgesehen
Beim Ändern eines OPC pausieren auch andere OPC kurzzeitig
Ursache ist, dass OPCUAServerManager.restart() ein kompletter Neustart ist (Phase A2 — Gegenstand des Partial Reload).
Sofortmaßnahme: OPC-Änderungen außerhalb der Betriebszeiten durchführen.
Daten / Cassandra
Warnung über Tombstone-Ansammlung
Im Betrieb können beim Löschen mehrerer OPC die Tombstone-Metriken von nodetool cfstats pe.app_tag kurzzeitig ansteigen.
- Da die Anzahl von OPC/Tag in diesem Gateway meist ≤ 1000 beträgt, ist dies unkritisch
- Zeitreihen (
TM_TAG_POINT) liegen 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.
Ursachen:
- Tippfehler in
tag_id ALLOW FILTERING-Query vonR03inAPP_TAG.xml, daher Partition Key nicht angegeben. tag_id muss exakt stimmen.
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
Protokolle außer HTTP unterstützen derzeit kein Write.
- Nur
HTTPDriver.bind()ist implementiert - Write für andere Protokolle erfordert eine SPI-Erweiterung zusammen mit Sparkplug Phase 3 (NCMD/DCMD)
Sicherheit / Betrieb
/api/* ist ohne Authentifizierung exponiert
Auslegungsbedingt wird ein Firmennetz vorausgesetzt (/api/* nicht in check-pattern von SecurityFilter enthalten). Bei externer Exponierung mTLS / API Key / Basic Auth vor einem Reverse Proxy vorschalten.
CSRF
CSRF gilt nur für das Muster *_.do. Die v1-Mutation-Endpunkte sind ausgenommen. Bei externer Exponierung mitbetrachten.
Leitfaden zur Logsammlung
Bei Problemmeldungen beschleunigt das Beifügen der folgenden Angaben die Analyse.
# 환경
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 vor dem Anhängen maskieren.