Apache Airflow 从源码安装与开发环境搭建指南

前言

Apache Airflow 是一个功能强大的工作流编排平台，本文将为开发者详细介绍如何从源码安装 Airflow 并搭建开发环境。不同于简单的安装教程，我们将深入解析各种安装方式的原理和适用场景，帮助开发者选择最适合自己的开发环境配置方案。

系统准备

Linux 系统依赖（以 Debian Bookworm 为例）

sudo apt install -y --no-install-recommends apt-transport-https apt-utils ca-certificates \
curl dumb-init freetds-bin krb5-user libgeos-dev \
ldap-utils libsasl2-2 libsasl2-modules libxmlsec1 locales libffi8 libldap-2.5-0 libssl3 netcat-openbsd \
lsb-release openssh-client python3-selinux rsync sasl2-bin sqlite3 sudo unixodbc

如需支持 MySQL/MariaDB，还需安装开发头文件：

sudo apt-get install libmariadb-dev libmariadbclient-dev

MacOS 系统依赖

brew install sqlite mysql postgresql

现代构建工具链

自 Airflow 2.8 版本起，项目采用 PEP 517/518 标准，使用 pyproject.toml 定义构建依赖和构建流程。这意味着：

1. 需要较新的打包工具版本（pip ≥ 22.1.0）
2. 构建过程使用 PEP 517 兼容的构建钩子确定动态构建依赖
3. 从 wheel 包安装不受此影响

推荐开发工具链：uv

uv 是一个新兴的 Python 包管理和环境管理工具，Airflow 社区推荐使用它来管理开发环境。

uv 安装与使用

1. 安装 uv（参考官方文档）
2. 同步依赖：

uv sync  # 基础依赖
uv sync --all-packages  # 包含所有开发依赖

3. 安装开发工具：

uv tool install -e ./dev/breeze
uv tool install pre-commit --with pre-commit-uv
uv tool install hatch
uv tool install flit
uv tool install cherry-picker

4. 启用 git 钩子：

pre-commit install

5. 在虚拟环境中运行命令：

uv run pytest
uv run airflow standalone

前端资源编译

Airflow 的 Web UI 需要先编译前端资源：

使用 breeze 工具

breeze compile-ui-assets

手动编译

pnpm install -frozen-lockfile --config.confirmModulesPurge=false
pnpm run build

使用 Hatch 构建

cd airflow-core
hatch build -c -t custom

传统方式：pip + virtualenv

虽然 uv 更现代，但传统方式仍有其适用场景：

1. 创建虚拟环境：

python3 -m venv PATH_TO_YOUR_VENV
source PATH_TO_YOUR_VENV/bin/activate

2. 安装依赖（以 Python 3.9 为例）：

pip install -e ".[devel,google]" \
   --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-main/constraints-3.9.txt"

使用 Hatch 构建包

Hatch 是 Airflow 官方推荐的包构建工具：

1. 安装 Hatch：

uv tool install hatch

2. 构建包：

hatch build  # 默认构建 wheel 和 sdist
hatch build -t wheel  # 仅构建 wheel
hatch build -t sdist  # 仅构建 sdist

3. 自定义构建（包含前端资源）：

hatch build -t custom -t wheel -t sdist

依赖管理最佳实践

1. 约束文件：使用约束文件确保依赖版本与 CI 环境一致
2. 无提供商约束：升级核心时保持现有提供商依赖

uv pip install -e ".[devel]" \
   --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-main/constraints-no-providers-3.9.txt"

Airflow 扩展包

Airflow 提供了多种扩展（extras）来启用额外功能：

• 数据库连接器（postgres, mysql 等）
• 云服务提供商（google, amazon, microsoft 等）
• 功能增强（celery, crypto, sendgrid 等）

具体扩展列表和功能可参考官方文档中的 extras 参考部分。

结语

本文详细介绍了 Apache Airflow 从源码安装的多种方式，从现代工具链 uv 到传统 pip 方式，从前端资源编译到包构建工具 Hatch 的使用。开发者可根据自身需求和环境选择合适的安装方式。对于长期开发者，推荐采用 uv + Hatch 的现代工具链组合，这将显著提升开发效率和环境一致性。