Tutoriais de VPS
Airflow 3 na VPS: Celery, serviços privados e recuperação
Implante Airflow 3.4.0 com Compose, FAB, PostgreSQL, Redis e Caddy. Configure API interna e saúde autenticada, limite concorrência, proteja chaves e ensaie recuperação de backups.

Airflow ajuda quando um fluxo precisa de dependências, novas tentativas, reprocessamento e histórico visível. Operá-lo exige coordenar scheduler, processador DAG, servidor API, workers, broker, banco de metadados e chaves de criptografia, além de instalar Python.
Este guia prepara uma implantação recuperável em uma VPS Ubuntu 24.04 com Compose, CeleryExecutor, PostgreSQL 17, Redis 7.4, autenticação FAB e Caddy HTTPS. O exemplo original fixa Airflow 3.3.1. A versão oficial consultada em 16 de novembro de 2026 é 3.4.0, lançada em 6 de novembro. Em instalação nova, use imagem Python 3.12 e constraints 3.4.0 correspondentes, aplicando os ajustes abaixo. Evite latest e confira notas do core, providers e segurança antes de atualizar.
- Extrair dados de APIs, bancos ou objetos, transformar e carregar.
- Gerar relatórios programados, sincronizar índices e arquivar logs.
- Coordenar aprendizado de máquina e outros processos em lote.
- Definir dependências, ramificações, tentativas, timeouts e intervenção manual.
- Preservar estados, parâmetros, logs e causas de falha.
Airflow não substitui fila, serviço contínuo ou requisições em milissegundos. Para poucos scripts independentes, cron ou timers systemd podem bastar; eventos em tempo real podem exigir Kafka ou Flink.
Airflow 3 usa api-server na UI/API e exige processador DAG separado. O antigo airflow webserver não serve: abrir a interface não comprova análise nem execução.
LocalExecutor simplifica um host pequeno. Celery separa agendamento da execução e permite adicionar workers:
| Componente | Função | Quantidade |
|---|---|---|
| Servidor API | UI, autenticação, API pública e saúde | 1 |
| Scheduler | Enfileirar tarefas elegíveis | 1 |
| Processador DAG | Analisar e serializar definições | 1 |
| Workers Celery | Receber e executar tarefas | 2, conforme capacidade |
| Triggerer | Acionadores de operadores adiáveis | 1 |
| PostgreSQL | Metadados e resultados Celery | 1 |
| Redis | Broker de mensagens | 1 |
Celery precisa de provider, broker e backend de resultados. Redis não é o histórico autoritativo: perda do broker interrompe distribuição. Configure senha, persistência, memória e monitoramento.
Dois workers na mesma VPS compartilham falha de host/disco. Sistemas críticos precisam separar banco, broker, controle e workers em domínios independentes; considere Helm oficial ou Airflow gerenciado.
Os 4GB do quick start são um mínimo para iniciar, não garantia de produção.
| Carga | VPS inicial sugerida | Concorrência | Condições |
|---|---|---|---|
| Aprendizado | 4 vCPU, 8GB RAM, SSD de 80GB | 2 | Um worker, limites reduzidos, sem tarefas pesadas |
| Produção pequena | 8 vCPU, 16GB RAM, NVMe de 160GB | 4–8 após testes | Começar conservadoramente e medir picos |
| Fluxos maiores | 16 vCPU, 32GB+ RAM | Medida | Separar workers, banco e logs |
Um DAG pode abrir processos Python, Pandas, navegador ou modelos que consomem muita RAM. Meça cada tarefa antes de elevar concorrência; saída 137 costuma ser OOM. Veja a lista de reinicializações.
Os limites do exemplo completo somam cerca de 18,3GiB. Não reservam memória, mas demanda simultânea pode superar 16GB. Para começar em 16GB, reduza cada worker para mem_limit: 2g e concorrência 2; ajuste depois de medir. Um laboratório de 8GB também exige um worker e limites menores de controle/banco.
| Porta | Função | Exposição |
|---|---|---|
80/TCP | ACME e redirecionamento HTTPS | Só Caddy |
443/TCP | UI/API com TLS | Só Caddy |
8080/TCP | Servidor API | Rede Docker, sem publicação |
5432/TCP | PostgreSQL | Rede Docker |
6379/TCP | Redis | Rede Docker |
22/TCP | Administração | Origens restritas e chaves SSH |
Não publique 0.0.0.0:5432 nem 0.0.0.0:6379. Confira exposição dos bancos e portas/firewall. O exemplo também publica UDP 443 para HTTP/3; habilite somente se necessário.
Instale Docker Engine e Compose v2 pelas instruções oficiais Ubuntu e confira ferramentas:
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl jq openssl
docker --version
docker compose version
Avalie atualizações e reinicialização do sistema. Aponte airflow.example.com ao host e abra apenas SSH restrito e portas Caddy. Publique AAAA com IPv6 funcionando. Com Cloudflare, confira DNS, modo TLS e acesso à origem sem retirar o firewall.
Use uma conta de manutenção sem root. A inicialização gera segredos e sobrescreve o ambiente; execute somente em instância nova:
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
Troque domínio/email e proteja .env. Fernet criptografa senhas de Connection/Variable; chaves JWT/API devem coincidir nos componentes que as usam. Preserve cópias seguras e dê escrita dos diretórios ao UID escolhido. Se a conta do host for root, selecione AIRFLOW_UID sem privilégios e ajuste proprietários.
Simple Auth Manager atende desenvolvimento/testes. Aqui usamos FAB oficial, com possibilidade de OAuth, LDAP ou SSO. Crie /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}"
Na instalação nova revisada, atualize imagem e versão 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 incluem providers Celery 3.26.0 e FAB 3.10.2. Não execute pip install -U sem restrições. Adicione dependências DAG via requirements.txt, reconstrua e guarde digest. A imagem anterior apenas gera a chave Fernet; os ajustes escolhem o core em execução.
Crie /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 da primeira inicialização, adicione a API interna em x-airflow-common.environment, mantendo a URL pública:
AIRFLOW__CORE__EXECUTION_API_SERVER_URL: http://airflow-apiserver:8080/execution/
Workers precisam desse endereço Docker acessível. localhost dentro do worker aponta para ele próprio; o proxy público não deve ser necessário para executar tarefas. Mantenha a chave JWT compartilhada.
Adicione este environment ao serviço redis existente. O health check lê uma variável do contêiner; interpolação Compose não a injeta automaticamente:
environment:
REDIS_PASSWORD: ${REDIS_PASSWORD}
Não duplique redis nem substitua command. mem_limit limita cada contêiner. Em hosts pequenos, retire airflow-worker-2 e reduza concorrência/limites. Use a lista Compose de produção.
Redis noeviction evita expulsar mensagens, mas rejeita gravações quando a memória acaba. Monitore capacidade, persistência e erros. Avalie RabbitMQ se confirmações, rotas ou operação forem mais adequadas.
Crie /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 renova certificados; não publique 8080, evitando acesso que contorne TLS. Configure AIRFLOW__API__BASE_URL com endereço real e defina intermediários confiáveis. Use HSTS includeSubDomains apenas se todos esses nomes suportarem HTTPS.
A validação quiet evita imprimir segredos expandidos; não publique configuração completa:
cd /opt/airflow
docker compose config --quiet
docker compose build --pull
docker compose up airflow-init
docker compose up -d
docker compose ps
A inicialização executa airflow db migrate, incluindo FAB configurado, e cria administrador. Confira 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
Carregue apenas seu ambiente local confiável antes de usar variáveis de domínio/banco no shell:
cd /opt/airflow
set -a
. ./.env
set +a
Confira 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 dispensa autenticação. HTTP 200 indica requisição atendida; confira também estados de banco/jobs no JSON. Teste análise DAG, execução real, logs completos e saúde contínua de Redis/PostgreSQL. Use Prometheus e Grafana.
Crie /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())
Acione pela UI após análise: ambas as tarefas devem terminar, o worker recebê-las e a UI mostrar logs. Se faltar:
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, permissões ou dependências; reiniciar API repetidamente não resolve análise. A data histórica com catchup desativado não solicita backlog.
Controle API/banco separadamente dos processos worker:
docker compose exec airflow-apiserver \
airflow pools set external_api 4 "第三方 API 并发限制"
docker compose exec airflow-apiserver airflow pools list
Atribua pool="external_api" às tarefas pertinentes. A descrição humana do pool pode usar o idioma da equipe. Use pools menores para alta RAM e limites por DAG. Aumentar parallelism, workers e conexões juntos pode saturar PostgreSQL, disco ou APIs externas.
Não basta dags/. Preserve:
- Metadados PostgreSQL, usuários, conexões, variáveis e histórico.
dags/,plugins/,config/e arquivos de implantação..envcom chaves Fernet/JWT/API e credenciais.- Logs de tarefas ou armazenamento remoto verificado.
- Dockerfile, requirements adicionais, tags e digests.
Crie /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
Insira logo após cd /opt/airflow estas linhas. Compose interpola .env, mas não define POSTGRES_USER/POSTGRES_DB no script:
set -a
. ./.env
set +a
umask 077
Inclua logs no tar quando locais e requirements.txt quando usado. Restrinja script/diretórios, torne backup.sh executável e criptografe arquivos fora do host. Confira pg_dump, arquivo e checksum. find só lista diretórios com mais de 14 dias; uma política explícita deve excluir após confirmar cópias independentes.
Sem Fernet não é possível descriptografar segredos mesmo com dump. Faça rotação na ordem chave nova,chave antiga (新密钥,旧密钥), execute airflow rotate-fernet-key com configuração compartilhada, confirme nova criptografia e retire a chave antiga.
Use outra VPS ou projeto Compose diferente, volumes novos, DNS de teste e portas sem conflitos. Recupere configuração/ambiente e carregue .env confiável. Estes comandos substituem o banco do 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
Troque o marcador de data pelo caminho real. Comece com imagem original compatível e aguarde PostgreSQL antes de dropdb/createdb. Confira login, DAGs, histórico, descriptografia, tarefa de teste e logs. Depois de reconstruir broker, reconcilie queued/running com efeitos externos antes de repetir operações não idempotentes.
Leia notas core/providers e faça backup externo. Pare todos os componentes que gravam antes de migrar metadados:
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
Atualize Dockerfile e ambiente juntos. Se removeu o segundo worker, retire-o também dos comandos. Use airflow db migrate, não airflow db init removido nem db upgrade histórico. Ensaie mudanças maiores com banco restaurado. Migração incompatível exige imagem antiga e banco/configuração anteriores para rollback.
Confira AIRFLOW__CORE__AUTH_MANAGER, FAB, airflow-init e AIRFLOW__API__BASE_URL. Instâncias API compartilham segredo; confira cabeçalhos proxy e URL pública.
Confira airflow-dag-processor, proprietários e airflow dags list-import-errors. O processador é obrigatório e independente da UI.
Confira autenticação Redis, broker URL, workers, filas, provider, pools e concorrência. Depois confira API interna e JWT.
Confira chaves API/JWT compartilhadas e relógios sincronizados; tokens expirados ou com horário incorreto rejeitam requisições e logs.
Some API, scheduler, processador, triggerer e workers antes de ajustar SQLAlchemy. Aumentar max_connections consome RAM e pode esconder vazamentos.
Use docker compose ps, docker inspect e journalctl -k. Reduza concorrência/pools pesados ou amplie recursos; veja o guia de reinicialização.
4GB serve para experimentar. Produção pequena pode começar em 8 vCPU/16GB com limites worker reduzidos, dimensionando por análise e picos de tarefas.
Use airflow api-server em vez de webserver e mantenha o processador DAG obrigatório. Atualize health checks e upstreams juntos.
PostgreSQL, DAGs, configuração e chaves são essenciais. AOF ajuda em falhas breves, mas Redis não é histórico; reconcilie tarefas pendentes antes de repetir.
Gerencia usuários/papéis e identidade empresarial. Adicione SSO/MFA, restrição de acesso ou VPN conforme necessidade; instalar FAB não configura isso automaticamente.
Não. Preserve chaves separadamente e faça rotação multichave com airflow rotate-fernet-key.
Aumentam paralelismo local; tolerar falha do host exige domínios independentes, logs remotos e backups externos.
- Fixe core, providers, PostgreSQL e Redis; evite
latest. - Publique Caddy e SSH restrito, mantendo 8080/5432/6379 privados.
- Execute API, scheduler, processador, triggerer e workers escolhidos.
- Confira
/api/v2/monitor/health, jobs, DAG de teste e logs completos. - Use senha FAB aleatória e planeje acesso empresarial.
- Guarde chaves Fernet/JWT/API e credenciais offline.
- Mantenha backups independentes de banco, implantação e logs; ensaie recuperação.
- Dimensione workers, pools, conexões e RAM por medições.
- Faça backup, pare componentes e execute
airflow db migrateao atualizar. - Monitore host, contêineres, profundidade da fila e falhas de tarefas.