Problembehebung
Dieses Dokument beschreibt häufig auftretende Probleme und deren Lösungen für die PlantPulse Plattform, die über eine One-Line- / Docker-Installation betrieben wird. Die meisten Probleme lassen sich beheben, indem die folgenden Schritte in der angegebenen Reihenfolge befolgt werden.
Die Plattform arbeitet als Docker Compose Stack — ein Zertifikat (plantpulse-certs), ein Data Lake, sechs Apps und ein Proxy. Alle neun müssen dauerhaft laufen, und (healthy) ist der Normalzustand. Es gibt keinen Container mit dem Namen plantpulse-platform.
Grenzen Sie zuerst ein, «was defekt ist». ./status.sh antwortet pro Dienst → Installationsstruktur
Erster Schritt: Prüfen Sie bei jedem Problem zunächst die folgenden drei Punkte.
Falls das Problem weiterhin besteht, erstellen Sie mit
./doctor.shein Diagnose-Tarball und senden Sie dieses an das technische Support-Team.
Probleme beim Container-Start
Symptom: Container erholt sich nicht aus dem Zustand unhealthy
| Ursache | Lösung |
|---|---|
| Aster TSDB Schema-Migration fehlgeschlagen | Fehler über ./logs.sh cassandra -n 300 prüfen, dann ./restart.sh versuchen. Bei wiederholtem Fehlschlag ./doctor.sh |
| Berechtigungsprobleme im Datenverzeichnis | Berechtigungen von /data1/pp-data auf dem Host prüfen. sudo chown -R root:root /data1/pp-data && sudo chmod -R 755 /data1/pp-data |
| Speichermangel (OOMKilled) | Über docker inspect <컨테이너> --format '{{.State.OOMKilled}}' prüfen. Die Grenzwerte variieren je Container — Data Lake DOCKER_DATALAKE_MEMORY, Apps DOCKER_SERVER_MEMORY etc. (Umgebungsvariablen) |
| JVM Warm-up nicht abgeschlossen | Der Boot-Vorgang dauert 3–5 Minuten. Wenn der Status «unhealthy» länger als 5 Minuten anhält, Diagnose des nächsten Schritts |
# 어떤 서비스가 비정상인가 (0 = 정상 / 2 = 비정상)
./status.sh
# 스택 전체 준비 판정
./stack-verify-boot.sh
# 컨테이너별 메모리 / CPU
docker stats --no-stream
# 헬스체크 엔드포인트 응답 확인
curl -kfsS https://<server-ip>:4950/api/health | jq
plantpulse-certs erstellt das Zertifikat einmalig und bleibt aktiv, um das Ablaufdatum zu überwachen. (healthy) ist der Normalzustand. Der Healthcheck prüft nicht nur, ob der Prozess läuft, sondern ob das Material im Volume verwendbar ist — einschließlich der verbleibenden Zeit bis zum Ablauf und ob der Keystore geöffnet werden kann.
Symptom: no such service · Container wird als nicht vorhanden angezeigt
Die Erstinstallation wurde nicht abgeschlossen oder die Container wurden über ./remove.sh entfernt.
Falls Sie gemäß alter Runbooks nach plantpulse-platform gesucht haben: Ein Container mit diesem Namen existiert nicht — prüfen Sie den Namen über ./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)
Dies tritt auf, wenn eine ältere Version von PlantPulse nativ auf dem Host läuft oder ein anderer Dienst den Port belegt.
# 호스트 native plantpulse 정지
pkill -ef plantpulse
# 특정 포트 점유 프로세스 확인 (예: 80)
ss -tlnp | grep :80
# 충돌 프로세스를 종료한 후 재시도
./restart.sh
Die detaillierte Portliste finden Sie auf der Seite Ports und Diensteverwaltung.
Image- / Registry-Probleme
Symptom: docker pull → unauthorized: authentication required
Die Registry-Authentifizierung ist abgelaufen oder es liegen keine Anmeldedaten vor.
docker login docker.kopens.io
# Username/Password 입력 후, 하던 설치 · 업그레이드 원라이너를 다시 실행
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
Wenn Sie sich in einem Air-Gap-Netzwerk befinden, folgen Sie bitte dem Installationsverfahren für Airgap-Netzwerke auf der Seite Docker-Installation.
Datenbankprobleme
Datenbankkomponenten laufen innerhalb der Container. Inspektionen werden durchgeführt, indem man mit ./shell.sh in den Container wechselt.
PostgreSQL (Meta DB)
Rolle: Speichert Metadaten der Plattform wie Benutzerinformationen, Standortkonfigurationen und Anlageneinstellungen.
./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 ist down | pd restart storage innerhalb des Containers ausführen. Auf dem Host ./restart.sh |
| Too many connections | Verbindungspool überschritten | Prüfung der Connection-Pool-Einstellungen in properties. Bei temporärem Problem Storage neu starten |
| Authentication failed | Passwort-Diskrepanz | Übereinstimmung von PP_PG_PASSWORD in /etc/kopens/plantpulse-platform.env mit den Application-Properties prüfen |
Pfadprüfung — Das Original des Secret-Sidecars befindet sich nur unter
/etc/kopens/plantpulse-platform.env(Berechtigung0600). In alten Installationen können unter/opt/kopens/gleichnamige Dateien verbleiben, diese werden jedoch nicht gelesen; das Installationsskript stellt den Originalzustand wieder her → Umgebungsvariablen-Referenz
Aster TSDB (Zeitreihe DB)
Rolle: Speichert große Datenmengen wie Sensor-Zeitreihendaten und Alarmverläufe.
./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 | Node down | Node-Status über pd node status prüfen, dann pd restart storage |
| WriteTimeout | Schreibverzögerung (Disk I/O gesättigt) | pd node compactionstats prüfen, manuelle Kompaktierung über pd node compact |
| ReadTimeout | Leseverzögerung (große Partitionen) | Partitionsgröße über pd node table-histograms prüfen |
| Diskplatzmangel | SSTable-Akkumulation | pd node cleanup ausführen, anschließend über df -h /data1 prüfen |
Valkey (Redis Cache)
./shell.sh
# 컨테이너 내부에서
redis-cli -a "$PP_REDIS_PASSWORD" ping
redis-cli -a "$PP_REDIS_PASSWORD" INFO memory
Login- / Konsolenverbindungsprobleme
Symptom: Konsole im Browser nicht erreichbar
# 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 을 엽니다
ss -tlnp | grep -E ':(80|443)\s'
| Symptom | Ursache | Lösung |
|---|---|---|
| Seite öffnet sich nicht | plantpulse-proxy ist abnormal | Status des Proxys über ./status.sh prüfen. Der Proxy ist der einzige Zugang für 80/443 |
| Seite öffnet sich nicht | Firewall-Blockierung | Freigabe von 80, 443, 4950 in der Unternehmens- oder Cloud-Firewall beantragen |
| Login fehlgeschlagen | Passwort-Diskrepanz | Standard-admin / admin123! prüfen. Bei Änderung Reset beim Administrator anfordern |
| 403 Forbidden | Fehlende Benutzerberechtigung | Administrator um Prüfung der Rolle (role) bitten |
| Sitzung abgelaufen | Automatischer Logout nach 30 Min. Inaktivität | Erneut anmelden |
Probleme bei der Datenerfassung
Pfad der Datenerfassung: OPC-Server → Message Broker (Kafka/MQTT) → Engine Pipeline → Aster TSDB. Wenn eine Stelle in diesem Pfad blockiert ist, werden keine Daten erfasst.
Symptom: Daten werden nicht erfasst
| Prüfpunkt | Prüfmethode |
|---|---|
| OPC-Verbindungsstatus | Web-Konsole > Verbindungsverwaltung > Status: CONNECTED prüfen |
| Engine-Status | Konsole > Monitoring > Systemstatus: RUNNING prüfen |
| Pipeline | Wenn MPS (Messages per Second) 0 ist, Empfang unterbrochen |
| Message Broker | In ./shell.sh wechseln, Kafka-Topics über /opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node topic prüfen |
| Netzwerk | Ping / Telnet vom OPC-Server zur Plattform-Host-IP |
Symptom: Datenverzögerung
| Ursache | Lösung |
|---|---|
| Pipeline-Queue-Stau | Erhöhung von engine.pipeline.threads in den Properties |
| Aster TSDB Schreibverzögerung | pd node compactionstats prüfen, Disk I/O überwachen |
| Kafka Lag | Consumer Lag über pd node topic prüfen |
| Netzwerkverzögerung | RTT-Messung zwischen OPC-Server ↔ Plattform-Host |
Performance-Probleme
Symptom: Konsole / API reagiert langsam
# 호스트에서 컨테이너 자원 사용량
docker stats --no-stream
# 앱 컨테이너의 JVM 메모리 (그 앱이 도는 컨테이너 안에서)
./shell.sh plantpulse-server-web
jmap -heap $(pgrep -f plantpulse-server)
Da die sechs Apps in jeweils eigenen Containern laufen, werden App-Prozesse innerhalb des Data-Lake-Containers nicht gefunden. Prüfen Sie mit ./status.sh den Zielcontainer und wechseln Sie dann mittels ./shell.sh <컨테이너> hinein.
| Ursache | Lösung |
|---|---|
| Container-Speichermangel | Grenzwert des entsprechenden Containers erhöhen, dann ./restart.sh — Data Lake DOCKER_DATALAKE_MEMORY, Apps DOCKER_SERVER_MEMORY etc. (Umgebungsvariablen) |
| JVM-Speichermangel | Anpassung der Heap-Größe im setenv innerhalb des Containers (Details unter Performance-Tuning) |
| Häufiges GC | Analyse der GC-Logs, Tuning der G1GC-Optionen |
| DB Slow Queries | PostgreSQL Slow Query Logs prüfen |
| Host-CPU-Sättigung | top / htop prüfen, Erhöhung von DOCKER_PP_CPUS prüfen |
Symptom: OutOfMemoryError
# 컨테이너 내부에서 heap dump 활성화
./shell.sh
# setenv 또는 JAVA_TOOL_OPTIONS 에 -XX:+HeapDumpOnOutOfMemoryError 추가
# 생성된 hprof 를 호스트로 복사
docker cp plantpulse-datalake:/path/to/heap.hprof /tmp/
Analyse erfolgt mit Eclipse MAT / VisualVM.
Alarmprobleme
| Symptom | Ursache | Lösung |
|---|---|---|
| Kein Alarm ausgelöst | Alarm-Einstellung ist deaktiviert | Alarm > Erweiterte Alarme prüfen → Ausgewählte Alarm-Einstellungen platzieren |
| Wert überschritten, aber Alarm nicht in Liste | Vorübergehend ausgeblendet · Geplante Wartung oder Reparaturunterdrückung · Außerbetriebsetzung | Ausblenden · Unterdrücken · Außerbetriebsetzung prüfen. Ausgeblendete Ereignisse über GET /api/v5/alarm/suppressed sichtbar |
| Alarm-Push wiederholt erfolgt | Unterdrückungszeit ist 0 | Alarm-Einstellungen: Doppelalarm-Unterdrückung → Unterdrückungszeit (Min.) |
| Rückkehr wird abgelehnt | Rückkehrprüfung fehlgeschlagen (Wert nicht im Normalbereich oder kein Wert innerhalb der letzten 10 Min.) | Wert prüfen und erneut zurückkehren oder Grund angeben und Trotzdem zurückkehren |
| Speichern des Statements abgelehnt | Fehlende Pflichtfelder je nach Typ | Pflichtfelder je Typ |
| Alarm-Erstellung 422 (API) | Manuell vergebene ID | Verwenden Sie die über GET /api/v5/alarm/config/new-id erhaltene ID |
| E-Mail-Benachrichtigung nicht gesendet | SMTP-Konfigurationsfehler | mail.properties prüfen (innerhalb des Containers /opt/kopens/plantpulse-platform/plantpulse-server/config/) |
| Kein Alarmton | Browser-Autoplay-Richtlinie | Im Browser die Autoplay-Funktion für die Seite zulassen |
UI-Probleme
| Symptom | Lösung |
|---|---|
| Anzeige verzerrt | Browser-Cache löschen (Ctrl+Shift+Delete) |
| Diagramme nicht angezeigt | JS-Fehler in den Browser-Entwicklertools (F12) > Console prüfen |
| Echtzeit-Aktualisierung unterbrochen | SSE (HTTP Streaming) Buffering- und Timeout-Einstellungen von Proxy/Firewall prüfen |
| Dashboard-Laden fehlgeschlagen | Existenz verknüpfter Tags / Datenquellen prüfen |
| Koreanische Zeichen fehlerhaft | PP_LANG=ko, PP_TZ=Asia/Seoul in env.sh prüfen, dann ./restart.sh |
Object Store (RustFS) Probleme
Endlose Einträge von AccessDenied im Log
[RUSTFS] level=ERROR op=GetObject err=S3Error(code: AccessDenied, message: "Access Denied")
Dies ist kein Problem mit den Anmeldedaten. Der Metrik-Collector der Management-API ruft alle 2 Sekunden den alten MinIO-Metrikpfad (/minio/v2/metrics/cluster) auf. Da RustFS diesen Pfad nicht besitzt, wird die Anfrage an den S3-Router weitergeleitet. Diese wird als Anfrage für einen Bucket mit dem Namen minio interpretiert. Da der Collector keine Signatur beifügt, wird die anonyme Anfrage abgelehnt.
| Frage | Antwort |
|---|---|
| Sind die Daten gefährdet? | Nein. Es handelt sich lediglich um eine abgelehnte Leseanfrage, die unabhängig von den gespeicherten Daten ist. |
| Hilft das Ändern des Passworts? | Nein — dies ist kein Eingriff für den Operator. Die Anfragen stammen von unserem Collector, der keine Signaturen sendet. Selbst wenn er es täte, blieben die Metriken leer, da der Endpunkt nicht existiert. |
| Wie oft tritt dies auf? | Alle 2 Sekunden — über 40.000 Zeilen pro Tag. |
| Was ist jetzt zu tun? | Betrachten Sie diese Signatur als «bekanntes Rauschen» und ignorieren Sie sie. Damit echte Fehler nicht übersehen werden, filtern Sie diese eine Zeile beim Betrachten der Logs heraus. |
| Wann verschwindet dies? | In der Version nach 2026.09 — der Collector wird so korrigiert, dass er nicht existierende Endpunkte nicht mehr aufruft. Dadurch verschwinden ca. 43.000 Zeilen pro Tag. |
Was in der nächsten Version verschwindet, sind die Logzeilen, nicht die Werte. Offline-Laufwerke · Offline-Nodes · Kapazitätsalarme werden danach weiterhin keine Werte empfangen, bis ein Metrikpfad in RustFS erstellt wird. Interpretieren Sie die Stille in den Logs nicht als «behoben».
Damals war der Metrikpfad ohne Authentifizierung offen (MINIO_PROMETHEUS_AUTH_TYPE=public), sodass eine Erfassung möglich war. Mit dem Wechsel zu RustFS entfällt die entsprechende Konfiguration, weshalb die sieben Metriken (minio_cluster_*) nicht mehr geliefert werden. Dies ist auch der Grund, warum diese Werte in der Konsole leer erscheinen.
Disk- / Volume-Probleme
Symptom: Diskplatzmangel
# 호스트 디스크 사용량
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 |
|---|---|
| Akkumulation alter Backups | Bereinigung alter tar.gz-Dateien in /data1/pp-backup/docker-volume |
| Unbenutzte Docker-Images | Bereinigung über docker system prune (Images/Netzwerke/Cache) |
| Aster TSDB SSTable-Akkumulation | Innerhalb des Containers pd node cleanup, pd node compact |
| Aufgeblähtes Logverzeichnis | Bereinigung von /opt/kopens/plantpulse-platform-docker/logs |
Achtung:
docker volume prunelöscht alle nicht verwendeten Volumes. Lassen Sie Container nicht im gestoppten Zustand, damit das Volumepp-*nicht versehentlich gelöscht wird.
Symptom: Wiederherstellung von Volume-Daten erforderlich
Bitte beachten Sie das Wiederherstellungsverfahren auf der Seite Operational Management - Backup und Recovery.
Update- / Rollback-Probleme
Symptom: Container arbeitet nach Upgrade nicht normal
Der offizielle Weg für Versionssprünge ist das erneute Ausführen des Installations-Oneliners. Schlägt das Upgrade fehl, setzt der Oneliner das System automatisch auf die Version vor dem Upgrade zurück (die Backup-Position wird im UPGRADE FAILED-Block angezeigt).
Beheben Sie die Ursache basierend auf den angezeigten Prüfpunkten und führen Sie den gleichen Oneliner erneut aus. Für manuelle Rollbacks verwenden Sie bin/upgrade-rollback.sh <백업 위치>. Setzen Sie das System nicht durch einfaches Ändern der Image-Tags über ./update.sh zurück — die Operations-Skripte und die Compose-Datei blieben sonst auf dem neuen Stand.
Symptom: NOT FOUND CONTAINER während des Updates
Die Erstinstallation (./install.sh) wurde nicht durchgeführt. Bitte führen Sie zuerst die Installation aus.
Netzwerk- / Cluster-Probleme
Symptom: Worker joinen nicht zum Master
# 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, dessen Join fehlgeschlagen ist, meldet denselben Status wie ein erfolgreicher Worker — da der interne Container-Check nur prüft, ob der Master «erreichbar» ist. In einer Messung vom 31.08.2026 hielt ein Worker, dessen Aster TSDB aufgrund von OOMKilled abgestürzt war, den Status health: starting aufrecht, obwohl der Ring nur aus einem Node bestand.
Entscheiden Sie zwingend anhand der Ring-Liste in pd node status. Das Hinzufügen von Workern wird durch bin/worker-add.sh validiert → Cluster-Installation
Symptom: Verbindungsfehler externer MQTT / Kafka Clients
Prüfen Sie, ob die Ports 1883/1884 (MQTT) und 9092/9093/9094 (Kafka) in der Host-Firewall sowie in der Unternehmens- oder Cloud-Firewall freigeschaltet sind. Eine detaillierte Portliste finden Sie in den Port-Konfigurationsinformationen.
- MQTT wird über
plantpulse-proxyempfangen. Anlagen müssen nur diesen Host kennen; selbst wenn der Broker verschoben oder umbenannt wird, sind keine Anpassungen an den Anlagen erforderlich. Port 1884 ist ein TLS-Passthrough, bei dem der Broker TLS terminiert. - Kafka durchläuft keinen Proxy. Da Clients nach dem Bootstrap erneut über die
advertised.listeners-Adresse verbinden, ist dies die erste zu prüfende Stelle, wenn nur der Bootstrap erfolgreich war, aber danach keine Kommunikation erfolgt.
Notfallmaßnahmen
Wenn der Container nicht reagiert
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 으로 전달
Bei Verdacht auf Datenkorruption
# 1. 즉시 정지 (추가 손상 방지)
./down.sh
# 2. 최신 백업 확인
ls -lh /data1/pp-backup/docker-volume/
# 3. 진단 tarball 생성 (절대 데이터를 임의로 수정하지 마세요)
./doctor.sh
# 4. 기술 지원팀 연락
Verbotene Maßnahmen bei Datenkorruption: Führen Sie kein manuelles Löschen von
pd node repair,pd node cleanupoder SSTables durch. Fehlerhafte Wiederherstellungsversuche können den Schaden vergrößern. Diese Schritte dürfen nur nach Absprache mit dem technischen Support erfolgen.
Erforderliche Informationen für Supportanfragen
Falls die oben genannten Methoden nicht helfen, senden Sie bitte die folgenden Informationen für eine schnellere Analyse:
| Punkt | Erfassungsmethode |
|---|---|
| Diagnose-Tarball | Datei nach Ausführung von ./doctor.sh |
| Container-Logs | ./logs.sh -n 500 > /tmp/container.log 2>&1 (alle acht Container) |
| Modul-Logs | Ergebnis von ./tools/copy-log-to-local.sh (/tmp/plantpulse-log/) |
| Image-Version | Ausgabe von ./stack-version.sh |
| Umgebungsvariablen | env.sh (Passwörter maskiert) |
| Systeminformationen | OS, CPU, RAM, Disk (uname -a, free -h, df -h) |
| Fehlermeldung | Exakte Fehlermeldung / Screenshot der Browser-Konsole (F12) |
| Reproduktionsschritte | Reihenfolge der durchgeführten Arbeiten unmittelbar vor dem Problem |
Technischer Support: webmaster@kopens.com
Verwandte Dokumente
- FAQ — Häufig gestellte Fragen
- Operational Management — Tägliche Betriebsbefehle
- Startguide — Verfahren zum Starten/Stoppen/Neustarten
- Backup und Recovery — Detaillierte Backup-Verfahren
- Performance-Tuning — JVM / DB Tuning
- Ports und Diensteverwaltung — Diagnose von Port-Konflikten