Gunicorn & Uvicorn
Gunicorn gerencia processos de worker para aplicações WSGI e ASGI; Uvicorn implementa o servidor ASGI. FastAPI em produção no 0.115+ comumente usa Gunicorn com UvicornWorker para concorrência multi-processo mais I/O assíncrono.
Receita
gunicorn app.main:app \
-w 4 \
-k uvicorn.workers.UvicornWorker \
-b 0.0.0.0:8000 \
--timeout 60 \
--graceful-timeout 30 \
--access-logfile -Quando usar isso:
- Implantações de FastAPI/Starlette em produção
- Flask/Django WSGI com workers síncronos (
-k syncpadrão) - Modelo de processo único de contêiner com pool de workers interno
- Implantações graciosas que precisam de tratamento SIGTERM
Exemplo de Trabalho
Arquivo de configuração Gunicorn ajustado para FastAPI com logging e contagem de workers a partir da variável de ambiente.
# gunicorn.conf.py
import multiprocessing
import os
bind = f"0.0.0.0:{os.environ.get('PORT', '8000')}"
worker_class = "uvicorn.workers.UvicornWorker"
workers = int(os.environ.get("WEB_CONCURRENCY", multiprocessing.cpu_count()))
timeout = 60
graceful_timeout = 30
keepalive = 5
accesslog = "-"
errorlog = "-"
loglevel = os.environ.get("LOG_LEVEL", "info")gunicorn -c gunicorn.conf.py app.main:appO que isso demonstra:
- O padrão
WEB_CONCURRENCYcorresponde às convenções Heroku/Render UvicornWorkerexecuta ASGI por processo worker- Logs de acesso/erro para stdout para coletores de logs de contêiner
Mergulho Profundo
Modelos de Worker
| Pilha | Classe do Worker |
|---|---|
| Flask/Django sync | sync (padrão) |
| FastAPI async | uvicorn.workers.UvicornWorker |
| gevent (legado) | gevent |
Pontos de Partida para Ajuste
- Workers:
2-4 x núcleos da CPUpara tarefas síncronas vinculadas à CPU; menos para ML com uso intensivo de memória - Timeout: acima do tempo de requisição p99; evite matar requisições lentas legítimas
- Keepalive: corresponda às configurações de keepalive do proxy reverso
Notas de Python
# Apenas para desenvolvimento - recarregamento com um único worker
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000Armadilhas
- Muitos workers em aplicativo de ML - OOM (Out Of Memory) mata o contêiner. Correção: reduza os workers ou externalize a inferência.
- Workers síncronos para aplicativo puramente assíncrono de I/O - subutiliza a concorrência. Correção: UvicornWorker ou uvicorn puro com async.
- Timeout menor que a consulta ao banco de dados - 502 durante relatórios. Correção: aumente o timeout ou mova trabalhos longos para uma fila.
- Sem timeout gracioso na implantação - requisições em andamento abortadas. Correção:
--graceful-timeout+ atraso do hookpreStopno K8s. - Executando uvicorn --reload em produção - inseguro e instável. Correção: configuração do gunicorn sem reload.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Hypercorn | Necessidades de ASGI HTTP/2 | O padrão da equipe é Gunicorn |
| uWSGI | Lojas Django legadas | FastAPI Greenfield |
| Múltiplas réplicas de uvicorn | Modelo de processo único por pod do K8s | Deseja pool de workers dentro do contêiner |
FAQs
gunicorn vs uvicorn sozinho?
Gunicorn supervisiona múltiplos workers Uvicorn; um único uvicorn é suficiente para desenvolvimento e produção pequena com escalonamento externo.
Como calculo os workers?
Comece com a contagem de CPU para I/O assíncrono; metade da CPU para síncrono vinculado à CPU; meça a latência e o RSS sob carga.
Django usa UvicornWorker?
As views assíncronas do Django 5.2 podem; a maioria das implantações do Django permanece com workers Gunicorn síncronos, a menos que o caminho assíncrono seja explícito.
E sobre websockets?
UvicornWorker suporta websockets; workers Gunicorn síncronos não.
Como expor métricas?
Diretório multiprocess do Prometheus ao usar múltiplos workers síncronos; middleware ASGI para métricas de requisição.
Como os workers recarregam o código?
Implante uma nova imagem de contêiner - não confie no recarregamento HUP em infraestrutura imutável.
Workers de Thread?
gthread para alguma sobreposição de I/O WSGI - menos comum que ASGI assíncrono para novos serviços FastAPI.
Como vincular IPv6?
[::]:8000 quando a plataforma requer dual-stack - verifique a configuração do balanceador de carga.
Terminação SSL?
No balanceador de carga ou ingress - geralmente não no Gunicorn dentro do contêiner.
Como isso interage com o Kubernetes?
Um contêiner executa Gunicorn com N workers; HPA escala pods com base em CPU/RPS - veja a página do Kubernetes.
Relacionado
- Noções Básicas de Implantação - Introdução a WSGI/ASGI
- Dockerizando Python - CMD usa Gunicorn
- Implantações Zero-Downtime - desligamento gracioso
- Saúde e Prontidão - sondas
- Monitoramento de Desempenho (APM) - ajuste de latência
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+.