Tutoriais de VPS
Django e FastAPI na VPS: Python, Gunicorn e Nginx
Implante Python no Ubuntu 24.04 com ambientes virtuais, workers WSGI/ASGI, systemd, estáticos Nginx e HTTPS. Configure Django, migrações, recuperação e Celery, com os limites da recarga explicados.

Um projeto que funciona localmente com runserver ou uvicorn main:app --reload pode falhar na VPS: pip install retorna externally-managed-environment, arquivos estáticos dão 404, DEBUG=False revela configurações pendentes ou fechar o SSH encerra o processo. Este guia para Ubuntu 24.04 cobre Python, ambientes virtuais, workers WSGI/ASGI, systemd, sockets Unix, Nginx, Django e implantações. Flask e Litestar exigem os respectivos pontos de entrada e modos de servidor.
| Responsabilidade | Componente | Finalidade |
|---|---|---|
| Executar a aplicação | Gunicorn/Uvicorn | runserver é de desenvolvimento; o servidor Django pode usar threads por padrão, mas não é adequado para produção |
| Supervisão e início automático | systemd | Independência do terminal e reinício após falhas |
| Portas públicas, TLS e arquivos | Nginx/Caddy | Evita Python como root e permite servir arquivos diretamente |
| Renovação do certificado | Certbot/Caddy | Evita vencimento quando configurado e monitorado corretamente |
Fluxo das requisições:
浏览器 → Nginx(443) → Unix socket → Gunicorn → 你的 Django/FastAPI 代码
↓
/static/ 直接由 Nginx 返回,不进 Python
Node e Python atendem E/S concorrente; ASGI não precisa de um processo por requisição simultânea. Workers Gunicorn são processos independentes. Os 80–150 MB para Django simples e 300 MB ou mais com bibliotecas pesadas do original são exemplos, não medições do seu projeto. (2 × CPU核数) + 1 é uma regra inicial aproximada.
| VPS de exemplo | Workers a avaliar | Condições |
|---|---|---|
| 2 vCPU / 2 GB | 2–3 | Comece com 2; os 5 da fórmula podem exceder a memória |
| 2 vCPU / 4 GB | 3–5 | Meça custo das requisições e pools |
| 4 vCPU / 8 GB | 5–9 | O original reserva 2 GB para banco e sistema; eles podem precisar de mais |
Observe RSS com ps aux | grep gunicorn, estime o total e reserve pelo menos os 30% ilustrativos para banco, cache e sistema. Valide a margem sob carga.
- pandas, NumPy e Pillow podem aumentar bastante a memória residente.
- Uma API ASGI de E/S pode começar com 2–4 workers; isso não garante alta concorrência.
- SSD importa em ambientes virtuais com milhares de arquivos pequenos.
RackNerd para planos anuais, Vultr para redimensionamento por hora e Contabo para ofertas de memória são exemplos. Confira preços atuais e meça o disco. CN2 GIA da BandwagonHost atende conectividade com a China continental conforme a rota, não latência mundial. Consulte dimensionamento da VPS.
Ubuntu 24.04 inclui Python 3.12. Confira as dependências reais e bloqueadas antes de substituí-lo. O original de setembro citava Django 6.1 com Python 3.12+, FastAPI 0.141 com 3.10+ e Gunicorn 26/Uvicorn 0.53 com 3.10+: são referências históricas.
Na consulta ao registry de 16 de novembro de 2026, Django 6.1.3 exige 3.12+, FastAPI 0.163.1 exige 3.11+, Gunicorn 27.0.1 e Uvicorn 0.54.0 exigem 3.10+. Python 3.12 atende a esses mínimos, sujeito ao restante das dependências. O lançamento de Python 3.14 em outubro de 2025 e suporte até outubro de 2030 são dados de ciclo de vida, não uma afirmação de que continue sendo a versão mais recente. Python 3.12 recebe suporte de segurança upstream até outubro de 2028; a retirada de 3.10 prevista pelo original para outubro de 2026 já passou. Planeje sair dessa versão e consulte o ciclo oficial junto com o suporte da distribuição.
Prefira 3.12 mantido pela distribuição quando suficiente. Instalar um interpretador comum mais recente não ativa free-threading automaticamente: isso exige build apropriado e extensões compatíveis.
sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-venv python3-dev build-essential \
libpq-dev nginx git curl ufw
python3 -V
python3-dev e build-essential ajudam a compilar psycopg, pillow e lxml quando não há wheel compatível; headers ausentes costumam gerar erros gcc. libpq-dev corresponde a PostgreSQL; MySQL pode precisar de default-libmysqlclient-dev.
Somente se outro interpretador for necessário, avalie o PPA externo deadsnakes e sua manutenção:
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt install -y python3.14 python3.14-venv python3.14-dev
pip install django no Python do sistema pode produzir:
error: externally-managed-environment
× This environment is externally managed
Ubuntu marca o interpretador como gerenciado para proteger dependências do apt. Crie um ambiente virtual em vez de ignorar essa proteção com --break-system-packages:
sudo useradd -r -m -d /srv/app -s /bin/bash appuser
sudo mkdir -p /srv/app/{releases,shared}
sudo chown -R appuser:appuser /srv/app
sudo -u appuser python3 -m venv /srv/app/shared/venv
sudo -u appuser /srv/app/shared/venv/bin/pip install --upgrade pip
O original reutiliza o ambiente em shared/. Para rollback confiável, prefira um ambiente por versão: modificar um venv compartilhado altera dependências da versão anterior antes da troca do código e pode quebrá-la.
Uma opção com uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv /srv/app/shared/venv --python 3.12
uv pip install --python /srv/app/shared/venv/bin/python -r requirements.txt
Revise o instalador, execute como a conta de implantação e confira permissões. uv 0.13.8 do registry substitui a série 0.12 do original; desempenho depende de cache, wheels e rede. Ele aceita requirements.txt sem exigir reorganizar o projeto.
Prepare acesso SSH ao repositório para appuser, confira a chave do host e substitua repositório e datas de exemplo:
sudo -u appuser git clone [email protected]:your/repo.git /srv/app/releases/20260920-140000
cd /srv/app/releases/20260920-140000
sudo -u appuser /srv/app/shared/venv/bin/pip install -r requirements.txt
sudo -u appuser /srv/app/shared/venv/bin/pip install gunicorn
Fixe requirements.txt com referências exatas como django==6.1.1, não restrições abertas como django>=6.1. São exemplos de sintaxe, não recomendações para manter versões sem patches. pip freeze > requirements.txt registra o ambiente instalado; uv pip compile pode gerar um lock com hashes. Inclua servidor e pacote worker no lock, evitando instalar Gunicorn sem versão em cada implantação.
/srv/app/shared/venv/bin/gunicorn \
--workers 3 \
--bind unix:/srv/app/shared/gunicorn.sock \
--timeout 60 \
--access-logfile - \
--error-logfile - \
myproject.wsgi:application
Em myproject.wsgi:application, substitua myproject pelo pacote que contém settings.py. O socket Unix evita exposição TCP, mas exige proxy e servidor na mesma máquina e permissões corretas. TCP privado em loopback também é válido.
Uma aplicação async def precisa de worker ASGI. Este é o exemplo antigo do original:
/srv/app/shared/venv/bin/gunicorn \
--workers 3 \
--worker-class uvicorn.workers.UvicornWorker \
--bind unix:/srv/app/shared/gunicorn.sock \
--timeout 60 \
main:app
uvicorn.workers foi descontinuado. Instale e fixe um uvicorn-worker testado e substitua a classe por uvicorn_worker.UvicornWorker. Ajuste também o entrypoint do systemd para main:app no FastAPI. Veja o worker mantido. uvicorn --workers 3 diretamente sob systemd é outra opção multiprocesso suportada.
--timeout geralmente controla quanto tempo um worker deixa de se comunicar com o Gunicorn, não um prazo universal por requisição; isso depende da classe. O padrão é 30 segundos. Coloque exportações e chamadas longas em uma fila como Celery e defina deadlines de aplicação e proxy.
Salve /etc/systemd/system/myapp.service:
[Unit]
Description=Django/FastAPI App via Gunicorn
After=network.target postgresql.service
[Service]
Type=notify
User=appuser
Group=www-data
WorkingDirectory=/srv/app/current
EnvironmentFile=/srv/app/shared/.env
ExecStart=/srv/app/shared/venv/bin/gunicorn \
--workers 3 \
--bind unix:/srv/app/shared/gunicorn.sock \
--umask 007 \
--timeout 60 \
--access-logfile - \
--error-logfile - \
myproject.wsgi:application
ExecReload=/bin/kill -s HUP $MAINPID
Restart=always
RestartSec=3
KillMode=mixed
TimeoutStopSec=30
MemoryMax=1500M
LimitNOFILE=65535
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/srv/app/shared
[Install]
WantedBy=multi-user.target
Antes de habilitar, aponte current para uma versão existente e crie static/media em shared. Ajuste o entrypoint WSGI/ASGI. O limite rígido de 1500M exige espaço para os demais serviços.
Group=www-datae--umask 007permitem acesso ao socket porwww-data; diretórios pai também precisam de permissão de travessia. Caso contrário aparececonnect() to unix:/... failed (13: Permission denied).Type=notifyusa a notificação de prontidão do Gunicorn; diferentemente deType=simple, pode aguardar inicialização. Confira a versão bloqueada e o worker escolhido.ExecReload=kill -s HUPenvia HUP para substituir workers, mas não garante mudar o diretório resolvido do processo mestre nem recarregar variáveis do systemd.- Com
ProtectSystem=strict, declare diretórios graváveis emReadWritePathspara evitarRead-only file system. Proteja segredos contra escrita da aplicação quando possível. After=postgresql.serviceestabelece ordem, não prontidão PostgreSQL. Use o serviço real e reintentos de conexão.
sudo systemctl daemon-reload
sudo systemctl enable --now myapp
sudo systemctl status myapp
Em falhas, confira journalctl -u myapp -n 50 --no-pager e a lista systemd.
Salve em /etc/nginx/sites-available/app.example.com antes de criar o link habilitado:
upstream app_server {
server unix:/srv/app/shared/gunicorn.sock fail_timeout=0;
}
server {
listen 80;
listen [::]:80;
server_name app.example.com;
client_max_body_size 20m;
access_log /var/log/nginx/app.access.log;
error_log /var/log/nginx/app.error.log warn;
# 静态文件直接由 Nginx 返回,不进 Python
location /static/ {
alias /srv/app/shared/static/;
expires 30d;
access_log off;
add_header Cache-Control "public, immutable";
}
location /media/ {
alias /srv/app/shared/media/;
expires 7d;
}
location / {
proxy_pass http://app_server;
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_redirect off;
proxy_connect_timeout 5s;
proxy_read_timeout 60s;
}
}
sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
Encaminhe e confie corretamente em X-Forwarded-Proto junto com SECURE_SSL_REDIRECT do Django para evitar loops após terminar TLS. Confie somente no seu proxy, que deve sobrescrever o header de protocolo recebido do cliente. Veja loops HTTPS.
Mantenha barras finais nos diretórios alias e permissões de leitura/travessia. Cache immutable é adequado para nomes com hash de conteúdo, não arquivos que mudam mantendo o nome. /media/ público entrega uploads sem autorização Django: arquivos privados precisam de outra estratégia. Consulte segurança Nginx ou Caddy.
Substitua domínio/e-mail, confira A/AAAA e abra as portas necessárias nos dois firewalls:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d app.example.com --redirect --agree-tos -m [email protected]
systemctl list-timers | grep certbot
sudo certbot renew --dry-run
Monitore a renovação e siga o guia de certificados.
- Configure
DEBUG = False. Páginas de debug expõem informações sensíveis e diagnósticos. - Preencha
ALLOWED_HOSTS. ComDEBUG = False,ALLOWED_HOSTSvazio rejeita requisições normais; use hosts reais sem esquema URL. - Carregue
SECRET_KEYda configuração protegida:
import os
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = os.environ.get("DJANGO_DEBUG", "0") == "1"
ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "").split(",")
STATIC_ROOT = "/srv/app/shared/static"
STATIC_URL = "/static/"
MEDIA_ROOT = "/srv/app/shared/media"
MEDIA_URL = "/media/"
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
CSRF_TRUSTED_ORIGINS = ["https://app.example.com"]
os.environ["..."] falha se faltar um segredo obrigatório, ao contrário de .get() permissivo. Configure origens CSRF reais e cookies seguros. DATABASE_URL exige parser ou DATABASES explícito: Django não o interpreta automaticamente.
- Execute
collectstatic:
sudo -u appuser /srv/app/shared/venv/bin/python manage.py collectstatic --noinput
sudo -u appuser /srv/app/shared/venv/bin/python manage.py migrate
Com DEBUG = False, collectstatic precisa preencher STATIC_ROOT e corresponder ao Nginx. CSS ausente também pode envolver permissões ou cache. Comandos de administração exigem diretório e ambiente corretos; EnvironmentFile do systemd não é carregado no shell automaticamente.
sudo -u appuser touch /srv/app/shared/.env
sudo chmod 600 /srv/app/shared/.env
O segredo da configuração original contém uma instrução: substitua-a pelo resultado de secrets.token_urlsafe(50), sem copiar a instrução como senha:
DJANGO_SECRET_KEY=用 python -c "import secrets;print(secrets.token_urlsafe(50))" 生成
DJANGO_DEBUG=0
DJANGO_ALLOWED_HOSTS=app.example.com
DATABASE_URL=postgres://app:[email protected]:5432/appdb
Proteja as credenciais e carregue-as explicitamente para migrações e coleta de estáticos. O banco no host deve escutar em 127.0.0.1 ou outra interface privada. Consulte exposição do banco, PostgreSQL e Redis para cache ou broker Celery.
O fluxo original está preservado como referência:
#!/usr/bin/env bash
set -euo pipefail
APP=/srv/app
VENV=$APP/shared/venv
RELEASE=$APP/releases/$(date +%Y%m%d-%H%M%S)
git clone --depth 1 [email protected]:your/repo.git "$RELEASE"
cd "$RELEASE"
"$VENV/bin/pip" install -r requirements.txt
"$VENV/bin/python" manage.py collectstatic --noinput
"$VENV/bin/python" manage.py migrate --noinput
ln -sfn "$RELEASE" "$APP/current"
sudo systemctl reload myapp
ls -1dt $APP/releases/* | tail -n +6 | xargs -r rm -rf
Execute como conta de implantação com permissão restrita para reiniciar, ambiente correto e backup prévio de banco e uploads. Não considere esse script uma implantação sem interrupção já validada. systemctl reload sinaliza o mestre Gunicorn existente, que pode continuar no diretório antigo já resolvido. Venv e estáticos compartilhados também alteram a versão anterior antes da troca. Use dependências e arquivos por versão, depois reinício controlado que resolva current novamente, ou duas instâncias com troca de proxy testada para disponibilidade contínua. Confira commit ativo e saúde pública.
migrate não é desfeito ao restaurar o link. Algumas migrações são reversíveis, mas perda destrutiva de dados pode não ser. Primeiro amplie o esquema de modo compatível e remova campos em outra implantação. Preserve set -euo pipefail para impedir a troca após falha em migrate. Retenha versões ativa e de rollback até verificar saúde e revise caminhos de limpeza antes de excluir.
- 502: confira
sudo systemctl status myapp, início,Permission deniedno socket e OOM. Veja 502/504. - 500 sem logs: envie Django
LOGGINGao stderr;DEBUG=Falsedesativa páginas de debug, não o registro de exceções. DisallowedHost/ 400: inclua o domínio real emALLOWED_HOSTS.- CSS/JS 404: confira
collectstatic, barras dealiase permissões. WORKER TIMEOUT: investigue bloqueios e o significado de--timeoutpara seu worker; use fila para tarefas longas.- Memória crescente/OOM:
--max-requests 1000 --max-requests-jitter 100recicla workers e pode conter vazamentos temporariamente. Investigue a causa; swap/ZRAM não a corrige. externally-managed-environment: crie venv, sem--break-system-packages.
Use o guia de logs e examine aplicação e proxy juntos:
sudo journalctl -u myapp -f
sudo tail -f /var/log/nginx/app.error.log
Celery não inicia com Gunicorn. O original apresenta esta unidade com worker em background:
[Unit]
Description=Celery Worker
After=network.target redis-server.service
[Service]
Type=forking
User=appuser
WorkingDirectory=/srv/app/current
EnvironmentFile=/srv/app/shared/.env
ExecStart=/srv/app/shared/venv/bin/celery -A myproject worker \
--detach --loglevel=info --concurrency=2 \
--pidfile=/srv/app/shared/celery.pid
Restart=always
[Install]
WantedBy=multi-user.target
Prefira worker em primeiro plano com Type=simple: remova --detach e a opção PID-file, ajuste projeto e ambiente da versão e mande logs ao journal. Prepare credenciais do broker, caminhos graváveis e reintentos de prontidão. Habilite uma unidade independente e reinicie-a nas implantações. Celery Beat exige outro serviço: uma única instância por agenda evita enfileirar tarefas duas vezes, e tarefas devem tolerar reexecução.
- Faça backup de banco, uploads, segredos e configuração; Git não basta. Execute um ensaio de restauração.
- Para muitos uploads, avalie armazenamento de objetos, acesso e backup; veja MinIO.
- Configure alertas de transferência antes do limite do provedor.
- Registre TTFB e memória iniciais para comparação; veja diagnóstico TTFB.
- Implantar Node.js para um serviço complementar;
- Dimensionar a VPS para equilibrar workers e memória;
- Dokploy para implantações Git gerenciadas;
- Runner GitHub Actions para builds CI;
- Serviço inacessível externamente para portas, escuta e firewall.