Installations-Troubleshooting — häufige Fehler bei der Installation

Häufige Symptome während oder unmittelbar nach der Installation (Schnellinstallation / Produktionslinie / Air-Gap-Installation), sortiert nach Häufigkeit. Bei Neuinstallationen ab 2026.05+ ist der Container-Modus Standard; die auf tools/setup.sh basierende vollständige H/W-Installation dient nur noch der Wartung von Legacy-Native-Systemen. Für Fehler im laufenden Betrieb nach der Installation siehe Betriebsleitfaden Container-Modus oder Diagnose / Inspektion.

Schnellprüfung direkt nach der Container-Modus-Installation (2026.05+)

sudo bash /opt/kopens/install/bin/status.sh   # 한 줄 상태
sudo bash /opt/kopens/install/bin/health.sh   # exit 0/1
curl -ks https://127.0.0.1/api/v1/system/version | python3 -m json.tool   # image_tag / build_date / container_mode
curl -ks https://127.0.0.1/api/v1/system/health  | python3 -m json.tool   # components UP

Wenn install.sh fehlgeschlagen ist, /var/log/kopens-install.log prüfen. Ist der Container unhealthy, dann journalctl -u plantpulse-edge.service -n 100 oder docker logs plantpulse-edge. Detaillierte Szenarien: /opt/kopens/install/RUNBOOK.md in der Box (Matrix A–E).

Beweissicherung vor der Störungsbehebung

Bevor Sie auf einer für den Produktivbetrieb vorgesehenen Box eine Neuinstallation, clean oder restore durchführen, sichern Sie nach Möglichkeit zuerst doctor.sh und das acceptance log. Passwörter werden niemals im Klartext weitergegeben.

sudo bash /opt/kopens/install/bin/doctor.sh || true
sudo journalctl -u plantpulse-edge.service -n 200 --no-pager \
  > /root/pp-edge-journal-$(date +%Y%m%d-%H%M%S).txt

1. Download- / Installationsphase

1.1 `curl: (6) Could not resolve host: product.kopens.io`

Ursache: DNS-Auflösung fehlgeschlagen.

Lösung:

nslookup product.kopens.io
# Server: ... (사내 DNS) — 응답이 없으면 DNS 가 안 풀림

# /etc/resolv.conf 확인
cat /etc/resolv.conf
# nameserver 8.8.8.8 또는 사내 DNS 가 있어야 함

# 임시로 공인 DNS 추가
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf

Ist DNS im Firmennetz blockiert, IP direkt in /etc/hosts eintragen:

# product.kopens.io 의 실제 IP 를 운영팀에 문의 후 등록
echo "X.X.X.X product.kopens.io" | sudo tee -a /etc/hosts

An Standorten, an denen nur product.kopens.io geöffnet ist, prüfen Sie auf dieselbe Weise auch .com.

1.2 `curl: (7) Failed to connect to product.kopens.io port 443`

Ursache: Firmen-Firewall blockiert outbound 443 oder es wird ein Proxy benötigt.

Lösung:

# 프록시 환경이면 export HTTP_PROXY / HTTPS_PROXY
export HTTPS_PROXY=http://proxy.company.local:8080
export HTTP_PROXY=http://proxy.company.local:8080

# 그 후 install.sh 다시 실행
bash < <(curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh)

Falls auch der Proxy nicht funktioniert: Transport per USB gemäß Air-Gap-Installation.

1.3 `tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory`

Ursache: Abbruch während des Downloads — zu wenig Speicherplatz oder Verbindungsabbruch.

Lösung:

# 디스크 공간
df -h /opt /tmp

# 다시 다운로드 (`-C` 로 이어받기)
curl -O -C - https://product.kopens.io/plantpulse-edge/KOPENS_EDGE_V2026.tar.zstd

# 무결성 확인 (있으면 sha256)
sha256sum KOPENS_EDGE_V2026.tar.zstd

1.4 `bash: java: command not found`

Ursache: Java nicht installiert. Bei Container-Installationen ab 2026.05+ installiert install.sh die benötigten Pakete normalerweise selbst; scheitert die Paketinstallation jedoch an einer Sicherheitsrichtlinie oder einem gesperrten Repo, kann eine manuelle Installation nötig sein.

