Zum Hauptinhalt springen

Startguide

Übersicht​

Wenn Sie die PlantPulse Platform mittels einer One-Line-Installation oder Docker installiert haben, befinden sich alle Betriebsskripte im Verzeichnis /opt/kopens/plantpulse-platform-docker/bin/. Diese Seite beschreibt, wie Sie die Platform, die als Docker Compose Stack betrieben wird, starten und verwalten.

Die Platform besteht aus neun Containern — einem Zertifikat, einem Data Lake, sechs Apps und einem Proxy. Alle neun laufen dauerhaft. Die gesamte Konfiguration finden Sie unter Docker-Installation — Installationsstruktur.

Falls Sie noch alte Skriptnamen verwenden

Die Namen auf der linken Seite existieren nicht mehr. Bitte verwenden Sie die gängigen Verben auf der rechten Seite.

Alter NameAktuelle Bezeichnung
start.shup.sh
platform-stop.shdown.sh
platform-update.shupdate.sh
platform-remove.shremove.sh
platform-bash.shshell.sh
platform-verify-boot.shstack-verify-boot.sh
worker-run.sh · worker-stop.sh · worker-update.sh · worker-bash.shSiehe Worker-Management

stack-run.sh · stack-stop.sh · stack-bash.sh · stack-update.sh · stack-remove.sh funktionieren weiterhin (sie weisen auf den neuen Namen hin und führen anschließend die gleiche Aktion aus).

Konfiguration der Umgebungsvariablen​

Bitte überprüfen Sie die Umgebungsvariablen vor dem Start der Platform. Da Ressourcenwerte basierend auf dem Host bei der Installation automatisch berechnet werden, gibt es bei den meisten Servern kaum Anpassungsbedarf.

vi /opt/kopens/plantpulse-platform-docker/bin/env.sh

Häufig angepasste Parameter​

VariableBeschreibungStandardwert
PP_LANGPlatform Locale (ko / en)en
PP_TZPlatform ZeitzoneAsia/Seoul
DOCKER_PP_CPUSAnzahl der vCPUs für ContainerErgebnis von nproc
DOCKER_PP_MEMORYArbeitsspeicher-Limit90 % des Host-RAM
DOCKER_DATALAKE_MEMORYData Lake Arbeitsspeicher-Limit96G (Minimum, darf 90 % des Host-RAM nicht überschreiten — Host unter 107G ist unterspekt)
DOCKER_PP_DATA_DISK_NAMEName der DatendiskAutomatische Rückverfolgung (bei Fehler sda)
DOCKER_PP_EXTERNAL_IPExterne Advertise-IP in NAT-UmgebungenLeerwert

Die vollständige Liste der Umgebungsvariablen finden Sie auf der Seite Referenz der Umgebungsvariablen.

Übernahme von Änderungen: Nach der Änderung von env.sh muss ein Neustart über ./restart.sh erfolgen, damit die neuen Einstellungen wirksam werden.

Passwörter können nicht über env.sh geändert werden

Auf einem installierten Knoten überschreibt der Secret-Sidecar (/etc/kopens/plantpulse-platform.env) sowohl env.sh als auch Shell-Exports. Verwenden Sie für Passwortänderungen passwd.sh unter Passwort-Rotation.

Start der Platform​

Start nach der Erstinstallation​

Nach Abschluss der Installation (install.sh) ist der Stack bereits in Betrieb. Bitte prüfen Sie lediglich den Status.

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh
./ops-check.sh

Start eines gestoppten Stacks​

Falls der Stack durch ./down.sh oder einen Host-Reboot gestoppt wurde, starten Sie ihn erneut.

cd /opt/kopens/plantpulse-platform-docker/bin
./up.sh

up.sh ist idempotent und wartet, bis das System bereit ist. Der Exit-Code 0 bedeutet nicht «Befehl erfolgreich ausgeführt», sondern «System ist nun einsatzbereit».

