Tutoriales de VPS
FastAPI en una VPS: Compose, PostgreSQL, Nginx y recuperación
Despliegue FastAPI y PostgreSQL con Docker Compose, puertos privados y Nginx HTTPS. Configure contenedores sin root, salud, migraciones Alembic, copias verificadas, restauración y reversión segura.

Ejecutar fastapi dev en desarrollo es el primer paso. Una API pública necesita supervisión, una base de datos preparada, HTTPS, migraciones que detengan el despliegue al fallar y copias recuperables. Esta guía usa una VPS Linux: Docker Compose administra FastAPI y PostgreSQL 18, el puerto de la aplicación se publica en 127.0.0.1 del host y Nginx termina HTTPS.
Sirve para un proyecto existente o como estructura de despliegue. El artículo original indica comprobaciones estáticas de configuración; son comprobaciones históricas, no una nueva prueba de despliegue de esta edición. Las cifras de recursos son puntos de partida, no mediciones de concurrencia.
Recorrido de las solicitudes:
浏览器或客户端 -> 80/443 -> Nginx -> 127.0.0.1:8000 -> FastAPI 容器
-> PostgreSQL 容器
Ni PostgreSQL ni el puerto 8000 necesitan exposición pública. Abra únicamente el acceso necesario para SSH, HTTP y HTTPS.
| Uso | Recursos iniciales | Workers iniciales | Qué observar |
|---|---|---|---|
| Pruebas o API interna poco usada | 1–2 vCPU, 2 GB RAM, 30 GB SSD | 1 | Memoria de compilación y disco libre |
| API pequeña en producción | 2 vCPU, 4 GB RAM, 50 GB SSD | 2 | Memoria por proceso y conexiones |
| Cálculo intensivo o inferencia | Dimensionar según la tarea | Empezar con 1 | CPU, memoria del modelo y tiempos de espera |
Cada worker carga su propia aplicación y crea sus pools. Si un proceso ocupa 500 MB, cuatro pueden acercarse a 2 GB antes de contar los otros servicios. Empiece con 1–2 y mida solicitudes reales.
Prepare:
- Ubuntu 24.04 u otra distribución Linux con soporte;
- Docker Engine y el plugin Compose;
- un dominio que apunte a la VPS, por ejemplo
api.example.com; - firewall del proveedor y UFW con el acceso necesario a 22, 80 y 443, sin publicar 8000 ni 5432;
- un proyecto con
/healthzy un entorno Alembic ya inicializado.
Instale Docker con la guía para VPS si hace falta. El directorio será /opt/fastapi-app. Prepare los archivos con una cuenta administrativa capaz de escribir en este directorio de root; el contenedor de la aplicación funcionará sin root.
Cree los directorios de despliegue y copias privadas:
sudo install -d -o root -g root -m 755 /opt/fastapi-app
cd /opt/fastapi-app
sudo install -d -o root -g root -m 700 backups
Estructura propuesta:
/opt/fastapi-app/
├── app/
│ ├── __init__.py
│ └── main.py
├── alembic/
├── alembic.ini
├── compose.yaml
├── Dockerfile
├── .dockerignore
├── .env
└── requirements.txt
Construya desde una imagen oficial de Python. La antigua tiangolo/uvicorn-gunicorn-fastapi está obsoleta. Con uv, guarde las versiones exactas en uv.lock y exporte antes de construir:
uv add "fastapi[standard]" sqlalchemy "psycopg[binary]" alembic pydantic-settings
uv export --format requirements-txt --no-dev --no-emit-project \
--output-file requirements.txt
Si ya usa Poetry, pip-tools u otra herramienta, manténgala. Versione el archivo de bloqueo y pruebe las actualizaciones. Compruebe la compatibilidad del proyecto y sus dependencias con Python 3.14 antes de adoptar la imagen del ejemplo.
Incluya una comprobación de vida barata, independiente de servicios externos:
from fastapi import FastAPI
app = FastAPI()
@app.get("/healthz", include_in_schema=False)
def healthz() -> dict[str, str]:
return {"status": "ok"}
La disponibilidad de la base puede tener un /readyz separado. No devuelva secretos, cadenas de conexión ni trazas. Este endpoint no inicializa modelos ni migraciones: configure el entorno Alembic, sus metadatos y su conexión PostgreSQL en el proyecto real.
Guarde /opt/fastapi-app/Dockerfile:
FROM python:3.14-slim
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
RUN groupadd --system --gid 10001 app \
&& useradd --system --uid 10001 --gid app --home-dir /app app
WORKDIR /app
COPY requirements.txt ./requirements.txt
RUN pip install --no-cache-dir --upgrade -r requirements.txt
COPY --chown=app:app . .
USER app
EXPOSE 8000
CMD ["fastapi", "run", "app/main.py", "--host", "0.0.0.0", "--port", "8000"]
Para dependencias compiladas, use varias etapas y deje gcc, cabeceras y cachés fuera de la imagen final. Actualice la base y registre el commit y la identidad de la imagen desplegada.
Excluya al menos estas rutas en .dockerignore:
.git
.env
__pycache__/
*.py[cod]
.pytest_cache/
.venv/
backups/
Excluir .env evita incorporar secretos a la imagen; Compose los suministra durante la ejecución.
Genere una contraseña una sola vez y únicamente en una instalación nueva:
cd /opt/fastapi-app
umask 077
db_password=$(openssl rand -base64 36 | tr -d '\n')
cat > .env.partial <<EOF
POSTGRES_DB=fastapi
POSTGRES_USER=fastapi
POSTGRES_PASSWORD=${db_password}
WEB_CONCURRENCY=2
EOF
mv .env.partial .env
chmod 600 .env
unset db_password
No suba .env a Git ni a solicitudes de soporte. Construya la URL SQLAlchemy con valores separados de POSTGRES_HOST, POSTGRES_DB, POSTGRES_USER y POSTGRES_PASSWORD, usando un constructor de URL para codificar correctamente @, : y / en contraseñas.
Se conserva a continuación la configuración original de /opt/fastapi-app/compose.yaml. Corrija el volumen PostgreSQL antes del primer arranque: las imágenes 18 usan /var/lib/postgresql/18/docker como PGDATA y /var/lib/postgresql como volumen. Sustituya el montaje postgres_data:/var/lib/postgresql/data por postgres_data:/var/lib/postgresql. Consulte la documentación oficial. Si ya hay datos, identifique dónde están y haga una copia verificada antes de cambiarlo; un cambio de montaje no migra datos y puede mostrar una base aparentemente vacía.
name: fastapi-production
x-app: &app
image: fastapi-app:local
build:
context: .
env_file:
- .env
environment:
POSTGRES_HOST: db
POSTGRES_PORT: "5432"
depends_on:
db:
condition: service_healthy
networks:
- backend
services:
db:
image: postgres:18-alpine
restart: unless-stopped
stop_grace_period: 1m
env_file:
- .env
volumes:
- postgres_data:/var/lib/postgresql/data
networks:
- backend
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
interval: 10s
timeout: 5s
retries: 10
start_period: 30s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
migrate:
<<: *app
command: ["alembic", "upgrade", "head"]
restart: "no"
profiles: ["tools"]
app:
<<: *app
restart: unless-stopped
init: true
command:
- fastapi
- run
- app/main.py
- --host
- 0.0.0.0
- --port
- "8000"
- --workers
- "${WEB_CONCURRENCY:-2}"
- --proxy-headers
- --forwarded-allow-ips=*
ports:
- "127.0.0.1:8000:8000"
read_only: true
tmpfs:
- /tmp:size=64m,mode=1777
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
healthcheck:
test:
- CMD
- python
- -c
- "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=3)"
interval: 15s
timeout: 5s
retries: 5
start_period: 20s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
networks:
backend:
volumes:
postgres_data:
depends_on normal establece el orden, no la disponibilidad. service_healthy espera a pg_isready, pero ese resultado por sí solo no comprueba credenciales ni esquema de la aplicación.
--forwarded-allow-ips=* acepta la información reenviada por Nginx: exige el enlace al loopback del host y una red backend de confianza. Revíselo si expone el puerto o conecta otros contenedores. Para archivos subidos o cachés, conserve read_only y monte directorios explícitos con propietarios, capacidad y copias definidos.
Valide el Compose corregido y construya:
cd /opt/fastapi-app
docker compose config --quiet
docker compose build --pull app
docker compose up -d db
docker compose ps
docker compose logs --tail=100 db
Cuando la base esté healthy, ejecute la migración independiente:
docker compose --profile tools run --rm migrate
docker compose up -d app
docker compose ps
docker compose logs --tail=100 app
curl --fail --show-error http://127.0.0.1:8000/healthz
docker image inspect fastapi-app:local --format '{{json .RepoDigests}}'
No lance alembic upgrade head a la vez desde todos los workers. Detenga la publicación si falla y revise sus registros. Al actualizar, mantenga la versión anterior hasta completar una migración compatible.
Use una etiqueta inmutable del commit en lugar de local o latest. Una imagen local puede no tener RepoDigests: registre también su ID y utilice un digest del registro cuando la publique. Cambiar postgres:18-alpine por otra versión principal no actualiza PostgreSQL de forma válida.
Instale proxy y herramientas de certificados en el host:
sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw status verbose
Aplique reglas equivalentes en el proveedor. Sustituya el dominio y guarde /etc/nginx/conf.d/fastapi.conf:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
listen [::]:80;
server_name api.example.com;
client_max_body_size 10m;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
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_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_connect_timeout 5s;
proxy_read_timeout 60s;
proxy_send_timeout 60s;
}
}
Valide antes de recargar y solicitar el certificado:
sudo nginx -t
sudo systemctl reload nginx
curl --fail --show-error http://api.example.com/healthz
sudo certbot --nginx -d api.example.com
sudo certbot renew --dry-run
curl --fail --show-error https://api.example.com/healthz
Certbot modifica Nginx para HTTPS. Compruebe A, AAAA y acceso público por 80/443; un AAAA incorrecto puede impedir la validación. Revise el temporizador de renovación y la prueba de renovación.
proxy_read_timeout no soluciona trabajos de exportación, vídeo o inferencia que duran minutos. Use una cola y consulta de estado para evitar ocupar conexiones y workers indefinidamente. Coordine client_max_body_size con los límites de la aplicación y el CDN. Véase seguridad de Nginx para TLS, cabeceras y límites de solicitudes.
Desactivar /docs y /openapi.json reduce exposición, pero las API administrativas requieren OAuth2, tokens breves, mTLS u otra autenticación adecuada, además de autorización en la aplicación.
Permita dominios frontend reales, métodos y cabeceras necesarios. CORS es una política del navegador, no impide curl ni llamadas entre servidores. Los endpoints sensibles necesitan autenticación y límites de solicitudes.
La migración necesita modificar el esquema; la ejecución suele necesitar solamente lecturas y escrituras del negocio. POSTGRES_USER inicializa un administrador, no un usuario mínimo de ejecución. Separe los permisos según el SQL real antes de producción. Mantenga 5432 privado y use un túnel SSH para administración temporal.
Conserve modo 600 en .env. Genere secretos independientes para base, correo, nube y JWT. Compose env_file no los oculta a usuarios con root o acceso Docker.
El formato personalizado permite inspeccionar con pg_restore. Guarde el script en /opt/fastapi-app/backup.sh:
#!/usr/bin/env bash
set -euo pipefail
umask 077
cd /opt/fastapi-app
backup_stamp=$(date -u +%Y%m%dT%H%M%SZ)
backup_file="backups/fastapi-${backup_stamp}.dump"
partial_file="${backup_file}.partial"
test ! -e "$backup_file"
test ! -e "$partial_file"
docker compose exec -T db sh -c \
'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom --no-owner' \
> "$partial_file"
test -s "$partial_file"
docker compose exec -T db pg_restore --list < "$partial_file" > /dev/null
mv "$partial_file" "$backup_file"
sha256sum "$backup_file" > "${backup_file}.sha256"
printf 'Backup ready: %s\n' "$backup_file"
Ejecútelo y compruebe los archivos:
chmod 700 /opt/fastapi-app/backup.sh
/opt/fastapi-app/backup.sh
ls -lh /opt/fastapi-app/backups
La copia contiene la base del negocio, pero no .env, Nginx, archivos subidos, definiciones de roles ni identidad de imágenes. Respáldelos aparte y cifrados. Copie el archivo completo y .sha256 fuera de la VPS: un único disco no protege de perder la máquina o la cuenta. Una copia diaria puede perder casi un día de cambios. Para objetivos más estrictos, aumente la frecuencia o diseñe archivado WAL. Véase ensayo de recuperación.
La prueba crea una base temporal en la misma instancia PostgreSQL. Comprueba lectura, objetos y consultas básicas, no reconstrucción de una VPS completa. Para bases grandes, use otra instancia aislada y evite agotar disco o E/S de producción:
cd /opt/fastapi-app
backup_file='backups/fastapi-YYYYMMDDTHHMMSSZ.dump'
restore_db="restore_$(date -u +%Y%m%d%H%M%S)"
sha256sum -c "${backup_file}.sha256"
docker compose exec -T db pg_restore --list < "$backup_file" > /dev/null
docker compose exec -T db sh -c \
'createdb -U "$POSTGRES_USER" "'$restore_db'"'
docker compose exec -T db sh -c \
'pg_restore -U "$POSTGRES_USER" -d "'$restore_db'" --no-owner --exit-on-error' \
< "$backup_file"
docker compose exec -T db sh -c \
'psql -U "$POSTGRES_USER" -d "'$restore_db'" -c "\\dt"'
Sustituya el nombre de archivo. Revise filas de tablas importantes, restricciones únicas, registros recientes y alembic_version. Solo después de comprobar que la variable apunta a la base temporal, elimínela:
printf 'temporary database: %s\n' "$restore_db"
docker compose exec -T db sh -c \
'dropdb -U "$POSTGRES_USER" "'$restore_db'"'
unset restore_db
No use pg_restore --clean contra producción. Documente también DNS, certificados, archivos, variables, roles, versión de imagen y orden de restauración.
Observe por separado copia, construcción, migración e inicio:
cd /opt/fastapi-app
/opt/fastapi-app/backup.sh
docker compose build --pull app
docker compose --profile tools run --rm migrate
docker compose up -d app
docker compose ps
docker compose logs --tail=100 app
curl --fail --show-error https://api.example.com/healthz
Son comandos independientes: no siga manualmente después de un error. La automatización debe detenerse al fallar. Pruebe interfaces y migraciones en un entorno previo, conserve la imagen anterior y diseñe cambios de esquema compatibles. Revertir una imagen no deshace una migración; posponga eliminaciones destructivas a una publicación posterior compatible.
Haga copia y ensayo antes de actualizar parches de PostgreSQL. Los cambios de versión principal necesitan otro plan. No use docker compose down -v para solucionar problemas: elimina los volúmenes declarados.
Compruebe cada capa:
curl -v http://127.0.0.1:8000/healthz
docker compose ps
docker compose logs --tail=200 app
sudo tail -n 100 /var/log/nginx/error.log
sudo ss -lntp 'sport = :8000'
Si falla localhost:8000, revise aplicación, contenedor y enlace. Si funciona localmente pero falla el dominio, revise upstream y restricciones SELinux/AppArmor. Siga la lista 502/504.
docker compose ps
docker compose logs --tail=200 db
docker compose exec -T db sh -c \
'pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB"'
docker compose exec -T app getent hosts db
Dentro de Compose use db, no 127.0.0.1. Cambiar .env no modifica una contraseña ya inicializada en el volumen; cambie el rol en PostgreSQL y sincronice la aplicación.
Compruebe X-Forwarded-Proto, confianza en el proxy y exposición privada. Una subruta /api requiere coordinar root_path de FastAPI y el reenvío de rutas de Nginx. Un subdominio API suele simplificarlo.
Revise memoria y conexiones:
docker stats --no-stream
journalctl -k --since '1 hour ago' | grep -i -E 'oom|killed process'
docker compose exec -T db sh -c \
'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "select count(*) from pg_stat_activity;"'
Reduzca workers si falta memoria y reduzca los pools de cada proceso si sobran conexiones. Aumentar solo max_connections de PostgreSQL puede agravar el consumo.
- FastAPI en Docker: imágenes, dependencias, workers y base obsoleta;
- Orden de arranque Compose:
service_healthyy comprobaciones de salud; - Módulo proxy Nginx:
proxy_passy cabeceras; - Certbot con Nginx: emisión y renovación;
- PostgreSQL pg_dump: comportamiento y límites de copias lógicas;
- Tutorial Alembic: entorno de migración y
upgrade head.
Complete construcción, migración, salud, copia y restauración en un dominio de pruebas antes de cambiar el DNS de producción. Mantenga una copia recuperable, una imagen anterior y una migración ejecutada una sola vez por publicación.