Systemstart und -stopp

Überblick

PlantPulse läuft als Docker-Compose-Stack. Start / Stopp / Neustart werden an einer zentralen Stelle über die gemeinsamen Verben in /opt/kopens/plantpulse-platform-docker/bin/ verwaltet; die Reihenfolge der Abhängigkeiten zwischen den Containern wird automatisch durch depends_on von compose angewendet, sodass der Betreiber sich nicht um die Reihenfolge kümmern muss.

Die Bedeutung von Exit-Code 0 ist anders

up.sh und restart.sh bedeuten mit 0 nicht «Befehl erfolgreich», sondern «jetzt verwendbar». Bei der Zertifikatsrotation am 14.08.2026 gab es einen Vorfall, bei dem man aufgrund von «gestartet» zum nächsten Schritt überging und dann bei einem noch nicht bereiten Broker stehen blieb. Deshalb wurden die beiden Verben so geändert, dass sie warten, bis alles bereit ist.

status.sh ist anders — 0 = normal / 2 = anormal.

Empfohlene Betriebsbefehle (Zusammenfassung)

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

./up.sh                # 기동 (멱등) — 준비될 때까지 대기. 0 = 준비 완료
./down.sh              # 안전 종료 (의존 순서의 역순, 상태 보존)
./restart.sh           # graceful drain → 정지 → 기동 → 준비 대기
./status.sh            # 서비스 / health / 볼륨 요약. 0 = 정상 / 2 = 비정상
./ops-check.sh         # 헬스 + 최근 critical log
./logs.sh [서비스]     # 로그 보기 — 1회 출력, -f 로 따라가기 (인자 없으면 전체)
./stack-verify-boot.sh # 스택 전체 준비 판정
./doctor.sh            # 진단 tarball (시스템 변경 없음)

Alle Verben unterstützen --help. Die alten Namen (stack-run.sh · stack-stop.sh · stack-bash.sh · stack-update.sh · stack-remove.sh) funktionieren weiterhin.

Umgebungsvariable	Standardwert	Bedeutung
PP_READY_TIMEOUT	900	Obergrenze für Wartezeit auf Bereitschaft (Sekunden)
PP_READY_INTERVAL	15	Prüfintervall (Sekunden)
PP_WAIT=0	—	Kein Warten. Die 0 bedeutet in diesem Fall nicht «bereit»

Startreihenfolge (automatisch)

Zwischen den Containern

Die depends_on von compose sorgt mit der Bedingung service_healthy für die Reihenfolge — gewartet wird nicht auf «Prozess läuft», sondern auf «verwendbar». Diese Reihenfolge ist nicht willkürlich, sondern spiegelt die Startreihenfolge des Anwendungsorchestrators wider.

Die letzten vier (warehouse · opcua · aasx · ha) haben keine Reihenfolge untereinander.

Innerhalb des Data-Lake-Containers

Die Infrastrukturkomponenten starten innerhalb eines einzelnen Containers plantpulse-datalake erneut in einer bestimmten Reihenfolge.

Reihenfolge	Bereich	Hauptkomponenten	Typische Ports
1	Speicherung	Aster TSDB, PostgreSQL, Valkey, RustFS	9042 / 5432 / 6379 / 9000
2	Analyse	Spark, Hive, Kyuubi, Gravitino	7077 / 9083 / 10000 / 19001
3	Zeitreihe	TSE Engine, UI	7800 / 3000
4	Messaging	Kafka, MQTT	9092 / 1883
5	Workflow	Temporal, Kestra	7233 / 8233 / 8380
6	Verarbeitung	CEP, Data Gateway, SQL, Monitor	7400 / 5500 / 4000 / 4950

Benötigte Zeit

Der Prozessstart selbst dauert 3–5 Minuten (JVM-Aufwärmphase), aber bei einer sauberen Installation dauert es wegen der Schema-Migration und Stabilisierung der Aster TSDB 15–18 Minuten, bis alle Komponenten stabil sind.

