在 Docker 中运行 Airflow

本快速入门指南将帮助你在 Docker 中快速启动并运行 CeleryExecutor。

注意

此过程可用于学习和探索。但若要在实际生产环境中使用，适配过程可能会相当复杂，而且 docker compose 文件并未提供生产系统所需的安全保证。对本过程进行更改将需要 Docker 与 Docker Compose 的专业知识，Airflow 社区可能无法提供帮助。

因此，当你准备在生产环境中运行 Airflow 时，建议使用 官方 Airflow 社区 Helm Chart 的 Kubernetes 部署方式。

开始之前

本过程假设你已经熟悉 Docker 与 Docker Compose。如果你之前没有使用过这些工具，请先浏览 Docker 快速入门（尤其是 Docker Compose 部分）以了解它们的工作方式。

如果尚未安装，请按以下步骤安装所需工具。

  1. 在工作站上安装 Docker Community Edition (CE)。根据你的操作系统，可能需要将 Docker 配置为至少分配 4 GB 内存，以保证 Airflow 容器正常运行。请参考 Docker for Windows 或 Docker for Mac 文档中的“资源”章节获取更多信息。

  2. 在工作站上安装 Docker Compose v2.14.0 或更高版本。

旧版本的 docker-compose 不支持 Airflow docker-compose.yaml 所需的全部特性，请确认你的版本满足最低要求。

提示

macOS 上 Docker 默认分配的内存通常不足以启动 Airflow，内存不足可能导致 Web 服务器不断重启。建议为 Docker Engine 分配至少 4 GB（理想情况下 8 GB）内存。

可通过以下命令检查当前分配的内存是否足够

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

警告

某些操作系统（如 Fedora、ArchLinux、RHEL、Rocky）最近引入的内核更改会导致在这些系统提供的社区 Docker 实现中运行的 Docker Compose 消耗 100% 内存。

这属于 containerd 配置的向后不兼容问题，Airflow 的部分依赖会受到影响，已在多个 issue 中追踪。

目前 containerd 团队尚未提供解决方案，但在 此评论 中指出，安装 Linux 版 Docker Desktop 可以解决该问题，并使 Breeze 正常运行。

获取 docker-compose.yaml

要在 Docker Compose 上部署 Airflow，请获取 docker-compose.yaml。

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

重要提示

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

此文件包含多个服务定义

  • airflow-scheduler - 调度器（scheduler） 监控所有任务和 DAG，并在依赖完成后触发任务实例。

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

  • airflow-api-server - API 服务器的访问地址为 https://:8080。

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

  • airflow-triggerer - Triggerer 为可延迟（deferrable）任务运行事件循环。

  • airflow-init - 初始化服务。

  • postgres - 数据库服务。

  • redis - Redis 消息中间件，用于在调度器与工作节点之间转发消息。

如需启用 Flower，可添加 --profile flower 参数，例如 docker compose --profile flower up，或在命令行显式指定 docker compose up flower。

  • flower - Flower 应用 用于监控环境，访问地址为 https://:5555。

上述所有服务共同实现了 CeleryExecutor。更多信息请参见 架构概览。

容器内的若干目录会被挂载，这意味着它们的内容会在本机与容器之间保持同步。

  • ./dags - 你可以把 DAG 文件放在这里。

  • ./logs - 存放任务执行和调度器产生的日志。

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

  • ./plugins - 你可以把 自定义插件 放在此目录。

该文件使用最新的 Airflow 镜像（apache/airflow）。如果需要安装新的 Python 包或系统库，可 自定义构建镜像。

初始化环境

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

设置正确的 Airflow 用户

在 Linux 上，快速入门需要获取主机的用户 ID，并将组 ID 设置为 0。否则在 dags、logs、config 与 plugins 中创建的文件会归属 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。

在 SELinux/AppArmor 系统上可能会出现权限问题。如遇此情况，请在 docker-compose.yaml 中的所有卷后添加后缀 :z。

