Fehlerbehebung

Hier finden Sie Ursachen und Maßnahmen nach Symptom. Die meisten Probleme lassen sich mit den folgenden 3 Befehlen eingrenzen.

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh                  # ① 컨테이너 상태 + 헬스 + 세션 수
curl -s localhost:5170/health       # ② 서버가 살아 있는가
docker logs --tail 100 plantpulse-studio-server   # ③ 무엇이 잘못됐는가

---

Logs anzeigen

Ziel	Befehl
Studio-Server (am wichtigsten)	docker logs -f --tail 200 plantpulse-studio-server
Web (nginx)	docker logs --tail 100 plantpulse-studio-web
Builder-Seitenwagen	docker logs --tail 100 plantpulse-studio-agent-server
Skript folgen	bash bin/logs.sh (Basisserver) · bash bin/logs.sh studio-web
Automatische Sicherung	tail -50 dist/backup.log
App-Sitzungscontainer	docker ps --filter label=plantpulse-studio=1 zur Namensprüfung, dann docker logs <name>

Nach Zeitraum eingrenzen

docker logs --since 30m plantpulse-studio-server
docker logs --since "2026-07-28T09:00:00" plantpulse-studio-server

Keine Schlüssel in Logs

API-Schlüssel und Tokens werden nicht in Logs aufgezeichnet (auch im Audit-Log nur Fingerabdrücke statt Werte). Wenn Sie Logs an das Support-Team senden, reichen Standortinformationen wie Website- und Anlagenname aus.

---

Mit einem Blick prüfen, ob diese Installation «funktionsfähig» ist

GET /api/v1/diagnostics     (관리자 전용)

Dies ist der erste Anlaufpunkt bei Fragen wie «Der Bildschirm erscheint, aber PDF wird nicht erzeugt» oder «Die App öffnet sich nicht».

{"ok": true,
 "os":        {"ok": true, "detail": "Debian GNU/Linux 13"},
 "chromium":  {"ok": true, "detail": "Chromium 153…"},
 "pdf":       {"ok": true, "detail": "26568 bytes"},
 "fontsCjk":  {"ok": true, "detail": "15 faces"},
 "docker":    {"ok": true, "detail": "server 29.8.1"}}

Für jeden Punkt gibt es {ok, detail}, und ok oben ist nur dann wahr, wenn alles wahr ist. pdf ist keine Beschreibung, sondern das Ergebnis eines tatsächlichen Backens einer PDF auf Koreanisch, und docker prüft, ob ein Sitzungscontainer gestartet werden kann.

Andere Frage als /health – nicht vom Bildschirm aus pollen

/health fragt «lebt es?» günstig und häufig, die Diagnose fragt «kann es?» teuer und selten (bäckt tatsächlich eine PDF). Wenn Sie es regelmäßig vom Dashboard aus aufrufen, wird das selbst zur Last.

Symptom → Ursache Schnellvergleich

