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.
  • Potato 2.9 dehnt das Präfix auf statische Dateien, clientseitiges fetch und Medien-URLs sowie auf jede eigenständige Seite aus: Admin, Dashboards, Session-Review und die alten v1-Seiten (#168, von Aldo Costa).
  • Vor Potato 2.9 ignorierten das Login-Formular, /done, /logout, /pocket, die Formulare zum Zurücksetzen des Passworts und Admin-Weiterleitungen das Präfix, und die Medien-URLs in poster, srcset und track bekamen keins. Führe ein Upgrade durch, wenn eine Bereitstellung hinter einem Proxy an einer dieser Stellen das Präfix verliert.

Verwandt

Implementierungsdetails finden Sie in der Quelldokumentation.