Gemessen (31.08.2026, 32 vCPU / 128 GiB): Data Lake 217 s, Webserver 316 s. Ein Neustart mit vorhandenen Daten ist deutlich schneller.

Stoppreihenfolge

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

Die Reihenfolge muss nicht manuell eingehalten werden. compose stoppt in umgekehrter Reihenfolge der Abhängigkeiten, sodass die datenschreibende Seite (Apps) zuerst stoppt und der Data Lake zuletzt. Für jeden Container ist eine großzügige Stoppfrist (stop_grace_period) hinterlegt — beim Data Lake 180 Sekunden — damit die Aster TSDB Zeit hat, den Memtable zu flushen.

Die Volumes (pp-data · pp-temp · pp-backup · pp-security · pp-proxy-certs) werden immer erhalten, unabhängig von Stopp oder Entfernung.

Verwenden Sie nicht docker kill oder einen erzwungenen Host-Stopp

Nicht geflushte Memtable-Daten der Aster TSDB können verloren gehen. Verwenden Sie unbedingt ./down.sh. Wenn der Container nicht mehr antwortet, folgen Sie dem Notfallverfahren.

Neustart

Kompletter Neustart

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

1. (Falls er läuft) Graceful-Drain-Anfrage an den Data Lake senden
2. Den gesamten Stack in umgekehrter Reihenfolge der Abhängigkeiten stoppen
3. In der Reihenfolge depends_on wieder starten
4. Auf Bereitschaft warten — bei Exit-Code 0 ist der Zustand verwendbar

Wird verwendet bei bin/env.sh-Änderungen, Änderung von Locale/Zeitzone, Behebung vorübergehender Probleme, regelmäßigem Neustart.

Nur eine App neu starten

Die sechs Apps laufen jeweils in einem eigenen Container. Wenn nur dieser Container neu gestartet wird, bleiben die anderen Apps und die Infrastruktur unverändert aktiv. Das ist einer der Gründe für die Aufteilung in Container.

cd /opt/kopens/plantpulse-platform-docker
docker compose -f compose/docker-compose.yml restart plantpulse-server-web

docker compose restart berücksichtigt die Abhängigkeitsreihenfolge nicht

Wenn mehrere Apps zusammen wiederhergestellt werden müssen, ist es sicherer, den gesamten Stack mit ./restart.sh neu zu starten.

Nur Infrastrukturkomponenten neu starten

./shell.sh                                                              # 데이터레이크 진입
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd restart storage
exit

Die Namen, die pd restart <서비스> akzeptiert, sind nur die acht in services/order.txt — storage · analytics · messaging · timeseries · cep · workflow · data-gateway · admin-api. Andere Namen enden mit unknown service. Weitere Details finden Sie im Startleitfaden.

Statusüberprüfung

Einzeilige Zusammenfassung

./status.sh            # 0 = 정상 / 2 = 비정상

status.sh betrachtet fünf Dinge als anormal.

Bewertung	Inhalt
Serviceliste kann nicht gelesen werden	Fehler bei der compose-Analyse oder kein Docker-Zugriff
Kein Container für von compose deklarierten Diensten	Nicht gestartet
Container ist nicht running	Alle neun laufen dauerhaft — keine Ausnahmen
Health des Dauerlauf-Containers ist unhealthy	starting / none gelten als Bewertung ausstehend
Health-API liefert nicht OK	Probe innerhalb des Data Lake

Volumes und conf werden nur gemeldet und nicht in den Exit-Code aufgenommen — je nach Installationskonfiguration ist es normal, dass einige fehlen.

Alle neun mit dem gleichen Maßstab betrachten

plantpulse-certs brennt Zertifikate einmal und bleibt dann aktiv, um den Ablauf zu überwachen. Alle neun können mit dem gleichen Maßstab (healthy) betrachtet werden.

