Tutoriais de VPS
FastAPI na VPS: Compose, PostgreSQL, Nginx e recuperação
Implante FastAPI e PostgreSQL com Docker Compose, portas privadas e Nginx HTTPS. Configure contêineres sem root, saúde, migrações Alembic, backups verificados, restauração e rollback seguro.

Rodar fastapi dev localmente é só o começo. Uma API pública precisa de supervisão, banco pronto, HTTPS, migrações que interrompam a implantação em caso de falha e backups restauráveis. Esta estrutura usa uma VPS Linux: Docker Compose gerencia FastAPI e PostgreSQL 18, a porta da aplicação fica em 127.0.0.1 no host e o Nginx do host termina HTTPS.
Use a estrutura com um projeto existente ou como base de implantação. O artigo original informa verificações estáticas da configuração; esse registro histórico não representa um novo teste de implantação nesta edição. Os recursos sugeridos são pontos de partida, não resultados de carga.
Fluxo de requisições:
浏览器或客户端 -> 80/443 -> Nginx -> 127.0.0.1:8000 -> FastAPI 容器
-> PostgreSQL 容器
Não publique PostgreSQL nem a porta 8000 na internet. Libere somente o acesso necessário a SSH, HTTP e HTTPS.
| Uso | Recursos iniciais | Workers iniciais | O que observar |
|---|---|---|---|
| Testes ou API interna pouco usada | 1–2 vCPU, 2 GB RAM, 30 GB SSD | 1 | Memória de build e espaço livre |
| API pequena em produção | 2 vCPU, 4 GB RAM, 50 GB SSD | 2 | Memória por processo e conexões |
| Cálculo intensivo ou inferência | Dimensionar conforme a tarefa | Começar com 1 | CPU, memória do modelo e timeouts |
Cada worker carrega a aplicação e seus próprios pools. Com 500 MB por processo, quatro podem chegar perto de 2 GB antes dos outros serviços. Comece com 1–2 e meça requisições reais.
Prepare:
- Ubuntu 24.04 ou outra distribuição Linux com suporte;
- Docker Engine e o plugin Compose;
- um domínio apontando para a VPS, como
api.example.com; - firewall do provedor e UFW permitindo o acesso necessário a 22, 80 e 443, sem publicar 8000 ou 5432;
- um projeto com
/healthze ambiente de migração Alembic inicializado.
Se necessário, siga o guia Docker para VPS. O diretório usado será /opt/fastapi-app. Prepare os arquivos com uma conta administrativa que possa escrever nesse diretório de root; a aplicação no contêiner roda sem root.
Crie os diretórios de implantação e backup privado:
sudo install -d -o root -g root -m 755 /opt/fastapi-app
cd /opt/fastapi-app
sudo install -d -o root -g root -m 700 backups
Estrutura sugerida:
/opt/fastapi-app/
├── app/
│ ├── __init__.py
│ └── main.py
├── alembic/
├── alembic.ini
├── compose.yaml
├── Dockerfile
├── .dockerignore
├── .env
└── requirements.txt
Construa a partir de uma imagem oficial do Python. A antiga tiangolo/uvicorn-gunicorn-fastapi foi descontinuada. Com uv, registre as versões exatas em uv.lock e exporte antes do build:
uv add "fastapi[standard]" sqlalchemy "psycopg[binary]" alembic pydantic-settings
uv export --format requirements-txt --no-dev --no-emit-project \
--output-file requirements.txt
Se o projeto já usa Poetry, pip-tools ou outra ferramenta, mantenha-a. Versione o lockfile e teste atualizações. Confira a compatibilidade da aplicação e de suas dependências com Python 3.14 antes de escolher a imagem do exemplo.
Forneça uma verificação de vida barata e independente de serviços externos:
from fastapi import FastAPI
app = FastAPI()
@app.get("/healthz", include_in_schema=False)
def healthz() -> dict[str, str]:
return {"status": "ok"}
A prontidão do banco pode usar um /readyz separado. Não devolva segredos, strings de conexão nem stack traces. Esse endpoint não cria modelos ou migrações: configure o ambiente Alembic, os metadados e a conexão PostgreSQL no projeto real.
Salve /opt/fastapi-app/Dockerfile:
FROM python:3.14-slim
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
RUN groupadd --system --gid 10001 app \
&& useradd --system --uid 10001 --gid app --home-dir /app app
WORKDIR /app
COPY requirements.txt ./requirements.txt
RUN pip install --no-cache-dir --upgrade -r requirements.txt
COPY --chown=app:app . .
USER app
EXPOSE 8000
CMD ["fastapi", "run", "app/main.py", "--host", "0.0.0.0", "--port", "8000"]
Use build em várias etapas quando houver dependências compiladas, deixando gcc, headers e caches fora da imagem final. Atualize a imagem base e registre commit e identidade da imagem implantada.
Exclua pelo menos estes caminhos em .dockerignore:
.git
.env
__pycache__/
*.py[cod]
.pytest_cache/
.venv/
backups/
Excluir .env evita embutir segredos; o Compose os fornece na execução.
Gere a senha uma única vez, somente para uma instalação nova:
cd /opt/fastapi-app
umask 077
db_password=$(openssl rand -base64 36 | tr -d '\n')
cat > .env.partial <<EOF
POSTGRES_DB=fastapi
POSTGRES_USER=fastapi
POSTGRES_PASSWORD=${db_password}
WEB_CONCURRENCY=2
EOF
mv .env.partial .env
chmod 600 .env
unset db_password
Não envie .env ao Git nem a chamados. Monte a URL SQLAlchemy a partir de POSTGRES_HOST, POSTGRES_DB, POSTGRES_USER e POSTGRES_PASSWORD separados, usando um construtor de URL para codificar corretamente @, : e / presentes em senhas.
A configuração original de /opt/fastapi-app/compose.yaml está preservada abaixo. Corrija o volume PostgreSQL antes de iniciar: as imagens 18 usam /var/lib/postgresql/18/docker como PGDATA e /var/lib/postgresql como volume. Troque o mount postgres_data:/var/lib/postgresql/data por postgres_data:/var/lib/postgresql. Consulte a documentação oficial. Em uma instalação existente, identifique os dados reais e faça backup verificado primeiro; mudar o mount não migra os dados e pode apresentar um banco aparentemente vazio.
name: fastapi-production
x-app: &app
image: fastapi-app:local
build:
context: .
env_file:
- .env
environment:
POSTGRES_HOST: db
POSTGRES_PORT: "5432"
depends_on:
db:
condition: service_healthy
networks:
- backend
services:
db:
image: postgres:18-alpine
restart: unless-stopped
stop_grace_period: 1m
env_file:
- .env
volumes:
- postgres_data:/var/lib/postgresql/data
networks:
- backend
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
interval: 10s
timeout: 5s
retries: 10
start_period: 30s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
migrate:
<<: *app
command: ["alembic", "upgrade", "head"]
restart: "no"
profiles: ["tools"]
app:
<<: *app
restart: unless-stopped
init: true
command:
- fastapi
- run
- app/main.py
- --host
- 0.0.0.0
- --port
- "8000"
- --workers
- "${WEB_CONCURRENCY:-2}"
- --proxy-headers
- --forwarded-allow-ips=*
ports:
- "127.0.0.1:8000:8000"
read_only: true
tmpfs:
- /tmp:size=64m,mode=1777
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
healthcheck:
test:
- CMD
- python
- -c
- "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=3)"
interval: 15s
timeout: 5s
retries: 5
start_period: 20s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
networks:
backend:
volumes:
postgres_data:
depends_on comum define ordem, não prontidão. service_healthy espera pg_isready, mas isso sozinho não comprova credenciais e esquema da aplicação.
--forwarded-allow-ips=* confia nas informações encaminhadas pelo Nginx. Isso exige publicação apenas no loopback do host e rede backend confiável; reavalie ao abrir a porta ou conectar outros contêineres. Para uploads e caches, mantenha read_only e monte diretórios explícitos com proprietário, capacidade e política de backup.
Valide o Compose corrigido e construa:
cd /opt/fastapi-app
docker compose config --quiet
docker compose build --pull app
docker compose up -d db
docker compose ps
docker compose logs --tail=100 db
Quando o banco estiver healthy, execute a migração separada:
docker compose --profile tools run --rm migrate
docker compose up -d app
docker compose ps
docker compose logs --tail=100 app
curl --fail --show-error http://127.0.0.1:8000/healthz
docker image inspect fastapi-app:local --format '{{json .RepoDigests}}'
Não rode alembic upgrade head simultaneamente em todos os workers. Interrompa a implantação se falhar e examine os logs. Em atualizações, mantenha a aplicação anterior até concluir uma migração compatível.
Prefira tag imutável de commit a local ou latest. Imagens locais podem não ter RepoDigests: registre também o ID e use digest do registry ao publicá-las. Trocar postgres:18-alpine pela próxima versão principal não executa a atualização do PostgreSQL.
Instale proxy e ferramentas de certificado no host:
sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw status verbose
Aplique regras equivalentes no firewall do provedor. Substitua o domínio e salve /etc/nginx/conf.d/fastapi.conf:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
listen [::]:80;
server_name api.example.com;
client_max_body_size 10m;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
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;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_connect_timeout 5s;
proxy_read_timeout 60s;
proxy_send_timeout 60s;
}
}
Valide antes de recarregar e solicitar o certificado:
sudo nginx -t
sudo systemctl reload nginx
curl --fail --show-error http://api.example.com/healthz
sudo certbot --nginx -d api.example.com
sudo certbot renew --dry-run
curl --fail --show-error https://api.example.com/healthz
O Certbot altera o Nginx para HTTPS. Confira A, AAAA e acesso público em 80/443; AAAA incorreto costuma impedir a validação. Verifique o timer de renovação e o teste de renovação.
proxy_read_timeout não resolve exportações, vídeo ou inferência de vários minutos. Use fila e consulta de status para evitar ocupar conexões e workers indefinidamente. Alinhe client_max_body_size aos limites da aplicação e do CDN. Veja segurança do Nginx para TLS, headers e limitação de requisições.
Desativar /docs e /openapi.json reduz exposição, mas APIs administrativas continuam precisando de OAuth2, tokens curtos, mTLS ou outra autenticação adequada, além de autorização na aplicação.
Permita origens reais do frontend, métodos e headers necessários. CORS é uma política de navegador; não bloqueia curl nem chamadas entre servidores. Endpoints sensíveis precisam de autenticação e controle de frequência.
Migrações precisam alterar o esquema; a execução geralmente precisa apenas de leitura e escrita do negócio. POSTGRES_USER inicializa um administrador, não uma conta de execução com privilégio mínimo. Separe permissões conforme o SQL real antes da produção. Mantenha 5432 privado e use túnel SSH para administração temporária.
Preserve modo 600 em .env. Gere segredos independentes para banco, e-mail, nuvem e JWT. Compose env_file não os esconde de quem tem root ou acesso Docker.
O formato customizado permite inspeção com pg_restore. Salve o script como /opt/fastapi-app/backup.sh:
#!/usr/bin/env bash
set -euo pipefail
umask 077
cd /opt/fastapi-app
backup_stamp=$(date -u +%Y%m%dT%H%M%SZ)
backup_file="backups/fastapi-${backup_stamp}.dump"
partial_file="${backup_file}.partial"
test ! -e "$backup_file"
test ! -e "$partial_file"
docker compose exec -T db sh -c \
'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom --no-owner' \
> "$partial_file"
test -s "$partial_file"
docker compose exec -T db pg_restore --list < "$partial_file" > /dev/null
mv "$partial_file" "$backup_file"
sha256sum "$backup_file" > "${backup_file}.sha256"
printf 'Backup ready: %s\n' "$backup_file"
Execute e confira:
chmod 700 /opt/fastapi-app/backup.sh
/opt/fastapi-app/backup.sh
ls -lh /opt/fastapi-app/backups
O backup cobre o banco do negócio, não .env, Nginx, uploads, definições de roles ou identidade de imagens. Inclua tudo isso em backups separados e criptografados. Copie o dump final e .sha256 para fora da VPS; um único disco não protege contra perda da máquina ou da conta. Um backup diário pode perder quase um dia de alterações. Para objetivos menores, aumente a frequência ou planeje arquivamento WAL. Veja o ensaio de recuperação.
O exemplo cria um banco temporário na mesma instância PostgreSQL. Verifica leitura do dump, objetos e consultas básicas, não recuperação de toda a VPS. Para bancos grandes, use instância isolada para não esgotar disco e E/S da produção:
cd /opt/fastapi-app
backup_file='backups/fastapi-YYYYMMDDTHHMMSSZ.dump'
restore_db="restore_$(date -u +%Y%m%d%H%M%S)"
sha256sum -c "${backup_file}.sha256"
docker compose exec -T db pg_restore --list < "$backup_file" > /dev/null
docker compose exec -T db sh -c \
'createdb -U "$POSTGRES_USER" "'$restore_db'"'
docker compose exec -T db sh -c \
'pg_restore -U "$POSTGRES_USER" -d "'$restore_db'" --no-owner --exit-on-error' \
< "$backup_file"
docker compose exec -T db sh -c \
'psql -U "$POSTGRES_USER" -d "'$restore_db'" -c "\\dt"'
Substitua o nome de arquivo do exemplo. Confira contagens de tabelas importantes, restrições únicas, dados recentes e alembic_version. Depois de verificar que a variável aponta somente para o banco temporário, remova-o:
printf 'temporary database: %s\n' "$restore_db"
docker compose exec -T db sh -c \
'dropdb -U "$POSTGRES_USER" "'$restore_db'"'
unset restore_db
Não use pg_restore --clean na produção. Registre também DNS, certificados, uploads, variáveis, roles, versão da imagem e ordem de restauração.
Observe separadamente backup, build, migração e início:
cd /opt/fastapi-app
/opt/fastapi-app/backup.sh
docker compose build --pull app
docker compose --profile tools run --rm migrate
docker compose up -d app
docker compose ps
docker compose logs --tail=100 app
curl --fail --show-error https://api.example.com/healthz
São comandos separados: não prossiga manualmente depois de erro. A automação deve parar ao falhar. Teste interfaces e migrações em homologação, mantenha a imagem anterior e faça mudanças de esquema compatíveis. Voltar a imagem não desfaz migrações; deixe remoções destrutivas de colunas para uma implantação posterior compatível.
Faça backup e ensaio antes de atualizar patches PostgreSQL. Versões principais exigem um plano separado. Não use docker compose down -v para diagnosticar falhas: ele remove os volumes declarados.
Confira as camadas:
curl -v http://127.0.0.1:8000/healthz
docker compose ps
docker compose logs --tail=200 app
sudo tail -n 100 /var/log/nginx/error.log
sudo ss -lntp 'sport = :8000'
Se localhost:8000 falha, examine aplicação, contêiner e endereço de escuta. Se funciona localmente, confira upstream e restrições SELinux/AppArmor. Siga a lista 502/504.
docker compose ps
docker compose logs --tail=200 db
docker compose exec -T db sh -c \
'pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB"'
docker compose exec -T app getent hosts db
Dentro do Compose, use db, não 127.0.0.1. Alterar .env não atualiza uma senha já inicializada no volume; mude a role explicitamente no PostgreSQL e sincronize a aplicação.
Confira X-Forwarded-Proto, confiança no proxy e exposição privada. A subrota /api exige ajustar root_path do FastAPI e o encaminhamento do Nginx. Um subdomínio da API costuma simplificar.
Inspecione memória e conexões:
docker stats --no-stream
journalctl -k --since '1 hour ago' | grep -i -E 'oom|killed process'
docker compose exec -T db sh -c \
'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "select count(*) from pg_stat_activity;"'
Reduza workers quando faltar memória e os pools de cada processo quando houver conexões demais. Apenas aumentar max_connections do PostgreSQL pode agravar a pressão de memória.
- FastAPI em Docker: imagens, dependências, workers e imagem antiga;
- Ordem de início Compose:
service_healthye verificações de saúde; - Módulo proxy Nginx:
proxy_passe headers; - Certbot com Nginx: emissão e renovação;
- PostgreSQL pg_dump: comportamento e limites do backup lógico;
- Tutorial Alembic: ambiente de migração e
upgrade head.
Conclua build, migração, saúde, backup e restauração em um domínio de testes antes de mudar o DNS de produção. Mantenha backup restaurável, imagem anterior e migração executada uma única vez por implantação.