Domäne und Reverse Proxy

Konfiguration für den Betrieb von Studio über eine Domäne (besonders HTTPS) statt einer IP-Adresse. Diese Anleitung muss vollständig und in der angegebenen Reihenfolge umgesetzt werden. Wird ein Schritt übersprungen, treten unterschiedliche Symptome auf: „Vorschau zeigt leerer Bildschirm", „Build-Chat meldet Verbindungsfehler", „bereitgestellte App gibt 401-Fehler bei Datenabruf" usw.

Eine Domäne

Vorschau und bereitgestellte App werden unter derselben Domäne wie Studio unter dem Pfad /container/ bereitgestellt.

https://studio.company.com/              →  스튜디오 UI + API
https://studio.company.com/container/…   →  프리뷰 · 배포앱

Erforderlich sind 1 DNS-Eintrag, 1 Zertifikat, 1 vhost.

Früher waren es 2 Domänen

Vor 2026-08-23 musste die App auf einem separaten Host (studio-apps.company.com) gehostet werden, und diese Adresse musste über APPS_ORIGIN oder die Konfiguration „App Origin" bekannt gemacht werden. Diese Einstellung existiert nicht mehr.

Der Grund für die Entfernung war, dass wenn dieser Wert leer blieb, der Server die Vorschau-URL mit 요청호스트:5171 konstruierte, was in einer Reverse-Proxy-Konfiguration, die nur Port 80/443 freigibt, dazu führte, dass der Browser die Adresse nicht erreichen konnte und die Live-Vorschau ganz leer blieb. Mit relativen Pfaden kann es von Anfang an nicht schiefgehen.

Wenn alte APPS_ORIGIN-Werte in .env oder der Konfiguration vorhanden sind, werden sie jetzt nicht mehr gelesen.

Tradeoff — Ursprungstrennung aufgegeben

Vorschau und bereitgestellte App enthalten durch Chat erzeugten Code, also nicht vertrauenswürdigen Inhalt. Die frühere Struktur trennte die Ursprünge, um zu verhindern, dass dieses JavaScript auf Studio-Login-Token zugreift. Jetzt laufen sie im gleichen Ursprung, diese Isolierung existiert nicht mehr. Dies ist ein bewusster Kompromiss bei der Reduzierung auf eine Domäne.

Geben Sie Benutzern, denen Sie nicht vertrauen, keine App-Generierungsberechtigung. Diese Konfiguration setzt voraus, dass die Builder-Rolle nur internen Betreibern zugewiesen wird.

Checkliste der Voraussetzungen

1 DNS A-Eintrag
TLS-Zertifikat für diesen Hostnamen
Reverse Proxy kann :80 des Studio-Hosts erreichen
Firewall des Studio-Hosts erlaubt Proxy → :80

:5171 muss nicht offen sein

Der App-Listener (:5171) wird von web nginx innerhalb des Studio-Hosts behandelt — /container/ · /apps/ · /preview/ werden weitergeleitet, daher muss er nicht nach außen freigegeben werden. Öffnen Sie die Firewall nur in Installationen ohne Reverse Proxy, die über Ports direkt zugreifen.

1. vhost zum Proxy hinzufügen

Der externe Proxy braucht alles nur an :80 des Studio-Hosts weiterzuleiten. Das Routing von /container/ · /apps/ · /preview/ wird bereits von web nginx innerhalb des Hosts verwaltet.

4 notwendige Einstellungen

Da die Symptome bei fehlender Einstellung unterschiedlich ausfallen und die Fehlersuche erschweren, wird empfohlen, das folgende Beispiel direkt zu kopieren.

Einstellung	Symptom bei Fehlen
`proxy_set_header Host $http_host`	Routing und Link-Generierung werden verzerrt
`Upgrade` / `Connection` Header	WebSocket für Vorschau-Live-Refresh (HMR) wird unterbrochen — Codeänderungen werden nicht auf dem Bildschirm angezeigt
`proxy_read_timeout 3600s`	Build-Chat zeigt "Verbindungsfehler: network error" — wenn der Agent bei Tool-Ausführung Dutzende Sekunden schweigt, unterbreitet das Standard-60-Sekunden-Timeout den Stream
`proxy_buffering off`	Streaming-Responses stauen sich im Buffer — Antworten erscheinen verspätet als Blöcke

SSE (Server-Sent Events) ist zentral

Build-Chat und Query-Antwort werden über SSE in Echtzeit übertragen. Der Server sendet alle 25 Sekunden einen Heartbeat, daher muss der Proxy-Timeout nur länger sein, aber 3600s ist ein in echter Produktion validierter Wert.

nginx-Konfigurationsbeispiel

server {
  listen 80;
  server_name studio.company.com;

  location / {
    proxy_pass       http://<studio-host>:80;
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;   # 에이전트 SSE(빌드 채팅) — 필수
    proxy_buffering off;        # 스트리밍 즉시 전달 — 필수
    client_max_body_size 64M;   # 사진·도면 첨부
  }
}

HTTPS wird mit certbot oder ähnlich ausgestellt — der listen 443 ssl-Block erbt die obige Konfiguration einfach.

Wenn Sie einen vhost in web nginx des Studio-Hosts hinzufügen

Wenn Sie eine vhost-Datei direkt im conf.d des gepackten web nginx-Containers einhängen, stellen Sie sicher, dass der Dateiname mit zz- beginnt. nginx verwendet alphabetisch den ersten server-Block als Standard-Server, daher werden bei vorangehendem Namen alle nicht übereinstimmenden Anfragen an die falsche Stelle weitergeleitet, und Studio wird komplett unbrauchbar (tatsächlich geschehen).

