Zum Hauptinhalt springen

Fehlerbehebung

Hier finden Sie Symptome, Ursachen und Abhilfemaßnahmen. Die meisten Probleme lassen sich mit 3 Befehlen eingrenzen:

cd /opt/kopens/plantpulse-studio-docker

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

So lesen Sie Protokolle​

ZielBefehl
Studio-Server (am wichtigsten)docker logs -f --tail 200 pp-studio-server
Web (nginx)docker logs --tail 100 pp-studio-web
Datenbank (Bundle-Modus)docker logs --tail 100 pp-studio-postgres
Builder-Sidecardocker logs --tail 100 pp-studio-agent-server
Mit Skript verfolgenbash bin/logs.sh (Standard-Server) · bash bin/logs.sh studio-web
Automatische Sicherungtail -50 dist/backup.log
App-Sitzungscontainerdocker ps --filter label=plantpulse-studio=1 zum Überprüfen des Namens, dann docker logs <name>
Nach Zeitzone eingrenzen
docker logs --since 30m pp-studio-server
docker logs --since "2026-07-28T09:00:00" pp-studio-server
Schlüssel werden nicht in Protokollen protokolliert

API-Schlüssel und Token werden nicht in Protokollen protokolliert (in Audit-Protokollen nur Fingerabdrücke statt Werte). Wenn Sie Protokolle an das Support-Team weitergeben, müssen Sie nur Vor-Ort-Informationen wie Standortname und Anlagenname überprüfen.

Symptom → Schnelle Übersicht der Ursachen​