Lösung:

# Fedora / RHEL
sudo dnf install -y java-17-amazon-corretto-devel

# Ubuntu / Debian
sudo apt-get install -y temurin-17-jdk

# 확인
java -version
# openjdk version "17.x" ...

Bei einer neuen Container-Installation sollten Sie statt Java manuell einzurichten zuerst die Ursache der fehlgeschlagenen Paketinstallation in install.sh beheben. Nur bei älteren Native-Systemen gilt (legacy) vollständige H/W-Installation.

1.5 `docker: command not found`

Ursache: Docker nicht installiert oder Docker-Installationsschritt in install.sh fehlgeschlagen.

Lösung:

# Fedora
sudo dnf -y install docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker

# Ubuntu
curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker

# 확인
docker --version

2. Boot- / Startphase

2.0 Health liefert 503 im Container-Modus

Ursache: Eine der Komponenten ist DOWN. Sehen Sie zuerst den Komponentennamen im JSON von health nach.

Lösung:

curl -ks https://127.0.0.1/api/v1/system/health | python3 -m json.tool
sudo bash /opt/kopens/install/bin/status.sh
sudo bash /opt/kopens/install/bin/logs.sh tomcat | tail -100
sudo bash /opt/kopens/install/bin/logs.sh cassandra | tail -100
sudo bash /opt/kopens/install/bin/logs.sh mqtt | tail -100
sudo bash /opt/kopens/install/bin/logs.sh node-red | tail -100

Ursache im Log der jeweiligen Komponente ermitteln und beheben. Ist innerhalb von 30 Minuten keine Wiederherstellung möglich, führen Sie gemäß Eskalationsverfahren im Betriebsleitfaden Container-Modus backup.sh und doctor.sh aus.

2.1 (legacy native) Hängt bei Schritt `[4] DB START` (60 s+)

Ursache: Cassandra stellt das Commitlog wieder her. Beim ersten Boot oder nach einem unsauberen Shutdown normal — es braucht nur mehr Zeit.

Lösung:

# 별도 ssh 세션에서 실시간 로그
tail -f /opt/kopens/plantpulse-edge/db/logs/system.log

# `Listening for thrift clients` 또는 `Startup complete` 가 보이면 OK
# 그 후 메인 화면의 [4] 단계가 자동 진행됨

Erscheint nach 10 Minuten keine Meldung — Heap / Disk / beschädigte SSTable. Nach bin/node-cleanup.sh erneut versuchen.

2.2 (legacy native) Tomcat startet nach `[7] SERVER START` nicht — `Connection refused`

Ursache A: Unmittelbar nach dem Tomcat-Start 1–2 s kein Listen — normal.

Ursache B: Port 80 / 443 durch anderen Prozess belegt.

Lösung:

# 포트 점유 확인
sudo ss -lntp | grep -E ':80 |:443 '

# 점유 중이면 그 프로세스 정리 (예: nginx)
sudo systemctl stop nginx

# tomcat 재시작
sudo /opt/kopens/plantpulse-edge/bin/restart.sh

Ursache C: Startup-Error in catalina.out.

sudo tail -100 /opt/kopens/plantpulse-edge/server/logs/catalina.out | grep -E 'SEVERE|ERROR|Exception'

Maßnahmen je nach Meldung: Address already in use, Cannot find class, Failed to load app.properties usw.

2.3 Node-RED startet nicht

Ursache A: Port 1880 belegt. Ursache B: Rechte auf userDir (/opt/kopens/.../node/userDir). Ursache C: flows.json beschädigt.

Lösung:

# 1880 포트 점유?
sudo ss -lntp | grep 1880

# userDir 권한
ls -la /opt/kopens/plantpulse-edge/node/userDir/

# Node-RED 로그 (container)
sudo bash /opt/kopens/install/bin/logs.sh node-red | tail -50

# Node-RED 로그 (legacy native)
tail -50 /opt/kopens/plantpulse-edge/node/log/node-red.log

# flows.json 손상 시 백업본으로 복원
cd /opt/kopens/plantpulse-edge/node/userDir
cp .flows.json.backup flows.json

# 재시작
/opt/kopens/plantpulse-edge/node/bin/stop.sh
/opt/kopens/plantpulse-edge/node/bin/start.sh