Symptom	Häufige Ursache	Prüfung	Maßnahme
Webseite öffnet sich gar nicht	Stack heruntergefahren oder Port 80 belegt	bash bin/status.sh docker logs plantpulse-studio-web	bash bin/up.sh · Andere Dienste, die Port 80 nutzen, beenden
Bildschirm erscheint, aber Login schlägt fehl	Bootstrap-Konto nicht eingerichtet oder Plattform nicht erreichbar	grep STUDIO_LOCAL_USERS .env curl -s localhost:5170/health	.env Konto angeben, dann bash bin/restart.sh
Login plötzlich blockiert (nach kurzer Zeit erneut versuchen)	Login-Rate-Limit (10 pro Minute pro IP)	docker logs --tail 50 plantpulse-studio-server	1 Minute warten und erneut versuchen
Health bleibt DOWN, Log zeigt DB-Authentifizierungsfehler	DATABASE_URL Passwort geändert, aber Rolle in DB nicht angepasst	docker logs plantpulse-studio-server Direkte Verbindung von externer PG mit psql	Ursprüngliches Passwort wiederherstellen oder zuerst Passwort des Kontos in PostgreSQL ändern
Projekt öffnen schlägt fehl (500)	Sitzungs-Laufzeit-Image fehlt	docker image inspect plantpulse-studio-runtime:latest	bash bin/up.sh erneut ausführen (bei Air-Gap mit bin/load.sh importieren)
Vorschau- oder bereitgestellte App zeigt leeren Bildschirm (IP-Zugriff)	Firewall blockiert 5171	curl -I http://<server-ip>:5171/	5171 in Firewall öffnen
Vorschau leer + Konsole Mixed Content	Studio nutzt HTTPS, aber App-Assets werden über HTTP angefordert	Browser-Entwicklertools → Konsole	X-Forwarded-Proto $scheme zum Proxy hinzufügen → Domäne
Code geändert, aber Vorschau unverändert	Proxy upgraded HMR-Websocket nicht	Entwicklertools → Netzwerk → WS-Anfrage ist 101?	Upgrade/Connection Header auf beiden vhosts
Build-Chat dauert lange, dann "Verbindungsfehler: network error"	Proxy-Timeout ohne Übertragung (Standard 60 s)	Proxy-vhost-Konfiguration prüfen	proxy_read_timeout 3600s auf beiden vhosts
Antworten kommen nicht in Echtzeit, sondern in Blöcken	proxy_buffering aktiv (Standard)	〃	proxy_buffering off
Zugriff über beliebige Domäne landet auf falscher Seite	Reihenfolge des web-nginx-Setups (erste server als Standard-Server)	docker exec plantpulse-studio-web ls /etc/nginx/conf.d	vhost-Dateinamen so ändern, dass sie mit zz- beginnen
Echte Daten in bereitgestellter App geben 401	① Sitzung vor Domänentrennung angemeldet ② Plattform-Schlüssel nicht gesetzt	Abmelden → erneut anmelden Einstellungen → Plattform-Tab	① Einmal neu anmelden ② PLATFORM_API_KEY setzen, dann bin/restart.sh
Schlüssel geändert, aber keine Wirkung	Nur .env geändert, docker restart liest .env nicht erneut	Ist das Badge im Einstellungsbildschirm 환경변수 기본값?	Schneller Weg – Neuen Schlüssel im Einstellungsbildschirm eingeben (sofort wirksam ohne Neustart). Wenn Umgebungsvariable geändert werden muss: bash bin/restart.sh (oder docker compose up -d --force-recreate)
App-Build schlägt mit "Seitenwagen"-Fehler fehl	Builder-Seitenwagen läuft nicht	docker ps --filter name=plantpulse-studio-agent-server curl -s localhost:8000/health	bash bin/restart.sh · Im Notfall in Einstellungen → Agent den Builder-Engine auf eingebaut umstellen
Chat zeigt «AI-Anbieter <address> nicht erreichbar. Überprüfen Sie Adresse und Schlüssel im Einstellungen → AI-Tab.»	AI-Adresse/-Schlüssel falsch, Gateway down	Einstellungen → AI-Tab → Verbindungstest docker logs --tail 50 plantpulse-studio-server	Adresse und Schlüssel im Bildschirm korrigieren – sofort wirksam (kein Neustart nötig)
Chat zeigt «AI-Anbieter nicht konfiguriert (Einstellungen).»	AI-Anbieter komplett leer	Einstellungen → AI-Tab	Adresse und Schlüssel eingeben, dann [Verbindungstest]
3D- oder große App-Builds sterben mittendrin	Speichermangel (Sitzungscontainer-Limit 2 GB, Host verfügbar)	docker stats · free -h	Gleichzeitig geöffnete Projekte reduzieren · Host-Speicher erweitern
Automatische Sicherung läuft nicht	cron nicht installiert oder DB nicht erreichbar	cat /etc/cron.d/pp-studio-backup tail -50 dist/backup.log	sudo bash bin/install-backup-cron.sh neu installieren · DRYRUN=1 bash bin/restore.sh zur DB-Erreichbarkeitsprüfung
Festplatte voll	Sicherungen und Build-Artefakte akkumulieren	df -h du -sh dist /var/lib/pp-studio/*	Aufbewahrungsanzahl reduzieren (BACKUP_KEEP) · Alte Sicherungen bereinigen
Update durchgeführt, aber alte Ansicht bleibt	Browser-Cache oder Image-Pull fehlgeschlagen	Browser hart neu laden (Ctrl+Shift+R) bash bin/update.sh Ausgabe des Pull-Ergebnisses	Registry-Login prüfen, dann bash bin/update.sh erneut ausführen

---

Detaillierte Diagnose

Wenn der Stack nicht hochkommt

cd /opt/kopens/plantpulse-studio-docker
bash bin/status.sh
docker ps -a --filter name=pp-studio          # Exited 인 컨테이너 찾기
docker logs --tail 200 plantpulse-studio-server

Wenn der Container neu startet (Restarting), liegt die Ursache in der letzten Logzeile. Am häufigsten sind DB-Verbindungsfehler und Fehler bei .env-Werten.

grep -E '^(DATABASE_URL|COMPOSE_PROFILES|PG_|DATA_ROOT|PLATFORM_API_TARGET)' .env

Installation auf "ordnungsgemäßen Zustand" in einem Schritt prüfen

bash bin/smoke-install.sh

Prüft der Reihe nach: Health · Unauthentifizierte Setup-API · Web-Antwort · Tatsächlicher Login · Sitzungs-Laufzeit-Image · Container-Status und meldet den ersten fehlgeschlagenen Punkt.

Probleme mit App-Sitzungen (Projekt öffnen)

docker ps --filter label=plantpulse-studio=1     # 지금 떠 있는 세션 컨테이너
docker image inspect plantpulse-studio-runtime:latest >/dev/null && echo "런타임 이미지 OK"

• Sitzungscontainer werden nach 30 Minuten Inaktivität automatisch zurückgeholt – ein fehlender Eintrag ist kein Fehler.
• Nach einem Server-Neustart werden verbleibende Sitzungscontainer automatisch bereinigt.
• Wenn mehrere Nutzer gleichzeitig öffnen, wird entsprechend Speicher belegt (prüfen mit docker stats).

Probleme mit Plattformverbindung (echte Daten)

Symptome sind normalerweise "Chat-Abfragen funktionieren, aber Werte kommen nicht" oder "Anlagenliste ist leer".

1. In Einstellungen → Plattform-Tab den Verbindungsstatus prüfen.
2. Prüfen, ob die PLATFORM_API_TARGET-Adresse von .env korrekt ist.
3. Prüfen, ob PLATFORM_API_KEY gesetzt ist → Geheimnisverwaltung
4. In den Server-Logs nach Plattform-Aufruffehlern suchen.

docker logs --tail 200 plantpulse-studio-server | grep -i platform

Wenn die Plattform kurzzeitig nicht verfügbar ist, wird die Watcher-Ausführung automatisch übersprungen (nach Neustart automatisch fortgesetzt).

Probleme mit Domäne und Proxy

Die Symptome sind vielfältig, aber die Ursache ist meist eines von 4 fehlenden Einstellungen. Vergleichen Sie die Checkliste unter Domäne und Reverse-Proxy direkt.

---

Wiederherstellungsoptionen

Situation	Maßnahme
Einstellungen falsch geändert, Stack instabil	.env zurücksetzen, dann bash bin/restart.sh
Daten beschädigt	Sicherung und Wiederherstellung — bash bin/restore.sh
Probleme nach Update	.env PP_IMAGE_TAG auf vorherige Version festlegen, dann bash bin/update.sh
Problem mit bereitgestellter App	In der Bereitstellungshistorie des Studio-Bildschirms auf vorherige Version zurückrollen

---

Was Sie bei Support-Anfragen mitsenden sollten

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh                    > /tmp/pp-status.txt
docker logs --tail 500 plantpulse-studio-server &> /tmp/pp-server.log
grep -vE 'KEY|TOKEN|PASSWORD' .env    > /tmp/pp-env-safe.txt   # 비밀 제외본

• Seit wann und bei welcher Aktion das Problem auftritt
• Screenshot (mit Browser-Entwicklertools-Konsole idealerweise)
• Installationsversion (.env, PP_IMAGE_TAG; wenn leer, VERSION-Kaliber) und Zugriffsmethode (IP / Domäne / Proxy vorhanden)

Vor dem Senden von Logs und Einstellungen

.env Original enthält API-Schlüssel. Erstellen Sie, wie oben beschrieben, eine Kopie ohne Geheimnisse und senden Sie diese.

---

Zugehörige Dokumente

• Installation · Air-Gap-Installation
• Domäne und Reverse-Proxy
• Sicherung und Wiederherstellung · Geheimnisverwaltung