Tutoriales de VPS
Airflow 3 en VPS: Celery, servicios privados y recuperación
Instale Airflow 3.4.0 con Compose, FAB, PostgreSQL, Redis y Caddy. Configure API interna y salud autenticada, limite concurrencia, proteja claves y ensaye recuperación de copias.

Airflow resulta útil cuando un flujo necesita dependencias, reintentos, recuperación de ejecuciones e historial observable. Operarlo exige coordinar scheduler, procesador de DAG, servidor API, workers, broker, metadatos y claves de cifrado, además de instalar Python.
Esta guía prepara una instalación recuperable en una VPS Ubuntu 24.04 con Compose, CeleryExecutor, PostgreSQL 17, Redis 7.4, autenticación FAB y Caddy HTTPS. El ejemplo original fija Airflow 3.3.1. La versión oficial consultada el 16 de noviembre de 2026 es 3.4.0, publicada el 6 de noviembre. Para una instalación nueva, utilice imagen Python 3.12 y constraints 3.4.0 coincidentes, aplicando los ajustes indicados. Evite latest y revise notas del núcleo, providers y seguridad antes de actualizar.
- Extraer datos de API, bases o almacenamiento de objetos y transformarlos/cargarlos.
- Generar informes programados, sincronizar índices o archivar logs.
- Coordinar aprendizaje automático y otros procesos por lotes.
- Expresar dependencias, ramas, reintentos, timeouts e intervención manual.
- Conservar estado, parámetros, logs y motivos de fallo.
No sustituye una cola, un servicio permanente ni una ruta de peticiones en milisegundos. Para pocos scripts independientes, cron o timers systemd pueden bastar; los flujos de eventos en tiempo real pueden necesitar Kafka o Flink.
Airflow 3 usa api-server para UI/API y exige procesador DAG separado. El antiguo airflow webserver no sirve: ver la interfaz no demuestra análisis de DAG ni ejecución.
LocalExecutor simplifica un host pequeño. Celery separa programación y ejecución y admite más workers:
| Componente | Función | Cantidad |
|---|---|---|
| Servidor API | UI, autenticación, API y salud | 1 |
| Scheduler | Encolar tareas elegibles | 1 |
| Procesador DAG | Analizar y serializar definiciones | 1 |
| Workers Celery | Recibir y ejecutar tareas | 2, según capacidad |
| Triggerer | Activadores de operadores diferibles | 1 |
| PostgreSQL | Metadatos y resultados Celery | 1 |
| Redis | Broker de mensajes | 1 |
Celery necesita provider, broker y backend de resultados. Redis no es la copia autoritativa del historial; perder el broker interrumpe distribución. Configure contraseña, persistencia, memoria y supervisión.
Dos workers en una VPS comparten fallo de host/disco. Los procesos críticos necesitan base, broker, control y workers en dominios independientes; evalúe Helm oficial o Airflow administrado.
Los 4GB del quick start son un mínimo para arrancar, no una garantía de producción.
| Carga | VPS orientativa | Concurrencia | Condiciones |
|---|---|---|---|
| Aprendizaje | 4 vCPU, 8GB RAM, 80GB SSD | 2 | Un worker, límites reducidos, sin tareas pesadas |
| Producción pequeña | 8 vCPU, 16GB RAM, 160GB NVMe | 4–8 tras pruebas | Empezar conservadoramente y medir picos |
| Flujos mayores | 16 vCPU, 32GB+ RAM | Medida | Separar workers, base y logs |
Un DAG puede abrir procesos Python, Pandas, navegadores o modelos con mucha RAM. Mida cada tarea antes de aumentar concurrencia; salida 137 suele indicar OOM. Consulte la lista de reinicios.
Los límites de todos los contenedores del ejemplo suman aproximadamente 18,3GiB. No reservan memoria, pero demanda simultánea puede superar 16GB. En una instalación inicial de 16GB, reduzca cada worker a mem_limit: 2g y concurrencia 2; ajuste después de medir. Un laboratorio de 8GB requiere también un worker y menores límites de control/base.
| Puerto | Función | Exposición |
|---|---|---|
80/TCP | ACME y redirección HTTPS | Solo Caddy |
443/TCP | UI/API cifrada | Solo Caddy |
8080/TCP | Servidor API | Red Docker, sin publicación |
5432/TCP | PostgreSQL | Red Docker |
6379/TCP | Redis | Red Docker |
22/TCP | Administración | Orígenes limitados y claves |
No publique 0.0.0.0:5432 ni 0.0.0.0:6379. Revise exposición de bases y puertos/cortafuegos. El ejemplo también publica UDP 443 para HTTP/3; habilítelo solo si se usa.
Instale Docker Engine y Compose v2 con las instrucciones oficiales Ubuntu y compruebe herramientas:
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl jq openssl
docker --version
docker compose version
Revise actualizaciones y reinicios. Apunte airflow.example.com al host y abra solo SSH restringido y puertos Caddy. Publique AAAA con IPv6 operativo. Con Cloudflare, revise DNS, modo TLS y conectividad al origen, sin retirar el cortafuegos.
Use una cuenta de mantenimiento sin root. Esta inicialización genera secretos y sobrescribe el entorno; sirve únicamente para instancia nueva:
sudo install -d -m 0750 -o "$USER" -g "$USER" \
/opt/airflow/{dags,logs,plugins,config,backups,caddy-data,caddy-config}
cd /opt/airflow
AIRFLOW_FERNET_KEY="$(docker run --rm apache/airflow:3.3.1-python3.12 \
python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
umask 077
cat > .env <<EOF
AIRFLOW_IMAGE_NAME=airflow-local:3.3.1
AIRFLOW_UID=$(id -u)
AIRFLOW_DOMAIN=airflow.example.com
AIRFLOW_ADMIN_USER=airflowadmin
AIRFLOW_ADMIN_PASSWORD=$(openssl rand -hex 24)
[email protected]
POSTGRES_DB=airflow
POSTGRES_USER=airflow
POSTGRES_PASSWORD=$(openssl rand -hex 32)
REDIS_PASSWORD=$(openssl rand -hex 32)
AIRFLOW_FERNET_KEY=${AIRFLOW_FERNET_KEY}
AIRFLOW_API_SECRET_KEY=$(openssl rand -hex 32)
AIRFLOW_JWT_SECRET=$(openssl rand -hex 32)
EOF
chmod 600 .env
Cambie dominio/email. Proteja .env. Fernet cifra contraseñas de Connection/Variable; claves JWT/API deben coincidir entre componentes. Guarde copias seguras y permita escritura de directorios al UID elegido. Si la cuenta del host es root, seleccione AIRFLOW_UID sin privilegios y ajuste propietarios.
Simple Auth Manager es para desarrollo/pruebas. Aquí se instala FAB oficial, con posibilidad de OAuth, LDAP o SSO. Cree /opt/airflow/Dockerfile:
FROM apache/airflow:3.3.1-python3.12
ARG AIRFLOW_VERSION=3.3.1
ARG PYTHON_VERSION=3.12
ARG CONSTRAINT_URL=https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt
RUN pip install --no-cache-dir \
"apache-airflow==${AIRFLOW_VERSION}" \
apache-airflow-providers-celery \
apache-airflow-providers-fab \
--constraint "${CONSTRAINT_URL}"
Para la instalación nueva revisada, actualice imagen y versión de constraints antes de construir:
cd /opt/airflow
sed -i 's/^FROM apache\/airflow:.*/FROM apache\/airflow:3.4.0-python3.12/;s/^ARG AIRFLOW_VERSION=.*/ARG AIRFLOW_VERSION=3.4.0/' Dockerfile
sed -i 's/^AIRFLOW_IMAGE_NAME=.*/AIRFLOW_IMAGE_NAME=airflow-local:3.4.0/' .env
chmod 600 .env
Constraints Python 3.12 de 3.4.0 incluyen providers Celery 3.26.0 y FAB 3.10.2. No ejecute pip install -U sin restricciones. Añada dependencias de DAG mediante requirements.txt, reconstruya y conserve digest. La imagen anterior solo genera la clave Fernet; estos cambios seleccionan el núcleo ejecutado.
Cree /opt/airflow/compose.yml:
x-airflow-common: &airflow-common
image: ${AIRFLOW_IMAGE_NAME}
build:
context: .
env_file:
- .env
environment: &airflow-common-env
AIRFLOW__CORE__EXECUTOR: CeleryExecutor
AIRFLOW__CORE__AUTH_MANAGER: airflow.providers.fab.auth_manager.fab_auth_manager.FabAuthManager
AIRFLOW__DATABASE__EXTERNAL_DB_MANAGERS: airflow.providers.fab.auth_manager.models.db.FABDBManager
AIRFLOW__DATABASE__SQL_ALCHEMY_CONN: postgresql+psycopg2://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres/${POSTGRES_DB}
AIRFLOW__CELERY__RESULT_BACKEND: db+postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres/${POSTGRES_DB}
AIRFLOW__CELERY__BROKER_URL: redis://:${REDIS_PASSWORD}@redis:6379/0
AIRFLOW__CORE__FERNET_KEY: ${AIRFLOW_FERNET_KEY}
AIRFLOW__API__SECRET_KEY: ${AIRFLOW_API_SECRET_KEY}
AIRFLOW__API_AUTH__JWT_SECRET: ${AIRFLOW_JWT_SECRET}
AIRFLOW__API__BASE_URL: https://${AIRFLOW_DOMAIN}
AIRFLOW__CORE__LOAD_EXAMPLES: "false"
AIRFLOW__SCHEDULER__ENABLE_HEALTH_CHECK: "true"
AIRFLOW__LOGGING__LOGGING_LEVEL: INFO
user: "${AIRFLOW_UID:-50000}:0"
volumes:
- ./dags:/opt/airflow/dags
- ./logs:/opt/airflow/logs
- ./plugins:/opt/airflow/plugins
- ./config:/opt/airflow/config
depends_on: &airflow-common-depends-on
postgres:
condition: service_healthy
redis:
condition: service_healthy
airflow-init:
condition: service_completed_successfully
restart: unless-stopped
logging:
driver: json-file
options:
max-size: 20m
max-file: "5"
services:
postgres:
image: postgres:17-alpine
environment:
POSTGRES_DB: ${POSTGRES_DB}
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- postgres-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 10
restart: unless-stopped
mem_limit: 2g
redis:
image: redis:7.4-alpine
command:
- redis-server
- --appendonly
- "yes"
- --requirepass
- ${REDIS_PASSWORD}
- --maxmemory
- 768mb
- --maxmemory-policy
- noeviction
volumes:
- redis-data:/data
healthcheck:
test: ["CMD-SHELL", "redis-cli -a '$${REDIS_PASSWORD}' ping | grep PONG"]
interval: 10s
timeout: 5s
retries: 10
restart: unless-stopped
mem_limit: 1g
airflow-init:
<<: *airflow-common
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
restart: "no"
command:
- bash
- -c
- |
set -e
airflow db migrate
if ! airflow users create \
--username "$${AIRFLOW_ADMIN_USER}" \
--password "$${AIRFLOW_ADMIN_PASSWORD}" \
--firstname Airflow \
--lastname Admin \
--role Admin \
--email "$${AIRFLOW_ADMIN_EMAIL}"; then
airflow users list | grep -Fq "$${AIRFLOW_ADMIN_USER}"
fi
airflow-apiserver:
<<: *airflow-common
command: api-server
healthcheck:
test: ["CMD", "curl", "--fail", "http://localhost:8080/api/v2/monitor/health"]
interval: 20s
timeout: 10s
retries: 10
start_period: 60s
mem_limit: 2g
airflow-scheduler:
<<: *airflow-common
command: scheduler
mem_limit: 2g
airflow-dag-processor:
<<: *airflow-common
command: dag-processor
mem_limit: 2g
airflow-triggerer:
<<: *airflow-common
command: triggerer
mem_limit: 1g
airflow-worker-1:
<<: *airflow-common
command: celery worker
environment:
<<: *airflow-common-env
AIRFLOW__CELERY__WORKER_CONCURRENCY: "4"
mem_limit: 4g
airflow-worker-2:
<<: *airflow-common
command: celery worker
environment:
<<: *airflow-common-env
AIRFLOW__CELERY__WORKER_CONCURRENCY: "4"
mem_limit: 4g
caddy:
image: caddy:2-alpine
environment:
AIRFLOW_DOMAIN: ${AIRFLOW_DOMAIN}
ports:
- "80:80"
- "443:443"
- "443:443/udp"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- ./caddy-data:/data
- ./caddy-config:/config
depends_on:
airflow-apiserver:
condition: service_healthy
restart: unless-stopped
mem_limit: 256m
volumes:
postgres-data:
redis-data:
Antes del primer arranque, añada a x-airflow-common.environment la API interna, conservando la URL pública:
AIRFLOW__CORE__EXECUTION_API_SERVER_URL: http://airflow-apiserver:8080/execution/
Los workers necesitan la dirección Docker accesible. localhost dentro de un worker apunta a él mismo; el proxy público no debe ser necesario para ejecutar tareas. Mantenga la clave JWT compartida.
Añada este environment al servicio redis existente. La comprobación de salud lee una variable del contenedor; la interpolación Compose por sí sola no la inyecta:
environment:
REDIS_PASSWORD: ${REDIS_PASSWORD}
No duplique redis ni sustituya su command. mem_limit limita cada contenedor. En hosts pequeños, retire airflow-worker-2 y reduzca concurrencia/límites. Revise la lista Compose de producción.
Redis noeviction evita expulsar mensajes, pero rechaza escrituras con memoria llena. Supervise capacidad, persistencia y errores. Evalúe RabbitMQ si encajan mejor sus confirmaciones, rutas o gestión.
Cree /opt/airflow/Caddyfile:
{$AIRFLOW_DOMAIN} {
encode zstd gzip
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
Referrer-Policy "strict-origin-when-cross-origin"
}
reverse_proxy airflow-apiserver:8080
}
Caddy renueva certificados; no publique 8080 para evitar acceso que omita TLS. Configure AIRFLOW__API__BASE_URL con la dirección real y defina intermediarios confiables. Use HSTS includeSubDomains solo si todos esos nombres admiten HTTPS.
La validación quiet evita imprimir secretos expandidos; no publique configuración completa:
cd /opt/airflow
docker compose config --quiet
docker compose build --pull
docker compose up airflow-init
docker compose up -d
docker compose ps
La inicialización ejecuta airflow db migrate, incluido FAB configurado, y crea administrador. Revise logs:
docker compose logs --tail=100 airflow-init
docker compose logs --tail=100 airflow-apiserver
docker compose logs --tail=100 airflow-scheduler
docker compose logs --tail=100 airflow-dag-processor
docker compose logs --tail=100 airflow-worker-1
docker compose logs --tail=100 caddy
Cargue solo su entorno local confiable antes de usar variables de dominio/base en el shell:
cd /opt/airflow
set -a
. ./.env
set +a
Compruebe componentes:
curl -fsS "https://${AIRFLOW_DOMAIN}/api/v2/monitor/health" | jq
docker compose exec airflow-scheduler \
airflow jobs check --job-type SchedulerJob --local
docker compose exec airflow-dag-processor \
airflow jobs check --job-type DagProcessorJob --local
docker compose exec airflow-worker-1 \
celery --app airflow.providers.celery.executors.celery_executor.app \
inspect ping
/api/v2/monitor/health no necesita autenticación. HTTP 200 indica petición atendida; revise también los estados de base y jobs del JSON. Compruebe análisis DAG, ejecución real, logs completos y salud continuada de Redis/PostgreSQL. Use Prometheus y Grafana.
Cree /opt/airflow/dags/vps_smoke_test.py:
from datetime import datetime
from airflow.sdk import DAG, task
with DAG(
dag_id="vps_smoke_test",
schedule=None,
start_date=datetime(2026, 1, 1),
catchup=False,
tags=["smoke-test"],
) as dag:
@task
def show_worker() -> str:
import socket
return socket.gethostname()
@task
def confirm(hostname: str) -> None:
print(f"Celery task completed on {hostname}")
confirm(show_worker())
Actívelo en la UI tras analizarse: ambas tareas deben terminar, el worker recibirlas y la UI mostrar logs. Si falta:
docker compose exec airflow-dag-processor airflow dags list-import-errors
docker compose exec airflow-dag-processor python /opt/airflow/dags/vps_smoke_test.py
Corrija imports, permisos o dependencias; reiniciar API repetidamente no resuelve análisis. La fecha histórica con catchup desactivado no solicita un backlog.
Controle acceso a API/base independientemente de procesos worker:
docker compose exec airflow-apiserver \
airflow pools set external_api 4 "第三方 API 并发限制"
docker compose exec airflow-apiserver airflow pools list
Asigne pool="external_api" a tareas pertinentes. Puede cambiar la descripción humana del pool al idioma del equipo. Use pools menores para alta RAM y límites por DAG. Aumentar parallelism, workers y conexiones juntos puede saturar PostgreSQL, disco o API externas.
No basta con dags/. Conserve:
- Metadatos PostgreSQL, usuarios, conexiones, variables e historial.
dags/,plugins/,config/y archivos de despliegue..envcon claves Fernet/JWT/API y credenciales.- Logs de tareas o almacenamiento remoto comprobado.
- Dockerfile, requirements adicionales, etiquetas y digests.
Cree /opt/airflow/backup.sh:
#!/usr/bin/env bash
set -Eeuo pipefail
cd /opt/airflow
stamp="$(date -u +%Y%m%dT%H%M%SZ)"
dest="backups/${stamp}"
mkdir -p "${dest}"
docker compose exec -T postgres \
pg_dump -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" \
--format=custom --no-owner --no-privileges \
> "${dest}/airflow.dump"
tar --exclude='./backups' \
-czf "${dest}/airflow-files.tar.gz" \
.env Dockerfile compose.yml Caddyfile dags plugins config
sha256sum "${dest}"/* > "${dest}/SHA256SUMS"
find backups -mindepth 1 -maxdepth 1 -type d -mtime +14 -print
Inserte inmediatamente después de cd /opt/airflow estas líneas. Compose interpola .env, pero no define POSTGRES_USER/POSTGRES_DB dentro del script:
set -a
. ./.env
set +a
umask 077
Añada logs a tar si son locales y requirements.txt si se usa. Restrinja script/directorios, haga ejecutable backup.sh y cifre archivos fuera del host. Compruebe pg_dump, archivo y checksum. find solo lista directorios de más de 14 días; una política explícita debe eliminar después de confirmar copias independientes.
Sin Fernet no se descifran secretos aunque exista dump. Rote con clave nueva,clave antigua (新密钥,旧密钥), ejecute airflow rotate-fernet-key con configuración compartida, confirme recifrado y retire la clave antigua.
Use otra VPS o un proyecto Compose distinto, volúmenes nuevos, DNS de pruebas y puertos sin conflictos. Recupere configuración/entorno y cargue .env confiable. Estos comandos reemplazan la base del destino:
cd /opt/airflow
docker compose down
docker compose up -d postgres redis
docker compose exec -T postgres \
dropdb -U "${POSTGRES_USER}" --if-exists "${POSTGRES_DB}"
docker compose exec -T postgres \
createdb -U "${POSTGRES_USER}" "${POSTGRES_DB}"
docker compose exec -T postgres \
pg_restore -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" \
--clean --if-exists --no-owner --no-privileges \
< backups/替换为时间戳/airflow.dump
docker compose run --rm airflow-init
docker compose up -d
Cambie el marcador de fecha por la ruta archivada real. Empiece con imagen compatible original y espere disponibilidad PostgreSQL antes de dropdb/createdb. Revise login, DAG, historial, descifrado, una tarea y logs. Tras reconstruir broker, concilie queued/running con efectos externos antes de repetir operaciones no idempotentes.
Lea notas core/providers y haga copia externa. Detenga todos los componentes que escriben antes de migrar metadatos:
cd /opt/airflow
./backup.sh
docker compose stop \
airflow-apiserver airflow-scheduler airflow-dag-processor \
airflow-triggerer airflow-worker-1 airflow-worker-2
# 修改 Dockerfile 和 .env 中的固定版本后
docker compose build --pull
docker compose run --rm airflow-init
docker compose up -d
docker compose ps
Actualice Dockerfile y entorno juntos. Si quitó el segundo worker, omítalo también en comandos. Use airflow db migrate, no airflow db init retirado ni db upgrade histórico. Ensaye cambios mayores con una base restaurada. Una migración incompatible exige imagen antigua y base/configuración anteriores para volver atrás.
Compruebe AIRFLOW__CORE__AUTH_MANAGER, FAB, airflow-init y AIRFLOW__API__BASE_URL. Las instancias API comparten secreto; revise cabeceras proxy y URL pública.
Revise airflow-dag-processor, propietarios y airflow dags list-import-errors. El procesador es obligatorio e independiente de UI.
Revise autenticación Redis, broker URL, workers, colas, provider, pools y concurrencia. Compruebe después API interna y JWT.
Compruebe claves API/JWT compartidas y relojes sincronizados; tokens caducados o mal temporizados rechazan peticiones y logs.
Sume API, scheduler, procesador, triggerer y workers antes de ajustar SQLAlchemy. Elevar max_connections consume RAM y puede ocultar fugas.
Use docker compose ps, docker inspect y journalctl -k. Reduzca concurrencia, pools pesados o amplíe recursos; vea la guía de reinicios.
4GB sirve para experimentar. Producción pequeña puede empezar en 8 vCPU/16GB con límites worker reducidos, dimensionando por análisis y picos de tarea.
Use airflow api-server en vez de webserver y el procesador DAG obligatorio. Actualice health checks y upstreams juntos.
PostgreSQL, DAG, configuración y claves son esenciales. AOF ayuda en fallos breves, pero Redis no es historial; concilie tareas pendientes antes de repetirlas.
Gestiona usuarios/roles e identidad empresarial. Añada SSO/MFA, acceso restringido o VPN según necesidad; instalar FAB no configura esas medidas automáticamente.
No. Conserve claves aparte y rote mediante transición multiclave y airflow rotate-fernet-key.
Aumentan paralelismo local; tolerar fallo del host necesita dominios independientes, logs remotos y copias externas.
- Fije núcleo, providers, PostgreSQL y Redis; evite
latest. - Publique Caddy y SSH restringido, conservando 8080/5432/6379 privados.
- Ejecute API, scheduler, procesador, triggerer y workers seleccionados.
- Revise
/api/v2/monitor/health, jobs, DAG de prueba y logs completos. - Use contraseña FAB aleatoria y planifique acceso empresarial.
- Guarde claves Fernet/JWT/API y credenciales offline.
- Mantenga copias independientes de base, despliegue y logs; ensaye recuperación.
- Dimensione workers, pools, conexiones y RAM por mediciones.
- Copie, detenga componentes y ejecute
airflow db migrateal actualizar. - Supervise host, contenedores, profundidad de cola y fallos de tareas.