Apache Airflow 安装前置条件（Prerequisites）完整指南：Python、数据库、Kubernetes 与系统环境要求

Apache Airflow® 是一个用于以编程方式编写、调度和监控工作流的平台。在动手安装之前，明确官方测试过的版本组合与系统环境要求，是避免后续部署踩坑的关键一步。本文以官方安装文档 prerequisites.rst 为核心骨架，结合当前仓库中的源码与配套文档，系统梳理 Python 版本、数据库后端、Kubernetes 版本、操作系统与硬件资源等全部前置条件，帮助你为开发、测试与生产环境做出正确的选型。

一、官方测试支持的版本矩阵

Airflow 是一个多组件、多依赖的复杂系统，其质量保证高度依赖 CI 流水线对不同版本组合的持续测试。以下是官方明确已测试的版本范围（内容自动生成自当前仓库的 prerequisites.rst）：

1. Python 版本

官方当前测试的 Python 版本为：3.10、3.11、3.12、3.13、3.14。

在仓库层面，这一要求被固化在 airflow-core/pyproject.toml 的包元数据中：

requires-python = ">=3.10,!=3.15"

也就是说，Python 版本下限为 3.10，同时显式排除尚未进入支持范围的 3.15，这与文档中列出的已测试版本严格对应。使用 pip 安装时，该声明会被 pip 自动校验，不满足版本要求的 Python 环境将直接拒绝安装。

2. 数据库后端

官方测试支持的数据库及版本如下：

数据库	支持版本
PostgreSQL	14、15、16、17、18
MySQL	8.0、8.4 及 Innovation 系列
SQLite	3.15.0+（仅限开发与测试）

其中 SQLite 是 Airflow 的默认元数据库。查看 config_templates/config.yml 中 [database] 段的定义可知，默认连接串为：

sqlite:///{AIRFLOW_HOME}/airflow.db

这意味着开箱即用的 Airflow（例如 pipx run apache-airflow standalone）会自动在 AIRFLOW_HOME 下创建 SQLite 数据库文件，无需额外配置即可启动。

3. Kubernetes 版本

若使用官方 Helm Chart 或自定义 Kubernetes 部署，官方测试的版本为：1.30、1.31、1.32、1.33、1.34、1.35。

Airflow 对 Kubernetes 与 Python 的支持遵循一个明确的生命周期策略（详见 supported-versions.rst）：当某个 Python/Kubernetes 版本到达 EOL（End of Life）后，Airflow 会在随后的第一个 MINOR 或 MAJOR 版本中移除对该版本的支持；而新版本发布后，官方会尽快将其纳入 CI 并发布对应的支持。因此，选择接近官方最新测试范围的版本，可以最大化获得社区支持与修复保障。

二、操作系统要求：POSIX 与 Windows 的取舍

Airflow 目前只能在 POSIX 兼容操作系统上运行，这一点在文档中以醒目的警告形式给出。具体而言：

• 开发环境：官方在贡献者常用的现代 Linux 发行版和近期版本的 macOS 上持续测试；
• 生产环境：只支持 Linux 发行版，这是唯一被官方支持的生产环境选项；
• Windows：可以通过 WSL2（Windows Subsystem for Linux 2）或 Linux 容器运行，官方并未将原生 Windows 支持列为高优先级事项。

值得特别强调的是，官方 CI 测试与社区维护的 Docker Hub 镜像所使用的发行版是 Debian Bookworm。这一事实在仓库根目录的 Dockerfile 中有直接证据：

ARG BASE_IMAGE="debian:bookworm-slim"

官方镜像正是基于 debian:bookworm-slim 构建的。因此，如果你的部署环境同样选择 Debian Bookworm（12），你将拥有与官方 CI 最接近的兼容性保证；选用其他 Linux 发行版（如 Ubuntu、CentOS 等）在多数场景下也可以工作，但需自行处理发行版差异带来的依赖问题。

三、硬件资源：4GB 内存只是起点

官方建议 Airflow 至少需要 4GB 内存，但同时明确指出：实际需求高度依赖于你所选择的部署方式。

需要澄清的是，官方无法为生产系统给出"最小资源"的硬性数字。原因在于影响资源消耗的因素极其复杂（详见 index.rst 中 Notes about minimum requirements），包括但不限于：

• 部署方式本身（PyPI 安装、Docker 镜像、Helm Chart、托管服务等）及部署环境的额外开销（如 Kubernetes 的 DNS、节点资源竞争）；
• 数据库、硬件、网络等技术细节；
• DAG 代码的复杂度、插件与配置的规模；
• 安装的 Provider 数量与种类（当前仓库的 providers/ 目录下就有数十个 Provider 包）；
• Airflow 的调优参数选择；
• DagRun 与 Task Instance 的数量、并行度以及任务本身的复杂度。

官方给出的最佳实践是：把 Airflow 的资源分配当作一个复杂系统来对待——它不是"设置好参数就一劳永逸"的可预测系统，而是需要持续监控、观察并动态调整参数的反馈循环系统。DAG 的特征会随时间（甚至一天内不同时段）变化，因此配套的监控系统是生产部署的必需品。关于调度器的调优可参考 fine-tuning-scheduler，整体效率优化可参考 best-practices。

