Proxy inverso (prefisso del percorso URL)

Potato può funzionare dietro un proxy inverso sotto un sottopercorso URL come https://host/app1/, cosa comune quando più server interni condividono un unico endpoint HTTPS pubblico:

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

L’interfaccia di annotazione carica risorse statiche ed esegue azioni tramite URL relativi alla radice (/static/..., /updateinstance, /annotate, /media/...). Quando Potato è montato sotto /app1, quegli URL verrebbero altrimenti risolti rispetto alla radice pubblica, il che si manifesta come errori 404 su CSS e JS, un’interfaccia nascosta o salvataggi automatici che falliscono con «annotations not saved». Un prefisso di distribuzione risolve il problema senza accorgimenti nginx specifici per ogni sito.

Come funziona

Entrambe le opzioni seguenti impostano lo SCRIPT_NAME di WSGI, che Potato legge come unica fonte di verità per l’output di url_for(...) reso dal server e per il prefisso lato client esposto al browser come window.config.url_prefix. Quel prefisso avvolge fetch(), sendBeacon(), EventSource e gli attributi href/action/src relativi alla radice. Quando non è impostato alcun prefisso, SCRIPT_NAME è vuoto e nulla cambia, quindi questa è un’operazione senza effetti per le normali esecuzioni di potato start.

Opzione A — POTATO_PROXY_FIX (il proxy invia un’intestazione inoltrata)

Usa questa opzione quando controlli il proxy ed esso può inviare intestazioni inoltrate. Potato abilita il ProxyFix di Werkzeug, che legge X-Forwarded-Prefix (e -Proto/-Host/-For) per ogni richiesta.

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

nginx, che rimuove il prefisso e lo inoltra come intestazione:

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 si fida delle intestazioni inoltrate. Abilita POTATO_PROXY_FIX solo quando l’applicazione è raggiungibile esclusivamente tramite il proxy attendibile. Se la porta interna è raggiungibile anche direttamente, un client potrebbe falsificare X-Forwarded-Prefix o -Host e contaminare gli URL generati.

Opzione B — POTATO_URL_PREFIX (la configurazione del proxy non può cambiare)

Usa questa opzione quando non puoi aggiungere intestazioni inoltrate ma conosci il percorso di montaggio pubblico. Potato inietta il prefisso direttamente in SCRIPT_NAME.

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

Il proxy deve comunque rimuovere il prefisso prima di inoltrare, in modo che Flask riceva percorsi senza prefisso come /static/styles.css:

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

Se entrambe le variabili sono impostate, vince il prefisso inoltrato per ogni richiesta e POTATO_URL_PREFIX funge da ripiego.

Streaming in tempo reale (Server-Sent Events)

I visualizzatori di agente in tempo reale e di codifica in tempo reale usano SSE. Il prefisso URL viene applicato automaticamente, ma SSE richiede anche che il proxy disabiliti il buffering nella posizione del flusso, altrimenti gli eventi vengono trattenuti:

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

Verifica

1. Carica https://host/app1/ e verifica che CSS e JS si carichino senza errori 404.
2. Esegui un’annotazione e verifica che venga salvata automaticamente.
3. Naviga Avanti/Indietro e verifica che i contenuti multimediali e i dati vengano renderizzati.
4. Se usi la valutazione dell’agente in tempo reale, verifica che il flusso si connetta e si aggiorni.

Note e limitazioni

• Anche i collegamenti relativi alla radice all’interno del contenuto di annotazione visualizzato ricevono il prefisso. Gli autori di contenuti che intendono puntare alla radice pubblica dovrebbero usare URL assoluti.
• Le distribuzioni installate con pip dipendono dalle risorse statiche impacchettate; assicurati che la tua build includa le directory static/ annidate.

Correlati

• Configurazione di produzione — HTTPS e gestione dei processi
• Valutazione dell’agente in tempo reale — i visualizzatori SSE interessati dal buffering

Per i dettagli di implementazione, consulta la documentazione di origine.