Servicebetrieb

Der AI-Stack ist docker compose eins. Die Betriebsbefehle liegen allesamt im bin/ der Installationsbasis und rufen compose stellvertretend auf.

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

Was man häufig braucht

Was Sie vorhaben	Befehl	Hinweis
Hochfahren	./up.sh	Exit-Code 0 bedeutet „bereit"
Herunterfahren	./down.sh
Neu starten	./restart.sh	0 heißt: nach Neustart bereit
Aktuellen Status ansehen	./status.sh	Zusammenfassung des compose-Stack-Status
Genauer untersuchen	./health.sh	Detaillierter Bericht je Service
Logs verfolgen	./logs.sh
Images neu ziehen und ausrollen	./update.sh	Zieht und startet anschließend neu

Vertrauen Sie dem Exit-Code

up.sh · restart.sh melden mit 0 nicht, dass der Container gestartet ist, sondern dass er nutzbar geworden ist. In Skripten brauchen Sie dafür keine eigene Warteschleife.

Wenn Sie herausfinden wollen, was falsch läuft

./doctor.sh

🔴 doctor.sh ändert nichts. Es liest nur und bewertet. Deshalb können Sie es während einer Störung beruhigt zuerst laufen lassen — die Entscheidung zur Behebung trifft der Mensch.

Von den Zeilen in der env-Datei werden diejenigen, die den Start blockieren, als «bad» markiert, und alte Namen bzw. doppelte Zeilen, die auch unverändert nichts bewirken (Warnungen der Prüfung vor dem Start — alias · oldname · media-same), werden gesondert als «old or redundant lines» angezeigt. Letztere sind keine Störungsursache. Den Bereinigungsbefehl gibt bin/lint-env.sh aus → Umgebungsvariablen konfigurieren

Wenn Sie nur einen einzelnen Container behandeln

Wenn Sie nicht den ganzen Stack anstoßen müssen, geben Sie dem Skript den Servicenamen mit.

cd /opt/kopens/plantpulse-ai-docker/bin
./status.sh                            # 무엇이 떠 있나
./restart.sh plantpulse-rag-api        # 0 이면 재시작 후 준비됨
./logs.sh plantpulse-lightrag

Rufen Sie docker compose nicht blind von Hand auf

Die compose-Datei liegt unter compose/, die Konfiguration unter /etc/kopens/plantpulse-ai.env. Wenn Sie docker compose … einfach im Installationsverzeichnis ausführen, findet es die Dateien nicht oder läuft, selbst wenn es sie findet, mit einer anderen Konfiguration — bei up kann sogar das bereitgestellte Image zurückgesetzt werden. Die Skripte rufen compose- und Konfigurationsdatei immer explizit auf.

Containernamen und ihre jeweilige Rolle finden Sie in der Tabelle unter Installationsübersicht.

Wenn Sie in den Container hinein müssen:

bin/shell.sh plantpulse-rag-api

Logs

./logs.sh                         # 스택 전체를 따라 본다
./logs.sh plantpulse-llm          # 서비스 하나

Container-Logs werden von Docker rotiert (in compose konfiguriert). Auf dem Host sammeln sich keine Dateien an, die Sie separat löschen müssten.

Container laufen als Non-Root

Ab 2026.10 geben alle Services in compose explizit den Ausführungsbenutzer (user:) an, und als root läuft nur noch plantpulse-dcgm, das GPU-Kennzahlen liest (zum Lesen der GPU-Profiling-Felder sind root und SYS_ADMIN nötig).

Was	Ausführungsbenutzer (uid:gid)
Unsere Images — Eingangsproxy · Copilot · Admin-Konsole · RAG · Zeitreihen-Insights · Dokumentenverständnis · Vision · Digital Thread usw.	10001:0
vLLM (plantpulse-llm · -emb · -rerank, bei Installationen mit aktiviertem Video/Audio plantpulse-asr) · plantpulse-asr-audio	10001:0
Beide Neo4j	7474:7474
Qdrant	1000:1000
Phoenix	65532:65532
Docling	1001:0
plantpulse-dcgm	root (Ausnahme)

Da der Eingangsproxy (plantpulse-proxy) ebenfalls Non-Root geworden ist, haben sich die Ports innerhalb des Containers auf 8080 · 9443 · 8443 geändert. Die vom Host aus sichtbaren Ports 80 · 443 · 5960 bleiben unverändert → Service-Port-Map

Schreibvolumes, die in älteren Installationen als root angelegt wurden, können von Non-Root-Prozessen nicht beschrieben werden. Docker ändert den Eigentümer bestehender Volumes nicht, und ein Schreibfehlschlag ist meist unauffällig (zeigt sich etwa nur auf der Konsole statt in der Logdatei) oder führt zum sofortigen Absturz (Qdrant stirbt direkt bei root-eigenem Storage). Deshalb rufen die Start-Skripte, über die up.sh · restart.sh · update.sh laufen, bevor compose hochgefahren wird, bin/volumes-nonroot.sh auf.