volumes:
  - ${AIRFLOW_PROJ_DIR:-.}/dags:/opt/airflow/dags:z
  - ${AIRFLOW_PROJ_DIR:-.}/logs:/opt/airflow/logs:z
  - ${AIRFLOW_PROJ_DIR:-.}/config:/opt/airflow/config:z
  - ${AIRFLOW_PROJ_DIR:-.}/plugins:/opt/airflow/plugins:z

如果添加上述后仍无法创建 airflow.cfg，可对 config/ 目录设置极宽松的权限。

sudo chmod -R 777 ./config

请注意，这是一种 **临时变通方案**，绝不应在生产环境中使用。

初始化数据库

在 所有操作系统 上，都需要运行数据库迁移并创建首个用户账户，执行方式如下：

docker compose up airflow-init

初始化完成后，你会看到有关文件、文件夹和插件的输出，最后会出现类似下面的信息：

airflow-init-1 exited with code 0

已创建的账户登录名为 airflow，密码为 airflow。

清理环境

我们提供的 docker‑compose 环境是一个 “quick‑start” 示例，并非为生产环境设计，存在多项限制——最可靠的故障恢复方式是清除并重新启动。

最简便的做法是：

  • 在下载了 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.2.0   "/usr/bin/dumb-init …"   3 minutes ago    Up 3 minutes (healthy)    8080/tcp                           compose_airflow-worker_1
ed9b09fc84b1   apache/airflow:3.2.0   "/usr/bin/dumb-init …"   3 minutes ago    Up 3 minutes (healthy)    8080/tcp                           compose_airflow-scheduler_1
7cb1fb603a98   apache/airflow:3.2.0   "/usr/bin/dumb-init …"   3 minutes ago    Up 3 minutes (healthy)    0.0.0.0:8080->8080/tcp             compose_airflow-api_server_1
74f3bbe506eb   postgres:16            "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 后，你可以通过三种方式与其交互：

运行 CLI 命令

你同样可以运行 CLI 命令，但必须在任意已定义的 airflow-* 服务容器中执行。例如，要运行 airflow info，请使用如下命令：

docker compose run airflow-worker airflow info

如果使用 Linux 或 macOS，建议下载可选的包装脚本，这样可以使用更简洁的命令来执行。

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

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

./airflow.sh info

还可以在容器中使用 bash 进入交互式 shell，或使用 python 进入 Python 环境。

./airflow.sh bash

./airflow.sh python

访问 Web 界面

集群启动后，你可以登录 Web 界面并开始实验 DAG。

Web 服务器可通过 https://:8080 访问。默认账户登录名为 airflow，密码为 airflow。

向 REST API 发送请求

Basic（基本）用户名密码认证 目前已支持 REST API，这意味着你可以使用常见工具发送请求。

Web 服务器可通过 https://:8080 访问。默认账户登录名为 airflow，密码为 airflow。

以下是一个示例 curl 命令，用于获取池列表：

ENDPOINT_URL="https://:8080"
JWT_TOKEN=$(curl -s -X POST ${ENDPOINT_URL}/auth/token \
                 -H "Content-Type: application/json" \
                 -d '{"username": "airflow", "password": "airflow"}' |\
            jq -r '.access_token' \
          )
curl -X GET \
    "${ENDPOINT_URL}/api/v2/pools" \
    -H "Authorization: Bearer ${JWT_TOKEN}"

清理

要停止并删除容器、删除带有数据库数据的卷以及清除已下载的镜像，请运行：

docker compose down --volumes --rmi all

使用自定义镜像

在本地运行 Airflow 时，可能希望使用一个扩展镜像以加入额外依赖——例如安装新的 Python 包，或将 Airflow Providers 升级到更高版本。只需在 docker-compose.yaml 中添加 build: .，并在同目录下放置自定义 Dockerfile，即可通过 docker compose build 构建镜像（仅需执行一次）。在运行 docker compose up 或 docker compose run 时，可添加 --build 参数实现即时重建。

