Nginx proxy reverso com FastAPI: publicar uma API com HTTPS

Publicado em 2026-10-26 por frfrand

Configurar Nginx e Uvicorn em um VPS com TLS e upstream local

Nginx proxy reverso com FastAPI: publicar uma API com HTTPS

Sua API FastAPI responde em localhost:8000, mas você quer que um cliente a abra em https://api.ejemplo.com. O Nginx pode receber HTTPS e encaminhar para a porta interna sem expor o Uvicorn diretamente à Internet.

Vamos convertê-lo em um procedimento que você pode usar em um VPS real. O objetivo é entender por que funciona, como testá-lo e qual problema surge se uma parte estiver mal configurada.

O que significa Nginx reverse proxy para FastAPI e quando você precisa

O reverse proxy é uma camada pública que gerencia conexões e pode direcionar requisições para vários serviços de acordo com o domínio. O FastAPI continua sendo executado como um processo privado, normalmente supervisionado pelo systemd ou dentro de um contêiner. O HTTPS termina no Nginx e o aplicativo recebe a solicitação interna.

Antes de alterar qualquer coisa em produção, anote o estado atual: IP, domínio, porta, serviço afetado e hora do último deploy. Uma modificação isolada é fácil de verificar; cinco mudanças simultâneas tornam mais difícil reconstruir o que aconteceu.

Configuração ou comandos de exemplo

# /etc/nginx/sites-available/api.ejemplo.com
server {
    listen 80;
    server_name api.ejemplo.com;
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
# Validar sintaxis ANTES de recargar
sudo nginx -t
sudo systemctl reload nginx

Os domínios, IPs, caminhos e nomes são ilustrativos. Não copie uma configuração inteira sobre a atual sem comparar primeiro. Nos exemplos que incluem portas ou firewall, certifique-se de preservar o acesso administrativo.

Como eu faria passo a passo

Preparação. Verifique se o FastAPI funciona localmente com curl http://127.0.0.1:8000/health.
Passo 2. Crie um server block com server_name correspondente ao DNS do domínio.
Passo 3. Configure o proxy para a porta interna e os cabeçalhos adequados.
Passo 4. Ative o HTTPS com um certificado válido; o bloco HTTP é apenas o ponto de partida.
Verificação. Verifique nginx -t, recarregue e teste pelo domínio a partir de outra rede.

Quando terminar, verifique a operação real a partir de outra conexão. Por exemplo, para uma API não basta abrir o navegador: execute uma solicitação de leitura, uma gravação em um banco de teste e consulte os logs do processo.

Exemplo de um projeto de verdade

Um aplicativo de reservas tem React em app.ejemplo.com e FastAPI em api.ejemplo.com. Ambos os domínios apontam para o mesmo VPS, mas o Nginx roteia cada um para seu serviço correspondente. O PostgreSQL permanece no ambiente privado.

A lição é simples: uma configuração de infraestrutura não vive isolada do aplicativo. O frontend, o servidor, o banco de dados e os workers se conectam, então medir onde começa a falha é mais útil do que reiniciar tudo.

O erro que evitaria

Não confunda proxy_pass com a URL usada pelo navegador. Se o FastAPI usar autenticação baseada em cookies ou links gerados, verifique os cabeçalhos e a configuração de proxies confiáveis. Nunca habilite --proxy-headers sem controlar quem pode se conectar ao processo.

Quando trabalha com servidores de clientes, guarde um backup ou procedimento de reversão antes de mudanças que afetem dados, rede ou certificados. E se não souber quais permissões uma operação precisa, evite executar como root apenas para parar de mostrar erros.

Como isso se relaciona com o ArduMaker?

Em um VPS do ArduMaker você pode administrar domínio, HTTPS e serviço de backend mantendo a porta 8000 interna. Isso ajuda a hospedar vários aplicativos sem abrir uma porta por projeto.

Em um caso típico você pode criar um VPS para o aplicativo, implantar via Git, associar domínio HTTPS e administrar o backend e os bancos de dados necessários. As ferramentas ajudam a centralizar operações, mas é preciso entender qual porta e processo cumpre cada função.

Perguntas que aparecem quando você testa

Como saber se a falha é de DNS ou do serviço? Consulte primeiro a resolução, depois a conexão à porta e finalmente a resposta do aplicativo. Essa ordem evita confundir problemas diferentes.

Posso expor um banco de dados para facilitar a manutenção? Melhor projetar acesso privado ou túneis autenticados quando possível. Expor uma porta não substitui as permissões do mecanismo nem o firewall.

O que devo documentar? A configuração esperada, como verificar e como voltar ao estado anterior. Esse documento ajuda mais do que uma lista de comandos sem contexto.

Referências

Em resumo: uma boa configuração de rede ou servidor é aquela que você consegue explicar, verificar e recuperar quando algo falha.