Proxy inverso (prefijo de ruta de URL)

Potato puede ejecutarse detrás de un proxy inverso bajo una subruta de URL como https://host/app1/, algo habitual cuando varios servidores internos comparten un único punto de entrada HTTPS público:

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

La interfaz de anotación carga recursos estáticos y ejecuta acciones mediante URL relativas a la raíz (/static/..., /updateinstance, /annotate, /media/...). Cuando Potato se monta bajo /app1, esas URL se resolverían en cambio respecto a la raíz pública, lo que se manifiesta como errores 404 en CSS y JS, una interfaz oculta o autoguardados que fallan con «annotations not saved». Un prefijo de despliegue resuelve esto sin trucos de nginx específicos para cada sitio.

Cómo funciona

Ambas opciones siguientes establecen el SCRIPT_NAME de WSGI, que Potato lee como única fuente de verdad para la salida de url_for(...) renderizada en el servidor y para el prefijo del lado del cliente expuesto al navegador como window.config.url_prefix. Ese prefijo envuelve fetch(), sendBeacon(), EventSource y los atributos href/action/src relativos a la raíz. Cuando no se establece ningún prefijo, SCRIPT_NAME está vacío y nada cambia, de modo que esto no tiene efecto en las ejecuciones normales de potato start.

Opción A — POTATO_PROXY_FIX (el proxy envía una cabecera reenviada)

Usa esto cuando controlas el proxy y este puede enviar cabeceras reenviadas. Potato habilita el ProxyFix de Werkzeug, que lee X-Forwarded-Prefix (y -Proto/-Host/-For) por solicitud.

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

nginx, que elimina el prefijo y lo reenvía como cabecera:

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 confía en las cabeceras reenviadas. Habilita POTATO_PROXY_FIX solo cuando la aplicación sea accesible exclusivamente a través del proxy de confianza. Si el puerto interno también es accesible directamente, un cliente podría falsificar X-Forwarded-Prefix o -Host y contaminar las URL generadas.

Opción B — POTATO_URL_PREFIX (la configuración del proxy no se puede cambiar)

Usa esto cuando no puedes añadir cabeceras reenviadas pero conoces la ruta de montaje pública. Potato inyecta el prefijo en el propio SCRIPT_NAME.

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

El proxy aún debe eliminar el prefijo antes de reenviar, de modo que Flask reciba rutas sin prefijo como /static/styles.css:

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

Si se establecen ambas variables, gana el prefijo reenviado por solicitud y POTATO_URL_PREFIX actúa como alternativa.

Transmisión en vivo (Server-Sent Events)

Los visores de agente en vivo y de codificación en vivo usan SSE. El prefijo de URL se aplica automáticamente, pero SSE también requiere que el proxy desactive el almacenamiento en búfer en la ubicación de la transmisión, o los eventos quedan retenidos:

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

Verificación

1. Carga https://host/app1/ y confirma que CSS y JS se cargan sin errores 404.
2. Haz una anotación y confirma que se autoguarda.
3. Navega Siguiente/Anterior y confirma que el contenido multimedia y los datos se renderizan.
4. Si usas evaluación de agente en vivo, confirma que la transmisión se conecta y se actualiza.

Notas y limitaciones

• Los enlaces relativos a la raíz dentro del contenido de anotación mostrado también llevan prefijo. Los autores de contenido que pretendan apuntar a la raíz pública deberían usar URL absolutas.
• Los despliegues instalados con pip dependen de los recursos estáticos empaquetados; asegúrate de que tu compilación incluya los directorios static/ anidados.

Relacionado

• Configuración de producción — HTTPS y gestión de procesos
• Evaluación de agente en vivo — los visores SSE afectados por el almacenamiento en búfer

Para detalles de implementación, consulta la documentación de origen.