2.4 `INSTALL COMPLETED` erscheint, aber Web nicht erreichbar (von außen)

Ursache: Firewall blockiert 80/443 (externer Zugriff).

Lösung:

# 게이트웨이 자체에서는 되는지
curl -kI https://127.0.0.1/api/v1/system/health
# HTTP/1.1 200 이면 게이트웨이 정상, 외부 접근만 차단됨

# firewalld 확인
sudo firewall-cmd --list-all
# 80/tcp, 443/tcp 가 ports 에 없으면 추가

sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

iptables-Umgebung:

sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

3. Netzwerk / Zeitsynchronisation

3.1 SSH-Abbruch nach `set-1.sh` / `set-2.sh`

Ursache: NIC-IP / Gateway / Subnetz falsch eingegeben.

Lösung (Konsole — Zugriff über KVM / IPMI / VM-Konsole):

# 현재 NIC 상태
nmcli dev show
ip a

# IP 수정 (예: enp1s0 의 IP 변경)
sudo nmcli con modify enp1s0 ipv4.address 192.168.0.50/24 ipv4.gateway 192.168.0.1
sudo nmcli con up enp1s0

# 재부팅 권장
sudo reboot

3.2 Uhrzeit zeigt 1970 / keine NTP-Synchronisation

Ursache: chrony-Dienst deaktiviert oder NTP nicht erreichbar.

Lösung:

# chrony 상태
sudo systemctl status chronyd
# Active: inactive (dead) 면 시작
sudo systemctl enable --now chronyd

# 동기 강제
sudo chronyc makestep
sudo chronyc tracking
# Reference ID 가 채워지면 OK

# 사내 NTP 서버 사용 시 /etc/chrony.conf 의 server 라인 수정
# server <internal-ntp-ip> iburst

3.3 Internetverkehr scheint über das PLC-Netz (NIC 2) zu laufen

Ursache: Beide NICs haben eine Default-Route.

Lösung:

# default route 확인
ip route | grep default

# 두 NIC 가 default 면 NIC 2 (PLC 망) 의 never-default 설정
sudo nmcli con modify enp2s0 ipv4.never-default yes
sudo nmcli con up enp2s0

4. Rechte / SELinux

4.1 `Permission denied` (binding port 80)

Ursache: Ausführung als Nicht-root-Benutzer.

Lösung: Alle Befehle nach sudo -i ausführen. Ist der Dienst als systemd-Service registriert, läuft er automatisch als root.

4.2 Meldung `avc: denied` (SELinux)

Ursache: SELinux im Enforcing-Modus — einzelne Pfade werden verweigert.

Lösung:

# 임시로 SELinux 끄기 (테스트용)
sudo setenforce 0

# 영구 (운영 환경에서 비추천)
sudo sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config

# 정식: 거부된 path 에 컨텍스트 부여 (운영팀과 함께)
sudo semanage fcontext -a -t bin_t '/opt/kopens/.*\.sh'
sudo restorecon -Rv /opt/kopens

5. Datenträger

5.1 Verzeichnis `/data1` existiert nicht

Ursache: Separater Datenträger nicht gemountet.

Lösung:

# 현재 마운트
df -h

# /data1 이 없으면 디스크 인식 → mkfs → mount
lsblk
# /dev/sdb 같은 디스크 확인 후
sudo mkfs.xfs /dev/sdb
sudo mkdir -p /data1
sudo mount /dev/sdb /data1
echo '/dev/sdb  /data1  xfs  defaults,noatime  0 2' | sudo tee -a /etc/fstab

5.2 Datenträger `/opt` voll — Entpacken der Artefakte fehlgeschlagen

Lösung: Bereinigung / Aufräumen — clean.sh + node-cleanup.sh + alte Backups löschen.

6. Erster Start — Daten / Registrierung

6.1 Karte Platform-API-Server 🔴 Verbindung fehlgeschlagen

Ursache: server.host / port / username in app.properties falsch, oder Platform läuft nicht, oder die Firmen-Firewall blockiert outbound.

Lösung:

# 외부에서 플랫폼 도달 가능?
curl -I https://<server.host>:<server.port>/

