Installationsprobleme beheben

Während oder direkt nach der Installation (Einzellinien-Installation / Produktionslinien-Installation / Installation im Air-Gap-Netzwerk) werden die am häufigsten auftretenden Symptome in der Reihenfolge ihrer Häufigkeit aufgeführt. Die Installation im Container-Modus ist der Standard. Fehler, die während des Betriebs nach der Installation auftreten, finden Sie unter Betrieb im Container-Modus oder Diagnose und Inspektion.

Schnelle Überprüfung direkt nach der Installation im Container-Modus 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. Wenn der Container unhealthy ist, journalctl -u plantpulse-edge.service -n 100 oder docker logs plantpulse-edge. Details: Betrieb im Container-Modus.

Beweise vor der Fehlerbehebung sichern

Bevor Sie auf einer für den Betrieb vorgesehenen Box eine Neuinstallation, ein Clean oder ein Restore durchführen, sollten Sie nach Möglichkeit zuerst doctor.sh und das acceptance log speichern. Das Passwort im Klartext wird nicht geteilt.

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

In einem Netzwerk mit DNS-Blockierung /etc/hosts die IP direkt hinzufügen:

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

Wenn nur product.kopens.io geöffnet ist, prüfen Sie auf die gleiche Weise auch .com.

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

Ursache: Die interne Firewall blockiert ausgehende Verbindungen auf Port 443 oder ein Proxy ist erforderlich.

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)

Wenn auch ein Proxy nicht funktioniert, folgen Sie der Vorgehensweise für Installation im Air-Gap-Netzwerk und transportieren Sie die Daten per USB.

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. Die Installation im Container-Modus 2026.05+ installiert normalerweise die Pakete, die install.sh benötigt. Wenn die Paketinstallation jedoch aufgrund interner Sicherheitsrichtlinien oder einer gesperrten Repository-Quelle fehlschlägt, kann eine manuelle Installation erforderlich 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 Neuinstallation im Container-Modus sollten Sie zuerst die Ursache des Fehlschlags der Paketinstallation gemäß install.sh beheben, anstatt Java manuell anzupassen.

1.5 `docker: command not found`

Ursache: Docker nicht installiert oder die Docker-Installationsphase gemäß 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-Status 503 im Container-Modus

Ursache: Eine der Komponenten ist DOWN. Prüfen Sie zuerst den Komponentennamen in der JSON-Datei health.

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

Prüfen Sie die Ursache in den Logs der jeweiligen Komponente und ergreifen Sie Maßnahmen. Wenn die Wiederherstellung nicht innerhalb von 30 Minuten erfolgt, führen Sie gemäß dem Eskalationsverfahren unter Betrieb im Container-Modus backup.sh und doctor.sh aus.

2.1 Hängenbleiben in der `[4] DB START`-Phase (60 Sekunden+)

Ursache: Cassandra führt die Wiederherstellung des Commitlogs durch. Dies ist beim ersten Start oder nach einem unerwarteten Beenden normal — es wird nur mehr Zeit benötigt.

Lösung:

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

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

Wenn nach 10 Minuten keine Meldung erscheint — Heap / Speicherplatz / beschädigte SSTables. bin/node-cleanup.sh und erneut versuchen.

2.2 Server startet nach `[7] SERVER START` nicht — `Connection refused`

Ursache A: Tomcat lauscht direkt nach dem Booten 1–2 Sekunden lang nicht — normal.

Ursache B: Die Ports 80 / 443 sind von einem 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-Fehler in catalina.out.

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

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

2.3 Node-RED startet nicht

Ursache A: Port 1880 ist belegt. Ursache B: Berechtigungen für 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

# 플로우 도구 로그
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` läuft, aber Web-UI (von außen) nicht erreichbar

Ursache: Firewall blockiert Ports 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

In einer 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 Vergabe einer statischen IP während der Installation

Ursache: Die IP, das Gateway und das Subnetz gemäß install.sh / NET1_IP / NET2_IP sind falsch. (Falls Sie die alten Skripte set-1.sh / set-2.sh verwendet haben: Diese existieren nicht mehr — jetzt setzt die Installation nmcli direkt.)

Lösung (über Konsole — 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 Zeit steht auf 1970 / NTP-Synchronisation schlägt fehl

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 Internet scheint über das PLC-Netz (NIC 2) durchzusickern

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. Berechtigungen / SELinux

4.1 `Permission denied` (Port 80 binden)

Ursache: Ausführung als nicht-root Benutzer.

Lösung: sudo -i vor allen Befehlen. Wenn der Dienst als systemd-Service registriert ist, erfolgt dies automatisch als root.

4.2 `avc: denied`-Meldung (SELinux)

Ursache: SELinux im Enforcing-Modus — einige Pfade werden abgelehnt.

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. Speicherplatz

5.1 Verzeichnis `/data1` existiert nicht

Ursache: Separates Laufwerk 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 Laufwerk `/opt` voll — Entpacken von Artefakten schlägt fehl

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

6. Erster Start — Daten / Registrierung

6.1 Karte Plattform-API-Server 🔴 Verbindungsfehler

Ursache: app.properties / server.host / port / username falsch, oder Plattform nicht in Betrieb, oder interne Firewall blockiert ausgehende Verbindungen.

Lösung:

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

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

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

6.2 Edge-ID leer oder nicht wie beabsichtigt

Ursache: app.properties / edge.id nicht konfiguriert.

Lösung: Web-UI-Konfiguration → edge.id=EDGE_<number> → Speichern → restart.sh.

6.3 Nach der PLC-Registrierung bleibt der Erfassungsstatus auf Unbekannt

Ursache A: Registrierung über auto_collect=false — manueller Start erforderlich. Ursache B: NIC des PLC-Netzes ist 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` 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 fehlgeschlagen, bevor die systemd-Unit platziert wurde. Prüfen Sie /var/log/kopens-install.log und führen Sie bash /opt/kopens/install/install.sh erneut aus.

