Desplegar FastAPI en un VPS: guía completa de producción

FastAPI obtiene todo su rendimiento del modelo ASGI asíncrono: conexiones WebSocket persistentes, streaming de respuestas y llamadas concurrentes a otros servicios. Las plataformas serverless suelen cortar las conexiones largas y facturan cada petición, lo que penaliza a una API de alto caudal o en tiempo real. En un VPS, usted lanza Uvicorn gobernado por Gunicorn con tantos workers como núcleos, mantiene las conexiones abiertas todo el tiempo que haga falta y coloca Nginx al frente para el TLS y el buffering. También controla el pool de conexiones hacia PostgreSQL y la caché Redis, dos palancas esenciales cuando sube la carga — el caudal realmente sostenido se mide sobre su propio tráfico.

Una API FastAPI es ligera: 1 vCPU y 1 GB de RAM bastan para empezar, pero apunte a 2 vCPU y 2 GB en cuanto añada una base de datos y una caché en el mismo VPS. Para una carga sostenida (>100 req/s), prevea al menos 4 vCPU y 4 GB.

Versiones recomendadas en 2025: Python 3.11+ (3.12 para el máximo rendimiento), FastAPI 0.115+ (soporte completo de Pydantic v2 y anotaciones Python 3.10+), Uvicorn 0.30+ (correcciones de estabilidad del event loop). Instale con Docker usando la imagen python:3.12-slim, o desde el repositorio oficial con pip install fastapi[standard]>=0.115 uvicorn[standard]>=0.30 gunicorn>=22.0.

En cuanto a infraestructura: Docker Engine 24+, Docker Compose v2 (plugin integrado, docker compose), Nginx 1.24+ como reverse proxy, y un dominio apuntado al VPS para el certificado TLS. Ubuntu 22.04/24.04 LTS es la base recomendada; Debian 12 también funciona.

Para las aplicaciones FastAPI en producción, asyncpg combinado con SQLAlchemy 2.x (modo async) ofrece el mejor equilibrio entre rendimiento y mantenibilidad. Configure el pool de conexiones según la carga esperada:

from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

engine = create_async_engine(
    DATABASE_URL,
    pool_size=10,        # conexiones persistentes
    max_overflow=20,     # conexiones adicionales bajo pico
    pool_timeout=30,     # segundos antes de error
    pool_recycle=1800,   # reciclado tras 30 min para evitar timeouts PostgreSQL
    echo=False,
)

AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

Inyecte la sesión en sus rutas mediante una dependencia FastAPI:

async def get_db():
    async with AsyncSessionLocal() as session:
        yield session

Para las migraciones de esquema, Alembic es la herramienta estándar. Inicialícelo en su proyecto (alembic init migrations) y configure alembic.ini para apuntar a su DATABASE_URL. Los comandos esenciales:

# Generar una migración desde sus modelos SQLAlchemy
alembic revision --autogenerate -m "add_users_table"

# Aplicar las migraciones pendientes
alembic upgrade head

# Verificar el estado actual
alembic current

En producción, ejecute alembic upgrade head antes de arrancar la API — añádalo como comando de inicio en su docker-compose.yml o en un script de arranque separado. Nunca ejecute las migraciones desde múltiples instancias simultáneamente.

Un pipeline sencillo de GitHub Actions es suficiente para la mayoría de los proyectos FastAPI: build de la imagen, push a un registry y despliegue en el VPS por SSH con zero-downtime.

# .github/workflows/deploy.yml
name: Deploy FastAPI
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build & push Docker image
        run: |
          docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} .
          echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
          docker push ghcr.io/${{ github.repository }}:${{ github.sha }}

      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: deploy
          key: ${{ secrets.VPS_SSH_KEY }}
          script: |
            cd /opt/myapp
            export IMAGE_TAG=${{ github.sha }}
            docker compose pull api
            docker compose up -d --no-deps api
            docker compose exec api alembic upgrade head

La opción --no-deps en docker compose up reinicia únicamente el contenedor api sin tocar db ni redis, lo que garantiza el zero-downtime para los servicios auxiliares. Para despliegues más robustos con rollback instantáneo, etiquete sus imágenes con el SHA del commit y conserve las últimas 3 versiones localmente.

Acceda a los logs de Uvicorn directamente desde Docker:

# Logs en tiempo real
docker compose logs -f api

# Últimas 100 líneas
docker compose logs --tail=100 api

Para logs estructurados en JSON (indexables por un agregador como Loki o Elasticsearch), sustituya el logger estándar de Python por loguru o structlog:

from loguru import logger
import sys

logger.remove()
logger.add(sys.stdout, format="{time} {level} {message}", serialize=True)

@app.middleware("http")
async def log_requests(request, call_next):
    logger.info("request", method=request.method, url=str(request.url))
    response = await call_next(request)
    logger.info("response", status=response.status_code)
    return response

Para exponer métricas Prometheus, añada un endpoint /metrics con prometheus-fastapi-instrumentator:

from prometheus_fastapi_instrumentator import Instrumentator

Instrumentator().instrument(app).expose(app, endpoint="/metrics")

Restrinja luego /metrics a su red interna desde Nginx (allow 127.0.0.1; deny all;) para evitar exponer las métricas públicamente.

Worker timed out (pid XXXXX) — Gunicorn mata un worker que no respondió en el plazo --timeout. Causas frecuentes: una ruta síncrona (def en lugar de async def) bloquea el event loop, o una operación bloqueante (lectura de archivo, llamada de red) se ejecuta sin asyncio.run_in_executor. Aumentar --timeout enmascara el problema; la corrección correcta es hacer la ruta asíncrona o delegar el trabajo bloqueante.

Address already in use (puerto 8000) — Un proceso Gunicorn anterior aún está activo. En Docker: docker compose down y luego docker compose up -d fuerza la recreación del contenedor y libera el puerto. Compruebe con docker ps -a que ningún contenedor zombie esté en marcha.

502 Bad Gateway tras un despliegue — Nginx redirigió la petición a la API durante su reinicio. Espere 10-15 segundos a que el healthcheck de Docker confirme que el nuevo contenedor está healthy antes de considerar el despliegue completado. Añada proxy_read_timeout 60; en Nginx para absorber los arranques lentos.

CORS en producción: No 'Access-Control-Allow-Origin' header — FastAPI sirve los orígenes declarados en CORSMiddleware. Verifique que CORS_ORIGINS en su .env contiene exactamente la URL del frontend (protocolo + dominio + puerto si no es estándar, sin barra al final). Un valor ["*"] funciona en desarrollo pero nunca debe ir a producción.

Conexión DB rechazada al arrancar — La API arranca antes de que PostgreSQL esté lista. El depends_on con condition: service_healthy en Docker Compose resuelve este caso. En Kubernetes o en despliegues sin Compose, implemente un bucle de reintentos con backoff exponencial en el código de inicio de la aplicación.

El Marketplace ServOrbit ofrece una plantilla FastAPI Stack preconfigurada: Python 3.12, Uvicorn, Gunicorn, Nginx y PostgreSQL 16 se instalan automáticamente en su VPS desde el pedido. Sin sesión SSH para la instalación de base — llega directamente al paso de clonar su repositorio y de lanzar Uvicorn. La ficha del marketplace contiene las especificaciones exactas, los casos de uso y una guía de primera conexión.