用途:将 Airflow 2.x 的 DAG 代码迁移到 3.x,处理导入、算子、Hook、上下文变量与元数据 API 用法的变动。
升级路径:迁移前建议先升到 Airflow 2.11,再升到至少 3.0.11,最好直接到 3.1;其他路径会使回滚困难。早期 3.0 版本问题较多。
自动修复:运行 Ruff 的 Airflow 迁移规则(AIR30/AIR301/AIR302/AIR31/AIR311/AIR312):ruff check --preview --select AIR --fix --unsafe-fixes .;之后按 reference/migration-checklist.md 手工检查残留问题,重点关注元数据库直连、旧导入、调度/上下文键、XCom、datasets 转 assets、REST API/认证、插件与文件路径。
架构变化:Worker 不再直连元数据库,任务通过 API 服务器的 Task Execution API 运行,DAG 处理器独立于调度器。任务代码仍可导入 ORM,但用它访问元数据库会报错:RuntimeError: Direct database access via the ORM is not allowed in Airflow 3.x。需改用 Airflow Python 客户端(apache-airflow-client==<版本>)或直接调用 REST API(如 /api/v2/dags)。触发器若在 asyncio 事件循环中同步调用 Hook,建议改用 sync_to_async(...)。
关键改动:DummyOperator 改为 airflow.providers.standard.operators.empty.EmptyOperator;装饰器改为 airflow.sdk.dag / airflow.sdk.task;Dataset 改为 Asset。上下文键 execution_date 改为 context["dag_run"].logical_date,templates_dict 改为 context["params"],triggering_dataset_events 改为 triggering_asset_events 等。默认 schedule 由 timedelta(days=1) 变为 None,catchup 由 True 变为 False。on_success_callback 不再在跳过时运行;@teardown 不允许 TriggerRule.ALWAYS。
行为与配置陷阱:cron 调度语义变化,需要 Airflow 2 风格可设 AIRFLOW__SCHEDULER__CREATE_CRON_DATA_INTERVAL=True;.airflowignore 由 regexp 改为 glob,保留旧行为可设 AIRFLOW__CORE__DAG_IGNORE_FILE_SYNTAX=regexp;OAuth 回调 URL 增加 /auth/ 前缀;共享工具需用全限定导入如 import dags.common。
限制:其余未在资料中给出的平台、收费与效果信息暂未提供。