Esta aplicação auto-hospedada vai funcionar atrás de um proxy reverso? Uma lista de verificação de compatibilidade
Uma aplicação Docker estar acessível numa porta não prova que se vai comportar corretamente num domínio HTTPS público. Utilize esta lista de verificação baseada em evidências para confirmar URLs canónicos, cabeçalhos encaminhados, cookies, carregamentos, ligações em tempo real e callbacks antes do lançamento.
Porque é que a compatibilidade com proxy reverso é uma preocupação na seleção de aplicações
Um proxy reverso fica entre um visitante e uma aplicação. Pode encaminhar um domínio público para um serviço interno e terminar TLS, pelo que a aplicação não tem necessariamente de escutar diretamente na internet. Este padrão de infraestrutura é comum, mas não garante que todas as aplicações auto-hospedadas funcionem corretamente atrás dele.
A questão importante não é apenas saber se o contentor inicia ou se a sua porta interna responde a um pedido. A aplicação tem de compreender o endereço público que os utilizadores veem, o esquema HTTPS original e, quando relevante, o endereço do cliente de origem. Também tem de funcionar com os limites e o comportamento de ligação do proxy para as funcionalidades que a sua equipa pretende utilizar.
Trate a compatibilidade com proxy reverso como um critério de seleção e de aceitação. Antes de se comprometer com uma aplicação, procure a documentação oficial de implementação e orientação explícita sobre definições de URL externa, proxies reversos, proxies fidedignos, cabeçalhos encaminhados, carregamentos, ligações em tempo real e autenticação externa. Quando a documentação for omissa, registe essa incerteza e teste o fluxo de trabalho exato de que necessita.
- Não equipare “funciona em Docker” a “está pronto para um domínio HTTPS público”.
- Prefira uma aplicação com configuração documentada para o seu URL externo ou canónico.
- Exija evidências de uma implementação de teste, e não apenas uma verificação de estado do contentor bem-sucedida.
- Utilize apenas o domínio público e os percursos normais dos utilizadores nos testes de aceitação; uma porta interna acedida diretamente pode ocultar falhas relacionadas com o proxy.
Mapeie o percurso do pedido antes de alterar definições
Anote o percurso completo de um pedido normal: navegador, nome DNS público, proxy reverso, aplicação e quaisquer serviços de suporte, como uma base de dados, serviço de e-mail, fornecedor de identidade, serviço de armazenamento de objetos ou destino de webhook. Isto transforma um problema vago de proxy num conjunto de limites que pode ser verificado.
O proxy recebe o pedido público e envia um pedido a montante para a aplicação. Nesse processo, a aplicação pode deixar de ver os detalhes da ligação original, salvo se estiver concebida para utilizar cabeçalhos de pedido fornecidos pelo proxy. O Traefik, por exemplo, adiciona automaticamente X-Forwarded-For, X-Real-Ip, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto e X-Forwarded-Server ao encaminhar pedidos por proxy.
Documente também quais as portas que são intencionalmente públicas. O Docker afirma que as portas dos contentores não são externamente acessíveis por predefinição; publicar uma porta torna-a disponível fora do anfitrião. Quando a aplicação a montante e o proxy partilham um anfitrião, publicar apenas para localhost pode restringir o acesso ao anfitrião Docker em vez de expor remotamente o serviço a montante.
- Nome ou nomes de anfitrião públicos, incluindo qualquer domínio alternativo.
- Esquema externo esperado: normalmente HTTPS para uma implementação pública.
- Pontos de entrada do proxy para HTTP e HTTPS.
- Nome de anfitrião e porta internos do serviço a montante.
- A localização do limite TLS.
- Qualquer proxy adicional, balanceador de carga, CDN, VPN ou túnel à frente do proxy reverso.
- Que portas a montante devem permanecer privadas e quais devem estar publicamente acessíveis.
Verificação 1: Configure e comprove o URL externo canónico
Muitas aplicações precisam de uma definição explícita para o endereço através do qual os utilizadores lhes acedem. A documentação oficial pode chamá-lo URL base, URL do site, URL público, URL externo, URL do servidor, URL raiz ou algo semelhante. Defina-o para o endereço HTTPS público final, incluindo qualquer prefixo de caminho necessário, em vez de um nome de contentor interno, endereço IP privado ou URL HTTP.
Esta definição influencia habitualmente as ligações na interface, as ligações enviadas por e-mail, os destinos de reposição de palavra-passe, as cargas úteis de webhook e a construção de callbacks OAuth. Uma discrepância aparentemente pequena pode provocar redirecionamentos para um nome de anfitrião interno, ligações HTTP a partir de um site HTTPS ou um fluxo de início de sessão que regressa ao local errado.
Utilize o nome de anfitrião final antes de testar integrações. Alterar posteriormente um URL público pode exigir mudanças na aplicação, no fornecedor de identidade, nos fornecedores de webhook e nos marcadores. Se a documentação oficial não explicar a definição ou se um subcaminho é suportado, não assuma que é seguro implementar sob um caminho como example.com/app.
- Defina o URL canónico documentado para o URL HTTPS público exato.
- Abra páginas numa sessão limpa do navegador e inspecione os redirecionamentos.
- Envie um e-mail de reposição de palavra-passe ou de convite, se a aplicação o suportar, e confirme que a ligação utiliza o endereço público.
- Crie uma ligação de partilha ou um recurso público, quando aplicável, e abra-o a partir de uma sessão separada.
- Teste tanto o nome de anfitrião simples como qualquer nome de anfitrião alternativo pretendido e, em seguida, escolha um endereço canónico.
Verificação 2: Estabeleça o limite de proxy fidedigno e de cabeçalhos encaminhados
Um proxy reverso precisa de uma forma de transmitir informações sobre o pedido que recebeu. A RFC 7239 define o cabeçalho normalizado Forwarded para informações alteradas ou perdidas através de proxies, incluindo endereço de origem, anfitrião e protocolo. Na prática, as aplicações também podem utilizar cabeçalhos X-Forwarded-*. A documentação da própria aplicação deve indicar quais os cabeçalhos que lê e como declarar proxies fidedignos.
A confiança é a parte crítica. Um cliente não pode ter a possibilidade de fornecer um cabeçalho que a aplicação trate como identidade, anfitrião ou esquema autoritativo do cliente. A RFC 7239 salienta que as conclusões baseadas em dados encaminhados dependem de confiar nos proxies que os adicionaram. O Traefik pode ser configurado para confiar nos dados de cabeçalhos encaminhados apenas a partir de endereços IP ou CIDRs especificados; a respetiva documentação desaconselha um modo de confiança total em produção.
Registe o intervalo de endereços do proxy ou o limite de rede em que a aplicação está configurada para confiar, se a aplicação tiver essa definição. Se existir mais do que uma camada de proxy, determine qual delas remove, substitui ou preserva os cabeçalhos encaminhados. Esta é uma decisão de segurança, não apenas uma conveniência de encaminhamento.
- Encontre a documentação oficial da aplicação sobre proxy reverso ou proxy fidedigno.
- Identifique se utiliza Forwarded, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-For ou outros cabeçalhos.
- Limite a confiança nos cabeçalhos ao limite de proxy conhecido sempre que o componente relevante o suportar.
- Evite expor diretamente a aplicação a montante em paralelo com o proxy, salvo se existir uma necessidade específica e controlada.
- Teste um pedido público normal e confirme que a aplicação indica o esquema e o anfitrião externos pretendidos.
Verificação 4: Verifique os endereços IP dos clientes e os eventos de auditoria
O tratamento de endereços de clientes é importante quando uma aplicação mostra histórico de inícios de sessão, regista eventos de auditoria, aplica controlos de acesso baseados em IP, limita pedidos ou toma decisões de segurança a partir de um endereço de origem. Atrás de um proxy, o par imediato visível para a aplicação pode ser o proxy, e não o navegador da pessoa.
Crie um teste controlado com pelo menos duas redes de clientes distintas, quando for prático. Execute uma ação que deva ser registada e examine depois a vista de auditoria ou os registos da aplicação de acordo com o comportamento documentado. O objetivo não é necessariamente expor endereços IP brutos a todos os administradores; é garantir que o contexto registado pela aplicação e quaisquer controlos baseados em IP funcionam como a sua política prevê.
Se a aplicação não documentar o tratamento de endereços de clientes com reconhecimento de proxy, evite assumir que os seus registos de atividade identificam a rede do utilizador de origem. Mantenha essa limitação no registo de compatibilidade e avalie se afeta os seus requisitos de segurança, conformidade ou suporte.
- Identifique as funcionalidades que dependem de informações de endereço do cliente.
- Verifique se os registos de auditoria mostram o endereço do proxy ou o contexto de cliente esperado.
- Teste qualquer funcionalidade documentada de lista de permissões de IP, lista de bloqueio, limitação de taxa ou início de sessão suspeito através da rota pública.
- Confirme que só são aceites informações de encaminhamento fornecidas por proxies fidedignos.
- Decida quem pode aceder a informações de auditoria e durante quanto tempo estas devem ser retidas.
Verificação 5: Teste carregamentos, limites de pedidos e pedidos de longa duração
Carregamentos grandes e pedidos lentos atravessam mais do que um limite. A aplicação pode impor o seu próprio limite de tamanho, enquanto o proxy pode impor outro. Com o middleware de buffering do Traefik, um pedido maior do que maxRequestBodyBytes não é encaminhado para o serviço e recebe HTTP 413. Um valor zero significa ilimitado, mas ilimitado não é automaticamente a escolha operacional correta.
O buffering altera o comportamento, além dos limites. O Traefik documenta que, quando o seu middleware de buffering está anexado, lê o corpo completo do pedido antes de o encaminhar e pode colocar corpos grandes de pedidos em buffer no disco de acordo com o limiar configurado. Avalie isto em função do tipo e do tamanho dos ficheiros que os seus utilizadores realmente precisam de enviar, em vez de utilizar um ficheiro de exemplo pequeno como único teste.
As operações de longa duração precisam das suas próprias evidências. Teste o fluxo de trabalho visível para o utilizador durante uma duração esperada e observe falhas na camada do navegador, do proxy e da aplicação. Um carregamento pequeno bem-sucedido não prova que uma importação, exportação ou outro pedido prolongado de dimensão considerável funcionará de forma fiável.
- Defina o maior ficheiro ou pedido normal para o serviço, além de um caso de rejeição ligeiramente maior.
- Teste um ficheiro próximo do limite de aceitação pretendido através do domínio público.
- Confirme onde um pedido de tamanho excessivo é rejeitado — no proxy ou na aplicação — e se a mensagem é compreensível.
- Analise as implicações para o disco caso os corpos dos pedidos possam ser colocados em buffer no disco.
- Teste de ponta a ponta uma ação de utilizador de longa duração esperada.
- Registe os limites configurados e observados em conjunto, para que alterações futuras não criem regressões acidentais.
Verificação 6: Confirme os requisitos de tempo real e streaming de ponta a ponta
Não assuma que todas as aplicações utilizam WebSockets, Server-Sent Events, respostas em streaming ou long polling da mesma forma. Primeiro, identifique a funcionalidade real que precisa de uma ligação persistente ou de streaming: notificações em direto, edição colaborativa, acesso a terminal, atualizações de painel, chat ou uma resposta gerada. Depois, teste essa funcionalidade através do domínio público final.
O Traefik documenta suporte para WebSocket e WebSocket seguro através de encaminhamento HTTP normal, incluindo o tratamento automático da atualização e a preservação de cabeçalhos WebSocket como Origin, Sec-WebSocket-Key e Sec-WebSocket-Version. Esta capacidade é útil, mas não elimina a necessidade de testar as próprias verificações de origem, autenticação, tratamento de sessões e comportamento de reconexão da aplicação.
Para funções de streaming e orientadas por eventos que não utilizam WebSockets, consulte a documentação da aplicação e do proxy relativamente ao comportamento de ligação relevante. Teste com o mesmo navegador, nome de anfitrião, configuração HTTPS e permissões de utilizador que os utilizadores de produção terão.
- Identifique a funcionalidade específica em tempo real de que a sua equipa necessita.
- Teste-a depois de iniciar sessão através do nome de anfitrião HTTPS público.
- Mantenha a funcionalidade ativa durante tempo suficiente para observar o comportamento normal de reconexão ou atualização.
- Teste com mais do que uma sessão de navegador se a funcionalidade envolver atualizações partilhadas.
- Verifique se os erros do navegador, os registos da aplicação e os registos do proxy apontam para o mesmo percurso de pedido quando ocorre uma falha.
- Não classifique uma funcionalidade como compatível até que o seu fluxo de trabalho real de utilizador tenha passado.
Perguntas frequentes
Todas as aplicações Docker podem funcionar atrás de um proxy reverso?
Não. A publicação de portas do Docker pode tornar um contentor acessível, mas a aplicação também tem de tratar corretamente o seu URL público, esquema HTTPS, detalhes de pedidos encaminhados, sessões e quaisquer carregamentos, callbacks ou ligações em tempo real necessários. Verifique estes comportamentos com a documentação oficial da aplicação e uma implementação de teste pelo percurso público.
Porque é que uma aplicação redireciona para HTTP ou para um nome de anfitrião interno atrás de um proxy?
Isto indica frequentemente que o URL externo canónico está em falta ou incorreto, ou que a aplicação não está a utilizar corretamente informações de proxy fidedigno sobre o anfitrião original e o esquema HTTPS. Defina o URL público documentado, configure o comportamento de proxy fidedigno quando a aplicação o suportar e volte a testar através do domínio público final.
Que cabeçalhos encaminhados devo verificar?
Verifique os cabeçalhos documentados pela aplicação. O Traefik adiciona automaticamente X-Forwarded-For, X-Real-Ip, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto e X-Forwarded-Server ao encaminhar por proxy. A RFC 7239 também define o cabeçalho normalizado Forwarded. Confie nessas informações apenas quando provêm de limites de proxy conhecidos.
Como devo testar a compatibilidade de carregamentos?
Carregue um ficheiro realista próximo do limite de produção pretendido através do endereço HTTPS público e, depois, teste um ficheiro maior que deva ser rejeitado. Identifique se a rejeição ocorre na camada do proxy ou da aplicação. Se utilizar buffering do Traefik, reveja a respetiva definição máxima do corpo do pedido e o comportamento de buffering para disco.
Os WebSockets precisam de uma configuração especial no proxy?
A resposta depende do proxy e da aplicação. O Traefik documenta suporte para WebSocket através de encaminhamento HTTP normal com tratamento automático de atualização. Ainda assim, teste a funcionalidade exata da aplicação que precisa de comunicação em tempo real através do domínio final, porque a autenticação, validação de origem, comportamento de reconexão e requisitos da aplicação variam.
Porque devem os URLs de redirecionamento OAuth ser testados depois de escolhido o domínio final?
O OAuth 2.0 exige que os pontos de redirecionamento sejam URIs absolutas e os servidores de autorização validam os URIs de redirecionamento fornecidos em relação aos valores registados. Nos fluxos de código de autorização, o redirect_uri utilizado no pedido de token tem de corresponder ao utilizado no pedido de autorização quando foi incluído. Registe e teste o URL exato de callback HTTPS público.
Fontes e leituras adicionais
- Port publishing and mapping — Docker
- EntryPoints Documentation — Traefik Labs
- Headers Documentation — Traefik Labs
- Buffering Documentation — Traefik Labs
- WebSocket User Guide — Traefik Labs
- Challenge Types — Internet Security Research Group / Let’s Encrypt
- RFC 7239: Forwarded HTTP Extension — RFC Editor / IETF
- RFC 6749: The OAuth 2.0 Authorization Framework — RFC Editor / IETF