Noções Básicas de Implantação
10 exemplos para você começar com Contêineres e Implantação - 7 básicos e 3 intermediários.
Pré-requisitos
uv venv && source .venv/bin/activate
uv pip install "fastapi>=0.115" "uvicorn[standard]>=0.34" "gunicorn>=23.0" "flask>=3.1"- Python 3.14.0 com FastAPI 0.115+, Flask 3.1 e pacotes de servidor instalados.
Exemplos Básicos
1. Aplicativo WSGI Mínimo (Flask)
Flask expõe um callable WSGI consumido pelo Gunicorn.
from flask import Flask
app = Flask(__name__)
@app.get("/health")
def health():
return {"status": "ok"}gunicorn -w 2 -b 0.0.0.0:8000 'app:app'app:appsignifica móduloapp, variávelapp- Múltiplos workers
-wlidam com requisições concorrentes (síncronas) - A rota de saúde é necessária para balanceadores de carga e Kubernetes
Relacionado: Gunicorn & Uvicorn - ajuste de workers
2. Aplicativo ASGI Mínimo (FastAPI)
Aplicativos FastAPI são ASGI - execute com Uvicorn ou worker Gunicorn+Uvicorn.
from fastapi import FastAPI
app = FastAPI()
@app.get("/health")
async def health():
return {"status": "ok"}uvicorn app:app --host 0.0.0.0 --port 8000- ASGI suporta I/O assíncrono e websockets
- Uvicorn é o servidor ASGI de referência para desenvolvimento e produção
- Vincule
0.0.0.0em contêineres, não127.0.0.1
Relacionado: Gunicorn & Uvicorn - ASGI em produção
3. Porta Orientada por Ambiente
Leia a porta do ambiente para implantações 12-factor.
import os
PORT = int(os.environ.get("PORT", "8000"))- Plataformas (Heroku, Fly, ECS) injetam
PORT - O padrão ajuda o
uvicornlocal sem variável de ambiente - Valide
int()e falhe rapidamente em valores inválidos
Relacionado: Configuração e Segredos em Produção - configuração de ambiente
4. Mapa Mental do Modelo de Processo
Entenda quem aceita conexões TCP.
Cliente -> Balanceador de Carga -> Mestre Gunicorn -> processos worker -> seu aplicativo
- O mestre gerencia os workers; os workers executam o código do aplicativo Python
- Um contêiner geralmente executa um mestre Gunicorn com N workers
- Trabalho intensivo de CPU pode precisar de um processo worker de fila separado
Relacionado: Dockerizando Python - entrypoint do contêiner
5. Servidor de Desenvolvimento vs. Produção
Nunca use os servidores de desenvolvimento integrados do Flask/FastAPI em produção.
# apenas desenvolvimento
flask --app app run --debug
# produção
gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 app:app- Servidores de desenvolvimento não possuem modelo de worker robusto e endurecimento de segurança
--reloadé apenas para iteração local- Produção usa Gunicorn/Uvicorn com logging e desligamento gracioso
Relacionado: Melhores Práticas de Implantação - checklist de produção
6. Hook de Desligamento Gracioso
Drene requisições em andamento no SIGTERM de orquestradores.
import signal
def handle_sigterm(signum, frame):
print("desligando graciosamente")
signal.signal(signal.SIGTERM, handle_sigterm)- Kubernetes envia SIGTERM antes da exclusão do pod
- Gunicorn/Uvicorn lidam com timeout gracioso - ajuste
--graceful-timeout - Feche pools de banco de dados em eventos de desligamento (lifespan do FastAPI)
Relacionado: Implantações Sem Interrupção - atualizações rolling
7. Arquivos Estáticos vs. Servidor de Aplicativo
Sirva ativos estáticos de CDN ou proxy reverso, não workers Python.
location /static/ { alias /var/www/static/; }
location / { proxy_pass http://app:8000; }- Workers Python são para requisições dinâmicas
- Whitenoise é aceitável para pequenos arquivos estáticos Django em PaaS
- Descarregue a terminação TLS para o balanceador de carga ou nginx
Relacionado: Kubernetes para Aplicativos Python - ingress
Exemplos Intermediários
8. Lifespan do FastAPI para Inicialização/Desligamento
Gerencie conexões com o contexto de lifespan ASGI.
from contextlib import asynccontextmanager
from fastapi import FastAPI
@asynccontextmanager
async def lifespan(app: FastAPI):
# inicialização
yield
# limpeza de desligamento
app = FastAPI(lifespan=lifespan)- Substitua
@app.on_eventobsoleto por lifespan - Inicialize o pool de banco de dados na inicialização, feche no desligamento
- Testes podem substituir o lifespan para isolamento
Relacionado: Saúde e Prontidão - design de probe
9. Realidade da Memória Multi-Worker
Cada worker carrega uma cópia completa do seu aplicativo e modelos.
gunicorn -w 4 app:app
# 4x custo de importação, 4x RAM de modelo ML se carregado na importação- Aumente os workers até a CPU ou RAM saturar - depois aumente as réplicas
- Carregue modelos pesados sob demanda por worker na primeira requisição ou use um serviço de inferência compartilhado
- Monitore RSS por contêiner em produção
Relacionado: Monitoramento de Desempenho (APM) - ajuste de produção
10. Comando de Entrypoint do Contêiner
Documente o comando exato de produção no CMD do Dockerfile.
CMD ["gunicorn", "-w", "2", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000", "app.main:app"]- A forma de execução (array JSON) evita problemas de sinal de shell
- Corresponda ao comando no manifesto do Kubernetes e docker-compose
- Teste de fumaça de CI executa o mesmo entrypoint contra a imagem de staging
Relacionado: Dockerizando Python - layout da imagem
Versões da Pilha: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.