关于如何使用自定义 Providers、Python 包、apt 包等扩展镜像的示例，请参阅 构建镜像。

注意

创建自定义镜像意味着你需要维护相应的自动化脚本，以便在所需安装的包或 Airflow 本身升级时重新构建镜像。请务必保管好这些脚本。另外，若仅运行纯 Python 任务，可使用 Python Virtualenv，在运行时动态安装依赖。自 Airflow 2.8.0 起，virtualenv 还能被缓存。

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

自定义镜像的常见场景是希望添加一组存放于 requirements.txt 的依赖。开发时，你可能倾向于在启动官方 Airflow 镜像时动态安装，但这会导致启动速度显著下降，并且没有必要，因为 Docker Compose 已内置这种开发流程。按照前一章节的做法，在本地迭代时自动构建并使用自定义镜像。具体步骤如下：

  1. 在 docker-compose.yaml 中注释掉 image: ... 行，并去掉 build: . 行的注释。你的 docker‑compose 关键片段应类似（请使用正确的镜像标签）：

#image: ${AIRFLOW_IMAGE_NAME:-apache/airflow:3.2.0}
build: .

  1. 在与你的 docker-compose.yaml 同一目录下创建 Dockerfile，内容示例：

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

最佳实践是在自定义镜像中使用与原始镜像相同版本的 apache‑airflow。这样可以避免 pip 在安装其他依赖时降级或升级 Airflow，从而导致版本冲突。

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

运行 docker compose build 构建镜像，或在 docker compose up、docker compose run 时加上 --build 标志，让 Docker 在需要时自动构建。

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

如果你拥有自定义的配置文件并希望在 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 文档中关于 Windows 与 Mac 的章节。

使用 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** 字段中选择刚刚添加的 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: No module named 'XYZ'

Docker Compose 文件使用最新的 Airflow 镜像（apache/airflow）。如果需要安装新的 Python 或系统库，可 自定义并扩展镜像。

下一步？

从这里起，你可以前往 教程章节获取更多示例，或进入 How‑to Guides 章节开始动手实践。

Docker Compose 支持的环境变量

不要将此处的变量名与镜像构建时的 build 参数混淆。AIRFLOW_UID 为构建参数，默认值为 50000，在镜像构建时“写入”进去。相对地，下面列出的环境变量是在容器运行时通过 -e（或使用 id -u 的结果）进行设置，从而使用宿主机的动态用户 ID。

Variable

描述

默认值

AIRFLOW_IMAGE_NAME

要使用的 Airflow 镜像。

apache/airflow:3.2.0

AIRFLOW_UID

Airflow 容器运行时使用的用户 UID。若想使用非默认 UID（例如在映射宿主机文件夹时），请将其设为 id -u 的返回值。改变后，容器内部会创建对应 UID、名称为 default 的用户，并把其 HOME 设为 /airflow/home/，以共享在该目录下安装的 Python 库，从而实现 OpenShift 兼容。更多请参阅 Arbitrary Docker User。

50000

注意

在 Airflow 2.2 之前，Docker Compose 还拥有 AIRFLOW_GID 参数，但它并未提供额外功能，只会增加混淆，已被删除。

这些额外变量主要用于在 Docker Compose 中试验/测试 Airflow 安装，它们并非面向生产环境，而是帮助首次使用者快速完成最常见的自定义。

Variable

描述

默认值

_AIRFLOW_WWW_USER_USERNAME

Web UI 管理员账户的用户名。如果设置此值，管理员 UI 用户会自动创建。仅在想要快速启动带嵌入式开发数据库的容器进行测试时有用。

airflow

_AIRFLOW_WWW_USER_PASSWORD

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

airflow

_PIP_ADDITIONAL_REQUIREMENTS

若非空，Airflow 容器将在启动时尝试安装变量中指定的依赖，例如 lxml==4.6.3 charset-normalizer==1.4.1。此功能在 Airflow 镜像 2.1.1 及以上版本可用。

此条目是否有帮助？