Zum Hauptinhalt springen

Domain und Reverse-Proxy

Einrichtung für den Betrieb von Studio über eine Domain (insbesondere HTTPS) statt über eine IP-Adresse. Dieses Kapitel muss vollständig in der richtigen Reihenfolge durchgeführt werden, damit alles funktioniert. Fehlt auch nur ein Schritt, treten scheinbar unterschiedliche Symptome auf, wie "Vorschau ist leer", "Build-Chat Verbindungsfehler" oder "Daten in der Bereitstellungs-App liefern 401".

Es gibt nur eine Domain​

Vorschau und Bereitstellungs-App werden unter demselben Domain-Pfad /container/ wie das Studio serviert.

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

Benötigt werden 1 DNS-Record, 1 Zertifikat, 1 vhost.

Die App nutzt dieselbe Domain

Die App wird nicht auf einen separaten Host ausgelagert. Da alle Vorschau- und Bereitstellungsadressen relative Pfade sind, funktioniert das unverändert in einer Reverse-Proxy-Konfiguration, die nur Port 80/443 freigibt.

Der Preis – wir verzichten auf die Trennung der Origin

Vorschau- und Bereitstellungs-App enthalten chatgenerierten Code, also nicht vertrauenswürdige Inhalte. Diese laufen auf derselben Origin wie das Studio – das bedeutet, es gibt keine Isolierung durch getrennte Origins. Dies ist eine bewusste Entscheidung, um die Domain auf eine zu reduzieren.

Daher: Geben Sie nicht vertrauenswürdigen Benutzern keine Berechtigung zur App-Erstellung. Die Konfiguration setzt voraus, dass die Rolle "Builder" nur internen Operatoren zugewiesen wird.

Checkliste für die Vorbereitung​

  • 1 DNS-A-Record
  • TLS-Zertifikat für den entsprechenden Hostnamen
  • Reverse-Proxy kann Port :80 der Studio-Box erreichen
  • Firewall der Studio-Box erlaubt Proxy → :80
:5171 muss nicht geöffnet werden

Der App-Listener (:5171) wird vom Web-nginx in der Studio-Box an /container/ · /apps/ · /preview/ weitergereicht, daher muss er nicht nach außen exponiert werden. Öffnen Sie die Firewall nur bei Installationen, die direkt über einen Port ohne Reverse-Proxy zugreifen.

1. vhost zum Proxy hinzufügen​

Der externe Proxy muss alles nur an Port :80 der Studio-Box weiterleiten. /container/ /apps/ · /preview/ Aufteilung wird bereits vom Web-nginx in der Box verarbeitet.

4 Punkte, die unbedingt enthalten sein müssen​

Da die Symptome bei fehlenden Punkten unterschiedlich sind und die Ursache schwer zu finden ist, wird empfohlen, das folgende Beispiel direkt zu kopieren und zu verwenden.

EinstellungSymptom, wenn sie fehlt
proxy_set_header Host $http_hostRouting- und Link-Erzeugung stimmen nicht
Upgrade / Connection-HeaderWebSocket für die Live-Aktualisierung der Vorschau (HMR) bricht ab, Codeänderungen werden nicht im Bildschirm angezeigt
proxy_read_timeout 3600sBuild-Chat zeigt "Verbindungsfehler: network error" – wenn der Agent bei der Werkzeugausführung für Dutzende Sekunden schweigt, bricht das Standard-Timeout von 60 Sekunden den Stream ab
proxy_buffering offStreaming-Antworten stauen sich im Puffer und die Antwort erscheint verspätet in Blöcken
SSE (Server-Sent-Events-Streaming) ist entscheidend

Build-Chat und Frage-Antwort werden in Echtzeit per SSE übertragen. Der Server sendet alle 25 Sekunden einen Heartbeat, daher reicht ein Proxy-Timeout, das länger als das ist, aber 3600s ist ein in der Praxis verifizierter Wert.

Beispiel für nginx-Konfiguration​

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 z. B. mit certbot ausgestellt – der listen 443 ssl-Block erbt die obige Konfiguration unverändert.

Wenn ein vhost zum Web-nginx der Studio-Box hinzugefügt wird

Wenn Sie eine vhost-Datei direkt in den conf.d des gebündelten Web-nginx-Containers mounten, stellen Sie sicher, dass der Dateiname mit zz- beginnt. nginx verwendet den ersten server-Block in alphabetischer Reihenfolge als Standardserver. Wenn der Name früher steht, werden alle nicht passenden Anfragen an die falsche Stelle geleitet und das gesamte Studio funktioniert nicht mehr (dies ist tatsächlich so vorgekommen).

