Skip to content

Reverse-Proxy (URL-Pfadpräfix)

Stellen Sie Potato unter einem Unterpfad hinter einem Reverse-Proxy bereit, etwa https://host/app1/. Konfigurieren Sie ein Bereitstellungs-URL-Präfix, damit statische Assets, Annotationsaktionen und Live-Streams unter dem Mount-Pfad korrekt aufgelöst werden.

Potato kann hinter einem Reverse-Proxy unter einem URL-Unterpfad laufen wie https://host/app1/, was üblich ist, wenn mehrere interne Server einen einzigen öffentlichen HTTPS-Endpunkt teilen:

text
https://host/app1/  ->  http://127.0.0.1:8000/
https://host/app2/  ->  http://127.0.0.1:8001/

Die Annotations-UI lädt statische Assets und führt Aktionen über wurzelrelative URLs aus (/static/..., /updateinstance, /annotate, /media/...). Wenn Potato unter /app1 eingehängt ist, würden diese URLs andernfalls gegen die öffentliche Wurzel aufgelöst, was sich als 404-Fehler bei CSS und JS, eine verborgene Oberfläche oder Autosaves zeigt, die mit „annotations not saved“ fehlschlagen. Ein Bereitstellungspräfix behebt dies ohne websitespezifische nginx-Tricks.

Funktionsweise

Beide Optionen unten setzen den WSGI-SCRIPT_NAME, den Potato als einzige Wahrheitsquelle für die serverseitig gerenderte url_for(...)-Ausgabe und für das clientseitige Präfix liest, das dem Browser als window.config.url_prefix bereitgestellt wird. Dieses Präfix umschließt fetch(), sendBeacon(), EventSource sowie wurzelrelative href/action/src-Attribute. Wenn kein Präfix gesetzt ist, ist SCRIPT_NAME leer und nichts ändert sich; bei gewöhnlichen potato start-Aufrufen bleibt dies also wirkungslos.

Option A — POTATO_PROXY_FIX (der Proxy sendet einen weitergeleiteten Header)

Verwenden Sie dies, wenn Sie den Proxy kontrollieren und er weitergeleitete Header senden kann. Potato aktiviert Werkzeugs ProxyFix, das pro Anfrage X-Forwarded-Prefix (sowie -Proto/-Host/-For) liest.

bash
export POTATO_PROXY_FIX=1
potato start config.yaml -p 8000

nginx, das das Präfix entfernt und es als Header weiterleitet:

nginx
location /app1/ {
    proxy_pass         http://127.0.0.1:8000/;   # trailing slash strips /app1/
    proxy_set_header   Host              $host;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   X-Forwarded-Prefix /app1;
}

ProxyFix vertraut weitergeleiteten Headern. Aktivieren Sie POTATO_PROXY_FIX nur, wenn die Anwendung ausschließlich über den vertrauenswürdigen Proxy erreichbar ist. Ist der interne Port auch direkt erreichbar, könnte ein Client X-Forwarded-Prefix oder -Host fälschen und die generierten URLs vergiften.

Option B — POTATO_URL_PREFIX (die Proxy-Konfiguration kann nicht geändert werden)

Verwenden Sie dies, wenn Sie keine weitergeleiteten Header hinzufügen können, aber den öffentlichen Mount-Pfad kennen. Potato fügt das Präfix selbst in SCRIPT_NAME ein.

bash
export POTATO_URL_PREFIX=/app1
potato start config.yaml -p 8000

Der Proxy muss das Präfix dennoch vor der Weiterleitung entfernen, damit Flask präfixlose Pfade wie /static/styles.css erhält:

nginx
location /app1/ {
    proxy_pass       http://127.0.0.1:8000/;     # trailing slash strips /app1/
    proxy_set_header Host $host;
}

Sind beide Variablen gesetzt, gewinnt das pro Anfrage weitergeleitete Präfix, und POTATO_URL_PREFIX dient als Rückfalloption.

Live-Streaming (Server-Sent Events)

Die Live-Agent- und Live-Coding-Viewer verwenden SSE. Das URL-Präfix wird automatisch angewendet, aber SSE erfordert außerdem, dass der Proxy das Puffern am Stream-Standort deaktiviert, sonst werden Ereignisse zurückgehalten:

nginx
location /app1/api/ {
    proxy_pass            http://127.0.0.1:8000/api/;
    proxy_set_header      Host $host;
    proxy_buffering       off;
    proxy_read_timeout    3600s;
}

Überprüfung

  1. Laden Sie https://host/app1/ und bestätigen Sie, dass CSS und JS ohne 404-Fehler laden.
  2. Erstellen Sie eine Annotation und bestätigen Sie, dass sie automatisch gespeichert wird.
  3. Navigieren Sie zu Weiter/Zurück und bestätigen Sie, dass Medien und Daten gerendert werden.
  4. Falls Sie die Live-Agent-Auswertung nutzen, bestätigen Sie, dass der Stream verbindet und aktualisiert.

Hinweise und Einschränkungen

  • Wurzelrelative Links innerhalb des angezeigten Annotationsinhalts erhalten ebenfalls das Präfix. Inhaltsautoren, die auf die öffentliche Wurzel verweisen möchten, sollten absolute URLs verwenden.
  • Mit pip installierte Bereitstellungen sind auf die gebündelten statischen Assets angewiesen; stellen Sie sicher, dass Ihr Build die verschachtelten static/-Verzeichnisse enthält.

Verwandt

Implementierungsdetails finden Sie in der Quelldokumentation.