Airflow Summit 2025 将于 10 月 07-09 日举行。立即注册获取早鸟票!

在 Docker 中运行 Airflow

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

注意

此过程对学习和探索很有用。但是,将其用于实际场景可能很复杂,并且 docker compose 文件不提供生产系统所需的任何安全保证。对此过程进行更改需要 Docker 和 Docker Compose 的专业知识,并且 Airflow 社区可能无法为您提供帮助。

因此,当您准备在生产环境中运行 Airflow 时,我们建议使用 Kubernetes 以及 官方 Airflow 社区 Helm Chart

开始之前

此过程假设您熟悉 Docker 和 Docker Compose。如果您之前没有使用过这些工具,则应花点时间阅读 Docker 快速入门(特别是关于 Docker Compose 的部分),以便熟悉它们的工作原理。

如果您尚未安装所需的工具,请按照以下步骤进行安装。

  1. 在您的工作站上安装 Docker Community Edition (CE)。根据您的操作系统,您可能需要配置 Docker 以使用至少 4.00 GB 内存,以便 Airflow 容器正常运行。有关更多信息,请参阅 Docker for WindowsDocker for Mac 文档中的资源部分。

  2. 在您的工作站上安装 v2.14.0 或更新版本的 Docker Compose

旧版本的 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 时,Docker Compose 中的 Airflow 会消耗 100% 的内存。

这是与 containerd 不兼容的配置有关的问题,一些 Airflow 依赖项对此有问题,并在一些问题中进行了跟踪

containerd 团队目前还没有解决方案,但似乎在 Linux 上安装 Docker Desktop 可以解决此问题,如 此评论 中所述,并且可以毫无问题地运行 Breeze。

获取 docker-compose.yaml 文件

要在 Docker Compose 上部署 Airflow,您应该获取 docker-compose.yaml 文件。

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

重要

从 2023 年 7 月起,Compose V1 已停止接收更新。我们强烈建议升级到更新版本的 Docker Compose,随附的 docker-compose.yaml 在 Compose V1 中可能无法正常工作。

此文件包含几个服务定义

  • airflow-scheduler - 调度器 监控所有任务和 DAG,然后在其依赖项完成后触发任务实例。

  • airflow-dag-processor - DAG 处理器解析 DAG 文件。

  • airflow-webserver - Web 服务器位于 http://localhost:8080

  • airflow-worker - 执行调度器分配的任务的工作节点。

  • airflow-triggerer - 触发器运行可推迟任务的事件循环。

  • airflow-init - 初始化服务。

  • postgres - 数据库。

  • redis - Redis - 将消息从调度器转发到工作节点的代理。

(可选)您可以通过添加 --profile flower 选项来启用 flower,例如 docker compose --profile flower up,或通过在命令行上显式指定它,例如 docker compose up flower

所有这些服务允许您使用 CeleryExecutor 运行 Airflow。有关更多信息,请参阅 架构概述

容器中的一些目录是挂载的,这意味着它们的内容在您的计算机和容器之间同步。

  • ./dags - 您可以将 DAG 文件放在此处。

  • ./logs - 包含任务执行和调度器的日志。

  • ./config - 您可以添加自定义日志解析器或添加 airflow_local_settings.py 以配置集群策略。

  • ./plugins - 您可以将 自定义插件 放在此处。

此文件使用最新的 Airflow 镜像 (apache/airflow)。如果您需要安装新的 Python 库或系统库,您可以构建自己的镜像

初始化环境

首次启动 Airflow 之前,您需要准备环境,即创建必要的文件、目录并初始化数据库。

设置正确的 Airflow 用户

Linux 上,快速入门需要知道您的主机用户 ID,并且需要将组 ID 设置为 0。否则,在 dagslogsconfigplugins 中创建的文件将由 root 用户拥有。您必须确保为 docker-compose 配置它们

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

请参阅 Docker Compose 环境变量

对于其他操作系统,您可能会收到关于 AIRFLOW_UID 未设置的警告,但您可以安全地忽略它。您也可以在与 docker-compose.yaml 相同的文件夹中手动创建一个 .env 文件,包含以下内容以消除警告