Der Healthcheck ist im Image enthalten. Dass compose keinen Probe-Block enthält, ist beabsichtigt, und das Label pp.healthcheck: image macht das deutlich. Wenn der Probe-Pfad in einem anderen Repository definiert würde und man ihn in compose eintrüge, würde er beim Kunden brechen, sobald die Datei verschoben wird.

Container-Überprüfung

docker ps                       # 아홉 개가 모두 (healthy)
docker stats --no-stream        # 컨테이너별 CPU / 메모리

Healthcheck-API

# 호스트 / 외부에서 — 4950 이 publish 되어 있습니다
curl -kfsS https://<server-ip>:4950/api/health | jq

# 컨테이너 안에서 — 어떤 구성에서도 동작합니다
docker exec plantpulse-datalake curl -kfsS https://127.0.0.1:4950/api/health | jq

Die Werte "status" sind nur OK · WARN · FAIL, wobei OK/WARN der normale Bereich ist.

Auf 4949 ist dieselbe API verfügbar

Konsole und Health-API werden auf beiden Ports bereitgestellt — 4950 (HTTPS) und 4949 (Klartext-HTTP). Es sind dieselbe Konsole und dieselbe API, nur das Schema ist unterschiedlich. 4949 leitet nicht mehr auf 4950 um.

4949 ist Klartext — Login-Passwort und Session-Cookies fließen unverschlüsselt. In nicht vertrauenswürdigen Netzwerken verwenden Sie 4950. 4949 ist die Option für Umgebungen, in denen die Warnung zum selbstsignierten Zertifikat tatsächlich den Betreiber aufhalten soll.

Log-Überprüfung

./logs.sh                              # 여덟 컨테이너를 시간순으로 한 화면에
./logs.sh plantpulse-server-web -n 200 # 특정 컨테이너
./logs.sh cassandra                    # 데이터레이크 안 컴포넌트 로그 파일
./logs.sh --list                       # 볼 수 있는 대상 전체
./logs.sh -f plantpulse-proxy          # 계속 따라가기 (Ctrl-C 로 종료)

Standardmäßig werden die letzten N Zeilen (Standard: 200) ausgegeben und dann beendet. Zum Mitverfolgen hängen Sie -f an.

Automatische Startkonfiguration

Keine separate Konfiguration erforderlich. Die Container haben in compose eine Neustartrichtlinie, sodass sie beim Neustart des Hosts zusammen mit dem Docker-Daemon hochkommen. plantpulse-certs ist restart: unless-stopped — wenn jemand sie absichtlich gestoppt hat, bleiben sie auch nach einem Daemon-Neustart gestoppt. Beim Neustart werden keine neuen Zertifikate gebrannt.

Zu prüfen ist nur der automatische Start des Docker-Daemons.

systemctl is-enabled docker     # enabled 여야 합니다
sudo systemctl enable docker    # 아니라면

Der Proxy kann direkt nach einem Neustart kurz rot erscheinen

Ein Host-Neustart ist der einzige Pfad, bei dem die depends_on-Reihenfolge nicht angewendet wird — da alles gleichzeitig hochkommt, kann der Healthcheck des Proxys kurz fehlschlagen, bis der Webserver läuft (gemessen maximal 316 s). Das Wiederholungsbudget ist auf 360 s festgelegt, und docker startet Container nicht wegen unhealthy neu. Daher handelt es sich um einen vorübergehenden Zustand, der sich selbst erholt.

Notfallverfahren

Web-Konsole reagiert nicht

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

# 1. 어느 컨테이너가 문제인가
./status.sh

# 2. 프록시와 웹 서버 로그
./logs.sh plantpulse-proxy -n 100
./logs.sh plantpulse-server-web -n 200

# 3. 웹 서버만 재시작 (인프라는 유지)
cd /opt/kopens/plantpulse-platform-docker
docker compose -f compose/docker-compose.yml restart plantpulse-server-web