Service	Angepasste Stelle	Angepasster Eigentümer
plantpulse-copilot-web · plantpulse-timeseries-insight-api	App-Logs	10001:0
plantpulse-timeseries-insight-server	App-Logs · installationsspezifische Fine-Tuning-Gewichte	10001:0
plantpulse-lightrag	Index-Storage · Eingangs-Rohdaten	10001:0
vLLM-Set (Transkription plantpulse-asr nur bei aktivierten Installationen)	Compile-Cache	10001:0
plantpulse-asr-audio (nur bei aktivierten Installationen)	Audio-Bibliotheks-Volume (pi-asr-audio)	10001:0
plantpulse-neo4j · plantpulse-digital-thread-neo4j	Daten	7474:7474
plantpulse-qdrant	Vektorspeicher	1000:1000
plantpulse-phoenix	Daten	65532:65532
plantpulse-proxy	Zertifikate (pp-proxy-certs)	10001:0
plantpulse-registry (nur bei aktiviertem Profil)	Image-Storage	10001:0

Die Anpassung erfolgt nur, wenn mindestens eine Datei nicht dem Benutzer dieses Services gehört, sodass nur beim ersten Mal tatsächlich gearbeitet und danach nur noch geprüft wird. Schlägt die Anpassung fehl, wird der Start gestoppt (da ein Start mit falschem Eigentum zu stillen Schreibfehlschlägen führen würde).

Beim manuellen Aufruf von docker compose up wird dieser Schritt übersprungen

Auf Hosts, die mit 2026.09 oder früher aufgesetzt wurden, muss der erste Start unbedingt über bin/up.sh (oder update.sh · restart.sh) erfolgen.

Was standardmäßig nicht hochfährt — compose-Profile

Profil	Container	Verwendung
registry	plantpulse-registry · plantpulse-registry-ui	Lokaler Image-Storage für Hub-Knoten im Air-Gap-Netzwerk
media	plantpulse-asr · plantpulse-asr-audio	Video-/Audio-Transkription (inklusive sprachbasierter Abfrage). Wird über eine Zeile PI_MEDIA_ENABLED=true in der Host-env aktiviert — die Betriebsskripte (up.sh · restart.sh · status.sh · logs.sh …) lesen diesen Wert und hängen das Profil entsprechend an → Video-/Audio-Erfassung

Geben Sie bei media nicht direkt den Profilnamen an, sondern aktivieren Sie über PI_MEDIA_ENABLED — dieser Schalter stimmt auch die Werte von rag-api · Dokumentenverständnis sowie das Laden der Transkriptionsmodelle mit ab. Tragen Sie COMPOSE_PROFILES in der Host-env ein, startet die Prüfung vor dem Start mit unknown.

plantpulse-asr-audio ist ein einmaliger Service, der die Audio-Bibliothek auf das Volume verschiebt und sich dann beendet. Steht in status.sh «Exited (0)», ist das normal und gilt als erfolgreich. Endet er mit einem Code ungleich 0, startet auch plantpulse-asr nicht.

Backup und Passwörter

Was Sie vorhaben	Befehl	Dokumentation
Backup anlegen	./backup.sh (was dabei erfasst wird: ./backup.sh --list — Logs · Caches und das Audio-Bibliotheks-Volume der Transkription sind ausgenommen)	Datenbankverwaltung
Passwörter · Schlüssel ändern	./passwd.sh	Passwörter und API-Schlüssel ändern
Installation entfernen	./remove.sh	Nicht rückgängig zu machen

Datenbanken nutzen die der Plattform

PostgreSQL · Aster TSDB · Redis (Valkey) · RustFS werden vom AI-Stack nicht selbst gestartet. Sie teilen sich die Plattform-Installation (Host von PP_DATALAKE_ADMIN_URL). Fallen diese vier aus, bleibt auch die AI zugleich stehen — klären Sie im Störungsfall zunächst anhand der Service-Port-Map, auf welcher Seite das Problem liegt.

Ab 2026.10 beziehen die Container Konto und Passwort dafür beim Start von der Plattform. Ist die Plattform nicht erreichbar, bleibt der empfangende Container mit FATAL stehen; wurde das Passwort auf der Plattform geändert, genügt ein Neustart des betreffenden Containers → Umgebungsvariablen konfigurieren

Verwandte Dokumente

• AI-Admin-Konsole — Status auf einen Blick
• Logs und Monitoring
• Service-Port-Map