Configuração de reverse proxy nginx explicada
Aprenda a montar um server block nginx no Ubuntu 24.04, com proxy_pass, quatro headers, WebSocket, barras finais e uploads sem surpresas.
O que uma configuração de reverse proxy nginx faz
Um reverse proxy nginx recebe os pedidos que chegam às portas 80 e 443 e encaminha cada um para uma aplicação que já está a escutar numa porta local. Depois, devolve ao navegador a resposta dessa aplicação. A configuração é um único bloco server, e esse bloco é curto. Quase toda a dificuldade está em cinco ou seis linhas que informam a aplicação sobre a identidade real do cliente e o protocolo usado por esse cliente.
Tudo o que se segue é configurado de raiz no Ubuntu 24.04, usando o pacote nginx da distribuição. O ponto de partida é uma aplicação que já responde em 127.0.0.1:3000. Se ainda não escolheu um proxy, leia primeiro como o nginx se compara com o Caddy e o Traefik. O que se segue mostra a configuração nginx, linha a linha.
Execute estas configurações no seu próprio servidor. Teste cada alteração com sudo nginx -t antes de recarregar o serviço e leia o resultado apresentado.
Onde o nginx mantém a configuração no Ubuntu
sudo apt update
sudo apt install -y nginx
ls -l /etc/nginx/sites-enabled/O ficheiro principal é /etc/nginx/nginx.conf. Define opções globais dentro de um bloco http { } e inclui depois dois diretórios: /etc/nginx/conf.d/*.conf e /etc/nginx/sites-enabled/*. No Ubuntu e no Debian, crie um ficheiro por site em /etc/nginx/sites-available/ e ative-o com um link simbólico para /etc/nginx/sites-enabled/. Apagar o link simbólico desativa o site, mas mantém o ficheiro.
Duas diretivas usadas mais tarde só funcionam no contexto http, nunca dentro de um bloco server: map e upstream. Coloque-as no seu próprio ficheiro em /etc/nginx/conf.d/, porque esse diretório é incluído ao nível http.
O pacote instala um site ativo chamado default. Está marcado como default_server, o que significa que responde a qualquer pedido cujo cabeçalho Host não corresponda a nenhum server_name na sua configuração. Enquanto permanecer ativo, um pedido que não corresponda aos seus nomes é encaminhado para esse site, e não para a sua aplicação. Remova o link simbólico quando o seu próprio site estiver a funcionar.
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginxO menor bloco de servidor que faz proxy de uma aplicação
server {
listen 80;
listen [::]:80;
server_name app.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
}
}Guarde-o como /etc/nginx/sites-available/app.example.com, ative-o e carregue a configuração.
sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
curl -sI -H 'Host: app.example.com' http://127.0.0.1/listen 80; associa o serviço a IPv4 e listen [::]:80; associa-o a IPv6. Se omitir a segunda linha, todas as ligações IPv6 ao servidor são recusadas. Um navegador dual-stack cuja consulta ao DNS (domain name system) devolve um registo AAAA normalmente recorre a IPv4 e esconde o problema, mas um visitante que use apenas IPv6, ou um cliente que tente apenas o primeiro endereço recebido, vê uma ligação recusada, enquanto todos os utilizadores IPv4 veem um site funcional. O erro que recebe diz: "funciona comigo".
server_name é comparado com o cabeçalho Host enviado pelo navegador. Pode listar vários nomes, separados por espaços. Se nenhum bloco corresponder, o nginx usa o bloco que estiver default_server, razão pela qual foi necessário remover o site instalado pelo pacote.
location / é uma correspondência por prefixo no caminho do pedido, e / corresponde a todos os caminhos. proxy_pass é o endereço ao qual o nginx abre uma ligação. Mantenha a aplicação associada a 127.0.0.1 para que o único acesso seja através do nginx. Se a aplicação estiver a correr num contentor, publique-a como 127.0.0.1:3000:3000 e não como 3000:3000, porque o Docker escreve as suas próprias regras e publica as portas diretamente para além do ufw, pelo que uma porta publicada sem restrições fica acessível a partir da Internet, independentemente do que o ufw indicar. A documentação do Docker define a cadeia DOCKER-USER como o local para filtrar esse tráfego, mas associar a aplicação a 127.0.0.1 é a correção mais simples.
A linha curl envia o cabeçalho Host correto a partir do próprio servidor, permitindo testar o bloco antes de o DNS apontar para algum destino.
O que o nginx envia para o upstream quando não configura mais nada
proxy_pass, sozinho, oculta quatro informações da sua aplicação.
O pacote nginx 1.24.0 distribuído com o Ubuntu 24.04 usa HTTP/1.0 para comunicar com o backend por predefinição e envia Connection: close. Assim, cada pedido abre uma nova ligação ao upstream e não é possível fazer uma atualização de protocolo. O nginx 1.29.7, lançado em março de 2026, alterou essas predefinições: a partir dessa versão, o nginx usa HTTP/1.1 no upstream, não envia o cabeçalho Connection e reutiliza ligações agrupadas em vez de abrir uma nova para cada pedido. Mesmo nessa versão, uma atualização para WebSocket ainda precisa dos cabeçalhos apresentados mais abaixo.
O cabeçalho Host é reescrito com o valor de proxy_pass, que é 127.0.0.1:3000. Uma aplicação que cria ligações absolutas com base em Host passa a produzir ligações que ninguém fora do servidor consegue abrir.
A ligação que chega à aplicação vem do nginx, por isso a aplicação vê 127.0.0.1 como endereço do cliente. Cada linha de log e cada limite de taxa dentro da aplicação regista então o proxy em vez do visitante.
A aplicação não consegue saber que o navegador usou HTTPS, porque a ligação que recebeu é HTTP simples num endereço de loopback.
Quatro linhas corrigem tudo isso.
Os quatro cabeçalhos a definir e o que cada um permite ao backend ver
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}Host transporta o nome introduzido pelo visitante. $host é o nome do pedido, sem a porta e com as letras convertidas para minúsculas. Defina-o para que a aplicação crie URLs absolutos corretos, como o redirecionamento depois de um início de sessão ou a ligação numa mensagem de correio eletrónico para repor a palavra-passe. Se o omitir, a aplicação assume 127.0.0.1:3000 como o seu próprio nome. O proxy_redirect predefinido do nginx reescreve um cabeçalho Location ou Refresh que aponte para o endereço proxy_pass, por isso um redirecionamento simples depois do início de sessão normalmente continua a chegar ao destino correto. No entanto, as URLs absolutas que a aplicação escreve nas páginas e nas mensagens de correio eletrónico, como a ligação para repor a palavra-passe, apontam para 127.0.0.1:3000, um endereço que o navegador do visitante não consegue abrir. Se a aplicação também precisar da porta, por exemplo, porque é servida na porta 8080, use $http_host, que é o cabeçalho exatamente como foi enviado pelo cliente.
X-Real-IP transporta um valor: $remote_addr, o endereço a partir do qual o nginx aceitou a ligação. As aplicações leem-no para os seus próprios logs de acesso e para a sua própria limitação de taxa.
X-Forwarded-For transporta uma lista. $proxy_add_x_forwarded_for acrescenta $remote_addr ao valor que o cliente já colocou nesse cabeçalho, pelo que o valor fica separado por vírgulas e a entrada adicionada pelo nginx é a última. Esse detalhe determina se o cabeçalho pode ser considerado fiável: um cliente pode enviar qualquer X-Forwarded-For que queira, por isso uma aplicação que leia a primeira entrada pode receber qualquer endereço. Quando o nginx é o servidor de edge, escreva $remote_addr em vez disso e descarte a versão do cliente. Quando existe uma CDN ou outro proxy à frente, use set_real_ip_from e real_ip_header do módulo realip, para que $remote_addr passe a ser o verdadeiro endereço do cliente.
X-Forwarded-Proto transporta http ou https. Os frameworks leem-no para decidir se devem marcar os cookies como Secure e se devem forçar um redirecionamento para HTTPS. Se o omitir num site TLS e a aplicação estiver configurada para forçar HTTPS, verá http, responderá com um redirecionamento para o endereço HTTPS, receberá o pedido seguinte através do nginx, continuará a ver http e redirecionará novamente. O navegador desiste e mostra ERR_TOO_MANY_REDIRECTS.
Repetir estas quatro linhas em cada location faz com que fiquem diferentes ao longo do tempo. Coloque-as num único ficheiro e inclua-o.
# /etc/nginx/snippets/proxy-headers.conf
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;location / {
include snippets/proxy-headers.conf;
proxy_pass http://127.0.0.1:3000;
}A herança neste caso tem uma armadilha. Uma location herda as diretivas proxy_set_header do seu bloco server apenas enquanto não define nenhuma diretiva própria. Se adicionar um proxy_set_header dentro da location, todos os cabeçalhos definidos ao nível do server são eliminados nessa location. Por isso, mantenha todos no mesmo nível ou include o snippet em cada location que faz proxy.
Por que minha aplicação WebSocket conecta e depois desconecta?
Isso acontece porque as configurações padrão impedem o upgrade, e o tempo limite padrão de leitura fecha um túnel inativo depois de 60 segundos. Um WebSocket começa como uma solicitação HTTP que contém Upgrade: websocket e Connection: Upgrade. Esses são cabeçalhos hop-by-hop, o que significa que o proxy deve consumi-los em vez de encaminhá-los. Além disso, no nginx 1.24.0 do Ubuntu 24.04, o protocolo upstream padrão é HTTP/1.0, que não tem nenhum mecanismo de upgrade. É necessário restaurar ambos manualmente.
O map deve ficar no contexto http, em um arquivo próprio.
# /etc/nginx/conf.d/websocket.conf
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}Depois, configure o location.
location / {
include snippets/proxy-headers.conf;
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}O map existe para que um location possa atender os dois tipos de tráfego. Em uma solicitação comum, $http_upgrade fica vazio, e $connection_upgrade se torna close. Em uma solicitação de upgrade, ele contém websocket, e o cabeçalho enviado ao upstream é Connection: upgrade. Definir proxy_set_header Connection "upgrade"; diretamente envia esse cabeçalho também em todas as solicitações de páginas comuns, e alguns backends respondem a esse tipo de solicitação com 400.
proxy_http_version 1.1; é o padrão a partir do nginx 1.29.7. Nessas versões, portanto, a linha não altera nada e não causa problemas. No pacote 1.24.0, ela é obrigatória. As linhas Upgrade e Connection são obrigatórias em todas as versões, porque o nginx nunca encaminha esses dois cabeçalhos por conta própria.
proxy_read_timeout é o que causa os relatos de que “carrega e depois para de atualizar”. O valor padrão é 60 segundos, e ele mede o intervalo entre duas leituras do backend, não a duração da conexão. Um WebSocket que permanece sem atividade por 60 segundos é fechado pelo nginx, e o console do navegador mostra o fechamento do socket com o código 1006. Aplicações que enviam seu próprio heartbeat com intervalo inferior a um minuto nunca percebem o problema. As que não enviam encerram exatamente depois de um minuto. Editores colaborativos e dashboards são os primeiros a apresentar esse problema; uma instância do n8n hospedada localmente atrás de HTTPS é um exemplo comum.
Por que uma barra final em proxy_pass altera as URLs?
A regra cabe numa frase. Se proxy_pass terminar com uma URI (identificador uniforme de recursos), mesmo que seja apenas /, o nginx remove a parte do caminho do pedido que correspondeu ao prefixo location e coloca essa URI no lugar. Se proxy_pass terminar no host e na porta, o caminho do pedido é encaminhado sem alterações.
location /app/ {
proxy_pass http://127.0.0.1:3000/;
}Um pedido para /app/status chega ao backend como /status.
location /app/ {
proxy_pass http://127.0.0.1:3000;
}Um pedido para /app/status chega ao backend como /app/status.
A forma adequada depende da aplicação. Uma aplicação com uma configuração de caminho base ou subpasta precisa da segunda forma, com essa configuração definida para /app. Uma aplicação que não conhece prefixos precisa da primeira. A primeira forma tem um efeito imediato: o HTML devolvido pela aplicação continua a conter caminhos absolutos, como /static/main.css, o navegador pede-os na raiz do site, nenhuma location corresponde e a página é apresentada sem estilos. O separador de rede do navegador mostra esses pedidos de recursos a devolverem 404. A correção é usar a configuração de caminho base da própria aplicação ou adicionar uma segunda location /static/ a apontar para o mesmo backend.
Uma location com expressão regular não pode conter uma URI em proxy_pass. sudo nginx -t recusa a configuração e indica o motivo: "proxy_pass" cannot have URI part in location given by regular expression, or inside named location, or inside "if" statement, or inside "limit_except" block.
Esta classe de problemas desaparece quando cada aplicação recebe o seu próprio nome, app.example.com, encaminhado por proxy a partir de location /. Os subcaminhos só compensam quando não é possível adicionar registos DNS.
Como coloco mais de um backend atrás do mesmo nome?
Com um bloco upstream. Ele pertence ao contexto http. Por isso, escreva-o antes do bloco server no mesmo ficheiro ou em /etc/nginx/conf.d/.
upstream app_backend {
least_conn;
server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
server 127.0.0.1:3001 max_fails=3 fail_timeout=30s;
keepalive 32;
}A diretiva location identifica-o: proxy_pass http://app_backend;.
O método predefinido é round robin. least_conn envia cada pedido para o backend com menos ligações ativas. Isto é adequado para pedidos com durações diferentes. ip_hash fixa o endereço de um cliente a um backend. Precisa de ip_hash quando a aplicação mantém as sessões na própria memória. Com round robin entre dois backends deste tipo, as pessoas são terminadas sessão aleatoriamente quando os pedidos chegam à instância que ainda não as tinha visto. A melhor solução é mover as sessões para armazenamento partilhado.
max_fails=3 fail_timeout=30s significa que três tentativas falhadas em 30 segundos retiram esse servidor durante 30 segundos. Quando todos os servidores do bloco estão nesse estado, os clientes recebem 502 e o registo de erros indica no live upstreams while connecting to upstream.
keepalive 32 mantém abertas até 32 ligações inativas aos backends por processo worker. Isto elimina o handshake TCP da maioria dos pedidos. No Ubuntu 24.04 com a versão 1.24.0, esta linha ativa a cache. Desde o nginx 1.29.7, a cache está ativa por predefinição. No entanto, a predefinição documentada é keepalive 32 local;, e o parâmetro local impede que as ligações em cache sejam partilhadas entre diferentes locations. Assim, no 1.29.7 e posteriores, um keepalive 32; isolado não se limita a repetir a predefinição. Ao omitir local, permite que qualquer location que faça proxy para o mesmo servidor upstream reutilize uma ligação agrupada. Isto altera o comportamento predefinido. Nessas versões, omita a linha ou escreva keepalive 32 local; para manter a predefinição. Escreva-a sem parâmetros apenas se quiser ativar essa partilha. O parâmetro local é novo no 1.29.7. Por isso, o pacote 1.24.0 não o aceita. Para backends HTTP, a configuração recomendada pelo nginx para o agrupamento é definir proxy_http_version como 1.1 ou como 2 no nginx 1.29.4 e posteriores, com o cabeçalho Connection removido antes de ser enviado ao upstream. O nginx também documenta ligações persistentes HTTP/1.0, criadas ao enviar Connection: Keep-Alive para um backend que as suporte, mas não recomenda esse método. Desde o 1.29.7, ambas as partes da configuração recomendada são predefinidas. No 1.24.0, adicione proxy_http_version 1.1; e proxy_set_header Connection ""; à location manualmente. Caso contrário, o nginx continua a enviar HTTP/1.0 com Connection: close e o agrupamento nunca é reutilizado. Se a mesma location também utilizar o mapa WebSocket, altere o caso vazio de close para uma cadeia vazia. Assim, os pedidos normais não transportam o cabeçalho Connection e a ligação agrupada é reutilizada.
map $http_upgrade $connection_upgrade {
default upgrade;
'' '';
}Os nomes dentro de um bloco upstream são resolvidos quando o nginx inicia. Se o backend for um contentor que receba um endereço novo quando reinicia, o nginx continua a utilizar o endereço antigo até ser recarregado. O nginx 1.27.3 e posteriores podem acompanhar essas alterações sem recarregar o serviço, através de um resolver, de um zone no bloco upstream e do parâmetro resolve em cada linha server. No entanto, o pacote 1.24.0 é anterior a essa funcionalidade. Numa rede Docker, pode transferir a resolução para o momento do pedido através do resolver incorporado.
resolver 127.0.0.11 valid=10s;
set $backend http://app:3000;
proxy_pass $backend;Quando os contentores aparecem e desaparecem com frequência suficiente para obrigarem a editar o nginx continuamente, um proxy que leia labels dos contentores é uma opção melhor. Traefik à frente de várias aplicações Docker Compose cria as rotas a partir dos próprios contentores.
Por que os uploads falham com 413 Request Entity Too Large?
client_max_body_size tem o valor padrão de 1 megabyte. Um corpo de pedido maior é recusado pelo nginx com um erro 413, e o log de erros regista client intended to send too large body. Aumente este valor no bloco server ou no bloco location onde os uploads ocorrem.
client_max_body_size 512m;O valor 0 desativa completamente esta verificação. Com 512m, o nginx continua a recusar corpos de pedido acima desse limite. Por isso, um erro 413 que persista depois desta alteração não identifica o backend como origem. Verifique o valor efetivo de client_max_body_size no location que trata o upload e consulte o log de erros do nginx antes de verificar o limite de upload da própria aplicação.
Por padrão, o nginx lê todo o corpo do pedido antes de abrir a ligação ao upstream. Primeiro, grava os dados maiores num ficheiro temporário em disco. Isso protege a aplicação contra clientes lentos, porque o backend recebe o upload à velocidade total da rede local. Para uploads muito grandes, pode transmitir o corpo diretamente.
proxy_request_buffering off;Para uploads com codificação chunked em HTTP/1.1 no pacote 1.24.0, defina também proxy_http_version 1.1; nesse location; caso contrário, o nginx continua a armazenar o corpo em buffer. O backend recebe então o corpo à medida que ele chega e tem de conseguir processá-lo dessa forma. Depois de o nginx começar a enviar o corpo para o upstream, não pode repetir o pedido noutro upstream.
client_body_timeout, que tem o valor padrão de 60 segundos, aplica-se ao intervalo entre duas leituras consecutivas do corpo, não ao upload completo. Um upload lento mas contínuo não excede esse limite. Um upload parado é interrompido.
Armazenamento temporário das respostas e a configuração que interrompe a saída em tempo real
proxy_buffering está ativado por padrão e, normalmente, é o comportamento pretendido. O nginx lê a resposta da aplicação à mesma velocidade a que a aplicação a consegue escrever, armazena-a e envia-a para um cliente lento ao ritmo desse cliente. O processo de trabalho da aplicação termina mais cedo, em vez de permanecer ocupado durante toda a transferência lenta.
Isto interrompe as respostas em fluxo contínuo. Os eventos enviados pelo servidor e a saída de logs em tempo real não mostram dados ao leitor até um buffer ficar cheio. Desative o armazenamento temporário apenas nessa localização.
proxy_buffering off;Se controlar a aplicação, a melhor opção é enviar o cabeçalho X-Accel-Buffering: no apenas nas respostas em fluxo contínuo. O nginx lê esse cabeçalho em cada resposta e desativa o armazenamento temporário apenas para ela. Assim, as páginas comuns mantêm essa vantagem.
Quando o log de erros indica upstream sent too big header while reading response header from upstream, os cabeçalhos da resposta não couberam num único buffer. proxy_buffer_size usa por padrão uma única página de memória, com 4 ou 8 kilobytes, dependendo da plataforma. Cookies longos ou cabeçalhos de autenticação grandes excedem esse limite. Aumente os dois valores.
proxy_buffer_size 16k;
proxy_buffers 8 16k;Onde o TLS deve ser configurado nesta configuração?
No Nginx, à frente de tudo o que foi apresentado acima. O TLS (segurança da camada de transporte) termina no proxy, e a ligação do Nginx à aplicação continua como HTTP simples através do endereço de loopback, onde nenhum outro dispositivo da rede a pode ler. A aplicação fica a saber que o visitante usou HTTPS através de X-Forwarded-Proto, o quarto dos quatro cabeçalhos.
Não escreva manualmente os caminhos dos certificados. Aponte o registo DNS para o servidor, abra a firewall e deixe o Certbot editar este mesmo bloco de servidor: ele adiciona a linha listen 443 ssl com os caminhos ssl_certificate e também um redirecionamento da porta 80. Emitir um certificado Let's Encrypt para o Nginx com o Certbot explica a emissão e o temporizador de renovação.
sudo ufw allow 'Nginx Full'
sudo ufw statusNginx Full é um perfil de aplicação instalado pelo pacote do Nginx e abre as portas 80 e 443 em conjunto. A porta 80 tem de continuar aberta para o desafio de renovação HTTP-01, mesmo depois de todos os visitantes serem redirecionados para HTTPS.
Teste a configuração e depois recarregue
sudo nginx -t
sudo systemctl reload nginxnginx -t analisa todos os ficheiros incluídos e indica se o teste foi bem-sucedido ou apresenta o ficheiro e a linha onde parou. Leia essa saída antes de recarregar. Um recarregamento com uma configuração inválida não é aplicado: o nginx continua a servir a configuração anterior, por isso o site permanece disponível enquanto a alteração não produz qualquer efeito. systemctl restart comporta-se de forma diferente e pior, porque um reinício encerra primeiro o servidor em execução. Assim, um erro de configuração deixa o nginx completamente parado. Por predefinição, recarregue a configuração e reserve o reinício para as alterações que realmente o exigem.
sudo tail -f /var/log/nginx/error.log
sudo ss -lntp | grep -E ':(80|443|3000)'A linha ss mostra qual processo mantém cada porta aberta. Assim, pode confirmar que a aplicação está realmente a escutar no local indicado por proxy_pass.
As falhas que você encontrará na prática
502 Bad Gateway, com connect() failed (111: Connection refused) while connecting to upstream no log de erros. Não há nenhum processo a escutar no endereço indicado em proxy_pass. A aplicação está parada, está associada a outra porta ou está associada a um endereço interno do contentor que o host não consegue alcançar.
502 com no live upstreams while connecting to upstream. Todos os servidores do bloco upstream estão atualmente marcados como falhados por max_fails. Corrija os backends. O nginx tenta novamente quando fail_timeout expira.
504 Gateway Time-out, com upstream timed out (110: Connection timed out) while reading response header from upstream. O backend aceitou a ligação e depois não enviou nada durante proxy_read_timeout segundos. Aumentar o timeout é correto para um relatório genuinamente lento, mas está errado quando a aplicação está bloqueada.
Todos os caminhos devolvem 404 pela aplicação. A regra da barra final reescreveu o caminho. Compare o caminho registado pela aplicação com o caminho solicitado.
É apresentado um site diferente. server_name não corresponde ao cabeçalho Host, por isso o pedido passou para o bloco default_server.
A página carrega, mas a interface bloqueia após cerca de um minuto. Este é o caso de WebSocket: falta a configuração de Upgrade ou proxy_read_timeout continua definido como 60 segundos.
FAQ
Porque é que o nginx devolve 502 Bad Gateway depois de eu adicionar proxy_pass?
O nginx não conseguiu abrir uma ligação ao endereço em proxy_pass. O log de erros em /var/log/nginx/error.log indica a causa: connect() failed (111: Connection refused) while connecting to upstream significa que não há nada a escutar nesse endereço, e no live upstreams significa que todos os servidores num bloco upstream foram marcados como falhados. Execute sudo ss -lntp | grep 3000 para ver qual é o processo que ocupa a porta e em que endereço está ligado. Uma aplicação ligada a um endereço interno do contentor, ou a uma porta diferente da configurada, produz sempre este erro.
Porque é que a minha aplicação se desliga após cerca de um minuto atrás do nginx?
A ligação é um WebSocket e proxy_read_timeout ainda tem o valor predefinido de 60 segundos, que mede o intervalo entre duas leituras do backend. Um socket sem tráfego é fechado pelo nginx e a consola do browser apresenta o código de fecho 1006. Defina proxy_http_version 1.1 (o valor predefinido desde o nginx 1.29.7, mas não no pacote 1.24.0 distribuído pelo Ubuntu 24.04), encaminhe Upgrade e Connection com um map em $http_upgrade, e aumente proxy_read_timeout para algo como 3600s. Sem o cabeçalho Upgrade, a atualização nunca ocorre, pelo que a aplicação recorre a polling ou não apresenta atualizações em tempo real.
A barra final em proxy_pass é importante?
Sim, e altera o caminho que o backend recebe. Com location /app/ e proxy_pass http://127.0.0.1:3000/, um pedido para /app/status chega ao backend como /status, porque qualquer URI depois do host e da porta substitui o prefixo correspondente ao location. Remova essa barra final e o mesmo pedido chega como /app/status. Remover o prefixo quebra frequentemente as ligações para os próprios recursos da aplicação. Essas ligações permanecem absolutas e acabam por devolver 404 na raiz do site. Por isso, numa aplicação com uma definição de caminho base, é preferível usar a forma que mantém o caminho.
Porque é que o log da minha aplicação regista 127.0.0.1 como o endereço IP de todos os visitantes?
Porque a ligação recebida pela aplicação vem realmente do nginx, através do endereço de loopback. O endereço do visitante só chega à aplicação num cabeçalho que configure: proxy_set_header X-Real-IP $remote_addr; para um valor único e proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; para a cadeia acrescentada. Depois, a aplicação tem de ser configurada para confiar nesses cabeçalhos. Lembre-se de que um cliente pode enviar o seu próprio X-Forwarded-For. Por isso, quando o nginx é o servidor de edge, substitua esse valor por $remote_addr em vez de o acrescentar.
Preciso de TLS na ligação entre o nginx e a minha aplicação?
Não, se a aplicação estiver no mesmo servidor e ligada a 127.0.0.1, porque esse tráfego nunca sai da máquina. Termine o TLS no nginx, mantenha proxy_pass em HTTP simples através do loopback e envie X-Forwarded-Proto $scheme para a aplicação saber que o visitante usou HTTPS. Se o backend estiver noutro host, através de uma rede que não controla, essa ligação precisa da sua própria proteção. Pode usar HTTPS até ao backend ou um túnel privado entre as duas máquinas.