在 Docker 中运行 Airflow
本快速入门指南将帮助您通过 Docker 快速启动并运行使用 CeleryExecutor 的 Airflow。

注意
此流程适用于学习和探索。然而,将其应用于实际场景可能较为复杂,且提供的 docker compose 文件不包含生产系统所需的安全保障。修改此流程需要具备 Docker 和 Docker Compose 的专业知识,Airflow 社区可能无法提供相关支持。
因此,我们建议在生产环境中使用 Kubernetes 和官方 Airflow 社区 Helm Chart。

准备工作

本流程假设您熟悉 Docker 和 Docker Compose。如果您尚未接触过这些工具,请先学习 Docker 快速入门(尤其是 Docker Compose 部分)。

安装必要工具

  1. 安装 Docker Community Edition (CE)
    根据您的操作系统,可能需要为 Docker 分配至少 4GB 内存以确保 Airflow 容器正常运行。

  2. 安装 Docker Compose v2.14.0 或更高版本
    旧版本的 docker-compose 不支持 Airflow docker-compose.yaml 文件的所有功能,请确保版本符合最低要求。

提示
在 macOS 上,Docker 的默认内存分配通常不足以运行 Airflow。如果内存不足,可能导致 Web 服务器不断重启。建议为 Docker Engine 分配至少 4GB 内存(理想情况下 8GB)。
可以通过以下命令检查内存:

docker run --rm "debian:bookworm-slim" bash -c 'numfmt --to iec $(echo $(($(getconf _PHYS_PAGES) * $(getconf PAGE_SIZE))))'

警告
某些操作系统(如 Fedora、ArchLinux、RHEL、Rocky)最近的内核变更导致在社区版 Docker 中运行 Airflow 时内存占用 100%。
这是 containerd 配置的向后兼容性问题,相关讨论见:

获取 docker-compose.yaml

运行以下命令下载 docker-compose.yaml

curl -LfO 'https://airflow.apache.org/docs/apache-airflow/3.0.1/docker-compose.yaml'

重要说明
从 2023 年 7 月起,Compose V1 停止更新。强烈建议升级到新版 Docker Compose,旧版可能无法正确运行此文件。

文件内容

该文件包含以下服务定义:

  • airflow-scheduler:监控任务和 DAG,触发满足依赖的任务实例。
  • airflow-dag-processor:解析 DAG 文件。
  • airflow-api-server:API 服务器,运行在 http://localhost:8080
  • airflow-worker:执行调度器分配的任务。
  • airflow-triggerer:运行可延迟任务的事件循环。
  • airflow-init:初始化服务。
  • postgres:数据库。
  • redis:消息代理,转发调度器到工作器的消息。
  • flower(可选):监控环境,运行于 http://localhost:5555。可通过 docker compose --profile flower up 启用。

挂载目录

以下目录与容器同步:

  • ./dags:存放 DAG 文件。
  • ./logs:任务执行和调度器日志。
  • ./config:自定义日志解析器或 airflow_local_settings.py
  • ./plugins:自定义插件。

初始化环境

首次启动前,需初始化环境和数据库。

设置 Airflow 用户(Linux)

确保文件权限正确:

mkdir -p ./dags ./logs ./plugins ./config
echo -e "AIRFLOW_UID=$(id -u)" > .env

其他操作系统可忽略警告,或手动创建 .env 文件:

AIRFLOW_UID=50000

初始化 airflow.cfg(可选)

生成默认配置:

docker compose run airflow-cli airflow config list

初始化数据库

运行以下命令完成数据库迁移并创建首个用户:

docker compose up airflow-init

完成后会显示:

airflow-init_1 | Upgrades done  
airflow-init_1 | Admin user airflow created  
airflow-init_1 | 3.0.1  
start_airflow-init_1 exited with code 0

默认账号:airflow,密码:airflow

清理环境

若需从头开始:

  1. 运行 docker compose down --volumes --remove-orphans
  2. 删除 docker-compose.yaml 所在目录:rm -rf '<DIRECTORY>'
  3. 重新下载文件并从头开始。

启动 Airflow

运行以下命令启动所有服务:

docker compose up

检查容器状态:

docker ps

应显示所有容器为“healthy”。

访问环境

可通过以下方式交互:

  1. CLI 命令
    docker compose run airflow-worker airflow info
    
    或使用便捷脚本:
    curl -LfO 'https://airflow.apache.org/docs/apache-airflow/3.0.1/airflow.sh'
    chmod +x airflow.sh
    ./airflow.sh info
    
  2. Web 界面
    访问 http://localhost:8080,使用账号 airflow/airflow
  3. REST API
    示例请求:
    ENDPOINT_URL="http://localhost:8080/"
    curl -X GET --user "airflow:airflow" "${ENDPOINT_URL}/api/v1/pools"
    

停止并清理

运行以下命令停止并删除容器及数据:

docker compose down --volumes --rmi all

使用自定义镜像

如需扩展镜像(如添加 Python 包),可修改 docker-compose.yaml

  1. 取消 build: . 注释,并添加 Dockerfile
    FROM apache/airflow:3.0.1
    ADD requirements.txt .
    RUN pip install apache-airflow==${AIRFLOW_VERSION} -r requirements.txt
    
  2. 运行 docker compose build 或添加 --build 标志。

特殊配置

  • 自定义配置文件:替换 ./config/airflow.cfg 并调整 AIRFLOW_CONFIG 路径。
  • 网络配置:若需从容器访问主机服务,需在 docker-compose.yaml 中添加 extra_hosts(如 Linux 下 host.docker.internal:host-gateway)。

使用 PyCharm 调试

  1. 修改 docker-compose.yaml,添加 airflow-python 服务。
  2. 在 PyCharm 中配置 Python 解释器,选择 Docker Compose 和 airflow-python 服务。
  3. 完成配置后即可调试。

常见问题

  • 模块未找到:需通过自定义镜像安装依赖。
  • 其他问题:参考 FAQ

后续步骤

环境变量

变量名 描述 默认值
AIRFLOW_IMAGE_NAME Airflow 镜像 apache/airflow:3.0.1
AIRFLOW_UID 运行容器的用户 UID 50000

测试专用变量(非生产用途):

  • _AIRFLOW_WWW_USER_USERNAME:管理员账号(默认 airflow)。
  • _AIRFLOW_WWW_USER_PASSWORD:管理员密码(默认 airflow)。
  • _PIP_ADDITIONAL_REQUIREMENTS:动态安装 Python 依赖(如 lxml==4.6.3)。