企业官网建设流程全解析

Apache Airflow 本地开发与运行环境搭建实战：pyenv + venv + constraints + standalone 全流程指南

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow

本指南以当前仓库根目录的 INSTALLING.md 为主体，系统讲解如何在 macOS / Linux 上从零搭建 Apache Airflow 的本地环境：既涵盖「仅安装运行 Airflow」的pyenv + virtualenv + pip经典路线（含约束文件实现可复现安装），也介绍仓库官方推荐的基于uv的本地开发环境方案，最后深入airflow standalone命令的源码实现，说明它如何一键拉起调度器、Web 界面等全部组件并自动初始化数据库与用户。读完本文，你将能独立完成 Airflow 的安装、启动、Web UI 登录，并理解其依赖管理机制与单机启动的内部原理。

一、先分清两种场景：运行 Airflow 与开发 Airflow

Apache Airflow 仓库把「使用」与「开发」两条路径明确区分，对应完全不同的工具链：

• 仅安装并运行 Airflow（跑起一个实例、编写 DAG、调用 UI）：你拥有很大的自由度，pyenv、venv、pip、uv均可。官方在 start.rst 中声明，正式支持pip与uv两种安装方式；poetry、pip-tools等工具因约束文件工作流不同而不在官方支持之列。
• 在 Airflow 源码上进行开发与测试（修改核心代码、运行单测）：仓库自 2024 年 11 月起只推荐uv一种本地环境搭建方式，原因是 Airflow 在代码库中大规模使用了uv workspace特性。详见贡献者文档 07_local_virtualenv.rst。

⚠️ 无论哪条路径，都应避免使用系统自带 Python 或 Homebrew 安装的 Python——这些版本通常被标记为--externally-managed（PEP 668），会限制依赖安装，导致pip install失败。这也是 Debian/Ubuntu 用户必须先创建虚拟环境再安装的根本原因。

版本前提（以当前仓库为准）

本仓库airflow-core/src/airflow/__init__.py中的__version__为3.4.0，根目录 pyproject.toml 声明requires-python = ">=3.10,!=3.15"，classifiers 覆盖 Python 3.10/3.11/3.12/3.13/3.14。也就是说当前主线支持的 Python 为 3.10～3.14（不含 3.15）。在动手前请先确认你的 Python 版本处于该范围内。

二、仅运行 Airflow：pyenv + 虚拟环境 + pip 安装

INSTALLING.md 给出了一套在 macOS 与 Linux 上推荐的 pyenv 安装流程。它适合不希望用系统包管理器污染全局环境的场景，通过 pyenv 精确锁定 Python 版本，再借助virtualenv隔离 Airflow 庞大的依赖树。

第 1 步：安装 pyenv

macOS 推荐通过 Homebrew 安装：

brew install pyenv

Linux 用户通常使用官方pyenv-installer脚本完成安装（细节以 pyenv 官方安装文档为准）。

第 2 步：安装并切换指定 Python 版本

以 Python 3.11.9 为例：

pyenv install 3.11.9 pyenv global 3.11.9 python --version # 确认当前生效版本

把 Python 版本固定下来，是后续使用「约束文件（constraints）」实现可复现安装的前提——因为约束文件的 URL 依赖你实际的 Python 主次版本号。

第 3 步：创建并激活虚拟环境

Airflow 依赖数量众多且与第三方 provider 包存在版本耦合，强烈建议隔离：

python -m venv airflow_venv source airflow_venv/bin/activate

第 4 步：带约束文件安装 Apache Airflow

Apache Airflow 发布在 PyPI 上。核心命令是：

pip install apache-airflow==3.1.8 --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.8/constraints-3.11.txt"

这条命令的关键在于--constraint约束文件。为什么要用它？

• 约束文件是 Airflow 发布时「冻结」的第三方依赖版本集合；
• 有时第三方发行版会发布新版本并意外破坏 Airflow，直接裸装pip install apache-airflow可能踩中这类上游回归；
• 使用约束文件后，安装会精确落到当时经过验证的依赖组合上，从而实现可复现安装。

约束文件的 URL 必须同时指定两个维度：Airflow 版本与你的 Python 版本。例如上面的 URL 含义是「针对 Airflow 3.1.8、Python 3.11 的约束文件」，Python 3.12 用户应把后缀换成constraints-3.12.txt。

需要额外 provider 时，通过 extras 语法追加，例如同时安装 Amazon 与 Google 相关 provider：