# 4. 회복되지 않으면 진단 번들
bin/doctor.sh

Wenn der Proxy grün ist, der Bildschirm aber 502 zeigt

Der Healthcheck des Proxys prüft nur sich selbst + Erreichbarkeit des Upstreams (den Gesundheitszustand des Backends bewertet der Healthcheck des Webservers selbst). Wenn der Proxy grün ist, der Bildschirm aber nicht angezeigt wird, prüfen Sie plantpulse-server-web.

OOM (Out Of Memory) tritt auf

# 1. 어느 컨테이너가 OOM 인가
docker inspect plantpulse-server-web --format '{{.State.OOMKilled}} {{.State.ExitCode}} {{.RestartCount}}'

# 2. 호스트 커널 로그
dmesg | grep -i "out of memory\|oom"

# 3. 컨테이너별 사용량
docker stats --no-stream

Für jeden Container gibt es separate Grenzwerte — der Data Lake hat DOCKER_DATALAKE_MEMORY (Standard 96G), Apps haben DOCKER_SERVER_MEMORY · DOCKER_BATCH_MEMORY usw. (Umgebungsvariablen). Nach Anpassung der Werte mit ./restart.sh anwenden.

Ein OOM einer App bringt nicht das Ganze zum Stillstand

Die separate mem_limit pro App ist der erste Zweck der Container-Trennung. Wenn eine App an ihre Grenze stößt, bleiben Infrastruktur und andere Apps aktiv.

DB-Verbindungsfehler

Die Datenbanken befinden sich alle in plantpulse-datalake.

cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh                                                            # 데이터레이크 진입

/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node psql       # PostgreSQL
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node cql        # Cassandra
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node status     # Cassandra 링 상태

Um nur die Infrastruktur wiederherzustellen, verwenden Sie im Container pd restart storage; wenn das nicht funktioniert, auf dem Host ./restart.sh.

Bei Verdacht auf Datenbeschädigung

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

./down.sh                                  # 즉시 정지 (추가 손상 방지)
ls -lh /data1/pp-backup/docker-volume/     # 최신 백업 확인
./doctor.sh                                # 진단 번들 (데이터를 임의로 수정하지 마세요)

Senden Sie das erzeugte Tarball an webmaster@kopens.com.

Betriebs-Checkliste

Tägliche Inspektion

Prüfpunkt	Befehl / Prüfmethode	Normaler Standard
Gesamtdienststatus	./status.sh	Exit-Code 0
Betriebs-Health	./ops-check.sh	Keine kritischen Logs
Health-API	curl -kfsS https://<server-ip>:4950/api/health	status ist OK oder WARN
Container	docker ps	Alle neun sind (healthy)
Festplattenauslastung	df -h /data1	Auslastung unter 80 %
Container-Ressourcen	docker stats --no-stream	Ausreichend Puffer im Vergleich zu Grenzwerten
Aster-TSDB-Status	Im Container pd node status	Alle Knoten UN (Up/Normal)

Wöchentliche Inspektion

Prüfpunkt	Befehl / Prüfmethode	Normaler Standard
Aster-TSDB-Compaction	Im Container pd node compactionstats	Keine übermäßigen ausstehenden Aufgaben
Aster-TSDB-Tabellen	Im Container pd node table-stats	Keine anormalen Erhöhungen
Kafka-Topics / Lag	Im Container pd node topic	Anzahl verzögerter Nachrichten im normalen Bereich
Backup-Prüfung	ls -lh /data1/pp-backup/docker-volume/	Normales Backup vorhanden
Docker-Auslastung	docker system df	Keine Anhäufung ungenutzter Images
Log-Größe	du -sh /opt/kopens/plantpulse-platform-docker/logs	Keine anormalen Erhöhungen
Sicherheitsupdates	Überprüfung der OS-Paketupdates	Keine bekannten Schwachstellen

---