UmgebungsvariableStandardwertBedeutung
PP_READY_TIMEOUT900Max. Wartezeit für Bereitschaft (Sekunden)
PP_READY_INTERVAL15Prüfintervall (Sekunden)
PP_WAIT=0—Kein Warten (hier bedeutet 0 nicht «bereit»)

Die Daten in den Volumes (pp-data, pp-temp, pp-backup, pp-security, pp-proxy-certs) bleiben erhalten. Templates und Konfigurationen werden über Host-Bind-Mounts (/etc/kopens/conf) verwaltet.

Startreihenfolge​

Die Container starten in der von Compose in depends_on festgelegten Reihenfolge. Da es sich um eine service_healthy-Bedingung handelt, wird nicht nur darauf gewartet, dass der Prozess läuft, sondern dass er «benutzbar» ist.

plantpulse-certs (healthy 까지)
│
plantpulse-datalake (healthy 까지)
│
plantpulse-server-web (healthy 까지) ──── plantpulse-proxy
│
plantpulse-batch-web (healthy 까지)
│
├── plantpulse-warehouse
├── plantpulse-plugin-opcua
├── plantpulse-plugin-aasx
└── plantpulse-ha (이 넷은 서로 순서가 없습니다)

Innerhalb des Data Lake Containers starten die Infrastrukturkomponenten erneut in dieser Reihenfolge:

ReihenfolgeKategorieKomponente
1StorageValkey(Redis), PostgreSQL, Aster TSDB, RustFS
2AnalyseSpark, Hadoop, Hive, Kyuubi, Gravitino
3ZeitreiheZeitreihen-Engine, Zeitreihen-UI
4MessagingKafka, MQTT
5WorkflowTemporal, Kestra
6VerarbeitungCEP, Data Gateway, SQL, Monitor
Zeitaufwand

Der reine Prozessstart dauert 3–5 Minuten (JVM Warming-up), aber eine Reininstallation benötigt 15–18 Minuten, bis alle Komponenten stabil sind. Die Schema-Migration und Stabilisierung von Aster TSDB ist dabei der langsamste Teil.

Messung (31.08.2026, 32 vCPU / 128GiB): Data Lake 217s, Webserver 316s. Neustarts bei vorhandenen Daten sind wesentlich schneller.

Boot-Validierung​

cd /opt/kopens/plantpulse-platform-docker/bin
./stack-verify-boot.sh

stack-verify-boot.sh bewertet nicht einen einzelnen Container, sondern den gesamten Stack — ob alle neun «running·healthy» sind und ob der Proxy den Port 443 bedient.

up.sh und restart.sh führen ein Polling durch, bis dieses Skript erfolgreich ist; dies ist die Grundlage dafür, dass der Exit-Code 0 beider Befehle «benutzbar» bedeutet.

Überprüfung des erfolgreichen Starts​

# 서비스 / health / 볼륨 요약 (0 = 정상 / 2 = 비정상)
./status.sh

# 운영 health + 최근 critical log 점검
./ops-check.sh

# 헬스체크 엔드포인트 직접 호출
curl -kfsS https://<server-ip>:4950/api/health | jq

# Docker 상태
docker ps

Wenn in docker ps alle neun den Status (healthy) haben, ist der Start erfolgreich.

Stopp der Platform​

cd /opt/kopens/plantpulse-platform-docker/bin
./down.sh

Stoppt den Stack sicher. Da die Daten in den Docker-Volumes erhalten bleiben, wird der vorherige Zustand nach einem Neustart mit ./up.sh beibehalten.

Achtung: docker kill oder ein erzwungener Host-Shutdown kann die Datenkonsistenz beeinträchtigen. Verwenden Sie unbedingt ./down.sh.

Neustart der Platform​

cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh

Beendet interne Komponenten «graceful» (Drain), stoppt den Stack in umgekehrter Abhängigkeitsreihenfolge, startet ihn erneut in der depends_on-Reihenfolge und wartet, bis das System bereit ist.

Wird bei Änderungen an env.sh, zur Behebung temporärer Betriebsprobleme oder für regelmäßige Neustarts verwendet.