AIRFLOW_UID=50000

初始化 airflow.cfg(可选)

如果您想在启动 airflow 服务之前使用默认值初始化 airflow.cfg,请运行此命令。

docker compose run airflow-cli airflow config list

这将在 config 文件夹中用默认值填充 airflow.cfg

初始化数据库

所有操作系统上,您都需要运行数据库迁移并创建第一个用户帐户。为此,请运行此命令。

docker compose up airflow-init

初始化完成后,您应该会看到如下消息

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

创建的帐户登录名是 airflow,密码是 airflow

清理环境

我们准备的 docker-compose 环境是“快速入门”环境。它不是为生产环境设计的,存在许多注意事项——其中之一是解决任何问题的最佳方法是清理并从头开始。

最佳做法是

  • 在您下载 docker-compose.yaml 文件的目录中运行 docker compose down --volumes --remove-orphans 命令

  • 删除您下载 docker-compose.yaml 文件的整个目录 rm -rf '<DIRECTORY>'

  • 从头开始重新执行本指南,首先重新下载 docker-compose.yaml 文件

运行 Airflow

现在您可以启动所有服务了

docker compose up

注意

docker-compose 是旧语法。请查看 Stackoverflow

在第二个终端中,您可以检查容器的状态,确保没有容器处于不健康状态

$ docker ps
CONTAINER ID   IMAGE                  COMMAND                  CREATED          STATUS                    PORTS                              NAMES
247ebe6cf87a   apache/airflow:3.0.0   "/usr/bin/dumb-init …"   3 minutes ago    Up 3 minutes (healthy)    8080/tcp                           compose_airflow-worker_1
ed9b09fc84b1   apache/airflow:3.0.0   "/usr/bin/dumb-init …"   3 minutes ago    Up 3 minutes (healthy)    8080/tcp                           compose_airflow-scheduler_1
7cb1fb603a98   apache/airflow:3.0.0   "/usr/bin/dumb-init …"   3 minutes ago    Up 3 minutes (healthy)    0.0.0.0:8080->8080/tcp             compose_airflow-webserver_1
74f3bbe506eb   postgres:13            "docker-entrypoint.s…"   18 minutes ago   Up 17 minutes (healthy)   5432/tcp                           compose_postgres_1
0bd6576d23cb   redis:latest           "docker-entrypoint.s…"   10 hours ago     Up 17 minutes (healthy)   0.0.0.0:6379->6379/tcp             compose_redis_1

访问环境

启动 Airflow 后,您可以通过 3 种方式与其交互

运行 CLI 命令

您也可以运行 CLI 命令,但必须在某个已定义的 airflow-* 服务中运行。例如,要运行 airflow info,请运行以下命令

docker compose run airflow-worker airflow info

如果您使用 Linux 或 Mac OS,可以通过下载可选的包装脚本来简化工作,该脚本允许您使用更简单的命令运行命令。

curl -LfO 'https://airflow.org.cn/docs/apache-airflow/3.0.0/airflow.sh'
chmod +x airflow.sh

现在您可以更轻松地运行命令了。

./airflow.sh info

您也可以使用 bash 作为参数进入容器中的交互式 bash shell,或使用 python 进入 python 容器。

./airflow.sh bash
./airflow.sh python

访问 Web 界面

集群启动后,您可以登录 Web 界面并开始使用 DAG 进行实验。

Web 服务器位于: http://localhost:8080。默认帐户的登录名是 airflow,密码是 airflow

向 REST API 发送请求

目前 REST API 支持 基本用户名密码认证,这意味着您可以使用常用工具向 API 发送请求。

Web 服务器位于: http://localhost:8080。默认帐户的登录名是 airflow,密码是 airflow

以下是一个示例 curl 命令,它发送一个请求以检索池列表

ENDPOINT_URL="http://localhost:8080/"
curl -X GET  \
    --user "airflow:airflow" \
    "${ENDPOINT_URL}/api/v1/pools"

