在Docker中运行Airflow¶
本快速入门指南将帮助您快速在Docker环境中使用CeleryExecutor启动并运行Airflow。
警告
此流程对于学习和探索很有帮助。然而，将其应用于实际场景可能会比较复杂，且docker compose文件无法提供生产系统所需的安全保障。修改此流程需要具备Docker和Docker Compose的专业知识，Airflow社区可能无法为您提供帮助。
因此，我们建议在生产环境中运行Airflow时，使用Kubernetes配合Official Airflow Community Helm Chart。
开始之前¶
本流程假设您已熟悉Docker和Docker Compose。如果您之前未使用过这些工具，建议先花时间学习Docker快速入门（特别是Docker Compose部分），以便了解它们的工作原理。
如果尚未完成，请按照以下步骤安装必要的工具。
在工作站上安装 Docker Community Edition (CE)。根据您的操作系统，可能需要配置Docker使用至少4.00 GB内存以确保Airflow容器正常运行。更多信息请参阅 Docker for Windows 或 Docker for Mac 文档中的资源部分。
在工作站上安装 Docker Compose v2.14.0 或更高版本。
旧版本的docker-compose不支持Airflow docker-compose.yaml文件所需的所有功能，因此请仔细检查您的版本是否符合最低版本要求。
提示
The default amount of memory available for Docker on macOS is often not enough to get Airflow up and running. If enough memory is not allocated, it might lead to the webserver continuously restarting. You should allocate at least 4GB memory for the Docker Engine (ideally 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会占用100%内存。这些Docker实现由各操作系统团队维护。
这是一个与向后不兼容的containerd配置相关的问题，部分Airflow依赖项存在此问题，并在以下几个问题中被追踪：
目前containerd团队尚未提供解决方案，但根据此评论所述，在Linux上安装Docker Desktop似乎可以解决问题，并能顺利运行Breeze。
获取 docker-compose.yaml¶
要在Docker Compose上部署Airflow，您应该获取docker-compose.yaml。
curl -LfO 'https://airflow.apache.org/docs/apache-airflow/2.10.5/docker-compose.yaml'
重要
自2023年7月起，Compose V1已停止接收更新。
我们强烈建议升级到Docker Compose的更新版本，提供的docker-compose.yaml在Compose V1中可能无法正常运行。
该文件包含多个服务定义：
airflow-scheduler- scheduler监控所有任务和DAG，当它们的依赖项完成后就会触发任务实例。airflow-webserver- 网页服务器可通过http://localhost:8080访问。airflow-worker- 执行调度器分配任务的worker。airflow-triggerer- triggerer运行一个事件循环用于可延迟任务。airflow-init- 初始化服务。postgres- 数据库。redis- The redis - 作为消息代理，将消息从调度器转发到工作器。
可选地，您可以通过添加--profile flower选项来启用flower，例如docker compose --profile flower up，或者通过在命令行中明确指定它，例如docker compose up flower。
flower- The flower app 用于监控环境。可通过http://localhost:5555访问。
所有这些服务都允许您使用CeleryExecutor运行Airflow。更多信息请参阅Architecture Overview。
容器中的某些目录被挂载，这意味着它们的内容会在您的计算机和容器之间同步。
./dags- 你可以将DAG文件放在这里。./logs- 包含任务执行和调度器的日志。./config- 您可以添加自定义日志解析器或添加airflow_local_settings.py来配置集群策略。./plugins- 你可以在这里放置你的自定义插件。
本文件使用最新版Airflow镜像(apache/airflow)。 如需安装新的Python库或系统库，您可以构建自定义镜像。
初始化环境¶
在首次启动Airflow之前，您需要准备环境，即创建必要的文件、目录并初始化数据库。
设置正确的Airflow用户¶
在Linux系统上，快速启动需要知道您的主机用户ID，并且需要将组ID设置为0。
否则，在dags、logs和plugins目录中创建的文件将归属于root用户。
您必须确保为docker-compose正确配置这些设置：
mkdir -p ./dags ./logs ./plugins ./config
echo -e "AIRFLOW_UID=$(id -u)" > .env
对于其他操作系统，您可能会收到AIRFLOW_UID未设置的警告，但您可以安全地忽略它。您也可以手动在与docker-compose.yaml相同的文件夹中创建一个.env文件，内容如下以消除警告：
AIRFLOW_UID=50000
初始化数据库¶
在所有操作系统上，您需要运行数据库迁移并创建第一个用户账户。为此，请运行。
docker compose up airflow-init
初始化完成后，您应该会看到类似这样的消息：
airflow-init_1 | Upgrades done airflow-init_1 | Admin user airflow created airflow-init_1 | 2.10.5 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 '' 从头开始按照本指南操作，首先重新下载
docker-compose.yaml文件
运行Airflow¶
现在您可以启动所有服务：
docker compose up
注意
docker-compose 是旧语法。请查看 Stackoverflow。
在第二个终端中，您可以检查容器的状态，并确保没有容器处于不健康状态：
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
247ebe6cf87a apache/airflow:2.10.5 "/usr/bin/dumb-init …" 3 minutes ago Up 3 minutes (healthy) 8080/tcp compose_airflow-worker_1
ed9b09fc84b1 apache/airflow:2.10.5 "/usr/bin/dumb-init …" 3 minutes ago Up 3 minutes (healthy) 8080/tcp compose_airflow-scheduler_1
7cb1fb603a98 apache/airflow:2.10.5 "/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命令。
通过浏览器使用网页界面。
使用 the REST API。
运行CLI命令¶
你也可以运行CLI命令，但必须在已定义的airflow-*服务中执行。例如，要运行airflow info，请执行以下命令：
docker compose run airflow-worker airflow info
如果您使用的是Linux或Mac OS系统，可以通过下载可选包装脚本来简化操作流程，这些脚本能让您以更简洁的命令执行任务。
curl -LfO 'https://airflow.apache.org/docs/apache-airflow/2.10.5/airflow.sh'
chmod +x airflow.sh
现在您可以更轻松地运行命令了。
./airflow.sh info
你也可以使用bash作为参数进入容器中的交互式bash shell，或者使用python进入python容器。
./airflow.sh bash
./airflow.sh python
访问网页界面¶
集群启动后，您可以登录网页界面并开始试验DAG。
网页服务器地址为：http://localhost:8080。
默认账户的用户名是airflow，密码是airflow。
向REST API发送请求¶
Basic username password authentication 目前 支持REST API，这意味着您可以使用常用工具向API发送请求。
网页服务器访问地址为：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 providers升级到更高版本。这可以通过在docker-compose.yaml中指定build: .并放置自定义Dockerfile文件来实现。然后你可以使用docker compose build命令构建镜像(只需执行一次)。你也可以在运行其他docker compose命令时添加--build标志来即时重建镜像。
关于如何通过自定义提供程序、Python包、apt包等方式扩展镜像的示例，可以在构建镜像中找到。
注意
创建自定义镜像意味着您还需要维护一定程度的自动化，因为当您要安装的软件包或Airflow升级时，您需要重新创建这些镜像。请不要忘记保存这些脚本。同时请记住，在运行纯Python任务的情况下，您可以使用Python Virtualenv函数，它将在运行时动态获取并安装Python依赖项。从Airflow 2.8.0开始，Virtualenvs也可以被缓存。
特殊情况 - 通过requirements.txt文件添加依赖¶
自定义镜像的常见情况是，当您需要向其中添加一组依赖项时——这些依赖项通常存储在requirements.txt文件中。在开发过程中，您可能会想在启动原始airflow镜像时动态添加这些依赖，但这会带来一系列副作用（例如您的容器启动速度会明显变慢——每个额外的依赖项都会进一步延迟容器启动时间）。而且这种做法完全没有必要，因为docker compose已经内置了开发工作流。您可以按照前一章的指导，在本地使用docker compose迭代时自动构建并使用您的自定义镜像。具体来说，当您需要添加自己的需求文件时，应该执行以下步骤：
注释掉
image: ...行，并移除build: .行的注释，在docker-compose.yaml文件中。你的docker-compose文件相关部分应该看起来类似这样（请使用正确的镜像标签）：
#image: ${AIRFLOW_IMAGE_NAME:-apache/airflow:2.10.5}
build: .
在与
docker-compose.yaml文件相同的文件夹中创建Dockerfile，内容类似如下：
FROM apache/airflow:2.10.5
ADD requirements.txt .
RUN pip install apache-airflow==${AIRFLOW_VERSION} -r requirements.txt
最佳实践是将apache-airflow安装为与原始镜像相同版本。这样可以确保pip在安装其他依赖项时不会尝试降级或升级apache airflow，这种情况可能发生在您尝试添加与当前使用的apache-airflow版本冲突的依赖项时。
将
requirements.txt文件放在同一目录下。
运行 docker compose build 来构建镜像，或者向 docker compose up 或
docker compose run 命令添加 --build 标志以根据需要自动构建镜像。
特殊情况 - 添加自定义配置文件¶
如果您有一个自定义配置文件并希望在您的Airflow实例中使用它，您需要执行以下步骤：
在
docker-compose.yaml文件中，移除AIRFLOW_CONFIG: '/opt/airflow/config/airflow.cfg'这一行的注释。将您的自定义
airflow.cfg文件放置在本地配置文件夹中。如果您的配置文件名称不是
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的更多信息。
在Docker容器内使用PyCharm调试Airflow¶
前提条件：在PyCharm中创建一个项目并下载(docker-compose.yaml)。
步骤：
修改
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'错误。
配置PyCharm解释器
打开PyCharm并导航至设置 > 项目: <您的项目名称> > Python解释器。
点击“添加解释器”按钮并选择“在Docker Compose上”。
在配置文件字段中，选择您的
docker-compose.yaml文件。在服务字段中，选择新添加的
airflow-python服务。点击“下一步”并按照提示完成配置。
构建解释器索引可能需要一些时间。
3) 在docker-compose/command和python服务中的actions里添加exec
配置完成后，您可以在容器环境中调试Airflow代码，模拟本地设置。
常见问题解答：常见问题¶
ModuleNotFoundError: 未找到模块 名为 'XYZ'¶
Docker Compose 文件使用了最新的 Airflow 镜像 (apache/airflow)。如果您需要安装新的 Python 库或系统库，可以自定义并扩展它。
下一步是什么？¶
Docker Compose支持的环境变量¶
不要将这里的变量名与构建镜像时设置的构建参数混淆。AIRFLOW_UID构建参数在镜像构建时默认为50000，因此它会被"固化"到镜像中。另一方面，以下环境变量可以在容器运行时设置，例如使用id -u命令的结果，这样就能使用动态的主机运行时用户ID，而这个ID在构建镜像时是未知的。
变量 |
描述 |
默认值 |
|---|---|---|
|
要使用的Airflow镜像。 |
apache/airflow:2.10.5 |
|
运行Airflow容器的用户UID。
如果你想使用非默认的Airflow UID（例如当从主机映射文件夹时，
应将其设置为 |
|
注意
在Airflow 2.2之前，Docker Compose还包含AIRFLOW_GID参数，但它并未提供任何额外功能——只会增加混淆——因此该参数已被移除。
这些额外的变量在您通过Docker Compose试用/测试Airflow安装时非常有用。 它们不适用于生产环境，但能让首次使用的用户通过最常见的自定义配置更快地启动环境。
变量 |
描述 |
默认值 |
|---|---|---|
|
管理员UI账户的用户名。 如果指定了该值，系统将自动创建 管理员UI用户。这仅在您想试用Airflow 并希望启动一个包含嵌入式开发数据库的 容器时有用。 |
airflow |
|
管理员界面账户的密码。
仅在设置 |
airflow |
|
如果不为空，airflow容器将尝试安装该变量中指定的依赖项。
例如： |