升级到 Airflow 3¶

Apache Airflow 3 是一个主要版本，并包含重大变更。本指南将引导您完成从 Airflow 2.x 升级到 Airflow 3.0 所需的步骤。

步骤 1: 处理前提条件¶

确保您使用的是 Airflow 2.7 或更高版本。
确保您的 Python 版本在支持列表中。Airflow 3.0.0 支持以下 Python 版本：Python 3.9、3.10、3.11 和 3.12。
确保您没有使用任何已在 Airflow 3 中移除的功能或特性。

步骤 2: 清理和备份现有的 Airflow 实例¶

强烈建议您在开始迁移过程之前备份您的 Airflow 实例，特别是您的 Airflow 元数据数据库。
- 如果您的数据库没有“热备份”能力，您应该在关闭 Airflow 实例后进行备份，以确保数据库备份的一致性。例如，如果您不关闭 Airflow 实例，数据库备份将不会包含所有的 TaskInstances 或 DagRuns。
- 如果您没有进行备份而迁移失败，您可能会陷入半迁移状态。这可能是由迁移过程中您的 Airflow CLI 与数据库之间的网络连接中断等原因造成的。进行备份是避免此类问题的重要预防措施。
长期运行的 Airflow 实例会积累大量不再需要的数据（例如，旧的 XCom 数据）。Schema 更改将是 Airflow 3 升级过程的一部分。如果数据库很大，这些 schema 更改可能需要很长时间。为了更快、更安全的迁移，我们建议您在升级前清理您的 Airflow 元数据库。您可以使用 airflow db clean Airflow CLI 命令来精简您的 Airflow 数据库。
确保没有与 DAG 处理相关的错误，例如 AirflowDagDuplicatedIdException。您应该能够无错误地运行 airflow dags reserialize。如果您必须解决来自 DAG 处理的错误，请确保在升级之前将您的更改部署到旧实例，并等待所有 DAG 都被重新处理（且所有错误都消失）后，再继续升级。

步骤 3: DAG 作者 - 检查您的 Airflow DAG 兼容性¶

为了最大程度地减少从早期版本 Airflow 升级带来的阻力，我们创建了一个使用 Ruff 的 DAG 升级检查工具。

最新可用的 ruff 版本将包含最新的规则，但请务必使用至少 0.11.6 版本。以下示例演示了如何检查 DAG 不兼容性，这些不兼容性需要在 Airflow 3 上按预期运行之前进行修复。

ruff check dag/ --select AIR301

要预览推荐的修复，运行以下命令：

ruff check dag/ --select AIR301 --show-fixes

某些更改可以自动修复。为此，运行以下命令：

ruff check dag/ --select AIR301 --fix

步骤 4: 安装标准提供程序¶

一些原本捆绑在 airflow-core 包中（例如 BashOperator 和 PythonOperator）的常用 Operators，现已拆分到单独的包中：apache-airflow-providers-standard。
为了方便起见，此包也可以安装在 Airflow 2.x 版本上，以便可以修改 DAG，使其从标准提供程序包而不是 Airflow Core 引用这些 Operators。

步骤 5: 部署管理者 - 升级您的 Airflow 实例¶

为了更轻松、更安全的升级过程，我们还创建了一个用于升级 Airflow 实例配置的工具。

第一步是运行如下所示的配置检查工具：

airflow config update

此配置工具还可以自动更新您的配置，使其与 Airflow 3 兼容。可以通过如下方式完成：

airflow config update --fix

Airflow 升级中最主要的部分是数据库升级。Airflow 3 的数据库升级过程与 Airflow 2.7 或更高版本相同。

airflow db migrate

如果您有使用 Flask-AppBuilder 视图 (appbuilder_views)、Flask-AppBuilder 菜单项 (appbuilder_menu_items) 或 Flask blueprints (flask_blueprints) 的插件，您将需要将其转换为 FastAPI apps，或确保安装提供了 Airflow 3 向后兼容层的 FAB 提供程序。理想情况下，您应该将插件转换为 FastAPI apps (fastapi_apps)，因为 FAB 提供程序中的兼容层已被弃用。

步骤 6: 启动脚本的更改¶

在 Airflow 3 中，Webserver 已成为一个通用的 API 服务器。可以使用以下命令启动 API 服务器：

airflow api-server

现在必须独立启动 DAG 处理器，即使是用于本地或开发设置。

airflow dag-processor

您现在应该能够启动您的 Airflow 3 实例了。

重大变更¶

Airflow 2.x 中一些已弃用的功能在 Airflow 3 中不再可用。其中包括：

SubDAGs: 已被 TaskGroups、Assets 和数据感知调度 (Data Aware Scheduling) 取代。
Sequential Executor: 已被 LocalExecutor 取代，LocalExecutor 可以与 SQLite 一起用于本地开发用例。
SLAs: 已弃用并移除；将由即将推出的 Deadline Alerts 取代。
Subdir: 作为许多 CLI 命令的参数，--subdir 或 -S 已被DAG 捆绑包 (DAG bundles)取代。
一些 Airflow 上下文变量: 以下键在任务实例的上下文 (context)中不再可用。如果未替换，将导致 DAG 错误： - tomorrow_ds - tomorrow_ds_nodash - yesterday_ds - yesterrow_ds_nodash - prev_ds - prev_ds_nodash - prev_execution_date - prev_execution_date_success - next_execution_date - next_ds_nodash - next_ds - execution_date
的 catchup_by_default DAG 参数现在默认为 False。
的 create_cron_data_intervals 配置现在默认为 False。这意味着默认将使用 CronTriggerTimetable 而不是 CronDataIntervalTimetable
Simple Auth 现在是默认的 auth_manager。要继续使用 FAB 作为 Auth Manager，请安装 FAB 提供程序并将 auth_manager 设置为 FabAuthManager
```
airflow.providers.fab.auth_manager.fab_auth_manager.FabAuthManager
```