7.3 Kein Autostart nach Neustart

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

7.4 firefox / GUI-Tools nicht installiert (Server-Modus)

Ursache: Keine GUI-Pakete auf einem Headless-Server.

Lösung: Kann ignoriert werden; kein Einfluss auf den Gateway-Betrieb. firefox aus setup.sh entfernen oder aus dnf install herausnehmen und fortfahren.

8. Log-Speicherorte — wo nachsehen

Komponente	Speicherort der Logs
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`
Integriertes Tail	`/opt/kopens/plantpulse-edge/bin/log-viewer.sh`

9. Wenn es immer noch nicht funktioniert

Im Container-Modus status.sh, health.sh, journalctl -u plantpulse-edge.service -n 200 Ausgabe erfassen
df -h, free -h, systemctl status ... Ergebnisse und die obigen Logauszüge an das Betriebsteam weiterleiten
install.sh der Einzellinien-Installation erneut ausführen — da idempotent, kann es gefahrlos mehrfach ausgeführt werden.

10. Weitere Informationen

Standardverfahren: Einzellinien-Installation
Air-Gap-Netzwerk: Installation im Air-Gap-Netzwerk
Checkliste nach der Installation: Inspektion nach der Installation
Diagnose im Betrieb: Diagnose und 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-Status 503 im Container-Modus​

2.1 Hängenbleiben in der [4] DB START-Phase (60 Sekunden+)​

2.2 Server startet nach [7] SERVER START nicht — Connection refused​

2.3 Node-RED startet nicht​

2.4 INSTALL COMPLETED läuft, aber Web-UI (von außen) nicht erreichbar​

3. Netzwerk / Zeitsynchronisation​

3.1 SSH-Abbruch nach Vergabe einer statischen IP während der Installation​

3.2 Zeit steht auf 1970 / NTP-Synchronisation schlägt fehl​

3.3 Internet scheint über das PLC-Netz (NIC 2) durchzusickern​

4. Berechtigungen / SELinux​

4.1 Permission denied (Port 80 binden)​

4.2 avc: denied-Meldung (SELinux)​

5. Speicherplatz​

5.1 Verzeichnis /data1 existiert nicht​

5.2 Laufwerk /opt voll — Entpacken von Artefakten schlägt fehl​

6. Erster Start — Daten / Registrierung​

6.1 Karte Plattform-API-Server 🔴 Verbindungsfehler​

6.2 Edge-ID leer oder nicht wie beabsichtigt​

6.3 Nach der PLC-Registrierung bleibt der Erfassungsstatus auf Unbekannt​

7. Sonstiges​

7.1 systemd plantpulse-edge.service nicht aktiviert​

7.3 Kein Autostart nach Neustart​

7.4 firefox / GUI-Tools nicht installiert (Server-Modus)​

8. Log-Speicherorte — wo nachsehen​

9. Wenn es immer noch nicht funktioniert​

10. Weitere 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-Status 503 im Container-Modus

2.1 Hängenbleiben in der `[4] DB START`-Phase (60 Sekunden+)

2.2 Server startet nach `[7] SERVER START` nicht — `Connection refused`

2.3 Node-RED startet nicht

2.4 `INSTALL COMPLETED` läuft, aber Web-UI (von außen) nicht erreichbar

3. Netzwerk / Zeitsynchronisation

3.1 SSH-Abbruch nach Vergabe einer statischen IP während der Installation

3.2 Zeit steht auf 1970 / NTP-Synchronisation schlägt fehl

3.3 Internet scheint über das PLC-Netz (NIC 2) durchzusickern

4. Berechtigungen / SELinux

4.1 `Permission denied` (Port 80 binden)

4.2 `avc: denied`-Meldung (SELinux)

5. Speicherplatz

5.1 Verzeichnis `/data1` existiert nicht

5.2 Laufwerk `/opt` voll — Entpacken von Artefakten schlägt fehl

6. Erster Start — Daten / Registrierung

6.1 Karte Plattform-API-Server 🔴 Verbindungsfehler

6.2 Edge-ID leer oder nicht wie beabsichtigt

6.3 Nach der PLC-Registrierung bleibt der Erfassungsstatus auf Unbekannt

7. Sonstiges

7.1 systemd `plantpulse-edge.service` nicht aktiviert

7.3 Kein Autostart nach Neustart

7.4 firefox / GUI-Tools nicht installiert (Server-Modus)

8. Log-Speicherorte — wo nachsehen

9. Wenn es immer noch nicht funktioniert

10. Weitere Informationen