SymptomHäufige UrsacheÜberprüfenAbhilfe
Weboberfläche wird gar nicht geöffnetStack läuft nicht oder Port 80 wird verwendetbash bin/status.sh
docker logs pp-studio-web		bash bin/start.sh · Andere Dienste bereinigen, die Port 80 verwenden
Oberfläche öffnet sich, Anmeldung schlägt fehlBootstrap-Konto nicht eingestellt oder Platform nicht erreichbargrep STUDIO_LOCAL_USERS .env
curl -s localhost:5170/health		Konto in .env angeben, dann bash bin/restart.sh
Anmeldung wird plötzlich blockiert (nach kurzer Zeit wiederholen)Anmelde-Ratenlimit (10 Versuche/Minute pro IP)docker logs --tail 50 pp-studio-server1 Minute warten und dann erneut versuchen
Health bleibt DOWN, Protokoll zeigt DB-AuthentifizierungsfehlerVorhandene Daten, aber PG_PASSWORD wurde geändertdocker logs pp-studio-postgres
docker logs pp-studio-server		Auf ursprüngliches Passwort zurücksetzen oder Kontopasswort zunächst in PostgreSQL ändern
Projekt öffnen schlägt fehl (500)Session Runtime Image nicht vorhandendocker image inspect plantpulse-studio-runtime:latestbash bin/start.sh erneut ausführen (für Air-Gap mit bin/load.sh importieren)
Vorschau/bereitgestellte App zeigt leeren Bildschirm (IP-Zugriff)Port 5171 von Firewall blockiertcurl -I http://<server-ip>:5171/Port 5171 in Firewall öffnen
Vorschau zeigt leeren Bildschirm + Konsole Mixed ContentStudio ist HTTPS, aber App-Assets werden über HTTP angefordertBrowser-Entwicklertools-KonsoleProxy mit X-Forwarded-Proto $scheme hinzufügen → Domäne
Code behoben, aber Vorschau bleibt gleichProxy aktualisiert HMR-WebSocket nichtEntwicklertools → Netzwerk → WS-Anfrage ist 101Zwei vhosts mit Upgrade/Connection Header hinzufügen
Build-Chat dauert lange, dann "Verbindungsfehler: network error"Proxy-Timeouts ohne Datenübertragung (Standard 60 Sekunden)Proxy-vhost-Konfiguration überprüfenproxy_read_timeout 3600s zu beiden vhosts hinzufügen
Antwort kommt nicht in Echtzeit, sondern in Blöckenproxy_buffering aktiviert (Standard)〃proxy_buffering off
Zugriff auf beliebige Domäne führt zu falschem OrtWeb nginx Config-Ladereihenfolge (erste server ist Standard-Server)docker exec pp-studio-web ls /etc/nginx/conf.dvhost-Dateinamen mit zz- beginnen lassen
Bereitgestellte App erhält 401 bei echten Daten① Sitzung vor Domänentrennung angemeldet ② Platform-Schlüssel nicht eingestelltAbmelden → Erneut anmelden versuchen
Umgebungseinstellungen → Platform-Registerkarte		① Einmalig erneut anmelden ② PLATFORM_API_KEY eingestellt, dann bin/restart.sh
Schlüssel geändert, wird aber nicht angewendetdocker restart liest .env nicht erneutUmgebungseinstellungen zeigen „Verwaltet durch Umgebungsvariable"bash bin/restart.sh (oder docker compose up -d --force-recreate)
App-Build schlägt mit „Sidecar"-Fehler fehlBuilder-Sidecar nicht gestartetdocker ps --filter name=pp-studio-agent-server
curl -s localhost:8000/health		bash bin/restart.sh · Im Notfall in Umgebungseinstellungen → Agent zu integriertem Builder-Engine wechseln
Chat zeigt „AI-Provider nicht erreichbar"AI-Adresse/-schlüssel Fehler, Gateway downUmgebungseinstellungen → AI-Registerkarte → Verbindung testen
docker logs --tail 50 pp-studio-server		Adresse/-schlüssel korrigieren → bin/restart.sh
3D/große App-Build bricht in der Mitte abUnzureichender Speicher (Session Container Limit 2 GB, Host-Speicher)docker stats · free -hGleichzeitig offene Projekte reduzieren · Host-Speicher aufrüsten
Automatische Sicherung läuft nichtcron nicht installiert oder DB nicht erreichbarcat /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 zum Überprüfen der DB-Erreichbarkeit
Festplatte vollAnsammlung von Sicherungen und Build-Artefaktendf -h
du -sh dist /var/lib/pp-studio/*		Aufbewahrte Anzahl reduzieren (BACKUP_KEEP) · alte Sicherungen bereinigen
Nach Update wird alter Bildschirm angezeigtBrowser-Cache oder Image-Pull fehlgeschlagenBrowser Hard Refresh (Ctrl+Shift+R)
bash bin/start.sh Pull-Ergebnis in Ausgabe		Registry-Anmeldung überprüfen, dann bash bin/start.sh erneut ausführen

Detaillierte Diagnose​

Wenn der Stack nicht hochfährt​

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

Wenn Container sich ständig neu starten (Restarting), finden Sie die Ursache in der letzten Zeile des Protokolls. Am häufigsten sind Datenbankverbindungsfehler und .env Wertfehler.

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

Installation auf „korrekten Zustand" auf einmal überprüfen​

bash bin/smoke-install.sh

Überprüft Health, API für unauthentifizierte Einstellungen, Web-Antwort, tatsächliche Anmeldung, Session Runtime Image und Container-Status nacheinander und meldet das erste fehlgeschlagene Element.

App-Sitzungsprobleme (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 freigegeben — nicht vorhanden zu sein ist kein Fehler.
  • Das Neustarten des Servers bereinigt automatisch verbleibende Sitzungscontainer.
  • Mehrere Benutzer, die gleichzeitig öffnen, benötigen entsprechend viel Speicher (mit docker stats überprüfen).

Platform-Verbindungsprobleme (echte Daten)​

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

  1. Überprüfen Sie den Verbindungsstatus in Umgebungseinstellungen → Platform Registerkarte.
  2. Überprüfen Sie, ob die PLATFORM_API_TARGET Adresse in .env korrekt ist.
  3. Überprüfen Sie, ob PLATFORM_API_KEY eingestellt ist → Geheimverwaltung
  4. Überprüfen Sie das Serverprotokoll auf Platform-Aufrufffehler.
docker logs --tail 200 pp-studio-server | grep -i platform

Wenn Platform kurzzeitig ausfällt, wird die Watcher-Ausführung automatisch übersprungen (automatisch neu gestartet nach Neustart).

Domänen- und Proxy-Probleme​

Symptome treten auf vielfältige Weise auf, aber die Ursache ist normalerweise eine fehlende Einstellung von vier Konfigurationen. Vergleichen Sie die Checkliste in Domäne und Reverse Proxy direkt.

Wiederherstellungsmöglichkeiten​

SituationAbhilfe
Einstellungen falsch angepasst, Stack funktioniert nicht richtig.env original wiederherstellen, dann bash bin/restart.sh
Daten beschädigtSicherung und Wiederherstellung — bash bin/restore.sh
Nach Update treten Probleme auf.env der TAG auf vorherige Version fixieren, dann bash bin/start.sh
Bereitgestellte App hat ProblemeAuf der Studio-Oberfläche Rollback auf frühere Version im Bereitstellungsverlauf

Hilfreich beim Einreichen einer Support-Anfrage​

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh                    > /tmp/pp-status.txt
docker logs --tail 500 pp-studio-server &> /tmp/pp-server.log
grep -vE 'KEY|TOKEN|PASSWORD' .env    > /tmp/pp-env-safe.txt   # 비밀 제외본
  • Seit wann und bei welcher Operation tritt es auf
  • Screenshot (noch besser mit Browser-Entwicklertools-Konsole)
  • Installationsversion (.env des TAG) und Zugriffsmethode (IP / Domäne / mit oder ohne Proxy)
Vor dem Übermitteln von Protokollen/Konfiguration

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

Verwandte Dokumentation​