Überprüfung des Service-Status​

Gesamtübersicht​

./status.sh

Zeigt Serviceliste, Containerstatus, Health-Ergebnisse und Volumeninformationen auf einen Blick. Der Exit-Code ist verbindlich — 0 bedeutet Normalbetrieb, 2 bedeutet Anomalie, sodass dies direkt für Monitoring-Automatisierungen genutzt werden kann.

Betriebliche Inspektion​

./ops-check.sh

Prüft Container-Health, Health-API-Antworten und aktuelle kritische Logs. Dabei werden alle acht Container durchleuchtet.

Überprüfung der Host-Ressourcen​

docker stats --no-stream # 컨테이너별 CPU / 메모리
docker ps # 컨테이너 상태

Da für jeden Container separate mem_limit gelten, kann individuell geprüft werden, welcher Container seine Grenze erreicht hat. Die Grenzwerte pro App finden Sie in der Referenz der Umgebungsvariablen.

Zugriff auf Container-Innenraum​

cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh # 인자가 없으면 데이터레이크
./shell.sh plantpulse-server-web # 특정 컨테이너

Die Liste der zugänglichen Services kann über ./status.sh eingesehen werden.

Cluster-Worker sind nicht in dieser Liste

shell.sh löst nur Namen von Services des Basis-Stacks auf. Worker befinden sich im erstellten Overlay (compose/docker-compose.worker.yml) und werden daher über docker exec -ti plantpulse-worker-<n> /bin/bash angesprochen.

Neustart auf Komponentenebene​

Da die Container getrennt sind, gibt es zwei Arten des Neustarts.

Die sechs Apps — Neustart auf Containerebene​

Da jede App in ihrem eigenen Container läuft, bedeutet ein Neustart des Containers direkt den Neustart dieser App. Andere Apps und die Infrastruktur bleiben unbeeinflusst.

cd /opt/kopens/plantpulse-platform-docker
docker compose -f compose/docker-compose.yml restart plantpulse-server-web
ContainerInhalt
plantpulse-server-webWeb-Konsole
plantpulse-batch-webBatch
plantpulse-warehouse-webData Warehouse
plantpulse-plugin-opcuaOPC-UA Plugin
plantpulse-plugin-aasxAASX Plugin
plantpulse-haRedundanz-Recovery-Daemon
docker compose restart beachtet die Abhängigkeitsreihenfolge nicht

Wenn mehrere Apps gleichzeitig neu gestartet werden müssen, ist es sicherer, den gesamten Stack über ./restart.sh neu zu starten. Die Startreihenfolge ist plantpulse-server-web → plantpulse-batch-web → die restlichen vier.

Komponenten im Data Lake — Interne Skripte des Containers​

Infrastrukturkomponenten wie Storage, Analyse und Messaging laufen gemeinsam in einem einzigen Container (plantpulse-datalake). Daher muss man in den Container wechseln und einzelne Skripte verwenden.

# 호스트에서 데이터레이크 진입
./shell.sh

# 컨테이너 내부에서
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd restart storage
exit
SkriptZiel
pd restart storageAster TSDB, PostgreSQL, Valkey, RustFS
pd restart analyticsSpark, Hive, Kyuubi, Gravitino
pd restart messagingKafka, MQTT
pd restart timeseriesZeitreihen-Engine und UI
pd restart workflowTemporal, Kestra
pd restart cepCEP-Engine
pd restart data-gatewayData Gateway
pd restart admin-apiManagement-Konsolen-API (bis 2026-09-03 «monitor»)

Akzeptierte Namen sind nur die in services/order.txt aufgeführten — storage · analytics · messaging · timeseries · cep · workflow · data-gateway · admin-api. Alle anderen Namen enden mit unknown service. SQL-Query-Tools (Kyuubi, Hive) haben kein eigenes Skript, sondern sind in analytics enthalten.

Hinweis: Wenn eine Infrastrukturkomponente neu gestartet wurde, empfiehlt es sich, auch die davon abhängenden App-Container neu zu starten.