四、数据库后端的硬性限制：MariaDB 与 SQLite 的红线

1. MariaDB 不被支持

尽管 MariaDB 与 MySQL 高度相似，官方明确不支持将 MariaDB 作为 Airflow 的后端数据库。文档给出了两个原因：

• MariaDB 与 MySQL 在索引处理等方面存在已知差异；
• 官方不会针对 MariaDB 测试迁移脚本和应用运行。

文档甚至直言，过去尝试使用 MariaDB 的用户遭遇了大量运维问题，因此强烈劝阻这一做法，且此类用户无法获得社区支持。结论：生产环境请直接选择 PostgreSQL 或 MySQL。

2. SQLite 仅限开发与测试

SQLite 是 Airflow 测试套件中使用的默认后端，文档明确警告不要在生产环境使用 SQLite。对于本地开发，建议使用最新稳定版 SQLite（要求 3.15.0+）。

3. 数据库连接串与迁移

元数据库连接通过 config_templates/config.yml 中的 [database] sql_alchemy_conn 配置项指定，默认值为 sqlite:///{AIRFLOW_HOME}/airflow.db。该配置项标注为敏感信息（sensitive: true），SQLAlchemy 支持多种数据库引擎的连接串格式，例如 PostgreSQL：

postgresql+psycopg://postgres:airflow@postgres/airflow

设置好数据库后，需要执行数据库初始化/迁移命令。根据 setting-up-the-database.rst，标准做法是：

airflow db migrate

该命令在 schema 不存在时创建、已存在时迁移到最新版本。执行迁移期间必须确保 Airflow 组件处于停止状态。注意：在 Airflow 2.7.0 之前，该操作用的是 airflow db upgrade，该命令已被废弃，应统一使用 airflow db migrate。在 Helm Chart 部署等场景中，数据库初始化和迁移会在 Airflow 升级时自动执行。

五、系统级依赖：Debian Bookworm 一键安装

除了 Python 层面的依赖，Airflow 还需要若干系统级库。官方在 dependencies.rst 中给出了针对 Debian Bookworm（12）的完整安装命令：

sudo apt install -y --no-install-recommends 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

这些包覆盖了 Airflow 运行所需的多种底层能力：krb5-user（Kerberos 认证）、libsasl2-*（SASL 认证）、libxmlsec1（XML 安全）、freetds-bin（TDS 协议/SQL Server 连接）、unixodbc（ODBC 驱动）、libgeos-dev（空间计算库）等。其他发行版（如基于 yum 的发行版）需要寻找对应等价包——例如官方文档以 postgres-devel 举例说明：只有当你需要连接 PostgreSQL 时才需要安装对应的系统开发包。

六、安装方式概览：前置条件之上的选型

前置条件确认之后，还需结合整体安装方式做规划。官方在 installation/index.rst 中列出了多种安装途径，不同方式对前置条件的依赖程度不同：

安装方式	特点	典型前置条件
本地快速启动（standalone）	pipx run apache-airflow standalone 或 uvx apache-airflow standalone，自动生成管理员密码并使用 SQLite，适合快速体验，不适合生产	Python、4GB 内存
源码安装	从 ASF 官方发布源码构建，可验证软件完整性与来源	构建工具链、系统依赖
PyPI 安装	官方唯一支持的生产级安装机制，依赖约束文件（constraints）保证可重复安装	Python、数据库
官方 Docker 镜像	基于 debian:bookworm-slim，组件隔离、依赖维护简单	Docker 环境、数据库
官方 Helm Chart	基于官方镜像的 Kubernetes 部署，社区统一维护升级	Kubernetes 1.30+、Helm
托管服务	由第三方负责运维与调优	无需关心前置条件

无论选择哪种方式，版本选型的总原则是一致的：优先选择仍在维护中的 Airflow 主版本与官方已测试的 Python/数据库/Kubernetes 版本组合。例如当前仓库中 Airflow 3.x 处于维护状态，而 2.x 已进入 EOL 阶段（详见 supported-versions.rst），官方强烈建议安装功能更丰富的最新版本。

七、总结：安装前的检查清单

综合本文，启动任何 Airflow 部署前，建议逐项核对以下清单：

1. Python 环境：3.10~3.14（对应 pyproject.toml 的 >=3.10,!=3.15）；
2. 操作系统：生产环境使用 Linux（优先 Debian Bookworm，与官方 CI 及镜像一致）；Windows 请走 WSL2 或 Linux 容器；
3. 数据库：生产选择 PostgreSQL（14~18）或 MySQL（8.0/8.4/Innovation），禁用 MariaDB；本地开发可使用 SQLite 3.15.0+，但严禁用于生产；
4. Kubernetes（如采用容器化部署）：1.30~1.35；
5. 资源：至少 4GB 内存起步，并建立持续监控-观察-调整的资源管理循环；
6. 系统依赖：在 Debian Bookworm 上执行上文的 apt install 命令补齐运行时库；
7. 数据库初始化：停止组件后执行 airflow db migrate 创建/升级元数据库 schema。

只有同时满足上述前置条件，Airflow 的安装与后续运维才能获得官方文档与社区支持的有效保障。