Betrieb im Container-Modus

Ab dem Release 2026.05 wird PlantPulse Edge als ein einziger Docker-Container bereitgestellt. Diese Seite dient als Leitfaden, der den täglichen Betrieb und die Fehlerbehebung im Container-Modus an einem Ort zusammenfasst.

Native-Modus

Für bestehende native Bereitstellungen (direkte Installation auf dem System) verwenden Sie bitte die nativen Seiten unter 시작 (start.sh), 중지 (stop.sh), 재시작 (restart.sh) etc. im linken Menü. Diese Seite ist ausschließlich für Container-Bereitstellungen (systemctl status plantpulse-edge.service ist aktiv) vorgesehen.

Container vs. Native — Wo läuft es?

# 컨테이너 모드면 active
systemctl is-active plantpulse-edge.service

# 또는 직접 확인
curl -ks https://127.0.0.1/api/v1/system/version | grep container_mode

container_mode=true → Container-Modus. container_mode=false oder fehlende Antwort vom Endpoint bedeutet Native.

Einzeilige Statusprüfung

sudo bash /opt/kopens/install/bin/status.sh

Ausgabepunkte:

Container: Name / Image / Image_Tag / State / Health / Startzeitpunkt
Resources: CPU-Auslastung / MEM-Verbrauch / Anzahl der PIDs
Listening ports: 9 Ports (80, 443, 1883, 1884, 6379, 9042, 1880, 12000, 12443). 7799 (Tomcat JMX) ist nur für 127.0.0.1 reserviert und daher nicht aufgeführt.
App.properties Kernschlüssel (edge.id / site_id / dev.mode / mqtt.enable / sparkplug.enable)
API: /api/v1/system/version + /api/v1/system/health Antwort + HTTP-Code
Upgrade status: Inhalt von /etc/kopens/upgrade.status (idle/trial/committed/...)

Befehle für den täglichen Betrieb

Aufgabe	Befehl
Status prüfen	`bash /opt/kopens/install/bin/status.sh`
Health (basiert auf Exit-Code)	`bash /opt/kopens/install/bin/health.sh`
Logs anzeigen	`bash /opt/kopens/install/bin/logs.sh tomcat` (oder cassandra/mqtt/redis/node-red/api/catalina)
Logs verfolgen (follow)	`bash /opt/kopens/install/bin/logs.sh -f tomcat`
Shell im Container	`bash /opt/kopens/install/bin/shell.sh`
Konfiguration ändern	`bash /opt/kopens/install/bin/config.sh --set <key> <value>`
Neustart	`sudo systemctl restart plantpulse-edge.service`
Backup	`sudo bash /opt/kopens/install/bin/backup.sh`
Wiederherstellung	`sudo bash /opt/kopens/install/bin/restore.sh <archive>`
Diagnose-Erfassung (Escalation)	`sudo bash /opt/kopens/install/bin/doctor.sh`
OTA-Upgrade	`sudo bash /opt/kopens/install/upgrade.sh`

Health-Check-API

`/api/v1/system/version` — Keine Authentifizierung erforderlich

{
  "data": {
    "product_name": "PlantPulse Edge",
    "version": "2026",
    "build_date": "20260523",
    "image_tag": "2026-20260523",
    "container_mode": true
  },
  "meta": {
    "timestamp": 1778925572946,
    "request_id": "..."
  }
}

Hauptverwendung: OTA-Upgrade-Validierung, Fleet-Inventory von Monitoring-Tools.

`/api/v1/system/health` — Keine Authentifizierung erforderlich, HTTP 503 wenn eine Komponente DOWN

{
  "data": {
    "status": "UP",
    "uptime_ms": 1720008,
    "components": {
      "cassandra": "UP",
      "redis": "UP",
      "mqtt": "UP",
      "node_red": "UP",
      "opc_ua": "UP"
    }
  }
}

Wenn auch nur eine Komponente DOWN ist, erfolgt eine Meldung über status=DEGRADED + HTTP 503. Das OTA-Upgrade upgrade.sh prüft den Testlauf über eine separate Entscheidungsadresse /api/health?verdict=upgrade&expect_build=<빌드일> (Standard: 300 Sekunden).