pip install apache-airflow[amazon,google]==3.1.8 --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.8/constraints-3.11.txt"

版本说明：3.1.8是 INSTALLING.md 写作时使用的示例版本，请按需替换为你要安装的发布版本（例如与当前仓库主线一致的3.4.0），并同步替换 URL 中的 Airflow 版本号。

如果想使用更快的uv完成同样安装，只需在命令前加uv：

uv pip install "apache-airflow==3.1.8" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.8/constraints-3.11.txt"

对于版本与 URL 的动态拼装，start.rst 给出了用 shell 变量提取 Python 版本的做法：

AIRFLOW_VERSION=3.1.1 PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')" CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt" uv pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"

三、开发 Airflow 源码：为什么仓库只推荐 uv

如果你要基于当前仓库（而不是 PyPI 发布包）做二次开发或贡献代码，请直接阅读 07_local_virtualenv.rst。它解释了仓库对本地开发环境的核心决策：

uv workspace 支撑单仓多包

自 Airflow 2.0 起，项目被拆分为核心的apache-airflow与 90+ 个 provider 发行包；Airflow 3 又进一步把每个 provider 放进providers/下独立的子目录、每个都有独立pyproject.toml。根目录 pyproject.toml 的[tool.uv.workspace]与[tool.uv]段落把这些包全部注册为 workspace members。uv的 workspace 特性让开发者能用一次同步把核心、所有 provider 及其开发依赖一起装入同一个虚拟环境，这是传统pip无法直接做到的工作流。

常用 uv 开发命令

# 安装核心与全部 provider 的开发依赖（在仓库根目录执行） uv sync --all-packages # 仅同步某一个 provider（如 mongo）的依赖并在其目录下跑测试 cd providers/mongo uv sync uv run pytest # 只改 airflow-core 时，在 airflow-core 目录内同步 cd airflow-core uv sync --all-packages

注意uv sync会读取仓库根目录提交的 uv.lock，保证所有开发者获得一致的依赖版本，日常同步无需再手动传约束文件。若希望严格不动 lock 文件（如 CI 场景），可加--frozen：一旦pyproject.toml与uv.lock不一致它会直接报错而非悄悄更新。

依赖解析的“冷却期”机制

pyproject.toml中配置了exclude-newer = "4 days"：uv解析新依赖时会忽略最近 4 天内发布的包版本，避免上游刚发布就被 yank 或损坏的版本立刻破坏全体开发者的解析结果；该时间戳会被记录进uv.lock，保证不同机器使用同一解析口径。

macOS 用户还需注意：系统默认的ulimit（256）可能引发 “Too many open files”，建议执行ulimit -n 2048（或追加到~/.bashrc/~/.zshrc）再执行uv sync。若使用pip从源码构建，请确保pip≥ 22.1.0（Airflow 自 2.8 起遵循 PEP 517/518）。

四、设置 AIRFLOW_HOME：配置文件、日志与数据库的归宿

Airflow 需要一个目录来存放airflow.cfg配置、日志以及元数据库（默认 SQLite）等数据。通过环境变量AIRFLOW_HOME指定：

export AIRFLOW_HOME=~/airflow

注意：该命令仅对当前 shell 会话生效。要持久化，请把它追加到 shell 配置文件（如~/.bashrc或~/.zshrc）。start.rst 建议在安装 Airflow之前就设置好AIRFLOW_HOME，这样安装后的初始化流程会自动把文件落到正确位置。

首次启动后，$AIRFLOW_HOME下会生成默认的airflow.cfg。你可以直接编辑它，或用AIRFLOW__SECTION__KEY形式的环境变量覆盖任意配置项（例如 standalone 模式源码里就使用AIRFLOW__CORE__EXECUTOR强制本地执行器）。

五、一键启动全部组件：airflow standalone 及其内部原理

5.1 启动命令

airflow standalone

这个命令会自动初始化数据库、创建用户并启动全部组件，是本地快速体验 Airflow 的最短路径。

5.2 源码视角：standalone 到底做了什么

深入 standalone_command.py 可以看到StandaloneCommand.run()的完整执行序列：