清理

要停止并删除容器、删除包含数据库数据的卷以及下载镜像,请运行此命令

docker compose down --volumes --rmi all

使用自定义镜像

当您想在本地运行 Airflow 时,您可能希望使用包含一些额外依赖项的扩展镜像——例如,您可能添加新的 Python 包,或将 Airflow Provider 升级到更高版本。这可以通过在 docker-compose.yaml 中指定 build: . 并将自定义 Dockerfile 放在 docker-compose.yaml 旁边来轻松完成。然后您可以使用 docker compose build 命令构建您的镜像(只需要执行一次)。您也可以在运行其他 docker compose 命令时添加 --build 标志,以在运行时重建镜像。

有关如何使用自定义 Provider、Python 包、apt 包等扩展镜像的示例,请参见 构建镜像

注意

创建自定义镜像意味着您还需要维护一定程度的自动化,因为当您要安装的包或 Airflow 升级时,您需要重新创建镜像。请不要忘记保留这些脚本。另请记住,在运行纯 Python 任务的情况下,您可以使用 Python Virtualenv 函数,它将在运行时动态获取和安装 Python 依赖项。从 Airflow 2.8.0 开始,Virtualenv 也可以缓存。

特殊情况 - 通过 requirements.txt 文件添加依赖

自定义镜像的常见情况是,您想向其中添加一组依赖项——通常存储在 requirements.txt 文件中。在开发过程中,您可能想在启动原始 airflow 镜像时动态添加它,但这会产生许多副作用(例如,您的容器启动会慢得多——每个额外的依赖项都会进一步延迟您的容器启动时间)。此外,这完全没有必要,因为 docker compose 内置了开发工作流程。您可以——按照上一章所述,在本地使用 docker compose 进行迭代时自动构建和使用您的自定义镜像。特别是当您想添加自己的 requirements 文件时,您应该执行以下步骤

  1. 注释掉 docker-compose.yaml 文件中的 image: ... 行,并移除 build: . 行的注释。您的 docker-compose 文件中相关部分应如下所示(使用正确的镜像标签)

#image: ${AIRFLOW_IMAGE_NAME:-apache/airflow:3.0.0}
build: .
  1. 在与 docker-compose.yaml 文件相同的文件夹中创建 Dockerfile,内容如下所示

FROM apache/airflow:3.0.0
ADD requirements.txt .
RUN pip install apache-airflow==${AIRFLOW_VERSION} -r requirements.txt

最佳实践是安装与原始镜像中相同版本的 apache-airflow。这样可以确保 pip 在安装其他依赖项时不会尝试降级或升级 apache airflow,如果您尝试添加与正在使用的 apache-airflow 版本冲突的依赖项,则可能会发生这种情况。

  1. requirements.txt 文件放在同一目录中。

运行 docker compose build 命令构建镜像,或者在 docker compose updocker compose run 命令中添加 --build 标志,以便根据需要自动构建镜像。

特殊情况 - 添加自定义配置文件

如果您有自定义配置文件并希望在 Airflow 实例中使用它,则需要执行以下步骤

  1. 用您的自定义配置文件替换本地 config 文件夹中自动生成的 airflow.cfg 文件。

  2. 如果您的配置文件名称与 airflow.cfg 不同,请在 AIRFLOW_CONFIG: '/opt/airflow/config/airflow.cfg' 中调整文件名

网络

通常,如果您想在本地使用 Airflow,您的 DAG 可能会尝试连接到在主机上运行的服务器。为此,必须在 docker-compose.yaml 中添加额外的配置。例如,在 Linux 上,配置必须在 services: airflow-worker 部分中添加 extra_hosts: - "host.docker.internal:host-gateway";并使用 host.docker.internal 代替 localhost。此配置因平台而异。有关更多信息,请查阅 Docker WindowsMac 文档。

使用 PyCharm 调试 Docker 容器中的 Airflow

先决条件:在 PyCharm 中创建一个项目并下载 (docker-compose.yaml)。

步骤

  1. 修改 docker-compose.yaml 文件

    services 部分下添加以下内容

airflow-python:
  <<: *airflow-common
  profiles:
      - debug
  environment:
      <<: *airflow-common-env
  user: "50000:0"
  entrypoint: [ "/bin/bash", "-c" ]

注意

此代码片段创建了一个名为 “airflow-python” 的新服务,专门用于 PyCharm 的 Python 解释器。在 Linux 系统上,如果您执行了命令 echo -e "AIRFLOW_UID=$(id -u)" > .env,您需要在 airflow-python 服务中设置 user: "50000:0" 以避免 PyCharm 的 Unresolved reference 'airflow' 错误。

  1. 配置 PyCharm 解释器

    • 打开 PyCharm 并导航到 Settings > Project: <Your Project Name> > Python Interpreter

    • 点击 “Add Interpreter” 按钮,选择 “On Docker Compose”

    • Configuration file 字段中,选择您的 docker-compose.yaml 文件。

    • Service field 字段中,选择新添加的 airflow-python 服务。

    • 点击 “Next” 并按照提示完成配置。

Configuring the container's Python interpreter in PyCharm, step diagram

构建解释器索引可能需要一些时间。 3) 在 python 服务中的 docker-compose/command 和 actions 中添加 exec

Configuring the container's Python interpreter in PyCharm, step diagram

配置完成后,您可以在容器环境中调试您的 Airflow 代码,这模拟了您的本地设置。

FAQ:常见问题

ModuleNotFoundError: 找不到名为 'XYZ' 的模块

Docker Compose 文件使用最新的 Airflow 镜像 (apache/airflow)。如果您需要安装新的 Python 库或系统库,您可以自定义和扩展它

下一步?

从这一点开始,您可以前往 教程 部分获取更多示例,或者如果您已准备好动手实践,请前往 操作指南 部分。

Docker Compose 支持的环境变量

请勿混淆此处的变量名与构建镜像时设置的构建参数。AIRFLOW_UID 构建参数在构建镜像时默认为 50000,因此它是“内置”到镜像中的。另一方面,以下环境变量可以在容器运行时设置,例如使用 id -u 命令的结果,这允许使用构建镜像时未知的动态主机运行时用户 ID。

变量

描述

默认值

AIRFLOW_IMAGE_NAME

要使用的 Airflow 镜像。

apache/airflow:3.0.0

AIRFLOW_UID

运行 Airflow 容器的用户 UID。如果您想使用非默认的 Airflow UID(例如,从主机映射文件夹时,应将其设置为 id -u 调用的结果),则可以覆盖此设置。更改后,将在容器内创建一个 UID 为此值的用户,名称为 default,其主目录设置为 /airflow/home/,以便共享安装在此处的 Python 库。这是为了实现 OpenShift 兼容性。更多信息请参阅 任意 Docker 用户

50000

注意

在 Airflow 2.2 之前,Docker Compose 也有 AIRFLOW_GID 参数,但它没有提供任何附加功能 - 只增加了混淆 - 因此已被移除。

这些附加变量在您通过 Docker Compose 尝试/测试 Airflow 安装时很有用。它们不适用于生产环境,但可以帮助初次使用者更快地使用最常见的自定义设置启动环境。

变量

描述

默认值

_AIRFLOW_WWW_USER_USERNAME

管理员 UI 账户的用户名。如果指定此值,将自动创建管理员 UI 用户。这仅在您想试运行 Airflow 并希望启动一个带有嵌入式开发数据库的容器时有用。

airflow

_AIRFLOW_WWW_USER_PASSWORD

管理员 UI 账户的密码。仅在设置了 _AIRFLOW_WWW_USER_USERNAME 时使用。

airflow

_PIP_ADDITIONAL_REQUIREMENTS

如果不为空,airflow 容器将尝试安装变量中指定的依赖项。例如:lxml==4.6.3 charset-normalizer==1.4.1。适用于 Airflow 镜像 2.1.1 及更高版本。

这篇文章有帮助吗?