2. Erneuter Login (erforderlich)​

Nach Abschluss der Domain-Einrichtung müssen sich alle Benutzer einmal abmelden und wieder anmelden.

Das Login-Cookie ist host-spezifisch zum Zeitpunkt der Ausstellung. Eine über die IP-Adresse angemeldete Sitzung wird nach dem Wechsel zur Domain nicht übertragen, sodass Datenanfragen mit 401 fehlschlagen.

3. Überprüfung​

PrüfpunktMethode
Studio wird angezeigthttps://studio.company.com aufrufen → anmelden
Vorschau wird angezeigtProjekt öffnen → Vorschau-Bildschirm erscheint, keine Mixed Content in der Konsole
App-Pfad ist erreichbarhttps://studio.company.com/container/ aufrufen → 404 oder App-Liste ist normal (verbunden)
Live-AktualisierungChat: einen Text ändern → Vorschau aktualisiert sich automatisch
Lange BuildsBuild-Chat mindestens 1 Minute laufen lassen → ohne "Verbindungsfehler" durchlaufen
Daten der Bereitstellungs-AppBereitgestellte App öffnen → echte Daten werden angezeigt (kein 401)

Hinweise​

IP und Domain nicht mischen

Nachdem die Domain eingerichtet ist, nur über die Domain zugreifen. Benutzer, die sich über die IP-Adresse anmelden, haben ein anderes Cookie, und die Daten der Bereitstellungs-App liefern 401.

Wenn Cloudflare vorgeschaltet ist
  • WebSocket wird standardmäßig unterstützt, daher ist keine zusätzliche Konfiguration nötig.
  • Das kostenlose Universal-Zertifikat deckt nur Subdomains der ersten Ebene ab (studio.company.com ✅, apps.studio.company.com ❌).
Größe von Anhängen

Da Vor-Ort-Fotos und Zeichnungen im Chat angehängt werden, client_max_body_size 64M einfügen. Fehlt es, schlagen große Bild-Uploads mit 413 fehl.

HTTPS nur ohne Reverse-Proxy​

Wenn kein separater Proxy-Server vorhanden ist und TLS direkt in der Studio-Box terminiert werden soll, verwenden Sie die TLS-Overlay-Erweiterung 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 Beispieldatei für das TLS-Overlay enthält noch die alte Struktur

In tls/nginx-tls.conf.example fehlt der /container/-Block, und es gibt noch den Kommentar mit dem veralteten APPS_ORIGIN und einen separaten Port (5443). Wenn Sie das direkt verwenden, führen die Adressen für Vorschau und Bereitstellungs-App (/container/…) zu 404.

Fügen Sie vorerst den /container/-Block direkt in eine Kopie (tls/nginx-tls.conf) ein – verwenden Sie die 4 Header aus dem obigen Beispiel für nginx-Konfiguration, und entfernen Sie das Präfix, um es an den App-Listener weiterzuleiten. Fügen Sie die Zeile APPS_ORIGIN nicht ein (wird nicht gelesen).

Schnellübersicht: Symptom → Ursache​

Dies sind häufig auftretende Probleme bei der Domain-Bereitstellung. Einen breiteren Überblick finden Sie unter Problemlösung.

SymptomUrsacheMaßnahme
Vorschau/App leer, Konsole zeigt Mixed ContentStudio läuft über HTTPS, aber App-Assets werden über HTTP angefordertX-Forwarded-Proto $scheme zum Proxy hinzufügen und alles auf HTTPS umstellen
Echte Daten in Bereitstellungs-App liefern 401Sitzung wurde vor der Domain-Einrichtung angemeldetEinmal ab- und wieder anmelden
Build-Chat dauert lange und zeigt "Verbindungsfehler: network error"Proxy-Timeout ohne Datenübertragung (Standard 60 s)proxy_read_timeout 3600s
Codeänderungen werden nicht in der Vorschau angezeigtHMR-WebSocket wird nicht hochgestuftUpgrade / Connection-Header hinzufügen
Antworten erscheinen verspätet in Blöckenproxy_buffering ist aktiviert (Standardwert)proxy_buffering off
Beliebige Domain landet an einer falschen StelleLadereihenfolge in web nginx conf.d (der erste server ist der Standardserver)vhost-Dateiname mit zz- beginnen
/container/… liefert 404Der /container/-Block fehlt in der TLS-Overlay-KopieSiehe Warnung oben
App erscheint nicht bei Installation mit direktem PortzugriffPort 5171 ist von der Firewall blockiertFirewall öffnen und mit curl -I http://<host>:5171/ prüfen

Verwandte Dokumente​