1. 静音 INFO 日志，随后调用calculate_env()计算子进程环境；
2. initialize_database()内部执行db.initdb()完成元数据库建表；
3. 在单个父进程下以SubCommand（内部即线程 +subprocess.Popen(["airflow", ...])）依次拉起四个核心组件：scheduler、dag-processor、api-server、triggerer；
4. 轮询检查三个 Job 是否已在运行并正常心跳（SchedulerJobRunner、DagProcessorJobRunner、TriggererJobRunner），全部就绪并经过约 3 秒延迟后打印 “Airflow is ready” 横幅；
5. 捕获KeyboardInterrupt（Ctrl+C）后逐个terminate()子进程并优雅退出。

calculate_env()中有两个关键的环境改写逻辑（对应单元测试 test_standalone_command.py 的test_calculate_env*系列用例）：

• 强制本地执行器：通过ExecutorLoader.import_default_executor_cls()检查当前默认执行器是否is_local，若不是（如 Celery、Kubernetes），则设置env["AIRFLOW__CORE__EXECUTOR"] = LocalExecutor，避免单机模式意外依赖外部 worker 集群；
• 强制 SimpleAuthManager：如果当前认证管理器不是SimpleAuthManager，则注入AIRFLOW__CORE__AUTH_MANAGER指向airflow.api_fastapi.auth.managers.simple.simple_auth_manager.SimpleAuthManager，从而保证开箱即用的本地登录体验。

5.3 三种执行器场景都被单测覆盖

TestStandaloneCommand::test_calculate_env对LOCAL_EXECUTOR / CELERY_EXECUTOR / KUBERNETES_EXECUTOR三种配置做了参数化测试，断言「非本地执行器一律回退为 LocalExecutor」；test_calculate_env_does_not_override_auth_if_already_set则验证当用户已显式配置 SimpleAuthManager 时不会重复改写环境。这从测试层面印证了 standalone 的目标是确定性地产出一个可在本机单进程运行的 Airflow。

六、登录 Web UI：账号密码从哪里来

全部组件就绪后，在浏览器打开：

http://localhost:8080

airflow standalone在首次运行时会在终端打印自动生成的用户名与密码。不过需要特别留意Airflow 3.x 的一个变化：start.rst 明确说明，管理员密码不一定总在终端输出中显示——它会被自动生成并保存到：

$AIRFLOW_HOME/simple_auth_manager_passwords.json.generated

默认即~/airflow/simple_auth_manager_passwords.json.generated。读取方式：

cat ~/airflow/simple_auth_manager_passwords.json.generated

用其中的密码（用户名为admin）登录，而非依赖终端回显的默认凭据。这一行为同样可以从源码得到印证：find_user_info()会先检查该密码文件是否已存在，若已生成则打印 “Password for the admin user has been previously generated in ... Not echoing it here”，只有首次运行时才调用am.init()生成并回显。

⚠️ standalone 是开发用途模式，源码就绪横幅中自带警告：Airflow Standalone is for development purposes only. Do not use this in production!生产环境请按 production-deployment 拆分运行各组件。

七、验证安装与跑第一个任务

7.1 验证安装

airflow version

7.2 用示例 DAG 触发任务

登录 UI 后可在首页启用example_bash_operatorDAG，也可直接用 CLI 触发任务实例与回填：

# 运行第一个任务实例 airflow tasks test example_bash_operator runme_0 2015-01-01 # 对 2015-01-01 到 2015-01-02 两天做 backfill 回填 airflow backfill create --dag-id example_bash_operator \ --from-date 2015-01-01 \ --to-date 2015-01-02

7.3 不用 standalone 时的手动拆分启动

若想理解各组件职责或为生产形态预演，可以放弃 all-in-one 命令，改用以下顺序逐个启动：

airflow db migrate airflow users create \ --username admin \ --firstname Peter \ --lastname Parker \ --role Admin \ --email spiderman@superhero.org airflow api-server --port 8080 airflow scheduler airflow dag-processor airflow triggerer

注：airflow users子命令仅在启用apache-airflow-providers-fab认证管理器时可用；而在airflow standalone的 SimpleAuthManager 场景下无需手动建用户，密码由系统自动生成。

7.4 开发期调试小工具

如果你在本地虚拟环境中做开发、需要直接查询元数据库，仓库还提供了内建命令：

airflow db shell

该命令会根据你配置的数据库类型提示所需安装的对应 CLI 客户端工具。

八、环境配置快速参考

至此，你已经完成了从 Python 环境治理、可复现依赖安装到单机多组件启动的完整闭环：后续可以继续研读 tutorial 学习 DAG 编写，或参考 production-deployment 将 standalone 形态演进为各组件独立部署的生产架构。

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow