Betriebshandbuch Container-Modus

Ab dem Release 2026.05 wird PlantPulse Edge als einzelner Docker-Container ausgeliefert. Diese Seite fasst den täglichen Betrieb und die Störungsbehebung im Container-Modus an einer Stelle zusammen.

native-Modus

Für Boxen mit klassischer native-Installation (direkte Installation auf dem System) verwenden Sie weiterhin die native-Seiten im linken Menü, etwa 시작 (start.sh), 중지 (stop.sh) und 재시작 (restart.sh). Diese Seite gilt ausschließlich für Boxen mit Container-Deployment (systemctl status plantpulse-edge.service ist active).

Container vs. native — wo läuft was?

# 컨테이너 모드면 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. Bei container_mode=false oder ausbleibender Antwort des Endpoints: native.

Statusprüfung in einer Zeile

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

Ausgabefelder:

Container: name / image / image_tag / state / health / Startzeitpunkt
Resources: CPU-Auslastung / MEM-Verbrauch / Anzahl PIDs
Listening ports: 10 Stück (80, 443, 1883, 1884, 6379, 7799, 9042, 1880, 12000, 12443)
App.properties — zentrale Schlüssel (edge.id / site_id / dev.mode / mqtt.enable / sparkplug.enable)
API: /api/v1/system/version + Antwort von /api/v1/system/health + HTTP-Code
Upgrade status: Inhalt von /etc/kopens/upgrade.status (idle/running/success/...)

Befehle für den täglichen Betrieb

Aufgabe	Befehl
Status prüfen	`bash /opt/kopens/install/bin/status.sh`
Health (auf Basis 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	`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 sammeln (Eskalation)	`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 nötig

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

Hauptzweck: Verifizierung von OTA-Upgrades, Fleet-Inventory in Monitoring-Werkzeugen.

`/api/v1/system/health` — keine Authentifizierung nötig, HTTP 503 if any DOWN

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

Ist auch nur eine Komponente DOWN, folgt status=DEGRADED + HTTP 503. Die 90-Sekunden-Health-Probe von OTA upgrade.sh wertet dies aus und entscheidet über den Auto-Rollback.

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 (neuester Stand von product.kopens.io)

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

Auf ein bestimmtes Tag

sudo bash /opt/kopens/install/upgrade.sh --to 2026-20260601

Rollback auf das vorherige Tag

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

Nur prüfen, ob ein neuer Build vorliegt

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

Ablauf

META-INF/VERSION.JSON 의 build_date 비교 (--check 모드 / auto 모드)
pre-snapshot → /data1/pp-backups/pe-backup-<ts>.tar.zst
docker pull <new-tag>
/etc/kopens/version.env 갱신 + systemctl restart
/api/v1/system/health 90초 probe
6a. all UP → success — snapshot 경로 유지
6b. DEGRADED → auto-rollback to previous tag + snapshot 경로 안내

Auslösung über UI / API (aus dem Container heraus)

echo '{"target_tag":"2026-20260601"}' > /etc/kopens/upgrade.request

kopens-upgrade.path (inotify) auf dem Host erkennt dies → führt upgrade.sh --from-trigger aus.

Passwörter (bei Serienauslieferung)

Ab iter 9 (2026.05) erzeugt install.sh bei der Erstinstallation für jede Box automatisch zufällige Passwörter.

Ablageort: /etc/kopens/credentials.txt (chmod 0600 root)
Inhalt: admin / mqtt / opcua / API key / Keystore-Passwort
Auslieferungsprozess: drucken/speichern → beim Versiegeln der Box beilegen → jederzeit per cat erneut einsehbar (nur root)

Änderung im laufenden Betrieb:

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

Die HiveMQ-auth.properties wird vom entrypoint bei jedem Start automatisch mit den mqtt.*-Einträgen aus /etc/kopens/app.properties synchronisiert; es genügt also, app.properties zu ändern.

Ressourcengrenzen (cgroup)

Standardwerte der systemd-Unit:

key	value
MemoryMax	12G
MemoryHigh	11G
CPUQuota	600% (6 cores)
TasksMax	8192

Override für 8-GB-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 der Komponenten

HiveMQ : -Xms2g -Xmx2g (Override über env HIVEMQ_HEAP — Heap-Standard 2g seit 2026-07)
Cassandra : automatische Berechnung anhand von /proc/meminfo des Hosts (1/4 of total) — 16G host → ~4G (env CASSANDRA_HEAP)
Tomcat : -Xms2g -Xmx2g (env TOMCAT_HEAP)
Redis / Node-RED : Standard

Logs

Das logrotate (cronie) im Container übernimmt automatisch: daily / Trigger bei size>100M / 14 Tage gzip-Aufbewahrung / copytruncate (ohne Neustart der Anwendung).

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

Störungsbehebung (Kurzfassung)

Die ausführliche Szenariomatrix finden Sie unter /opt/kopens/install/RUNBOOK.md.

Symptom	Schnelle Abhilfe
Einzelne Komponenten in /health sind DOWN	Ursache über `logs.sh <component>` eingrenzen. Bei mqtt prüfen, ob die Passwörter in auth.properties und app.properties übereinstimmen
Container in Restart-Schleife	`journalctl -u plantpulse-edge -n 100` + Portbelegung (`ss -tlnp \| grep :80`) prüfen
Docker-Karte unter /ui/apps ist leer	`docker.sock`-Mount fehlt — `-v /var/run/docker.sock` in der systemd-Unit prüfen
PLC-Verbindung flackert	`NET_RAW`-cap / PLC-Port prüfen (MELSEC 5001, LS 2004, Modbus 502, OPC UA 49320)

Keine Wiederherstellung innerhalb von 30 Minuten → Eskalation

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 redigiert) / Host-Metriken.

Referenzen / verwandte Seiten

Installation: 설치 > 한눈에 보기
Vollständige REST API: 고급 / 통합 파트너용 > REST API
Host-OS / sysctl / nmcli: /opt/kopens/install/install.sh und install/RUNBOOK.md auf der Box
Szenariomatrix (A–E): /opt/kopens/install/RUNBOOK.md auf der Box

Container vs. native — wo läuft was?​

Statusprüfung in einer Zeile​

Befehle für den täglichen Betrieb​

Health-Check-API​

/api/v1/system/version — keine Authentifizierung nötig​

/api/v1/system/health — keine Authentifizierung nötig, HTTP 503 if any DOWN​

Speicherorte für Daten / Konfiguration​

OTA-Upgrade​

Automatisch (neuester Stand von product.kopens.io)​

Auf ein bestimmtes Tag​

Rollback auf das vorherige Tag​

Nur prüfen, ob ein neuer Build vorliegt​

Ablauf​

Auslösung über UI / API (aus dem Container heraus)​

Passwörter (bei Serienauslieferung)​

Ressourcengrenzen (cgroup)​

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

Standard-Heap der Komponenten​

Logs​

Störungsbehebung (Kurzfassung)​

Keine Wiederherstellung innerhalb von 30 Minuten → Eskalation​

Referenzen / verwandte Seiten​