2. Erneutes Anmelden (erforderlich)

Nach der Domänenkonfiguration müssen sich alle Benutzer abmelden und dann erneut anmelden.

Login-Cookies sind zum Zeitpunkt ihrer Ausstellung spezifisch für den Host. Sitzungen, die über die IP angemeldet wurden, werden nach dem Wechsel zur Domäne nicht übertragen, und Datenabrufanfragen schlagen mit 401 fehl.

3. Verifikation

Verifikationspunkt	Methode
Studio lädt	`https://studio.company.com` aufrufen → anmelden
Vorschau wird angezeigt	Projekt öffnen → Vorschau angezeigt, Konsole zeigt keine `Mixed Content`
App-Pfad ist erreichbar	`https://studio.company.com/container/` aufrufen → 404/App-Liste bedeutet normal (verbunden)
Live-Refresh	Eine Nachricht im Chat bearbeiten → Vorschau aktualisiert sich automatisch
Langer Build	Build-Chat >1 Minute laufen lassen → Abschluss ohne „Verbindungsfehler"
App-Daten in Produktion	Bereitgestellte App öffnen → echte Daten angezeigt (kein 401-Fehler)

Vorsichtsmaßnahmen

Mischen Sie nicht IP und Domäne

Nach der Domänenkonfiguration greifen Sie nur über die Domäne zu. Benutzer, die über die IP zugreifen, haben unterschiedliche Cookies und erhalten 401-Fehler bei der App-Datenbeschaffung.

Bei Cloudflare als Proxy

WebSocket wird standardmäßig unterstützt, keine zusätzliche Konfiguration erforderlich.
Kostenlose Universal-Zertifikate decken nur Subdomänen auf 1 Ebene ab (studio.company.com ✅, apps.studio.company.com ❌).

Dateigröße für Anhänge

Da Vor-Ort-Fotos und Pläne im Chat angehängt werden, fügen Sie client_max_body_size 64M ein. Ohne dies schlagen große Foto-Uploads mit 413 fehl.

HTTPS nur ohne Reverse Proxy anbinden

Wenn es keinen separaten Proxy gibt und Sie TLS direkt auf dem Studio-Host beenden möchten, nutzen Sie das TLS-Overlay des Betriebspakets.

cd /opt/kopens/plantpulse-studio-docker
cp tls/nginx-tls.conf.example tls/nginx-tls.conf   # server_name 등 수정
# tls/cert.pem, tls/key.pem 배치(사내 CA 또는 공인 인증서)
docker compose -f docker-compose.yml -f docker-compose.tls.yml up -d

Die TLS-Overlay-Beispieldatei enthält noch die alte Struktur

tls/nginx-tls.conf.example hat noch keinen /container/-Block, und der Kommentar bezieht sich noch auf das nicht entfernte APPS_ORIGIN und einen separaten Port (5443). Wenn Sie es so verwenden, wird die Vorschau- und App-Adresse (/container/…) zu 404.

Fügen Sie vorerst in einer Kopie (tls/nginx-tls.conf) den /container/-Block selbst hinzu — verwenden Sie direkt die 4 Header aus dem nginx-Konfigurationsbeispiel, entfernen Sie das Präfix und leiten Sie an den App-Listener weiter. Die Zeile APPS_ORIGIN weglassen (wird nicht gelesen).

Symptom → Ursache Schnellreferenz

Dies sind häufig auftretende Probleme bei Domänen-Deployments. Einen breiteren Überblick finden Sie unter Troubleshooting.

Symptom	Ursache	Abhilfe
Vorschau/App zeigt leerer Bildschirm, Konsole zeigt `Mixed Content`	Studio ist HTTPS, aber App-Assets werden über HTTP angefordert	Fügen Sie `X-Forwarded-Proto $scheme` zum Proxy hinzu, dann alles auf HTTPS
Bereitgestellte App zeigt 401 bei echten Daten	Sitzung vor Domänenbindung angemeldet	Abmelden, dann 1x erneut anmelden
Build-Chat bricht nach längerer Ausführung mit „Verbindungsfehler: network error" ab	Proxy Idle-Timeout (Standard 60 Sekunden)	`proxy_read_timeout 3600s`
Codeänderungen werden nicht in der Vorschau angezeigt	HMR-WebSocket wird nicht aktualisiert	`Upgrade` / `Connection` Header hinzufügen
Antworten erscheinen verspätet als Blöcke	`proxy_buffering` ist aktiviert (Standard)	`proxy_buffering off`
Beliebige Domäne wird an falsche Stelle weitergeleitet	web nginx conf.d Ladereihenfolge (erster `server` ist Standard-Server)	vhost-Dateiname mit `zz-` beginnen
`/container/…` ergibt 404	TLS-Overlay-Kopie hat keinen `/container/`-Block	siehe obige Warnung
App wird nicht angezeigt bei direktem Port-Zugriff	Firewall blockiert 5171	Firewall öffnen, dann mit `curl -I http://<host>:5171/` prüfen

Eine Domäne​

Checkliste der Voraussetzungen​

1. vhost zum Proxy hinzufügen​

4 notwendige Einstellungen​

nginx-Konfigurationsbeispiel​

2. Erneutes Anmelden (erforderlich)​

3. Verifikation​

Vorsichtsmaßnahmen​

HTTPS nur ohne Reverse Proxy anbinden​

Symptom → Ursache Schnellreferenz​

Verwandte Dokumentation​