Speicherorte für Daten / Konfiguration

/data1/                                # 컨테이너 ↔ host bind mount, 컨테이너 교체에도 보존
├── pp-data/
│   ├── cassandra/{data, hints}        # SSTables, hints
│   ├── redis/                         # AOF / RDB
│   ├── hivemq/                        # MQTT persistence
│   └── node-userdir/                  # Node-RED flows + node_modules
├── pp-temp/cassandra/commitlog        # 휘발성 commit log
└── pp-backups/                        # backup.sh 산출물 + OTA pre-snapshot

/etc/kopens/                           # 설정 + signal files (read-write mount)
├── app.properties                     # 메인 설정 (165줄, 16개 섹션)
├── credentials.txt                    # 박스별 비번 (chmod 0600, 설치 시 1회 출력)
├── version.env                        # KOPENS_VERSION=<tag>
├── upgrade.status / upgrade.request   # OTA 시그널
└── host-action.status / .request      # restart/reboot/clean signal

/var/security/plantpulse/edge/         # SSL keystore (read-only mount, 100년 self-signed)

OTA-Upgrade

Automatisch (Aktuellste Version von product.kopens.io)

sudo bash /opt/kopens/install/upgrade.sh

Über einen spezifischen Tag

sudo bash /opt/kopens/install/upgrade.sh --to 2026.11-20261103-1006

Es werden nur unveränderliche Tags (YYYY.MM-YYYYMMDD-HHMM) akzeptiert.

Rollback eines laufenden Upgrades

sudo bash /opt/kopens/install/upgrade.sh --rollback

Funktioniert nur in den Zuständen trial und rollback_failed. Ein Downgrade von einem bestätigten Build auf einen älteren Build ist nicht möglich.

Nur Prüfung auf neue Builds

sudo bash /opt/kopens/install/upgrade.sh --check

Ablauf

Die Reihenfolge entspricht der «Ausführungsreifolge» unter Upgrade. Vorprüfung → Download → Signaturprüfung → Snapshot → Umschaltung → Testlauf → Bestätigung oder automatisches Rollback.

Status: cat /etc/kopens/upgrade.status — idle · downloading · verified · snapshot · switching · trial · committed · rolling_back · rolled_back · rollback_failed.

UI / API Trigger (Innerhalb des Containers)

POST /api/v1/system/upgrade verwendet /etc/kopens/upgrade.request.

Erkennung durch kopens-upgrade.path (inotify) des Hosts → Ausführung von upgrade.sh --from-trigger.

Passwörter (Bei Serienauslieferung)

Ab Iteration 9 (2026.05) wird bei der ersten Installation via install.sh für jede Box automatisch ein zufälliges Passwort generiert.

Ort: /etc/kopens/credentials.txt (chmod 0600 root)
Inhalt: Passwörter für admin / mqtt / opcua / API-Key / Keystore
Auslieferungsverfahren: Drucken/Speichern → Beilage bei Versiegelung der Box → Überprüfung per cat möglich (nur root)

Änderung im Betrieb:

config.sh --set edge.admin_password "NewStrongPass!"
config.sh --restart

Da HiveMQ auth.properties den Entrypoint bei jedem Booten automatisch mit mqtt.* in /etc/kopens/app.properties synchronisiert, muss nur die app.properties geändert werden.

Ressourcenlimits (cgroup)

Standardwerte der systemd-Unit:

Schlüssel	Wert
MemoryMax	12G
MemoryHigh	11G
CPUQuota	600% (6 Cores)
TasksMax	8192

Override für 8GB-Boxen (Drop-in)

sudo mkdir -p /etc/systemd/system/plantpulse-edge.service.d
sudo tee /etc/systemd/system/plantpulse-edge.service.d/override.conf <<'EOF'
[Service]
Environment=HIVEMQ_HEAP=1g
Environment=CASSANDRA_HEAP=1g
Environment=TOMCAT_HEAP=1g
MemoryMax=6G
MemoryHigh=5G
EOF
sudo systemctl daemon-reload
sudo systemctl restart plantpulse-edge.service

Standard-Heap für Komponenten