# 사내 방화벽 outbound 정책 — 운영팀에 문의 (HTTPS / 80 / 443)

# app.properties 수정 → 저장 → restart.sh

6.2 Edge-ID ist leer oder weicht ab

Ursache: edge.id in app.properties nicht gesetzt.

Lösung: Umgebungskonfiguration → edge.id=EDGE_<number> → speichern → restart.sh.

6.3 Erfassungsstatus bleibt nach PLC-Registrierung auf Unbekannt

Ursache A: Registrierung als auto_collect=false — manueller Start erforderlich. Ursache B: NIC des PLC-Netzes down oder PLC-IP nicht erreichbar.

Lösung:

# PLC IP ping
ping -c 3 192.168.100.20

# PLC 포트 도달 (Modbus 502 예시)
nc -vz 192.168.100.20 502

# 도달 OK 면 화면에서 ▶ 시작 누르기

7. Sonstiges

7.1 systemd `plantpulse-edge.service` wird nicht aktiviert

Dies ist der Standarddienst im Container-Modus.

Lösung:

sudo systemctl daemon-reload
sudo systemctl enable --now plantpulse-edge.service
sudo systemctl status plantpulse-edge.service --no-pager
sudo journalctl -u plantpulse-edge.service -n 100 --no-pager

Bei Unit not found ist /opt/kopens/install/install.sh vor dem Ablegen der systemd-Unit fehlgeschlagen. Prüfen Sie /var/log/kopens-install.log und führen Sie anschließend bash /opt/kopens/install/install.sh erneut aus.

7.2 (legacy native) systemd `plantpulse.service` wird nicht aktiviert

Lösung:

# 서비스 파일 위치
ls -la /etc/systemd/system/plantpulse.service

# 없으면 등록
sudo cp /opt/kopens/tools/service/plantpulse.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now plantpulse

# 상태
sudo systemctl status plantpulse
sudo journalctl -u plantpulse -n 100

7.3 Kein automatischer Start nach Reboot

sudo systemctl is-enabled plantpulse-edge.service
# enabled 가 아니면
sudo systemctl enable plantpulse-edge.service

Bei legacy native gilt dasselbe Verfahren mit plantpulse.service.

7.4 firefox / GUI-Tools lassen sich nicht installieren (Servermodus)

Ursache: Auf einem Headless-Server sind keine GUI-Pakete vorhanden.

Lösung: Kann ignoriert werden, der Gateway-Betrieb ist nicht betroffen. firefox aus setup.sh entfernen oder in dnf install weglassen und fortfahren.

8. Logspeicherorte — wo nachsehen

Komponente	Logspeicherort
Tomcat (Web / REST API)	`/opt/kopens/plantpulse-edge/server/logs/catalina.out`
Cassandra	`/opt/kopens/plantpulse-edge/db/logs/system.log`
HiveMQ (MQTT)	`/opt/kopens/plantpulse-edge/mqtt/log/hivemq.log`
Node-RED	`/opt/kopens/plantpulse-edge/node/log/node-red.log`
timeseries-engine	`/opt/kopens/plantpulse-edge/timeseries/engine/log/*.log`
systemd (container)	`journalctl -u plantpulse-edge.service -n 200`
systemd (legacy native)	`journalctl -u plantpulse -n 200`
Gesammeltes tail	`/opt/kopens/plantpulse-edge/bin/log-viewer.sh`

9. Wenn es weiterhin nicht funktioniert

Im Container-Modus: Ausgabe von status.sh, health.sh, journalctl -u plantpulse-edge.service -n 200 erfassen
Bei legacy native: 30 s mit bin/log-viewer.sh mitschneiden → SEVERE- / ERROR-Meldungen erfassen
Ergebnisse von df -h, free -h, systemctl status ... zusammen mit den Log-Auszügen an das Betriebsteam übergeben
Bei einer neuen Box install.sh aus der Schnellinstallation erneut ausführen. Nur bei älteren Native-Systemen einen erneuten Versuch mit tools/setup.sh aus der vollständigen H/W-Installation prüfen.

10. Weiterführende Informationen

Standardverfahren: Schnellinstallation
legacy native: (legacy) vollständige H/W-Installation
Air-Gap-Netzwerk: Offline- / Air-Gap-Installation
Checkliste nach der Installation: Checkliste direkt nach der Installation
Diagnose im Betrieb: Diagnose / Inspektion

