Tutoriais de VPS
Nginx proxy_pass: manter, remover ou substituir o prefixo da API
O backend funciona diretamente, mas retorna 404 pelo Nginx? Compare três formas de proxy_pass e confira caminho upstream, parâmetros, requisições POST e redirecionamentos.

O backend funciona quando você o acessa diretamente, mas retorna 404 pelo Nginx. Antes de alterar o proxy, compare o caminho que chega à aplicação. O cliente solicita /api/users, enquanto o backend pode esperar /users ou já atender /api/users. Uma barra em proxy_pass pode encaminhar a requisição para outra rota.
Este guia trata de locations HTTP comuns com correspondência por prefixo: manter, remover ou substituir o início do caminho. Primeiro confirme a URL esperada pelo upstream. Adicionar rewrite, redirecionamento e fallback ao mesmo tempo dificulta descobrir onde a requisição foi alterada.
Teste as rotas reais do backend no VPS. Troque a porta de exemplo pelo endereço em que o serviço escuta. Dentro de um contêiner, 127.0.0.1 pode não representar o host nem outro contêiner.
curl -i 'http://127.0.0.1:3000/users?limit=1'
curl -i 'http://127.0.0.1:3000/api/users?limit=1'
curl -i 'https://app.example.com/api/users?limit=1'
sudo nginx -T
Um endpoint autenticado pode retornar 401 ou 403 sem credenciais; isso não prova que a rota não existe. Confira no log do backend o caminho, o método e o status, além do server e da location que atendem o domínio. Remova tokens, cookies e endereços internos sensíveis antes de compartilhar logs ou configurações.
Se o log atual registra $status e $upstream_status, compare o status enviado ao cliente com o do upstream. Quando o status upstream está vazio, investigue respostas locais, cache e se a requisição chegou ao proxy. Páginas de erro personalizadas podem esconder a origem; a aparência da página não basta para identificá-la.
Um 502 causado por um backend inacessível exige conferir endereço, porta e rede dos contêineres; veja o guia de erros 502 e 504. Alterar a barra normalmente não resolve uma conexão recusada.
Considere a requisição /api/users?limit=1, a location /api/ e nenhuma regra rewrite adicional:
| Valor de proxy_pass | Caminho recebido pelo upstream | Rota esperada no backend |
|---|---|---|
http://127.0.0.1:3000 | /api/users?limit=1 | Já inclui /api/ |
http://127.0.0.1:3000/ | /users?limit=1 | Começa em /users |
http://127.0.0.1:3000/v1/ | /v1/users?limit=1 | Precisa do prefixo /v1/ |
A diferença relevante é a presença de uma URI depois do endereço; / também é uma URI. A referência de proxy_pass do Nginx explica que, com URI, ela substitui a parte correspondente do prefixo normalizado. Sem URI, o caminho original é mantido, sujeito a regras específicas quando há uma reescrita interna.
location /api/ {
proxy_pass http://127.0.0.1:3000;
}
Se o backend já define /api/, não acrescente a / final neste exemplo. Ela removeria o prefixo: o backend receberia /users, que pode não existir.
location /api/ {
proxy_pass http://127.0.0.1:3000/;
}
O prefixo /api/ é substituído por /. Verifique esse mapeamento antes de adicionar outro rewrite. Se a API funcionar, mas a documentação ou o login continuarem redirecionando incorretamente, confira a URL pública da aplicação.
location /api/ {
proxy_pass http://127.0.0.1:3000/v1/;
}
A requisição /api/users chega a /v1/users. Mantenha / nos dois limites. Escrever /v1 pode concatenar o restante do caminho como /v1users, que é outra rota.
Estes são trechos alternativos de location. Escolha apenas o que corresponde ao backend e incorpore-o ao site existente. Preserve certificados, autenticação, cabeçalhos, limites de requisições e outras rotas. Não coloque os três no mesmo server. WebSocket e interfaces de streaming também precisam de configurações próprias de proxy.
Uma location de prefixo terminada em / e atendida por uma diretiva de proxy pode gerar um 301 automático para o mesmo caminho sem a barra. Em uma configuração como /api/, /api redireciona para /api/; veja o tratamento especial de location.
Examine a primeira resposta com curl sem -L. Seguir redirecionamentos automaticamente pode esconder o problema. Em callbacks de login e endpoints POST, confirme o método e o destino finais; não dependa de como um cliente específico trata o 301.
Se /api precisa existir como endpoint independente, defina uma correspondência exata com sua rota upstream. Não redirecione indiscriminadamente todas as requisições para uma versão com barra. Um prefixo normal /api/ também não trata /apiary como o mesmo caminho.
Os mapeamentos simples da tabela preservam os parâmetros do exemplo. Para POST, verifique também método, corpo e Content-Type. Um GET bem-sucedido não confirma que pedidos ou uploads funcionam. Revise diretivas existentes que alterem o método, o corpo ou os cabeçalhos do proxy.
Mudar a rota de entrada não atualiza automaticamente todas as URLs geradas pela aplicação. Redirecionamentos absolutos, recursos no HTML, Cookie Path e callbacks de login podem continuar usando a raiz original. Configure primeiro a URL pública ou o caminho-base oficialmente suportado pela aplicação; depois avalie se é necessário reescrever respostas no proxy.
Quando uma aplicação não suporta subcaminhos, um subdomínio separado costuma ser mais fácil de manter. Substituir globalmente cada / por /api/ no HTML pode também alterar recursos, APIs e links externos de forma incorreta.
Locations com expressões regulares ou nomeadas, proxy_pass com variáveis e requisições alteradas por rewrite ... break podem seguir regras diferentes. Se encontrar $request_uri, grupos de captura ou vários redirecionamentos internos, compare a configuração real com as definições oficiais.
Com várias locations, confirme se outra regra mais específica ou uma expressão regular assume a requisição. Preserve os registros originais de caminhos codificados, barras repetidas e parâmetros assinados para comparar cada caso. Os exemplos comuns acima não comprovam compatibilidade com codificação ou assinaturas.
Não transforme um 404 da API na página inicial do frontend. Mesmo com status 200, uma resposta HTML continuará falhando para um cliente que espera dados. Para arquivos estáticos ou atualização de uma SPA, consulte o guia de 404 em Vue e React.
Faça backup da configuração do site, valide a sintaxe e só então recarregue:
sudo nginx -t && sudo systemctl reload nginx
curl -i 'https://app.example.com/api/users?limit=1'
Use requisições de teste permitidas para verificar caminho upstream, parâmetros, método e corpo. Confira também redirecionamentos de login e recursos das páginas. Evite testes em produção que criem pedidos, cobrem pagamentos ou enviem mensagens.
O artigo original registra 12 verificações isoladas com uma instalação existente do Nginx 1.19.6 e um backend simulado: os três mapeamentos, parâmetros, conteúdo POST e o 301 automático. Quando o backend aceitava apenas /root-only, manter o prefixo externo retornava 404 e removê-lo retornava 200. Essa versão local não é uma recomendação de instalação em produção. Os testes não cobrem autenticação real, TLS, CDN, WebSocket, login no navegador ou reescrita de URLs nas respostas.