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.
Die Namen auf der linken Seite existieren nicht mehr. Bitte verwenden Sie die gängigen Verben auf der rechten Seite.
| Alter Name | Aktuelle Bezeichnung |
|---|---|
start.sh | up.sh |
platform-stop.sh | down.sh |
platform-update.sh | update.sh |
platform-remove.sh | remove.sh |
platform-bash.sh | shell.sh |
platform-verify-boot.sh | stack-verify-boot.sh |
worker-run.sh · worker-stop.sh · worker-update.sh · worker-bash.sh | Siehe 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
| Variable | Beschreibung | Standardwert |
|---|---|---|
PP_LANG | Platform Locale (ko / en) | en |
PP_TZ | Platform Zeitzone | Asia/Seoul |
DOCKER_PP_CPUS | Anzahl der vCPUs für Container | Ergebnis von nproc |
DOCKER_PP_MEMORY | Arbeitsspeicher-Limit | 90 % des Host-RAM |
DOCKER_DATALAKE_MEMORY | Data Lake Arbeitsspeicher-Limit | 96G (Minimum, darf 90 % des Host-RAM nicht überschreiten — Host unter 107G ist unterspekt) |
DOCKER_PP_DATA_DISK_NAME | Name der Datendisk | Automatische Rückverfolgung (bei Fehler sda) |
DOCKER_PP_EXTERNAL_IP | Externe Advertise-IP in NAT-Umgebungen | Leerwert |
Die vollständige Liste der Umgebungsvariablen finden Sie auf der Seite Referenz der Umgebungsvariablen.
Übernahme von Änderungen: Nach der Änderung von
env.shmuss ein Neustart über./restart.sherfolgen, damit die neuen Einstellungen wirksam werden.
env.sh geändert werdenAuf 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».
| Umgebungsvariable | Standardwert | Bedeutung |
|---|---|---|
PP_READY_TIMEOUT | 900 | Max. Wartezeit für Bereitschaft (Sekunden) |
PP_READY_INTERVAL | 15 | Prü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:
| Reihenfolge | Kategorie | Komponente |
|---|---|---|
| 1 | Storage | Valkey(Redis), PostgreSQL, Aster TSDB, RustFS |
| 2 | Analyse | Spark, Hadoop, Hive, Kyuubi, Gravitino |
| 3 | Zeitreihe | Zeitreihen-Engine, Zeitreihen-UI |
| 4 | Messaging | Kafka, MQTT |
| 5 | Workflow | Temporal, Kestra |
| 6 | Verarbeitung | CEP, Data Gateway, SQL, Monitor |
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 killoder 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.
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
| Container | Inhalt |
|---|---|
plantpulse-server-web | Web-Konsole |
plantpulse-batch-web | Batch |
plantpulse-warehouse-web | Data Warehouse |
plantpulse-plugin-opcua | OPC-UA Plugin |
plantpulse-plugin-aasx | AASX Plugin |
plantpulse-ha | Redundanz-Recovery-Daemon |
docker compose restart beachtet die Abhängigkeitsreihenfolge nichtWenn 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
| Skript | Ziel |
|---|---|
pd restart storage | Aster TSDB, PostgreSQL, Valkey, RustFS |
pd restart analytics | Spark, Hive, Kyuubi, Gravitino |
pd restart messaging | Kafka, MQTT |
pd restart timeseries | Zeitreihen-Engine und UI |
pd restart workflow | Temporal, Kestra |
pd restart cep | CEP-Engine |
pd restart data-gateway | Data Gateway |
pd restart admin-api | Management-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.
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 로 종료)
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.
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).
| Modul | Log-Pfad |
|---|---|
| Valkey | plantpulse-storage/cache/valkey/logs/system.log |
| PostgreSQL | plantpulse-storage/db/postgres/logs/system.log |
| Aster TSDB | plantpulse-storage/db/cassandra/logs/system.log |
| RustFS | plantpulse-storage/object/rustfs/logs/system.log |
| Gravitino | plantpulse-analytics/gravitino/logs/system.log |
| Hive | plantpulse-analytics/hive/logs/system.log |
| Spark | plantpulse-analytics/spark/logs/system.log |
| Kyuubi | plantpulse-analytics/kyuubi/logs/system.log |
| Zeitreihen-Engine | plantpulse-timeseries/engine/logs/system.log |
| Kafka | plantpulse-messaging/kafka/logs/server.log |
| MQTT | plantpulse-messaging/mqtt/logs/hivemq.log |
| Temporal | plantpulse-workflow/temporal/logs/system.log |
| Kestra | plantpulse-workflow/kestra/logs/system.log |
| CEP | plantpulse-cep/logs/system.log |
| Data Gateway | plantpulse-data-gateway/logs/system.log |
| Management-Konsolen-API | plantpulse-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 # 그 다음에 컨테이너 제거
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.
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.
:::
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
| Punkt | Wert |
|---|---|
| Web-Konsole URL | https://[서버IP] (80/443) |
| Management-UI URL | https://[서버IP] (gleiche Adresse wie Web-Konsole) |
| Monitor-UI URL | https://[서버IP]:4950 |
| Standard-Administrator ID | admin |
| Standard-Passwort | admin123! |
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
| Skript | Beschreibung | Anwendungsfall |
|---|---|---|
pd node status | Clusterstatus prüfen | Regelmäßige Inspektion, Fehleranalyse |
pd node info | Knotendetails | Überprüfung der Knotenkonfiguration |
pd node compact | Manuelle Compaction ausführen | Freisetzung von Diskplatz |
pd node compactionstats | Status der Compaction prüfen | Leistungsüberwachung |
pd node flush | Memtable Flush | Arbeitsspeicherbereinigung |
pd node drain | Knoten-Drain (Sichere Beendigung) | Vor dem Herunterfahren eines Knotens |
pd node repair | Knotendaten-Wiederherstellung/Synchronisation | Bei Dateninkonsistenz |
pd node repair-table | Wiederherstellung spezifischer Tabellen | Tabellenspezifische Recovery |
pd node cleanup | Knotenbereinigung (Löschen unnötiger Daten) | Nach Knotenänderungen |
pd node remove | Knoten aus Cluster entfernen | Bei Knotenauflösung — zuerst RF mit pd node rf senken |
pd node rf [--check] [노드수] | Anpassung RF aller Keyspaces an den Ring | Bei Hinzufügen oder Entfernen von Knoten |
pd node add | Knoten zum Cluster hinzufügen | Bei Erweiterung |
pd node upgrade | Knoten-Upgrade | Bei Versionsaktualisierungen |
pd node tpstats | Threadpool-Statistik | Leistungsanalyse |
pd node proxyhistograms | Proxy-Histogramm | Latenzanalyse |
pd node table-histograms | Tabellen-Histogramm | Tabellenleistungsanalyse |
pd node table-stats | Tabellenstatistik | Überprüfung von Datengröße/Anzahl |
pd node sstable-size | SSTable-Größenprüfung | Überprüfung der Diskbelegung |
pd node cache-clear | Cache-Initialisierung | Bei Cache-Problemen |
pd node topic | Kafka-Topic-Management | Messaging-Inspektion |
pd node disk | Diskbelegung prüfen | Kapazitätsprüfung |
pd node errors | Error-Log Prüfung | Fehlerdiagnose |
pd node train-zstd | ZStandard-Kompressionslernen | Optimierung der Kompression |
pd node init-cms | CMS-Initialisierung | Erstkonfiguration |
Datenbankzugriff
| Skript | Beschreibung |
|---|---|
pd node psql | PostgreSQL Shell Zugriff (Metadaten-DB) |
pd node cql | Aster 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.