Proxy reverso (prefixo de caminho de URL)

O Potato pode rodar atrás de um proxy reverso sob um subcaminho de URL como https://host/app1/, o que é comum quando vários servidores internos compartilham um único ponto de entrada HTTPS público:

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

A interface de anotação carrega recursos estáticos e executa ações por meio de URLs relativas à raiz (/static/..., /updateinstance, /annotate, /media/...). Quando o Potato é montado sob /app1, essas URLs seriam, de outro modo, resolvidas em relação à raiz pública, o que se manifesta como erros 404 em CSS e JS, uma interface oculta ou salvamentos automáticos que falham com «annotations not saved». Um prefixo de implantação corrige isso sem truques de nginx específicos por site.

Como funciona

Ambas as opções abaixo definem o SCRIPT_NAME do WSGI, que o Potato lê como única fonte de verdade para a saída de url_for(...) renderizada no servidor e para o prefixo do lado do cliente exposto ao navegador como window.config.url_prefix. Esse prefixo envolve fetch(), sendBeacon(), EventSource e os atributos href/action/src relativos à raiz. Quando nenhum prefixo é definido, SCRIPT_NAME fica vazio e nada muda, portanto isto não tem efeito nas execuções comuns de potato start.

Opção A — POTATO_PROXY_FIX (o proxy envia um cabeçalho encaminhado)

Use isto quando você controla o proxy e ele pode enviar cabeçalhos encaminhados. O Potato habilita o ProxyFix do Werkzeug, que lê X-Forwarded-Prefix (e -Proto/-Host/-For) por requisição.

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

nginx, removendo o prefixo e encaminhando-o como cabeçalho:

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;
}

O ProxyFix confia nos cabeçalhos encaminhados. Habilite POTATO_PROXY_FIX apenas quando o aplicativo for acessível exclusivamente por meio do proxy confiável. Se a porta interna também for acessível diretamente, um cliente poderia forjar X-Forwarded-Prefix ou -Host e contaminar as URLs geradas.

Opção B — POTATO_URL_PREFIX (a configuração do proxy não pode ser alterada)

Use isto quando você não pode adicionar cabeçalhos encaminhados, mas conhece o caminho de montagem público. O Potato injeta o prefixo no próprio SCRIPT_NAME.

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

O proxy ainda precisa remover o prefixo antes de encaminhar, para que o Flask receba caminhos sem prefixo como /static/styles.css:

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

Se ambas as variáveis forem definidas, o prefixo encaminhado por requisição prevalece e POTATO_URL_PREFIX serve como alternativa.

Transmissão ao vivo (Server-Sent Events)

Os visualizadores de agente ao vivo e de codificação ao vivo usam SSE. O prefixo de URL é aplicado automaticamente, mas o SSE também exige que o proxy desative o buffering na localização da transmissão, ou os eventos ficam retidos:

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ção

1. Carregue https://host/app1/ e confirme que CSS e JS carregam sem erros 404.
2. Faça uma anotação e confirme que ela é salva automaticamente.
3. Navegue por Próximo/Anterior e confirme que a mídia e os dados são renderizados.
4. Se você usa avaliação de agente ao vivo, confirme que a transmissão se conecta e atualiza.

Notas e limitações

• Os links relativos à raiz dentro do conteúdo de anotação exibido também recebem o prefixo. Autores de conteúdo que pretendem apontar para a raiz pública devem usar URLs absolutas.
• Implantações instaladas via pip dependem dos recursos estáticos empacotados; certifique-se de que sua compilação inclua os diretórios static/ aninhados.

Relacionado

• Configuração de produção — HTTPS e gerenciamento de processos
• Avaliação de agente ao vivo — os visualizadores SSE afetados pelo buffering

Para detalhes de implementação, consulte a documentação de origem.