Tutoriales de VPS
Django y FastAPI en una VPS: Python, Gunicorn y Nginx
Despliegue Python en Ubuntu 24.04 con entornos virtuales, workers WSGI/ASGI, systemd, estáticos Nginx y HTTPS. Configure Django, migraciones, recuperación y Celery, con límites de la recarga explicados.

Un proyecto que funciona localmente con runserver o uvicorn main:app --reload puede fallar al llegar a la VPS: pip install devuelve externally-managed-environment, los archivos estáticos dan 404, DEBUG=False descubre ajustes pendientes o cerrar SSH detiene el proceso. Esta guía para Ubuntu 24.04 cubre Python, entornos virtuales, workers WSGI/ASGI, systemd, sockets Unix, Nginx, Django y publicaciones. Flask y Litestar requieren sus respectivos puntos de entrada y modos de servidor.
| Responsabilidad | Componente | Motivo |
|---|---|---|
| Ejecutar la aplicación | Gunicorn/Uvicorn | runserver es de desarrollo; el servidor Django puede usar hilos por defecto, pero no es adecuado para producción |
| Supervisión e inicio automático | systemd | Independiza el servicio del terminal y reinicia fallos |
| Puertos públicos, TLS y archivos | Nginx/Caddy | Evita ejecutar Python como root y sirve archivos directamente |
| Renovación de certificados | Certbot/Caddy | Evita caducidad si se configura y supervisa correctamente |
Recorrido de las solicitudes:
浏览器 → Nginx(443) → Unix socket → Gunicorn → 你的 Django/FastAPI 代码
↓
/static/ 直接由 Nginx 返回,不进 Python
Node y Python pueden atender E/S concurrente; ASGI no necesita un proceso por petición simultánea. Los workers Gunicorn son procesos independientes. Los 80–150 MB de un Django sencillo y los 300 MB o más con bibliotecas pesadas del original son ejemplos, no mediciones de su proyecto. (2 × CPU核数) + 1 es una regla inicial aproximada.
| VPS de ejemplo | Workers para evaluar | Condiciones |
|---|---|---|
| 2 vCPU / 2 GB | 2–3 | Empezar con 2; los 5 de la fórmula pueden agotar la memoria |
| 2 vCPU / 4 GB | 3–5 | Medir coste por solicitud y pools |
| 4 vCPU / 8 GB | 5–9 | El original reserva 2 GB para base y sistema; pueden necesitar más |
Observe RSS con ps aux | grep gunicorn, multiplique por los workers y reserve al menos el 30% ilustrativo para base, caché y sistema; compruebe ese margen con carga.
- pandas, NumPy y Pillow pueden aumentar considerablemente la memoria residente.
- Una API ASGI de E/S puede empezar con 2–4 workers; no garantiza concurrencia elevada.
- El SSD importa en entornos con miles de archivos pequeños.
RackNerd para planes anuales, Vultr para redimensionar por horas y Contabo para ofertas de memoria son ejemplos: compruebe precios actuales y mida el disco. CN2 GIA de BandwagonHost beneficia conexiones con China continental según la ruta, no la latencia mundial. Consulte dimensionamiento VPS.
Ubuntu 24.04 incluye Python 3.12. Revise el conjunto real de dependencias bloqueadas antes de sustituirlo. El original de septiembre citaba Django 6.1 con Python 3.12+, FastAPI 0.141 con 3.10+ y Gunicorn 26/Uvicorn 0.53 con 3.10+: son referencias históricas.
La consulta del registro del 16 de noviembre de 2026 indica Django 6.1.3 con 3.12+, FastAPI 0.163.1 con 3.11+, Gunicorn 27.0.1 y Uvicorn 0.54.0 con 3.10+. Python 3.12 cumple esos mínimos, sujeto al resto del proyecto. La publicación de Python 3.14 en octubre de 2025 y su soporte hasta octubre de 2030 son datos de ciclo de vida, no una afirmación de que siga siendo la versión más reciente. Python 3.12 recibe soporte de seguridad upstream hasta octubre de 2028; la fecha de retirada de 3.10 indicada para octubre de 2026 ya pasó. Planifique abandonarlo y consulte el ciclo oficial junto con el soporte de la distribución.
Mantenga 3.12 administrado por la distribución si basta. Instalar un Python normal más reciente no activa automáticamente free-threading; necesita la compilación correspondiente y extensiones compatibles.
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 y build-essential permiten compilar psycopg, pillow y lxml si no existe wheel compatible; faltan cabeceras cuando aparecen muchos errores gcc. libpq-dev corresponde a PostgreSQL; MySQL puede necesitar default-libmysqlclient-dev.
Solo si necesita otro intérprete, evalúe el PPA externo de deadsnakes y su mantenimiento:
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt install -y python3.14 python3.14-venv python3.14-dev
pip install django en el Python del sistema puede producir:
error: externally-managed-environment
× This environment is externally managed
Ubuntu marca el intérprete como administrado para proteger dependencias de apt. Cree un entorno virtual en lugar de omitir la protección con --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
El original reutiliza el entorno bajo shared/. Para una reversión fiable, prefiera un entorno por publicación: modificar uno compartido cambia dependencias de la versión anterior antes de cambiar el código y puede romperla.
Opcionalmente use 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 el instalador, ejecútelo como la cuenta de despliegue y compruebe permisos. uv 0.13.8 del registro sustituye la serie 0.12 del original; la velocidad depende de caché, wheels y red. Acepta requirements.txt sin obligar a reorganizar el proyecto.
Prepare acceso SSH al repositorio para appuser, verifique la clave del servidor y cambie las rutas y fechas de ejemplo:
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
Bloquee requirements.txt con referencias exactas como django==6.1.1, no restricciones abiertas como django>=6.1. Son ejemplos sintácticos, no instrucciones para conservar versiones sin parches. pip freeze > requirements.txt registra lo instalado; uv pip compile puede generar un bloqueo con hashes. Incluya servidor y paquete worker en ese bloqueo, evitando instalar Gunicorn sin versión en cada publicación.
/srv/app/shared/venv/bin/gunicorn \
--workers 3 \
--bind unix:/srv/app/shared/gunicorn.sock \
--timeout 60 \
--access-logfile - \
--error-logfile - \
myproject.wsgi:application
En myproject.wsgi:application, cambie myproject por el paquete con settings.py. El socket Unix evita exposición TCP, pero requiere proxy y servidor en la misma máquina y permisos correctos. TCP privado en loopback también es válido.
Una aplicación async def necesita un worker ASGI. Este es el ejemplo Uvicorn antiguo del 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 está obsoleto. Instale y bloquee un uvicorn-worker probado, y cambie la clase por uvicorn_worker.UvicornWorker. En systemd cambie también el punto de entrada a main:app para FastAPI. Consulte el worker mantenido. uvicorn --workers 3 directamente bajo systemd es otra opción multiproceso válida.
--timeout suele controlar cuánto tiempo un worker deja de comunicarse con Gunicorn, no un plazo universal por petición; depende del tipo de worker. El valor por defecto es 30 segundos. Lleve exportaciones y llamadas largas a una cola como Celery y defina plazos en aplicación y proxy.
Guarde /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 habilitarlo, haga que current apunte a una publicación existente y cree static/media bajo shared. Ajuste el punto de entrada WSGI/ASGI. El límite duro de 1500M requiere margen para otros servicios.
Group=www-datay--umask 007permiten acceso al socket parawww-data; los directorios padre también requieren permiso de recorrido. De lo contrario aparececonnect() to unix:/... failed (13: Permission denied).Type=notifyusa la notificación de disponibilidad de Gunicorn; a diferencia deType=simple, puede esperar la inicialización. Compruebe la versión y el worker elegidos.ExecReload=kill -s HUPenvía HUP para reemplazar workers, pero no garantiza cambiar el directorio ya resuelto del proceso maestro ni recargar variables de systemd.- Con
ProtectSystem=strict, declare directorios escribibles enReadWritePathspara evitarRead-only file system. Proteja los secretos contra escritura de la aplicación cuando sea posible. After=postgresql.serviceestablece orden, no disponibilidad de PostgreSQL. Use el servicio real y reintentos de conexión.
sudo systemctl daemon-reload
sudo systemctl enable --now myapp
sudo systemctl status myapp
Si falla, consulte journalctl -u myapp -n 50 --no-pager y la lista systemd.
Guarde el archivo en /etc/nginx/sites-available/app.example.com antes de enlazarlo:
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
Reenvíe y confíe correctamente en X-Forwarded-Proto con SECURE_SSL_REDIRECT de Django para evitar bucles tras terminar TLS. Solo confíe en su proxy, que debe sobrescribir la cabecera de protocolo recibida del cliente. Véase bucles HTTPS.
Mantenga barras finales en los directorios alias y permisos de lectura/recorrido. La caché immutable corresponde a nombres con hash de contenido, no a archivos que cambian conservando nombre. /media/ público entrega subidas sin autorización de Django: diseñe otra entrega para medios privados. Consulte seguridad Nginx o Caddy.
Cambie dominio y correo, revise A/AAAA y abra los puertos necesarios en ambos 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
Supervise la renovación y siga la guía de certificados.
- Configure
DEBUG = False. Las páginas de depuración exponen información sensible y diagnósticos. - Complete
ALLOWED_HOSTS. ConDEBUG = False,ALLOWED_HOSTSvacío rechaza solicitudes normales; indique nombres reales sin esquema URL. - Cargue
SECRET_KEYdesde configuración 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["..."] falla si falta el secreto, a diferencia de .get() con valor permisivo. Configure orígenes CSRF y cookies seguras reales. DATABASE_URL requiere un parser o DATABASES explícito: Django no lo interpreta automáticamente.
- Ejecute
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
Con DEBUG = False, collectstatic debe llenar STATIC_ROOT y coincidir con Nginx. CSS ausente también puede ser un problema de permisos o caché. Los comandos administrativos necesitan directorio y variables correctos; EnvironmentFile de systemd no se carga en su shell.
sudo -u appuser touch /srv/app/shared/.env
sudo chmod 600 /srv/app/shared/.env
El valor del secreto en la plantilla original contiene una instrucción: sustitúyala por el resultado de secrets.token_urlsafe(50), no copie esa instrucción como contraseña:
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 las credenciales y cárguelas explícitamente para migrar y recopilar estáticos. El banco del host debe escuchar en 127.0.0.1 u otra interfaz privada. Consulte exposición del banco, PostgreSQL y Redis para caché o broker Celery.
Se conserva el flujo original como referencia:
#!/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
Ejecútelo como cuenta de despliegue con permisos limitados para reiniciar, variables correctas y copia previa de base y subidas. No lo considere un despliegue sin interrupciones ya validado. systemctl reload avisa al maestro Gunicorn existente, que puede seguir en el antiguo directorio resuelto. El venv y los estáticos compartidos también alteran la publicación anterior antes del cambio. Use dependencias y archivos por versión; después haga un reinicio controlado que resuelva current nuevamente, o dos instancias con cambio de proxy probado si necesita continuidad. Compruebe commit activo y salud pública.
migrate no se deshace por restaurar el enlace. Algunas migraciones son reversibles; las pérdidas destructivas pueden no serlo. Primero amplíe el esquema de forma compatible y elimine columnas en otra publicación. Conserve set -euo pipefail para detener el cambio cuando falle migrate. Retenga versiones activa y anterior hasta comprobar salud y revise las rutas de limpieza antes de borrarlas.
- 502: revise
sudo systemctl status myapp, arranque,Permission denieddel socket y OOM; consulte 502/504. - 500 sin registros: envíe Django
LOGGINGa stderr;DEBUG=Falsedesactiva páginas de depuración, no el registro de excepciones. DisallowedHost/ 400: añada el dominio real enALLOWED_HOSTS.- CSS/JS 404: compruebe
collectstatic, barras dealiasy permisos. WORKER TIMEOUT: investigue operaciones bloqueantes y significado de--timeoutsegún el worker; use colas para tareas largas.- Memoria creciente/OOM:
--max-requests 1000 --max-requests-jitter 100recicla workers y puede contener temporalmente una fuga. Investigue la causa; swap/ZRAM no la repara. externally-managed-environment: cree un venv, sin--break-system-packages.
Consulte la guía de registros y observe aplicación y proxy juntos:
sudo journalctl -u myapp -f
sudo tail -f /var/log/nginx/app.error.log
Celery no arranca con Gunicorn. El original propone esta unidad con worker desacoplado:
[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
Prefiera un worker en primer plano con Type=simple: quite --detach y la opción PID-file, ajuste proyecto y entorno de la publicación, y mande logs al journal. Prepare credenciales del broker, rutas escribibles y reintentos de disponibilidad. Habilite una unidad independiente y reiníciela con las publicaciones. Celery Beat necesita otro servicio: una sola instancia por calendario evita duplicar envíos y las tareas deben tolerar reintentos.
- Copie base, subidas, secretos y configuración; Git no basta. Haga un ensayo de recuperación.
- Para muchas subidas, evalúe almacenamiento de objetos, acceso y respaldo; véase MinIO.
- Configure avisos de transferencia antes del límite del proveedor.
- Registre TTFB y memoria iniciales para comparar; véase diagnóstico TTFB.
- Desplegar Node.js para otro servicio del sitio;
- Dimensionar la VPS para equilibrar workers y memoria;
- Dokploy para despliegues Git administrados;
- Runner GitHub Actions para builds CI;
- Servicio inaccesible desde internet para puertos, escucha y firewall.