Apache Airflow 3.x 版本发布说明深度解读：从 3.0 服务化架构到 3.3 分区调度与多团队

Apache Airflow 3.x 版本发布说明深度解读从 3.0 服务化架构到 3.3 分区调度与多团队【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow导读本文基于当前仓库 RELEASE_NOTES.rst由 airflow-core/docs/release_notes.rst 通过 Sphinxinclude指令引入系统梳理 Apache Airflow 3.x 从 3.0.0 到 3.3.1 的演进脉络。文中完整保留各版本的核心变更、配置项、迁移步骤与命令行示例并结合仓库内 assets 文档、multi-team 文档、deadline-alerts 文档 等专题文档与源码路径进行佐证。读完本文你将掌握 Airflow 3.x 每一条重大特性的来龙去脉、需要关注的破坏性变更以及从 2.x 升级到 3.x、在 3.x 各版本间平滑滚动的实操要点。提示旧版本的发布说明请查阅各版本的 versioned 文档本仓库 RELEASE_NOTES.rst 只收录当前 3.x 系列的内容。一、总览3.x 各版本演进主线以发布说明为线索Airflow 3.x 的演进可以概括为一条主线、三次跃迁版本发布日期主题关键词3.0.02025-04-22服务化架构、Task Execution API、Edge Executor、DAG 版本化、资产调度、React UI 重写3.1.02025-09-25Human-in-the-Loop、Deadline Alerts、i18n 国际化、React 插件系统AIP-683.2.02026-04-07资产分区Asset Partitioning、多团队部署、gunicorn API 服务器、Python 3.143.3.02026-07-06分区能力扩展mappers/wait_policy、任务与资产状态存储AIP-103、可插拔重试策略AIP-105、Java/Go 语言 SDKAIP-1083.1.x / 3.2.x / 3.3.x 补丁持续安全加固、Triggerer 稳定性、升级迁移修复下面按大版本逐个展开。二、Airflow 3.0.0项目历史上最重大的架构转型3.0.0 被官方称为the most significant release in the projects history其核心是服务化service-oriented架构转型主要亮点如下。2.1 服务化架构Task Execution API 与 Task SDKAIP-723.0 引入了Task Execution API将任务执行与调度器解耦任务可以在 Airflow 传统运行时之外容器、边缘环境、其他运行时通过稳定契约执行。配套的Task SDK是运行 Airflow 任务的轻量级运行时环境为语言无关的任务执行奠定基础带来更好的隔离性、可移植性与可扩展性。同时3.0 引入了新的airflow.sdk命名空间集中暴露 DAG 作者的核心接口。DAG 作者应从此命名空间导入DAG、dag、task等对象而非内部模块以获得跨版本稳定、向前兼容的编写接口。这一思路在 3.1 中进一步推进见 3.1 节。2.2 Edge ExecutorAIP-69Edge Executor 在 3.0 中正式 GAGenerally Available用于在分布式或远程计算环境中执行任务面向事件驱动与边缘计算场景。它与 Task Execution API 集成支持混合与跨环境编排使任务 worker 更贴近数据或应用层。2.3 调度器托管 BackfillAIP-783.0 起backfill 不再作为独立的命令行任务启动而是完全由调度器管理。Backfill 运行与普通 DAG run 统一遵循相同的调度、版本化与可观测性模型并在 UI 与 REST API 中原生支持发起与监控。2.4 DAG 版本化AIP-66DAG 的结构性变更如任务重命名、依赖调整现在直接记录在元数据库中用户可以通过 UI 与 API 检查历史 DAG 定义为更安全的 backfill、更好的可观测性以及运行时决定的 DAG 逻辑奠定基础。注意发布说明明确指出triggerer 不初始化 DAG bundle——这意味着触发器trigger不能来自 DAG bundletriggerer 主进程不处理 trigger 代码随时间变化的问题触发器可以来自sys.path上的任何其他位置。2.5 资产Asset取代数据集AIP-74、AIP-75Datasets概念被重命名为Assets与数据生态的通用术语对齐内部模型也重构以支持未来的资产分区与校验。重命名波及模块、类、函数、配置键与内部模型关键映射包括Dataset→AssetDatasetEvent→AssetEventDatasetAlias→AssetAliasairflow.datasets.*→airflow.sdk.*DatasetTriggeredTimetable→AssetTriggeredTimetableairflow.listeners.spec.dataset.on_dataset_created→airflow.listeners.spec.asset.on_asset_createdcore.dataset_manager_class→core.asset_manager_classcore.dataset_manager_kwargs→core.asset_manager_kwargsasset装饰器让 DAG 定义更加资产中心化Airflow 得以更自然地支持事件驱动与数据感知调度。资产分区则在 3.2/3.3 中成为头号特性见第四、五节。2.6 统一调度字段与默认值变化移除schedule_interval与timetable参数DAG 统一使用schedule字段承载所有时间与事件驱动的调度逻辑。默认catchup_by_default False未显式设置catchup...的 DAG 不再默认补跑错过的区间。默认调度从once改为None。不再支持未来的 logical_date用logical_dateNone触发以当前时间戳运行的 run。由资产事件或 REST API 触发未指定logical_date的 DAG run 默认logical_dateNone、无数据区间此时访问data_interval_start、data_interval_end、logical_date会抛KeyErrorDAG 作者应改用dag_run.logical_date并做防御性判断。任务代码不能再直接访问元数据库与 DAG 状态、任务历史、DAG run 的交互必须走 REST API 或暴露的 context。2.7 移除的遗留特性与升级工具3.0 移除了 SLA、SubDAG、DAG 与 XCom pickling 以及若干内部 context 变量。升级路径明确用ruff校验 DAG 代码中已弃用/已移除的用法用airflow config update校验并升级配置文件3.0 为此提供了新的配置校验与升级工具升级要求从 Airflow 2.7 或更高版本开始Python 3.9–3.12。此外 CLI 被拆分为airflow与airflowctlAIP-81。历史 DAG 的迁移细节可参考仓库内的升级专项文档。三、Airflow 3.1.0人机协同、告警与国际化3.1.0 在 3.0 的架构地基之上补齐了面向 AI/ML 工作流与人机协同的能力。3.1 Human-in-the-LoopHITL3.1 引入 HITLHuman-in-the-Loop工作流可以暂停并等待人工决策非常适合 AI/ML 工作流、内容审核与审批场景。要点HITL 任务在等待人工输入时进入deferred状态具有相应角色的用户在 Airflow UI 中查看待处理任务、审阅上下文包括 XCom 数据与 DAG 参数并通过 Web 表单完成操作同时支持 API 驱动交互便于自定义 UI 与通知集成注意HITL operator 需要apache-airflow-providers-standard包与 Airflow 3.1。3.2 Task SDK 解耦与版本化序列化契约3.1 推进 Task SDK 与 Airflow Core 的解耦通过带版本契约的 DAG 序列化使组件独立部署时可独立升级。对 DAG 作者而言从airflow.sdk命名空间导入from airflow.sdk import DAG, task, asset即可获得最新编写特性与向前兼容性并减少对服务端 Airflow 版本的依赖。序列化契约的细节见 dag-serialization 文档。3.3 Deadline Alerts截止时间告警Deadline Alerts 提供主动式监控超过时间阈值时自动触发通知确保 SLA 合规。配置三要素参考点Reference pointDAG run 排队时间、logical date 或固定时间点区间Interval相对参考点的时间阈值可为正或负回调Callback使用 Airflow Notifiers 或自定义函数响应。典型用例每日 ETL 在调度时间后 1 小时未完成即告警关键截止时间前 30 分钟通知干系人资源受限的 DAG 排队过久时升级处理。3.1 中仅支持异步回调AsyncCallback同步回调SyncCallback在 3.2 中补充见 4.4 节。完整配置示例见 deadline-alerts 文档。3.4 UI 国际化i18n与 React 插件系统AIP-68i18nReact UI 支持 17 种语言阿拉伯语、加泰罗尼亚语、荷兰语、英语、法语、德语、希伯来语、印地语、匈牙利语、意大利语、韩语、波兰语、葡萄牙语、简体中文、西班牙语、繁体中文、土耳其语翻译系统含自动化完整性检查。React 插件系统取代旧的 Flask 式插件支持 React App完整 React 应用、外部视图iframe 嵌入外部 Web 应用并无缝鉴权、仪表盘小组件与菜单集成。开发体验方面支持热重载airflow-react-plugindev tools、TypeScript 与标准化加载校验示例见 custom-view-plugin 文档。3.5 推理执行流式 wait 端点与新的触发器规则3.1 新增流式 API 端点/dags/{dag_id}/dagRuns/{dag_run_id}/wait按指定间隔持续输出 JSON直到 DAG run 到达终态。例如# 以 2 秒轮询间隔观察 DAG run并携带 XCom 结果 curl -X GET http://localhost:8080/api/v2/dags/ml_pipeline/dagRuns/manual_2024_01_15/wait?resultinference_task \ -H Accept: application/x-ndjson适用场景包括 ML 推理监控、实时处理、API 集成与准同步工作流。此外新增触发器规则ALL_DONE_MIN_ONE_SUCCESS所有上游任务完成成功或失败且至少一个成功时触发填补了既有规则的空隙被跳过的上游任务按常规跳过后续任务。3.6 配置整理与安全清理若干[webserver]配置迁移到[api]段log_fetch_timeout_sec、hide_paused_dags_by_default、page_size、default_wrap、require_confirmation_dag_change、auto_refresh_interval移除[webserver] instance_name_has_markup、[webserver] warn_deployment_exposure[api] access_logfile替换为[api] log_config指向兼容logging.config.fileConfig的配置文件安全改进移除enable_xcom_deserialize_support配置允许反序列化未知对象存在远程代码执行风险XCom 展示改走更安全的方式API 默认 worker 数从 4 降为 1[api] workers多 CPU 场景推荐部署多个 API server 实例而非增加单进程 worker 数资产 API 响应键consuming_dags更名为scheduled_dags仅含在schedule参数中真正使用该资产的 DAG。3.7 structlog 全面落地Airflow 现在全面使用 structlog。BaseHook/BaseOperator的self.log已变为 structlog logger可在任务中输出结构化键值对日志# 之前stdlib 风格 # self.log.info(Registering adapter %r, item.name) # 现在结构化键值对 self.log.info(Registering adapter, nameitem.name)UI 中呈现为[2025-09-16 10:36:13] INFO - Registering adapter nameadapter1JSON 日志文件中则形如{timestamp: ..., log_level: info, event: Registering adapter, name: adapter1}。使用 OpenSearch/Elastic/Splunk 等集中存储时检索能力更强stdliblogging与structlog两种 logger 均可继续使用。版本要求3.1.0 起需要 Python 3.10/3.11/3.12/3.13移除已 EOL 的 Python 3.9。四、Airflow 3.2.0资产分区、多团队与 API 服务器现代化3.2.0 是功能密度极高的一次发布。4.1 资产分区Asset Partitioning——头号特性3.2.0 的旗舰特性是资产分区不再基于整个资产触发 DAG而是基于数据的特定分区调度下游处理只有相关数据切片触发下游工作。这对日期分区的 S3 路径、Hive 表分区、BigQuery 表分区等场景意义重大——此前任何对资产的更新都会触发所有下游 DAG现在只有正确的作业在正确的时间被触发。详细用法见 assets 文档。配套基础能力在 3.2 中引入、3.3 中扩展包括AllowedKeyMapper分区键校验、ChainMapper链式组合多个分区 mapper、时间分区 mapper时区感知、partition_date传播与airflow partitions clearCLI 命令、airflow dags clear分区范围重处理等。4.2 多团队部署Multi-Team3.2 引入多团队支持组织可在单个 Airflow 部署中运行多个相互隔离的团队每个团队拥有自己的 DAG、连接、变量、池与执行器实现资源与权限隔离而无需为每个团队部署独立实例。特别适合为多个数据工程/数据科学团队提供共享基础设施的平台团队。详见 multi-team 文档。警告多团队部署在 3.2.0 中为实验性功能可能随用户反馈变化。4.3 Deadline Alerts 同步回调SyncCallback在既有异步AsyncCallback之外3.2 新增SyncCallback同步回调由执行器而非 triggerer执行可通过executor参数指定目标执行器DAG 也可以通过向deadline参数传列表定义多个 Deadline Alert每个告警可选用任一回调类型。警告Deadline Alerts 在 3.2.0 中仍为实验性SyncCallback目前不支持存储在 Airflow 元数据库中的 Connection。注意3.2 中同步回调仅当[workers] state_store_backend相关配置就绪时才可访问连接与变量该限制在 3.3 中解除见 5.4 节。4.4 UI 增强与性能Grid 视图虚拟化只渲染可见行大幅提升任务运行数很多的 DAG 的渲染性能与内存占用XCom 管理可直接在 UI 中增删改 XCom 值HITL 详情历史审批/拒绝的完整审计轨迹Gantt 图改进展示所有任务尝试而非仅最新、显示任务显示名、跨浏览器一致的 ISO 日期格式、修复空日期崩溃单条 NDJSON 流替代逐 run 的 TI summary 请求GET /ui/grid/ti_summaries/{dag_id}?run_ids...成为唯一端点服务端每就绪一个 run 就输出一行 JSON各列渐进呈现旧的单 run 端点已移除同一dag_version_id的序列化 DAG 结构只加载一次。4.5 API 服务器gunicorn 支持与零停机 worker 回收API server 现支持以 gunicorn 作为替代服务器实现滚动 worker 重启防止长运行进程的内存累积。关键收益滚动重启新 worker 通过健康检查后才杀旧 worker、preloadfork 的写时复制内存共享、正确的 FIFO 信号处理SIGTTOU 杀最旧 worker。配置示例[api] # 使用 gunicorn 替代 uvicorn server_type gunicorn # 每 12 小时滚动重启 worker worker_refresh_interval 43200 # 一次只重启一个 worker worker_refresh_batch_size 1或通过环境变量export AIRFLOW__API__SERVER_TYPEgunicorn export AIRFLOW__API__WORKER_REFRESH_INTERVAL43200需要安装 gunicorn extrapip install apache-airflow-core[gunicorn]。默认 uvicorn 模式不支持滚动重启workers1 时无 master 进程可发信号、uvicorn 的 SIGTTOU 杀最新 worker 为 LIFO 语义、各 worker 独立加载无内存共享需要 worker 回收或多 worker 内存高效部署时请使用 gunicorn。4.6 其他重要变更Python 3.14 支持SQLAlchemy 仅支持 2.xsqlalchemy[asyncio]2.0.48结构化 JSON 日志[logging] json_logs使 API server 全部输出含访问日志、警告、未处理异常变为 NDJSONairflow celery worker尚不支持异常迁移到 Task SDK任务相关异常AirflowSkipException、TaskDeferred等改由airflow.sdk.exceptions提供airflow.exceptions保留代理并发出DeprecatedImportWarningsensor 输入校验失败抛ValueError此前为AirflowExceptionprovider 统一走airflow.providers.common.compat.sdk序列化serde逻辑移入 Task SDK从airflow.serialization.serde/airflow.serialization.serializers.*迁往airflow.sdk.serde/airflow.sdk.serde.serializers.*旧路径仍可用但会告警兼容层将在 Airflow 4 移除retry_exponential_backoff支持数值乘数True→2.0False→0固定retry_delay数值如3.5直接指定乘数REST API 模式从 boolean 变为 number运算符级render_template_as_native_obj覆盖可在单个 operator 上覆盖 DAG 级设置None为继承PythonOperator支持异步 callablepython_callable可直接接收async def函数continuous调度无需start_date未暂停即立即开始运行airflow scheduler --only-idle配合--num-runs只在调度器空闲时计数运行便于跑一次处理完所有触发移除airflow.traces中内部 OTel Trace 元类与共享 tracer 包装器内部代码未文档化从官方容器镜像移除 MySQL clientMySQL 用户需自行安装DagBag使用Path.relative_to保证跨平台一致FileLoadStat新增bundle_path/bundle_name字段且不再产生以/开头表示相对 dags 文件夹的路径破坏性变更建议改用pathlib.Pathairflow connections list移除冗余的--conn-id选项改用airflow connections getis_authorized_backfill从BaseAuthManager移除backfill 权限统一由DagAccessEntity.Run的requires_access_dag校验性能改进rendered task instance 字段清理提速约 42 倍max_num_rendered_ti_fields_per_task更名为num_dag_runs_to_retain_rendered_fields旧名仍可用、API server 启动任务不再加载完整SerializedDAG降低内存。五、Airflow 3.3.0分区扩展、状态存储与语言 SDK3.3.0 在 3.2 的分区基础上大幅扩展并引入三项全新机制均为 AIP 驱动。5.1 资产分区能力扩展在 3.2.0 分区基础之上3.3.0 扩展了单个上游资产事件到分区下游 DAG run 的扇出模型新分区 mapperRollupMapper多对一、FanOutMapper一对多、FixedKeyMapperSegmentWindow分类 rollup与时间窗口day/week/month/quarter/year及wait_policyWaitForAll或MinimumCount(n)组合控制分区 run 何时触发窗口可向前或向后扇出每次上游事件的总扇出量受新配置[scheduler] partition_mapper_max_downstream_keys限制可按 mapper 覆盖另有 per-mappermax_fan_out新增PartitionedAtRuntimetimetableDAG 声明其分区键在 run 启动时分配而非从上游事件映射Window支持forwardkwarg 实现前向扇出AIP-76。详细用法见 assets 文档。从源码结构看相关实现位于airflow-core/src/airflow/partition_mappers发布说明还提到从airflow.partition_mappers导出FanOutMapper与 wait policies。5.2 任务与资产状态存储AIP-1033.3.0 为任务与资产引入一等公民的状态存储任务可通过新的task_state_storeaccessor 持久化任意键值状态跨重试与 run 存活资产通过asset_state_store携带自身状态——两者都从 Task SDK 可用状态默认存于元数据库也可用自定义 worker 侧后端[workers] state_store_backend支持按 key 设置保留期与周期性垃圾回收以及可选的clear_on_success通过 Core API 与 Execution API 全量可管理get/set/delete/clear支持expires_at、default参数、patch 任务状态接口等。详见 task-and-asset-state-store 文档部署视角见 administration-and-deployment 下的同名文档。5.3 可插拔重试策略AIP-105任务重试行为现在可插拔除了固定的retries计数可附加自定义重试策略retry_policy决定是否重试以及何时重试例如仅在特定异常上重试或基于自定义逻辑退避。3.3 还修复了 retry-policy 覆盖未持久化到任务实例历史、retry_policy 序列化导致新 DAG 版本误创建等缺陷。参考 concepts 文档中的 retry-policies 章节。5.4 语言 Task SDKCoordinator 层AIP-1083.3.0 增加 Coordinator 层让单个任务实现可以用非 Python 语言编写而 DAG 与调度仍留在 Python在 DAG 中用task.stub(queue...)声明任务worker 将其路由到配置的 coordinatorJVM 语言用JavaCoordinatorGo 等自包含原生二进制用ExecutableCoordinatorcoordinator 在对应语言运行时中执行任务并通过 Execution API 代理 Variables、Connections 与 XComs3.3 同时支持extra字段与同步回调访问连接/变量。警告Coordinator 层与 Java/Go SDK 在 3.3.0 中为实验性可能随反馈变化。仓库中对应实现位于 java-sdk、go-sdk 目录文档入口见 language-sdks。5.5 其余核心变更rerun_with_latest_version控制 clear/rerun/backfill 的 DAG run 使用最新 bundle 版本还是初次运行的原始版本。优先级显式请求参数/CLI 标志 → DAG 级rerun_with_latest_version→[core] rerun_with_latest_version→ 默认值clear/rerun 为Falsebackfill 为True保持历史行为。详见 dag-bundles 文档Provider 示例 DAG 成为独立 bundle经ProvidersManager发现并注册为每 provider 一个 bundleapache-airflow-providers-distribution-example-dags第三方为distribution-example-dags由[core] load_examples控制是否注册。按bundle_namedags-folder过滤 provider 示例 DAG 的 REST API 客户端需更新远程日志解析与airflow.logging_config解耦远程任务日志 handler 解析由共享的airflow_shared.logging.factory模块接管优先级为用户[logging] logging_config_class导出REMOTE_TASK_LOG/DEFAULT_REMOTE_CONN_ID→ProvidersManager按remote_base_log_folder的 scheme 分发到 providerRemoteLogIO类经无参from_config()类方法实例化→ 读取airflow_local_settings.py的过渡性遗留回退Airflow 4.0 移除。airflow.logging_config.load_logging_config已弃用configure_logging改为惰性解析OTel 指标改进计时类指标由 Gauge 改为 Histogram保留 count/sum/分桶分布dag_processing.last_run.seconds_ago.{dag_file}变为 legacy 指标新指标带file_path/bundle_name/file_name标签可用[metrics] legacy_names_on关闭 legacy 指标新增task.executespan、head sampling 支持、run_type标签等新 Deadlines 页面Browse 菜单下拥有 Dag Runs 的can_read与menu_access的角色即可访问result装饰器将 TaskFlow 任务标记为 DAG 的结果任务多进程控制新增[core] mp_start_method、[core] mp_forkserver_preload可按[scheduler]/[triggerer]/[dag_processor]覆盖其他awaiting_input任务状态Human-in-the-Loop运行于 triggerer、on_kill()钩子BaseTrigger、[triggerer] shared_stream_cohort_grace_period、异步 XCom accessors、BaseHook.aget_hook、Variable.keys()、mTLS 与私有 CA 支持API client/server、teams syncCLI、--team-name参数pool CLI、triggerer、partitions clear等。六、补丁版本安全加固与稳定性修复要点发布说明中大量篇幅是各补丁版本的 Bug Fixes。以下是最值得运维与升级人员关注的几类。6.1 3.3.12026-08-12pandas 3 改变 DataFrame XCom 的存取方式#71169pandas 3 将公开类从pandas命名空间暴露DataFrame 限定名从pandas.core.frame.DataFrame变为pandas.DataFrame。Airflow 同时注册两个名称任一 pandas 版本写入的 DataFrame 均可被任一侧读取无需配置变更。滚动升级要求必须先把 Airflow 升级到该版本再让任何组件升级到 pandas 3尤其 worker否则旧组件拉取会报ImportError: pandas.DataFrame was not found in allow list...——该报错指向配置但不是 allow list 问题改配置无效升级 reader 即可恢复降级是不可逆门回滚会让 pandas 3 下写入的 DataFrame XCom 卡住同时注意 reader 的 pandas 版本决定拉取结果的dtypespandas 3 下字符串列返回str而非object、缺失值为nan而非None依赖dtype object、is None或DataFrame.equals()的下游代码需复查修复 2.x → 3.0 升级时配置了自定义 DAG bundle 的失败#70994迁移0082_3_1_0_make_bundle_name_not_nullable将所有遗留行赋值为bundle_namedags-folder导致使用其他 bundle 的部署触发 DagRun 时报Requested bundle dags-folder is not configured.。现在DagFileProcessorManager启动时执行一次性的 best-effort 回填按文件路径将受影响的 DAG 路由到正确 bundle未匹配的 DAG 在下一次成功解析时自愈或立即执行airflow dags reserialize强制触发团队作用域敏感配置值现在会被隐藏#71099敏感选项按基础 section 注册此前团队作用域覆盖[teamsection]配置段或AIRFLOW__TEAM___SECTION__KEY环境变量不被识别为同一选项而完整返回。现在先解析回基础选项再判定敏感性AirflowConfigParser.as_dict(display_sensitiveFalse)、GET /config、GET /config/section/{section}/option/{option}与airflow config list对团队作用域的敏感值返回 hidden 需要真实值时用display_sensitiveTrue。团队作用域的_cmd/_secret条目原地替换为 hidden 不支持为团队解析它们。6.2 3.2.22026-05-29SMTP STARTTLS 证书校验#65346airflow.utils.email.send_email的 STARTTLS 升级现在默认校验 SMTP 服务器证书。指向自签名/非校验证书 SMTP 且需保留旧行为的部署须在airflow.cfg中设置email.ssl_context nonedefault未设置时的新默认使用ssl.create_default_context该选项此前仅作用于SMTP_SSL路径现同时作用于 STARTTLSREST API 搜索语义变更#64963、#66015UI 从全匹配*_pattern切换为索引友好的*_prefix_pattern前缀匹配LIKE term%范围扫描可利用 B-tree 索引REST API 两种形式都保留*_pattern行为不变UI 每个搜索框新增 Match anywhere 正则图标开关可切回子串匹配Triggerer 竞态与死锁修复 子进程看门狗#64620、#64882、#66412触发器调用同步 SDK 方法如 Google provider 中safe_to_cancel用的get_task_states曾导致 triggerer 内部子进程崩溃而 triggerer 心跳正常、静默不处理触发器。修复采用响应多路复用每个请求带唯一 ID 路由回正确的调用方。新增[triggerer] runner_health_check_threshold默认 30 秒子进程静默超时后父进程停止更新心跳调度器即可检测挂起并重新分配触发器设为0可禁用allowed_deserialization_classes_regexp改为全串匹配#66499使用re.fullmatch()替代re.match()防止airflow\.models\.Variable之类模式误放行airflow.models.Variable_Malicious。默认值为空开箱即用不受影响依赖前缀匹配语义的如airflow\.models\.表示该命名空间下所有类需加.*airflow\.models\..*自定义 DeadlineReference 类必须注册通过AirflowPlugin的新deadline_references属性注册与自定义 timetable、自定义分区 mapper 的模式一致未注册的自定义引用在反序列化时抛DeadlineReferenceNotRegistered。6.3 3.2.12026-04-21/dags端点权限收紧#64822仅有 DAG 读权限的用户不再能从此端点取数现在需要DagAccessEntity.RUN、DagAccessEntity.HITL_DETAIL、DagAccessEntity.TASK_INSTANCE等额外权限端点返回这些实体的聚合数据。请为自定义角色补充 DAG Runs、Task Instances、HITL Details 的读权限UI 主题配置允许仅 CSS 覆盖、仅图标或空{}恢复 OSS 默认值tokens字段变为可选#64552。6.4 跨版本安全与可靠性主题纵观各补丁版本持续投入的方向包括密钥脱敏Variable JSON 列表值掩码、bulk 更新时审计日志中未掩码的密钥、嵌套在 list/tuple/set 中的敏感值日志掩码、rendered templates 中KubernetesPodOperator的密钥掩码、审计日志中所有 connection extra 与 variable 值掩码、API 访问日志中类密钥 query 参数的 redact 等认证加固SimpleAuthManager密码比较改用hmac.compare_digestCWE-208、登录 cookie 设置SameSiteLax、密码使用密码学安全 RNG、npm 漏洞修复、is_url_safe拒绝///等畸形 URL 防开放重定向、JWTkid/audience 校验、多 worker 下 FAB auth manager 竞态修复Triggerer/Scheduler 稳定性触发器文件句柄泄漏、json_logs下 Triggerer CrashLoopBackOff、任务-worker 通信死锁检测、调度器StaleDataError/UniqueViolation崩溃修复、HA 下重复任务执行修复、慢资产监听器导致的大扇出数据库锁竞争与语句超时迁移/降级可靠性多个 SQLite 外键禁用、MySQL 保留字interval、downgrade 性能deadline.callback_id索引、迁移 0094 用 SQL 替代 Python 反序列化等API 错误码规范化无效 trigger-DAG-run 请求返回清晰错误而非 500、SQLite 在 backfill 创建期间锁定时返回 503、空 backfill 窗口返回 422 并停止遗留孤儿行、陈旧任务实例的 rendered fields 设置返回 410 等。七、从 2.x 升级到 3.x 的实践清单综合 3.0.0 大版本说明与后续补丁升级前请对照核查代码层面用 ruff 检出airflow.sdk新导入路径DAG/dag/task/asset、统一schedule字段、处理logical_dateNone语义、为 asset/manual 触发的 run 做dag_run.logical_date防御、将任务异常改为从airflow.sdk.exceptions导入、将自定义序列化器迁往airflow.sdk.serde.serializers.*配置层面运行airflow config update校验升级核对[webserver]→[api]的配置迁移、api.page_size→api.fallback_page_limit弃用、max_num_rendered_ti_fields_per_task→num_dag_runs_to_retain_rendered_fields更名、email.ssl_context新默认值权限层面检查自定义角色是否具备DagAccessEntity.Runbackfill 权限已统一以及/dags端点所需的新读权限涉及多团队时核对团队作用域敏感值的掩码行为数据层面自定义 bundle 部署注意 3.3.1 的迁移回填必要时airflow dags reserializepandas 与 Airflow 的升级顺序先 Airflow 后 pandas 3XCom 中 DataFrame 的降级不可逆性部署层面Python 版本要求3.03.9–3.123.13.10–3.133.2 起支持 3.14、SQLAlchemy 2.x 唯一支持、API server worker 数建议接近 CPU 核数或部署多实例、需要滚动 worker 回收时选用 gunicornapache-airflow-core[gunicorn]。八、延伸阅读本文依据的权威全文RELEASE_NOTES.rst其文档入口为 airflow-core/docs/release_notes.rst资产与分区 assets 文档多团队部署multi-team 文档Deadline Alertsdeadline-alerts 文档HITLhitl 文档任务/资产状态存储AIP-103core-concepts 版本与部署版本DAG bundles 与版本控制dag-bundles 文档DAG 序列化契约dag-serialization 文档React 插件custom-view-plugin 文档语言 SDKJava/Go源码位于 java-sdk 与 go-sdk文档见 language-sdks。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考