Proxy inverse (préfixe de chemin d’URL)

Potato peut s’exécuter derrière un proxy inverse sous un sous-chemin d’URL tel que https://host/app1/, ce qui est courant lorsque plusieurs serveurs internes partagent un même point d’entrée HTTPS public :

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

L’interface d’annotation charge les ressources statiques et exécute les actions via des URL relatives à la racine (/static/..., /updateinstance, /annotate, /media/...). Lorsque Potato est monté sous /app1, ces URL seraient autrement résolues par rapport à la racine publique, ce qui se manifeste par des erreurs 404 sur le CSS et le JS, une interface masquée ou des sauvegardes automatiques qui échouent avec « annotations not saved ». Un préfixe de déploiement corrige cela sans bidouillages nginx propres à chaque site.

Fonctionnement

Les deux options ci-dessous définissent le SCRIPT_NAME WSGI, que Potato lit comme unique source de vérité pour la sortie de url_for(...) rendue côté serveur et pour le préfixe côté client exposé au navigateur sous la forme window.config.url_prefix. Ce préfixe enveloppe fetch(), sendBeacon(), EventSource et les attributs href/action/src relatifs à la racine. Lorsqu’aucun préfixe n’est défini, SCRIPT_NAME est vide et rien ne change ; il s’agit donc d’une opération sans effet pour les exécutions ordinaires de potato start.

Option A — POTATO_PROXY_FIX (le proxy envoie un en-tête transmis)

À utiliser lorsque vous contrôlez le proxy et qu’il peut envoyer des en-têtes transmis. Potato active le ProxyFix de Werkzeug, qui lit X-Forwarded-Prefix (et -Proto/-Host/-For) à chaque requête.

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

nginx, qui retire le préfixe et le transmet sous forme d’en-tête :

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 fait confiance aux en-têtes transmis. N’activez POTATO_PROXY_FIX que lorsque l’application est accessible exclusivement via le proxy de confiance. Si le port interne est aussi directement accessible, un client pourrait usurper X-Forwarded-Prefix ou -Host et corrompre les URL générées.

Option B — POTATO_URL_PREFIX (la configuration du proxy ne peut pas changer)

À utiliser lorsque vous ne pouvez pas ajouter d’en-têtes transmis mais que vous connaissez le chemin de montage public. Potato injecte lui-même le préfixe dans SCRIPT_NAME.

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

Le proxy doit tout de même retirer le préfixe avant de transmettre, afin que Flask reçoive des chemins sans préfixe tels que /static/styles.css :

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

Si les deux variables sont définies, le préfixe transmis par requête l’emporte et POTATO_URL_PREFIX sert de solution de repli.

Diffusion en direct (Server-Sent Events)

Les visionneuses d’agent en direct et de codage en direct utilisent SSE. Le préfixe d’URL est appliqué automatiquement, mais SSE exige aussi que le proxy désactive la mise en mémoire tampon sur l’emplacement du flux, faute de quoi les événements sont retenus :

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

Vérification

1. Chargez https://host/app1/ et vérifiez que le CSS et le JS se chargent sans erreur 404.
2. Réalisez une annotation et vérifiez qu’elle est enregistrée automatiquement.
3. Naviguez Suivant/Précédent et vérifiez que les médias et les données s’affichent.
4. Si vous utilisez l’évaluation d’agent en direct, vérifiez que le flux se connecte et se met à jour.

Notes et limites

• Les liens relatifs à la racine au sein du contenu d’annotation affiché sont également préfixés. Les auteurs de contenu qui souhaitent pointer vers la racine publique devraient utiliser des URL absolues.
• Les déploiements installés via pip reposent sur les ressources statiques empaquetées ; assurez-vous que votre build inclut les répertoires static/ imbriqués.

Voir aussi

• Configuration de production — HTTPS et gestion des processus
• Évaluation d’agent en direct — les visionneuses SSE affectées par la mise en mémoire tampon

Pour les détails d’implémentation, consultez la documentation source.