Führen Sie App-Neustartskripte nicht innerhalb des Data Lake Containers aus

restart-server.sh · restart-batch.sh · restart-warehouse.sh existieren zwar noch als Dateien, befinden sich jedoch in bin/ auf dem Host und sind nur gegenüber den jeweiligen App-Containern sinnvoll. Werden sie innerhalb des Data Lake Containers aufgerufen, schlägt dies mit «Modul nicht vorhanden» fehl, da die ausführbaren Dateien der Apps dort fehlen.

restart-opcua-server.sh und restart-aasx-server.sh existieren nicht mehr. OPC-UA und AAS laufen in ihren eigenen Containern (plantpulse-plugin-opcua bzw. plantpulse-plugin-aasx). Bitte starten Sie diese Container direkt neu.

docker restart plantpulse-plugin-opcua
docker restart plantpulse-plugin-aasx

Platform-Update​

Wenn eine neue Version veröffentlicht wird, führen Sie den Installations-Oneliner auf demselben Server erneut aus. Die neuen Betriebsskripte, Compose-Dateien und Images werden installiert, während die Daten in den Volumes erhalten bleiben.

sudo -i
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash

./update.sh ist kein offizielles Upgrade-Verfahren — es tauscht nur Images aus und erkennt keine in der neuen Version hinzugekommenen Services. Erforderliche Schritte und Validierungsmethoden finden Sie unter Upgrade.

Log-Management​

Logs ansehen — logs.sh​

cd /opt/kopens/plantpulse-platform-docker/bin

./logs.sh # 전체 컨테이너를 한 화면에 (서비스 이름 접두, 시간순)
./logs.sh plantpulse-server-web # 그 컨테이너의 로그
./logs.sh cassandra # 데이터레이크 안 컴포넌트 로그 파일
./logs.sh --list # 볼 수 있는 대상 전체 목록
./logs.sh -n 500 cep # 500줄만
./logs.sh -f plantpulse-server-web # 계속 따라가기 (Ctrl-C 로 종료)
Standardmäßig erfolgt eine einmalige Ausgabe

logs.sh gibt die letzten N Zeilen aus (Standard 200) und beendet sich. Um den Logs kontinuierlich zu folgen, fügen Sie -f hinzu. --no-follow wird aus Kompatibilitätsgründen akzeptiert, ist jedoch redundant, da dies bereits das Standardverhalten ist.

Wenn der betroffene Container unbekannt ist: ohne Argument ausführen

Bei einem Problem ist oft nicht sofort ersichtlich, welcher Container die Ursache ist. Durch Ausführung ohne Argument werden die Logs aller acht Container chronologisch gemischt ausgegeben, sodass die Ursache nicht übersehen wird.

--list liest die Serviceliste aus Compose und die Log-Verzeichnisse der Komponenten im Data Lake Container direkt aus. Es handelt sich nicht um eine manuell gepflegte Liste, sondern um die tatsächliche Liste zum jeweiligen Zeitpunkt.

Interne Log-Verzeichnisse der Container​

Log-Pfade der Komponenten innerhalb des Data Lake Containers (Prüfung nach Zugriff via ./shell.sh).

ModulLog-Pfad
Valkeyplantpulse-storage/cache/valkey/logs/system.log
PostgreSQLplantpulse-storage/db/postgres/logs/system.log
Aster TSDBplantpulse-storage/db/cassandra/logs/system.log
RustFSplantpulse-storage/object/rustfs/logs/system.log
Gravitinoplantpulse-analytics/gravitino/logs/system.log
Hiveplantpulse-analytics/hive/logs/system.log
Sparkplantpulse-analytics/spark/logs/system.log
Kyuubiplantpulse-analytics/kyuubi/logs/system.log
Zeitreihen-Engineplantpulse-timeseries/engine/logs/system.log
Kafkaplantpulse-messaging/kafka/logs/server.log
MQTTplantpulse-messaging/mqtt/logs/hivemq.log
Temporalplantpulse-workflow/temporal/logs/system.log
Kestraplantpulse-workflow/kestra/logs/system.log
CEPplantpulse-cep/logs/system.log
Data Gatewayplantpulse-data-gateway/logs/system.log
Management-Konsolen-APIplantpulse-datalake-admin-api/logs/system.log

Die Pfadbasis ist /opt/kopens/plantpulse-platform/. Da die Logs der sechs Apps in ihren jeweiligen Containern liegen, ist eine Ansicht über ./logs.sh <컨테이너> schneller.

Logs auf den Host kopieren​

cd /opt/kopens/plantpulse-platform-docker/bin
./tools/copy-log-to-local.sh

Fehlerdiagnose​

cd /opt/kopens/plantpulse-platform-docker/bin
./doctor.sh

Erstellt ein Diagnose-Tarball (/tmp/pp-doctor-<호스트>-<타임스탬프>.tar.zst). Dieser enthält Status, Health-Probe-Ausgaben, Logs, Konfigurationen und Host-Umgebungsinformationen aller Container. Passwörter und Schlüssel werden maskiert. Das System wird dabei nicht verändert.

Senden Sie den erstellten Tarball an das KOPENS-Supportteam für eine schnelle Analyse.

Worker-Management (Cluster-Umgebung)​

Wenn bei einem Betrieb mit einem Master-Knoten eine Erweiterung des Durchsatzes erforderlich ist, werden Worker-Container hinzugefügt. Die Referenzliste der Worker ist compose/workers.roster (ein Eintrag pro Zeile in <id> <ip>), woraus die Overlay-Compose-Datei generiert wird.

cd /opt/kopens/plantpulse-platform-docker

# 추가 — roster 등록 → 오버레이 재생성 → 볼륨 → pull → up → 링 조인 확인
bin/worker-add.sh # 빈 id·주소 자동 선택
bin/worker-add.sh 3 # id 지정
bin/worker-add.sh 3 10.99.0.103 # id·주소 지정

# 진입
docker exec -ti plantpulse-worker-3 /bin/bash

# 제거 — 반드시 이 순서
bin/worker-decommission.sh 3 # 데이터 이관 + 링 이탈 확인 + 복제 슬롯 정리
bin/worker-remove.sh # 그 다음에 컨테이너 제거
Das Entfernen eines aktiven Workers mit docker rm ist kein Löschen, sondern «Verwaisen»

Aster TSDB hält den Token-Bereich und die Host-ID des Knotens weiterhin (bei RF=3 bleibt das QUORUM bestehen, sodass kein Alarm ausgelöst wird). Der Master hält zudem den physischen Replikationsslot von PostgreSQL des Workers, wodurch WAL-Dateien bis zur Erschöpfung des Disksplatzes fixiert werden. Führen Sie unbedingt zuerst worker-decommission.sh aus — worker-remove.sh wird abgelehnt, solange der Container läuft.

Bei Verwendung des Skripts wird RF automatisch gesenkt

worker-decommission.sh ruft intern zuerst pd node rf <남는 수> auf. Nur bei manueller Eingabe von pd node remove muss die Reihenfolge selbst beachtet werden → pd node rf.

:::

Gelöschte Worker-Skripte

worker-run.sh · worker-stop.sh · worker-update.sh · worker-bash.sh wurden am 31.08.2026 entfernt. Diese basierten auf manuell verwalteten Worker-Listen und wurden durch die Roster-Methode ersetzt. Ersatzfunktionen sind worker-add.sh (inkl. pull), Compose-Verben, Compose pull+up -d sowie docker exec.

Weitere Details finden Sie auf der Seite Cluster-Installation.

Erstzugriff nach Installation​

PunktWert
Web-Konsole URLhttps://[서버IP] (80/443)
Management-UI URLhttps://[서버IP] (gleiche Adresse wie Web-Konsole)
Monitor-UI URLhttps://[서버IP]:4950
Standard-Administrator IDadmin
Standard-Passwortadmin123!

Sicherheitshinweis: Es wird empfohlen, das Standardpasswort nach dem ersten Login aus Sicherheitsgründen zu ändern. → Initialpasswort

Knoten-Management-Skripte (innerhalb des Data Lake Containers)​

Die Verwaltung von Aster TSDB und Datenbanken erfolgt über die pd CLI (/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd) im plantpulse-datalake Container. Bitte treten Sie zuerst über ./shell.sh bei.

Aster TSDB Verwaltung​

SkriptBeschreibungAnwendungsfall
pd node statusClusterstatus prüfenRegelmäßige Inspektion, Fehleranalyse
pd node infoKnotendetailsÜberprüfung der Knotenkonfiguration
pd node compactManuelle Compaction ausführenFreisetzung von Diskplatz
pd node compactionstatsStatus der Compaction prüfenLeistungsüberwachung
pd node flushMemtable FlushArbeitsspeicherbereinigung
pd node drainKnoten-Drain (Sichere Beendigung)Vor dem Herunterfahren eines Knotens
pd node repairKnotendaten-Wiederherstellung/SynchronisationBei Dateninkonsistenz
pd node repair-tableWiederherstellung spezifischer TabellenTabellenspezifische Recovery
pd node cleanupKnotenbereinigung (Löschen unnötiger Daten)Nach Knotenänderungen
pd node removeKnoten aus Cluster entfernenBei Knotenauflösung — zuerst RF mit pd node rf senken
pd node rf [--check] [노드수]Anpassung RF aller Keyspaces an den RingBei Hinzufügen oder Entfernen von Knoten
pd node addKnoten zum Cluster hinzufügenBei Erweiterung
pd node upgradeKnoten-UpgradeBei Versionsaktualisierungen
pd node tpstatsThreadpool-StatistikLeistungsanalyse
pd node proxyhistogramsProxy-HistogrammLatenzanalyse
pd node table-histogramsTabellen-HistogrammTabellenleistungsanalyse
pd node table-statsTabellenstatistikÜberprüfung von Datengröße/Anzahl
pd node sstable-sizeSSTable-GrößenprüfungÜberprüfung der Diskbelegung
pd node cache-clearCache-InitialisierungBei Cache-Problemen
pd node topicKafka-Topic-ManagementMessaging-Inspektion
pd node diskDiskbelegung prüfenKapazitätsprüfung
pd node errorsError-Log PrüfungFehlerdiagnose
pd node train-zstdZStandard-KompressionslernenOptimierung der Kompression
pd node init-cmsCMS-InitialisierungErstkonfiguration

Datenbankzugriff​

SkriptBeschreibung
pd node psqlPostgreSQL Shell Zugriff (Metadaten-DB)
pd node cqlAster TSDB CQL Shell Zugriff (Zeitreihen-DB)

Zusammenfassung häufiger Befehle​

cd /opt/kopens/plantpulse-platform-docker/bin

./preflight.sh # 설치 전 비파괴 사전 점검
./install.sh # 최초 설치 (OS+Docker+방화벽+스택)
./up.sh # 기동 — 준비될 때까지 대기 (0 = 준비 완료)
./down.sh # 정지 (상태 보존)
./restart.sh # graceful 재시작 (drain + 준비 대기)
./status.sh # 서비스 / health / 볼륨 요약 (0=정상 / 2=비정상)
./logs.sh [서비스] # 로그 보기 — 1회 출력. -f 로 따라가기 (인자 없으면 전체, 목록은 --list)
./shell.sh [서비스] # 컨테이너 bash 진입
./ops-check.sh # 운영 health + critical log 점검
./remove.sh # 컨테이너 제거 (볼륨은 보존)
./backup.sh # 볼륨 백업 (기본 pp-data · pp-security)
./doctor.sh # 장애 진단 tarball 생성
./passwd.sh --list # 바꿀 수 있는 비밀번호 목록
./stack-verify-boot.sh # 스택 전체 준비 판정

Alle Verben unterstützen --help.