Fehlerbehebung
Dieses Dokument behandelt häufig auftretende Probleme bei PlantPulse-Installationen unter One-Line / Docker und deren Lösungen. Die meisten Probleme lassen sich durch systematisches Durcharbeiten der nachstehenden Verfahren beheben.
Die Plattform läuft als Docker-Compose-Stack — ein einmaliger Zertifikat-Container (plantpulse-certs, Exited (0) sind normal), ein Datensee-Container, sechs App-Container und ein Proxy-Container. Es gibt keinen Container namens plantpulse-platform.
Grenzen Sie zuerst ein, was nicht funktioniert. ./status.sh antwortet nach Dienst → Stack-Struktur
Erster Schritt: Überprüfen Sie bei jedem Problem zunächst folgende drei Punkte:
Wenn das Problem nicht behoben ist, erstellen Sie mit
./doctor.shein Diagnose-Tarball und übergeben Sie es dem Support-Team.
Container-Startprobleme
Symptom: Container bleibt im Status unhealthy stecken
| Ursache | Lösung |
|---|---|
| Cassandra-Schemamigration fehlgeschlagen | Überprüfen Sie den Fehler mit ./logs.sh cassandra -n 300, versuchen Sie ./restart.sh. Bei wiederholtem Fehler ./doctor.sh |
| Berechtigungsprobleme im Datenverzeichnis | Überprüfen Sie die Berechtigungen für /data1/pp-data auf dem Host. sudo chown -R root:root /data1/pp-data && sudo chmod -R 755 /data1/pp-data |
| Speicher nicht ausreichend (OOMKilled) | Überprüfen Sie mit docker inspect <컨테이너> --format '{{.State.OOMKilled}}'. Jeder Container hat unterschiedliche Limits — Datensee DOCKER_DATALAKE_MEMORY, Apps DOCKER_SERVER_MEMORY usw. (Umgebungsvariablen) |
| JVM Warm-up nicht abgeschlossen | Das Booten dauert 3–5 Minuten. Wenn Unhealthy länger als 5 Minuten anhält, fahren Sie mit dem nächsten Schritt fort |
# 어떤 서비스가 비정상인가 (0 = 정상 / 2 = 비정상)
./status.sh
# 스택 전체 준비 판정
./stack-verify-boot.sh
# 컨테이너별 메모리 / CPU
docker stats --no-stream
# 헬스체크 엔드포인트 응답 확인
curl -kfsS https://<server-ip>:4950/api/health | jq
plantpulse-certs bäckt das Zertifikat und beendet sich selbst, sodass Exited (0) Erfolg bedeutet. Compose hat die Healthcheck dieses Containers absichtlich deaktiviert (healthcheck: disable), daher ist das Health-Feld leer und gesunde Container werden nicht als unhealthy angezeigt. status.sh und ops-check.sh beurteilen diesen Container nur nach dem Exit-Code, das sollten auch Sie tun.
Symptom: no such service · Container nicht gefunden
Die Erstinstallation wurde nicht abgeschlossen oder Container wurden mit ./remove.sh entfernt.
Wenn Sie alten Dokumentationen folgten und nach plantpulse-platform gesucht haben — dieser Container existiert nicht. Überprüfen Sie den Namen mit ./status.sh oder ./logs.sh --list.
cd /opt/kopens/plantpulse-platform-docker/bin
./install.sh # 최초 설치
# 또는 OS 설정이 이미 끝났다면
./up.sh # 컨테이너 생성 + 기동
Symptom: address already in use (Port-Konflikt)
Eine ältere Version von PlantPulse läuft nativ auf dem Host oder ein anderer Dienst belegt den Port.
# 호스트 native plantpulse 정지
pkill -ef plantpulse
# 특정 포트 점유 프로세스 확인 (예: 7500)
ss -tlnp | grep :7500
# 충돌 프로세스를 종료한 후 재시도
./restart.sh
Siehe Ports und Service-Verwaltung für die vollständige Portliste.
Image- / Registry-Probleme
Symptom: docker pull → unauthorized: authentication required
Die Registry-Authentifizierung ist abgelaufen oder Anmeldedaten fehlen.
docker login docker.kopens.io
# Username/Password 입력 후
./update.sh
Symptom: Image-Download fehlgeschlagen (Netzwerk)
# 1. 레지스트리 접근 가능 여부 확인
curl -fsSL https://docker.kopens.io/v2/
# 2. DNS 확인
nslookup docker.kopens.io
# 3. 회사 방화벽 / 프록시 차단 가능성 — 네트워크 관리자에게 다음 도메인 허용 요청
# docker.kopens.io, download.kopens.io
Für Air-Gap-Netzwerke folgen Sie dem Verfahren für Air-Gap-Installation auf der Seite Docker-Installation.
Datenbankprobleme
Datenbankkomponenten laufen innerhalb eines Containers. Inspektionen werden nach dem Betreten des Containers mit ./shell.sh durchgeführt.
PostgreSQL (Metadaten-DB)
Rolle: Speichert Benutzerinformationen, Seiten-Konfiguration, Asset-Konfiguration und andere Plattform-Metadaten.
./shell.sh # 컨테이너 진입
# 컨테이너 내부에서
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node psql # PostgreSQL 셸 접속
psql=# SELECT 1;
psql=# SHOW max_connections;
psql=# SELECT count(*) FROM pg_stat_activity;
| Symptom | Ursache | Lösung |
|---|---|---|
| Connection refused | PostgreSQL-Komponente nicht erreichbar | Führen Sie pd restart storage innerhalb des Containers aus. Auf dem Host: ./restart.sh |
| Too many connections | Verbindungspool überschritten | Überprüfen Sie die Connection-Pool-Konfiguration in properties. Bei vorübergehenden Problemen Storage neu starten |
| Authentication failed | Passwort stimmt nicht überein | Vergleichen Sie /etc/kopens/plantpulse-platform.env in PP_PG_PASSWORD mit den Anwendungs-Properties |
Pfadverifizierung — Die Authoritative Secrets-Sidecar befindet sich in
/etc/kopens/plantpulse-platform.env(Berechtigung0600). Ältere Installationen könnten Duplikate unter/opt/kopens/haben, diese werden aber nicht gelesen und das Installationsskript stellt die Authoritative wieder her → Umgebungsvariablen-Referenz
Cassandra (Zeitreihen-DB)
Rolle: Speichert Sensor-Zeitreihendaten, Alarm-Historien und andere große Datenmengen.
./shell.sh
# 컨테이너 내부에서
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node status # 클러스터 상태
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node compactionstats # 컴팩션 진행 상태
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node cql # CQL 셸 접속
| Symptom | Ursache | Lösung |
|---|---|---|
| Connection timeout | Knoten nicht erreichbar | Überprüfen Sie den Knotenstatus mit pd node status, dann pd restart storage |
| WriteTimeout | Schreibverzögerung (Disk I/O saturiert) | Überprüfen Sie mit pd node compactionstats, manuelle Kompaktierung mit pd node compact |
| ReadTimeout | Leseverzögerung (große Partitionen) | Überprüfen Sie die Partitionsgröße mit pd node table-histograms |
| Festplattenspeicher voll | SSTable-Ansammlung | Führen Sie pd node cleanup aus und überprüfen Sie mit df -h /data1 |
Valkey (Redis Cache)
./shell.sh
# 컨테이너 내부에서
redis-cli -a "$PP_REDIS_PASSWORD" ping
redis-cli -a "$PP_REDIS_PASSWORD" INFO memory
Login- / Konsolenprobleme
Symptom: Konsolenzugriff im Browser nicht möglich
# 1. 컨테이너 health 확인
./status.sh
# 2. 외부 노출 IP 설정 확인
grep DOCKER_PP_EXTERNAL_IP env.sh
# 3. 호스트 방화벽 확인
sudo firewall-cmd --list-ports # RHEL/Rocky/Oracle
sudo ufw status # Ubuntu
# 4. 포트 점유 확인 — 프록시가 80/443 을, 데이터레이크가 7443 을 엽니다
ss -tlnp | grep -E ':(80|443|7443)\s'
| Symptom | Ursache | Lösung |
|---|---|---|
| Seite lädt nicht | plantpulse-proxy nicht normal | Überprüfen Sie Proxy-Status mit ./status.sh. Der Proxy ist der einzige Eingang für Port 80/443 |
| Seite lädt nicht | Firewall blockiert | Fordern Sie die Freigabe von Port 80, 443, 7443, 4950 in der Unternehmens-/Cloud-Firewall an |
| Login fehlgeschlagen | Passwort stimmt nicht überein | Überprüfen Sie die Standard-Anmeldedaten admin / admin123!. Wenn geändert, fordern Sie eine Rückstellung beim Administrator an |
| 403 Forbidden | Berechtigungen unzureichend | Fragen Sie den Administrator nach Ihrer Rolle (Role) |
| Sitzung abgelaufen | Automatisches Logout nach 30 Minuten Inaktivität | Melden Sie sich erneut an |
Datensatzprobleme
Datensatz-Pfad: OPC-Server → Message Broker (Kafka/MQTT) → Engine-Pipeline → Cassandra. Wenn dieser Pfad an einer Stelle blockiert ist, werden keine Daten empfangen.
Symptom: Keine Datenerfassung
| Prüfpunkt | Überprüfungsmethode |
|---|---|
| OPC-Verbindungsstatus | Webkonsole > Verbindungsverwaltung > Status auf CONNECTED überprüfen |
| Engine-Status | Konsole > Überwachung > Systemstatus auf RUNNING überprüfen |
| Pipeline | MPS (Nachrichten pro Sekunde) = 0 bedeutet Empfang gestoppt |
| Message Broker | Mit ./shell.sh eintreten und Kafka-Themen mit /opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node topic überprüfen |
| Netzwerk | Ping / Telnet von OPC-Server → Plattform-Host-IP |
Symptom: Datenverzögerung
| Ursache | Lösung |
|---|---|
| Pipeline-Warteschlange überlastet | Erhöhen Sie engine.pipeline.threads in den Properties |
| Cassandra-Schreibverzögerung | Überprüfen Sie mit pd node compactionstats, überwachen Sie Disk I/O |
| Kafka lag | Überprüfen Sie Consumer Lag mit pd node topic |
| Netzwerkverzögerung | Messen Sie RTT zwischen OPC-Server ↔ Plattform-Host |
Leistungsprobleme
Symptom: Konsolen- / API-Antwort langsam
# 호스트에서 컨테이너 자원 사용량
docker stats --no-stream
# 앱 컨테이너의 JVM 메모리 (그 앱이 도는 컨테이너 안에서)
./shell.sh plantpulse-server-web
jmap -heap $(pgrep -f plantpulse-server)
Da die sechs Apps jeweils in ihren eigenen Containern laufen, finden Sie App-Prozesse nicht, wenn Sie in Datensee schauen. Überprüfen Sie den Ziel-Container mit ./status.sh, dann betreten Sie ihn mit ./shell.sh <컨테이너>.
| Ursache | Lösung |
|---|---|
| Container-Speicher unzureichend | Erhöhen Sie das Limit des betroffenen Containers und ./restart.sh — Datensee DOCKER_DATALAKE_MEMORY, Apps DOCKER_SERVER_MEMORY usw. (Umgebungsvariablen) |
| JVM-Speicher unzureichend | Passen Sie die Heap-Größe in der Container-internen setenv an (siehe Performance-Tuning) |
| Häufige GC | Analysieren Sie GC-Protokoll, tunen Sie G1GC-Optionen |
| Langsame DB-Abfragen | Überprüfen Sie PostgreSQL Slow-Query-Protokoll |
| Host-CPU saturiert | Überprüfen Sie mit top / htop, erwägen Sie DOCKER_PP_CPUS Erhöhung |
Symptom: OutOfMemoryError
# 컨테이너 내부에서 heap dump 활성화
./shell.sh
# setenv 또는 JAVA_TOOL_OPTIONS 에 -XX:+HeapDumpOnOutOfMemoryError 추가
# 생성된 hprof 를 호스트로 복사
docker cp plantpulse-datalake:/path/to/heap.hprof /tmp/
Analysieren Sie mit Eclipse MAT / VisualVM.
Alarmprobleme
| Symptom | Ursache | Lösung |
|---|---|---|
| Alarm wird nicht ausgelöst | Alarm-Konfiguration nicht bereitgestellt | Klicken Sie auf der Alarm-Konfigurationsseite auf „Bereitstellen" |
| Doppelte Alarme | Duplikat-Prüfung deaktiviert | Aktivieren Sie Duplikat-Prüfung in der Alarm-Konfiguration |
| E-Mail-Benachrichtigung nicht versendet | SMTP-Konfiguration fehlerhaft | Überprüfen Sie mail.properties (innerhalb des Containers /opt/kopens/plantpulse-platform/plantpulse-server/config/) |
| Benachrichtigungston fehlt | Autoplay-Richtlinie des Browsers | Aktivieren Sie Autoplay für Website in den Browser-Einstellungen |
UI-Probleme
| Symptom | Lösung |
|---|---|
| Bildschirm verzerrt | Browser-Cache löschen (Strg+Umschalt+Entf) |
| Diagramm wird nicht angezeigt | Öffnen Sie Entwickler-Tools (F12) > Konsole auf JS-Fehler überprüfen |
| Live-Aktualisierung unterbrochen | Überprüfen Sie SSE (HTTP-Streaming) Pufferung/Timeout-Einstellungen in Proxy/Firewall |
| Dashboard-Laden fehlgeschlagen | Überprüfen Sie Existenz verbundener Tags / Datenquellen |
| Textkodierung beschädigt | Überprüfen Sie env.sh auf PP_LANG=ko, PP_TZ=Asia/Seoul und führen Sie ./restart.sh aus |
Festplatte / Volume-Probleme
Symptom: Festplattenspeicher voll
# 호스트 디스크 사용량
df -h
df -h /data1 # 데이터 디스크
# Docker 사용량 (이미지 / 볼륨 / 빌드 캐시)
docker system df
# 컨테이너 내부 사용량
./shell.sh
df -h
du -sh /opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/data
| Ursache | Lösung |
|---|---|
| Alte Sicherungen angehäuft | Bereinigen Sie alte tar.gz-Dateien in /data1/pp-backup/docker-volume |
| Ungenutzte Docker-Images | Bereinigen Sie mit docker system prune (Images/Netzwerke/Cache) |
| Cassandra-SSTable-Ansammlung | Führen Sie pd node cleanup und pd node compact innerhalb des Containers aus |
| Log-Verzeichnis überdimensioniert | Bereinigen Sie /opt/kopens/plantpulse-platform-docker/logs |
Warnung:
docker volume prunelöscht alle ungenutzten Volumes. Stellen Sie sicher, dass Sie Container nicht versehentlich im gestoppten Zustand lassen — sonst könnten Volumes unbeabsichtigt gelöscht werden.pp-*
Symptom: Volume-Datenwiederherstellung erforderlich
Siehe Betriebsverwaltung - Sicherung und Wiederherstellung für die Wiederherstellungsvorgänge.
Update- / Rollback-Probleme
Symptom: Nach Update funktioniert Container nicht normal
./update.sh führt automatisch ein Rollback zu einem früheren Image durch, wenn die Healthcheck-Validierung fehlschlägt. Für manuelles Rollback:
# 1. 이전 버전 태그를 env.sh 에 지정
vi env.sh
# PP_IMAGE_TAG="2026.04" ← 이전 안정 버전
# 2. 업데이트 재실행
./update.sh
Symptom: Während des Updates NOT FOUND CONTAINER
Erstinstallation (./install.sh) wurde nicht durchgeführt. Führen Sie zunächst die Installation durch.
Netzwerk- / Cluster-Probleme
Symptom: Worker tritt Master nicht bei
# 1. 워커 컨테이너 진입 (워커는 기본 스택의 서비스가 아니라 shell.sh 로는 잡히지 않습니다)
docker exec -ti plantpulse-worker-1 /bin/bash
# 워커 내부에서 마스터 IP 로 연결 테스트
ping ${PP_MASTER_IP}
# 2. 마스터에서 링 확인 — 이것이 조인의 «유일한» 증거입니다
cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node status
# 3. JGroups / Cassandra 포트 (7000, 7001, 7800, 7801, 9042) 방화벽 허용 확인
Ein Worker mit fehlgeschlagenem Join meldet sich genauso als normal wie ein erfolgreicher Worker — die Container-Selbstprüfung prüft nur «kann ich den Master erreichen». Bei Messungen am 31.08.2026 behielt ein Worker mit OOMKilled Cassandra einen Ring mit 1 Knoten und meldete health: starting.
Überprüfen Sie immer mit der Ring-Liste in pd node status. bin/worker-add.sh übernimmt diese Überprüfung für Worker-Hinzufügungen → Cluster-Installation
Symptom: Externe MQTT- / Kafka-Client-Verbindung fehlgeschlagen
Stellen Sie sicher, dass Port 1883/1884 (MQTT) und 9092/9093/9094 (Kafka) in der Host-Firewall und der Unternehmens-/Cloud-Firewall zulässig sind. Siehe Port-Konfiguration für die vollständige Portliste.
- MQTT wird von
plantpulse-proxyakzeptiert. Anlagen müssen nur diesen Host kennen; wenn der Broker umzieht oder sich der Name ändert, müssen Anlage-Einstellungen nicht geändert werden. Port 1884 ist TLS-Passthrough, der Broker beendet TLS. - Kafka geht nicht durch den Proxy. Nach dem Bootstrap stellt der Client eine Verbindung mit
advertised.listenersher — wenn der Bootstrap erfolgreich ist, aber die nächste Verbindung still fehlschlägt, überprüfen Sie zuerst diese Adresse.
Notfallmaßnahmen
Container reagiert nicht
cd /opt/kopens/plantpulse-platform-docker/bin
# 1. 상태 확인
docker ps -a
./status.sh
# 2. 로그에서 마지막 에러 확인
./logs.sh -n 200
# 3. 안전 재시작
./restart.sh
# 4. 위 단계로 회복 안 될 경우 진단 tarball 생성
./doctor.sh
# 생성된 tarball 을 webmaster@kopens.com 으로 전달
Datenbeschädigung verdächtig
# 1. 즉시 정지 (추가 손상 방지)
./down.sh
# 2. 최신 백업 확인
ls -lh /data1/pp-backup/docker-volume/
# 3. 진단 tarball 생성 (절대 데이터를 임의로 수정하지 마세요)
./doctor.sh
# 4. 기술 지원팀 연락
Verboten bei Datenbeschädigung: Führen Sie nicht direkt
pd node repair,pd node cleanupoder SSTable-Löschungen durch. Falsche Wiederherstellungsmaßnahmen können Schäden vergrößern. Arbeiten Sie immer mit dem Support-Team zusammen.
Informationen für Support-Anfragen
Wenn die oben genannten Methoden nicht funktionieren, senden Sie die folgenden Informationen zur schnelleren Analyse:
| Element | Erfassungsmethode |
|---|---|
| Diagnose-Tarball | Führen Sie ./doctor.sh aus und senden Sie die generierte Datei |
| Container-Protokolle | ./logs.sh -n 500 > /tmp/container.log 2>&1 (alle acht Container) |
| Modulspezifische Protokolle | ./tools/copy-log-to-local.sh Ausgabe (/tmp/plantpulse-log/) |
| Image-Versionen | ./stack-version.sh Ausgabe |
| Umgebungsvariablen | env.sh (Passwörter maskiert) |
| Systeminformationen | OS, CPU, Speicher, Festplatte (uname -a, free -h, df -h) |
| Fehlermeldung | Exakte Fehlermeldung / Browser-Konsolen-Screenshot (F12) |
| Reproduktionsschritte | Ablauf der durchgeführten Aktionen vor dem Fehler |
Support: webmaster@kopens.com
Verwandte Dokumentation
- FAQ — Häufig gestellte Fragen
- Betriebsverwaltung — Tägliche Betriebsbefehle
- Erste-Schritte-Anleitung — Start-/Stopp-/Neustart-Verfahren
- Sicherung und Wiederherstellung — Detaillierte Sicherungsverfahren
- Performance-Tuning — JVM / DB-Tuning
- Ports und Service-Verwaltung — Port-Konflikt-Diagnose