HiveMQ: -Xms2g -Xmx2g (Override via env HIVEMQ_HEAP — Heap-Standard Juli 2026: 2g)
Cassandra: Automatische Berechnung basierend auf host /proc/meminfo (1/4 der Gesamtkapazität) — 16G Host → ~4G (env CASSANDRA_HEAP)
Tomcat: -Xms2g -Xmx2g (env TOMCAT_HEAP)
Redis / Node-RED: Standard

Logs

Die Logrotate (cronie) innerhalb des Containers verarbeitet die Logs automatisch: Täglicher Trigger / Trigger bei Größe > 100M / 14 Tage gzip-Aufbewahrung / copytruncate (ohne App-Neustart).

Komponente	Pfad (im Container)	Tool
Tomcat App	`$PE_HOME/server/log/system.log`	`logs.sh tomcat`
Tomcat Stdout	`$PE_HOME/server/logs/catalina.out`	`logs.sh catalina`
Cassandra	`$PE_HOME/db/logs/system.log`	`logs.sh cassandra`
HiveMQ	`$PE_HOME/mqtt/logs/hivemq.log`	`logs.sh mqtt`
Redis	`$PE_HOME/cache/log/redis.log`	`logs.sh redis`
Node-RED	`$PE_HOME/node/log/node-red.log`	`logs.sh node-red`
API Audit	`$PE_HOME/server/log/api.log`	`logs.sh api`
Host	`journalctl -u plantpulse-edge.service`	journalctl

Fehlerbehebung (Kurzfassung)

Siehe Installation für Installationsszenarien (Serienlinie · Einzelbox pro Standort · CI).

Symptom	Schnelle Lösung
/health Komponenten teilweise DOWN	Ursachenverfolgung mit `logs.sh <component>`. Bei MQTT: Passwörter in auth.properties / app.properties auf Übereinstimmung prüfen
Container Restart-Loop	`journalctl -u plantpulse-edge -n 100` + Prüfung auf Port-Belegung (`ss -tlnp \| grep :80`)
/ui/apps Docker-Karte leer	Fehlendes Mounting `docker.sock` — Prüfen von `-v /var/run/docker.sock` in der systemd-Unit
PLC-Verbindung instabil	`NET_RAW` cap / PLC-Port prüfen (MELSEC 5001, LS 2004, Modbus 502, OPC UA 49320)

Wenn keine Wiederherstellung innerhalb von 30 Minuten erfolgt → Escalation

sudo bash /opt/kopens/install/bin/backup.sh    # 1. 악화 전 스냅샷
sudo bash /opt/kopens/install/bin/doctor.sh    # 2. 진단 tarball (≈200KB)
# 3. /tmp/pe-doctor-*.tar.zst + .sha256 을 support@kopens.io 또는 https://support.kopens.io 업로드

Inhalt des pe-doctor tarballs: api / docker / systemd / Logs der 7 Komponenten / Konfiguration (Passwörter geschwärzt) / Host-Metriken.

Referenzen / Verwandte Seiten

Installation: 설치 > 한눈에 보기
Vollständige REST API: 고급 / 통합 파트너용 > REST API
Host OS / sysctl / nmcli: /opt/kopens/install/install.sh der Box
Installationsszenarien: Installation

Container vs. Native — Wo läuft es?​

Einzeilige Statusprüfung​

Befehle für den täglichen Betrieb​

Health-Check-API​

/api/v1/system/version — Keine Authentifizierung erforderlich​

/api/v1/system/health — Keine Authentifizierung erforderlich, HTTP 503 wenn eine Komponente DOWN​

Speicherorte für Daten / Konfiguration​

OTA-Upgrade​

Automatisch (Aktuellste Version von product.kopens.io)​

Über einen spezifischen Tag​

Rollback eines laufenden Upgrades​

Nur Prüfung auf neue Builds​

Ablauf​

UI / API Trigger (Innerhalb des Containers)​

Passwörter (Bei Serienauslieferung)​

Ressourcenlimits (cgroup)​

Override für 8GB-Boxen (Drop-in)​

Standard-Heap für Komponenten​

Logs​

Fehlerbehebung (Kurzfassung)​

Wenn keine Wiederherstellung innerhalb von 30 Minuten erfolgt → Escalation​

Referenzen / Verwandte Seiten​