1. Download- / Installationsphase​

1.1 curl: (6) Could not resolve host: product.kopens.io​

1.2 curl: (7) Failed to connect to product.kopens.io port 443​

1.3 tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory​

1.4 bash: java: command not found​

1.5 docker: command not found​

2. Boot- / Startphase​

2.0 Health liefert 503 im Container-Modus​

2.1 (legacy native) Hängt bei Schritt [4] DB START (60 s+)​

2.2 (legacy native) Tomcat startet nach [7] SERVER START nicht — Connection refused​

2.3 Node-RED startet nicht​

2.4 INSTALL COMPLETED erscheint, aber Web nicht erreichbar (von außen)​

3. Netzwerk / Zeitsynchronisation​

3.1 SSH-Abbruch nach set-1.sh / set-2.sh​

3.2 Uhrzeit zeigt 1970 / keine NTP-Synchronisation​

3.3 Internetverkehr scheint über das PLC-Netz (NIC 2) zu laufen​

4. Rechte / SELinux​

4.1 Permission denied (binding port 80)​

4.2 Meldung avc: denied (SELinux)​

5. Datenträger​

5.1 Verzeichnis /data1 existiert nicht​

5.2 Datenträger /opt voll — Entpacken der Artefakte fehlgeschlagen​

6. Erster Start — Daten / Registrierung​

6.1 Karte Platform-API-Server 🔴 Verbindung fehlgeschlagen​

6.2 Edge-ID ist leer oder weicht ab​

6.3 Erfassungsstatus bleibt nach PLC-Registrierung auf Unbekannt​

7. Sonstiges​

7.1 systemd plantpulse-edge.service wird nicht aktiviert​

7.2 (legacy native) systemd plantpulse.service wird nicht aktiviert​

7.3 Kein automatischer Start nach Reboot​

7.4 firefox / GUI-Tools lassen sich nicht installieren (Servermodus)​

8. Logspeicherorte — wo nachsehen​

9. Wenn es weiterhin nicht funktioniert​

10. Weiterführende Informationen​

1. Download- / Installationsphase

1.1 `curl: (6) Could not resolve host: product.kopens.io`

1.2 `curl: (7) Failed to connect to product.kopens.io port 443`

1.3 `tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory`

1.4 `bash: java: command not found`

1.5 `docker: command not found`

2. Boot- / Startphase

2.0 Health liefert 503 im Container-Modus

2.1 (legacy native) Hängt bei Schritt `[4] DB START` (60 s+)

2.2 (legacy native) Tomcat startet nach `[7] SERVER START` nicht — `Connection refused`

2.3 Node-RED startet nicht

2.4 `INSTALL COMPLETED` erscheint, aber Web nicht erreichbar (von außen)

3. Netzwerk / Zeitsynchronisation

3.1 SSH-Abbruch nach `set-1.sh` / `set-2.sh`

3.2 Uhrzeit zeigt 1970 / keine NTP-Synchronisation

3.3 Internetverkehr scheint über das PLC-Netz (NIC 2) zu laufen

4. Rechte / SELinux

4.1 `Permission denied` (binding port 80)

4.2 Meldung `avc: denied` (SELinux)

5. Datenträger

5.1 Verzeichnis `/data1` existiert nicht

5.2 Datenträger `/opt` voll — Entpacken der Artefakte fehlgeschlagen

6. Erster Start — Daten / Registrierung

6.1 Karte Platform-API-Server 🔴 Verbindung fehlgeschlagen

6.2 Edge-ID ist leer oder weicht ab

6.3 Erfassungsstatus bleibt nach PLC-Registrierung auf Unbekannt

7. Sonstiges

7.1 systemd `plantpulse-edge.service` wird nicht aktiviert

7.2 (legacy native) systemd `plantpulse.service` wird nicht aktiviert

7.3 Kein automatischer Start nach Reboot

7.4 firefox / GUI-Tools lassen sich nicht installieren (Servermodus)

8. Logspeicherorte — wo nachsehen

9. Wenn es weiterhin nicht funktioniert

10. Weiterführende Informationen