Apache Airflow 3.3.x 与 3.x 系列发布说明全解读从版本演进、重大变更到升级实操【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 官方发布说明文档 RELEASE_NOTES.rst 记录了从 2.5.0 到 3.3.1 共数十个版本的完整演进脉络涵盖重大行为变更、新特性、Bug 修复、文档更新四类条目。本文将聚焦于当前 3.3.x 主版本线的重大变更Significant Changes逐一还原其技术背景、配置项与迁移影响并结合本仓库 airflow-core/src/airflow、task-sdk/src 的源码实现给出可验证依据。读完本文你将能快速判断每次升级对你现有 DAG、XCom、调度行为与配置的影响掌握诸如 DataFrame XCom 兼容性、Asset 分区调度、任务/资产状态存储等新机制的落地要点。一、发布说明的结构与版本覆盖该文档是 Apache Airflow 通过 towncrier 从各版本 newsfragment见 airflow-core/newsfragments、chart/newsfragments聚合生成的发行说明文件开头明确提示「旧版本的说明可在按版本归档的文档中查看」。每个版本条目按统一模板组织为Significant Changes需要用户感知的重大行为变更、弃用与迁移指引是本篇解读的重点New Features / Bug Fixes新能力与缺陷修复的逐条清单Miscellaneous内部重构、性能优化、UI 打磨Doc Only Changes纯文档修正含多语言 UI 翻译补齐如zh-CN、zh-TW、ko等。文档覆盖的版本时间轴如下均为文档标注的发布日期版本发布日期系列主题3.3.12026-08-123.3.0 的修复与兼容性收尾pandas 3、bundle 迁移回填3.3.02026-07-06Asset 分区深化、任务/资产状态存储、可插拔重试策略、Java/Go 语言 SDK3.2.2 / 3.2.12026-05-29 / 2026-04-213.2.0 稳定性修复、triggerer 看门狗3.2.02026-04-07多团队multi-team、Python 3.14、仅支持 SQLAlchemy 23.1.x2025-09 ~ 2026-03HITL、Task SDK 解耦、i18n、React 插件、streaming wait API、structlog3.0.x2025-04 ~ 2025-08面向服务的架构、Edge Executor、DAG 版本化、React/FastAPI UI、基于 Asset 的调度2.10/2.112024-08 ~ 2026-033.x 演进前的 2.x 维护线二、Airflow 3.3.1围绕 3.3.0 的兼容性与稳健性收尾3.3.12026-08-12是当前文件中的最新版本其 Significant Changes 包含三项需要部署方主动评估的内容。1. pandas 3 改变了 DataFrame XCom 的存储与读取方式#71169pandas 3 将公开类移入pandas命名空间DataFrame 的限定名从pandas.core.frame.DataFrame变为pandas.DataFrame。由于 XCom 会把该名称与序列化值一并写入元数据库写入的限定名取决于推送方组件所用的 pandas 版本。Airflow 注册了两种名称因此任一 pandas 版本写入的 DataFrame XCom 均可被另一版本读取——无需改配置存量 XCom 保持可读。但文档明确给出了三条升级纪律先在全部组件尤其 worker上升级到本版本再让任一组件接触 pandas 3。旧组件拉取 pandas 3 写入的 DataFrame XCom 会直接失败报错为ImportError: pandas.DataFrame was not found in allow list for deserialization imports. To allow it, add it to allowed_deserialization_classes in the configuration文档特别提醒报错信息指向配置但 allow list 并非原因修改配置无效数据行并未损坏升级读取方后即可恢复。降级对这些 XCom 是单向门回滚到不支持该变更的版本会使 pandas 3 期间写入的 DataFrame XCom 无法读取直到再次升级。审查依赖dtypes的下游代码读取到的 DataFrame 外观由读取方的 pandas 版本决定。pandas 3 下字符串列返回str而非object缺失值返回nan而非None。按dtype object分支、用is None判断单元格、或用DataFrame.equals()与参照帧比较的代码在升级后可能行为不同。2. 修复 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.。3.3.1 让DagFileProcessorManager在启动时执行一次性的 best-effort 回填依据文件路径把受影响的 Dag 路由到正确的 bundle无法匹配的 Dag 会在下一次成功解析时自愈也可执行airflow dags reserialize强制立即生效。3. 敏感配置项在团队作用域下被正确隐藏#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 团队段不支持解析这些条目因此连命令串/密钥路径也不再展示非团队配置不受影响display_sensitiveTrue仍返回真实值。相关实现与解析器位于 airflow-core/src/airflow/config配置模式的权威定义在 airflow-core/src/airflow/config_templates/config.yml。4. 值得关注的 Bug 修复方向3.3.1 修复量较大按主题归类便于你对照排查调度与任务生命周期defer 任务状态无法恢复时改为失败而非卡死#71183TriggerDagRunOperator收到 404 时不再跳过回调#71083heartbeat 超时重试不再误触发on_failure_callback#69824deferable 任务经TaskFailedEvent失败时尊重 retries#71163none_failed_min_one_success不再跳过 mapped task group#70318。Triggerer清理未使用 trigger 提速以避免崩溃#70668json_logs开启时的 CrashLoopBackOff 修复#70669任务-worker 通信死锁可检测并浮出#70744。数据库与 API资产监听器大扇出导致的锁竞争/语句超时修复#71065SQLite 回填创建锁冲突返回 503#69659空回填窗口返回 422 且不再遗留孤儿行#69367PostgreSQL 14 的 Dag run 时长统计崩溃修复#70964。安全与脱敏JSON 列表中的敏感Variable值、审计日志中批量更新的密钥、嵌套在 list/tuple/set 中的敏感值均被正确掩码#71069/#71043/#70189KubernetesPodOperator的 Rendered Templates 视图掩码修复#70756重定向校验拒绝畸形 URL 防 open-redirect#70515。UIDags 列表组合过滤 500、任务日志滚动选中被清除、Clear Task 对话框原文翻译键等问题#71371/#71200/#71240。三、Airflow 3.3.0分区、状态存储与多语言任务执行的里程碑3.3.02026-07-06是当前文档中特性最集中的一次发布共有六个 Significant Changes 板块。1. Asset Partitioning上游事件到下游分区运行的大规模扇出承接 3.2.0 引入的 asset partitioning3.3.0 显著扩展了「单个上游 asset 事件扇出到多个下游分区 DagRun」的能力新增分区映射器partition mapper组合RollupMapper多对一聚合将多个上游分区事件聚合成下游运行实现类见 airflow-core/src/airflow/partition_mappers/base.pyFanOutMapper一对多扇出将一个事件拆到多个下游键实现类见 airflow-core/src/airflow/partition_mappers/temporal.pyFixedKeyMapperSegmentWindow分类categorical滚动聚合见 airflow-core/src/airflow/partition_mappers/fixed_key.py 与 airflow-core/src/airflow/partition_mappers/window.py。这些映射器与时间窗口day/week/month/quarter/year可向前或向后扇出以及wait_policyWaitForAll()或MinimumCount(n)组合决定分区运行何时触发。每个上游事件的总扇出量由新增配置[scheduler] partition_mapper_max_downstream_keys限定且每个 mapper 可单独覆盖该上限max_fan_out。配置项定义 airflow-core/src/airflow/config_templates/config.yml默认 1000容量检查的强制执行在 airflow-core/src/airflow/assets/manager.py完整的组合写法可参考官方示例 DAG airflow-core/src/airflow/example_dags/example_asset_partition.py例如RollupMapper(upstream_mapperFixedKeyMapper(all_regions), windowSegmentWindow([us,eu,apac]))的分类滚动、FanOutMapper的一对多时间扇出约 L317-L490。3.3.0 还引入PartitionedAtRuntimetimetable允许 DAG 声明其分区键在运行启动时分配而非从上游事件映射。此外把上游partition_key暴露到triggering_asset_events与dag_run.consumed_asset_eventsAIP-76。详细用法见 assets.rst。2. Task and Asset State StoreAIP-1033.3.0 为任务与资产提供了一等公民的状态存储任务可通过新的task_state_store访问器持久化跨重试、跨运行的任意键值状态资产经asset_state_store携带自身状态两者均可从 Task SDK 使用状态默认保存在元数据库中也可通过[workers] state_store_backend配置自定义的 worker 侧后端配置项见 airflow-core/src/airflow/config_templates/config.yml支持按 key 设置保留期并周期性垃圾回收可选clear_on_success在成功后清空提供 Core API 与 Execution API 双端管理端点并支持按名称/URI 访问、AssetUriRef、Pydantic 模型的序列化注册等SDK 侧访问器实现在 task-sdk/src/airflow/sdk例如上下文对象 task-sdk/src/airflow/sdk/definitions/context.py 中暴露相关 accessor 的实现get()还新增了default参数以简化读取。使用文档见 core-concepts/task-and-asset-state-store.rst 与部署清理相关章节 administration-and-deployment/task-and-asset-state-store-cleanup.rst。3. Pluggable Retry PoliciesAIP-105任务重试行为可插拔化除固定retries计数外可挂载自定义重试策略由策略决定「是否重试、何时重试」从而支持诸如仅对特定异常重试、按自定义逻辑退避等场景。实现与序列化位于 task-sdk/src/airflow/sdk 的 retry 相关模块注意 3.3.0 的 Bug 修复中也提到retry_policy被序列化时应避免触发新 Dag 版本生成#69315且重试策略覆盖需持久化到任务实例历史#69241——这两点在 3.3.0 内已被修复。4. Language Task SDKCoordinator 层与 Java/Go 实现AIP-1083.3.0 新增Coordinator 层单个任务可用非 Python 语言实现而 DAG 与其调度仍留在 Python。在 DAG 中通过task.stub(queue...)声明任务worker 将其路由到配置好的 coordinatorJVM 语言用JavaCoordinatorGo 等自包含原生二进制用ExecutableCoordinator由 coordinator 在对应语言运行时中执行任务并借 Execution API 代理 Variables、Connections、XCom。文档以 warning 形式明确Coordinator 层与 Java/Go SDK 在 3.3.0 中仍属实验性可能随用户反馈变化。文档入口language-sdks/index.rstJava SDK 仓库源码位于 java-sdkGo SDK 位于 go-sdk两目录均包含 example 与完整实现。5. Dag bundle 版本clear、rerun 与 backfill 时的版本选择#63884新增rerun_with_latest_version设置控制被 clear、rerun 或 backfill 的 DagRun 是使用最新 bundle 版本还是沿用初次运行时的版本。解析优先级为显式请求参数/CLI 标志 → DAG 级rerun_with_latest_version→[core] rerun_with_latest_version→ 兜底默认clear/rerun 为Falsebackfill 为True以保持历史行为。背景是2.x 总是用最新代码重跑3.x 引入 bundle 版本化后默认沿用原版本此设置把选择权交还给用户。同样在 3.3.0TriggerDagRunOperator的 rerun 也遵循该设置#67273。完整说明见 dag-bundles.rst。6. 其余值得注意的平台级变化Provider 示例 DAG 成为独立 bundle#66161provider 发行版自带的示例 DAG 改由ProvidersManager发现并注册为独立 bundle命名apache-airflow-providers-distribution-example-dags第三方为distribution-example-dags是否注册仍受[core] load_examples控制。按dags-folder过滤的 REST 客户端需改用新 bundle 名DAG 标识符不变。远程日志解析与airflow.logging_config解耦#67056远程 task 日志 handler 的解析移交airflow_shared.logging.factory优先级固定为① 自定义[logging] logging_config_class导出REMOTE_TASK_LOG/DEFAULT_REMOTE_CONN_ID②ProvidersManager按[logging] remote_base_log_folder的 scheme 分派 provider 的RemoteLogIO类经无参from_config()实例化③ 过渡期的airflow_local_settings.py旧路径将在 Airflow 4.0 移除。airflow.logging_config.load_logging_config被弃用并发出DeprecationWarninghandler 解析改为首次使用时的惰性解析。OpenTelemetry 计时指标改用 Histogram#64207timer/timing 指标不再用 Gauge 记录从而保留 count、sum 与分桶分布。Dag 处理「seconds ago」指标打标签#62487dag_processing.last_run.seconds_ago.{dag_file}成为 legacy 指标新指标dag_processing.last_run.seconds_ago带file_path、bundle_name、file_name标签前两者唯一定位 DAG 文件legacy 指标默认仍发出可用[metrics] legacy_names_on关闭。Browse 菜单新增 Deadlines 页面#67586任何已具备 Dag Runscan_read与menu_access的角色即可访问。7. 3.3.0 新特性与修复要点速览新特性方面除上述核心机制外还包含result装饰器标记 Dag 结果任务#64563、[core] mp_start_method与mp_forkserver_preload多进程启动方式控制#68875、awaiting_input任务状态支撑 Human-in-the-Loop#68028、REST API 的批量 clear/mark/delete#67709/#67948/#67095、按分区日期范围回填分区 DAG#67537、airflow dags clear分区范围重处理#66004、mTLS 与私有 CA 支持#67214、Execution/API 层 CORSallow_credentials可配置#66503等。修复主题包括Kubernetes executor 不可 pickle 的pod_override崩溃#68831、SimpleAuthManager系列安全加固hmac.compare_digest、SameSiteLax、安全随机密码对应 CWE-208 与 #66556/#66502/#66500、executor 事件中external_executor_id的预分配#65594、迁移 0080 deadline 行升级/降级#66016、以及airflow dags clear在非 UTC 分区 timetable 下清错日期等分区相关修复#67717/#68460。四、3.2.x多团队部署与稳定性主题3.2.x 系列在 3.2.0 引入多团队支持multi-team允许在单个 Airflow 部署中运行多个相互隔离的团队同版本还加入 Python 3.14 支持、仅支持 SQLAlchemy 2、任务侧异常与序列化逻辑迁移到airflow.sdk命名空间分别见文档 L1132、L1234、L1308、L1454、L1481 对应段落。3.2.2 的 Significant Changes 体现了 UI 与底层两方面的行为变化SMTP STARTTLS 默认校验证书#65346send_email的 STARTTLS 升级默认使用系统受信 CA 校验服务器证书。面向自签名 SMTP 且需保留旧行为的部署须在airflow.cfg设置email.ssl_context none默认值default未设置时同使用ssl.create_default_context()。该选项此前只作用于SMTP_SSL路径现在同样作用于 STARTTLS。UI 搜索从子串匹配转为前缀匹配#64963/#66015列表接口查询参数由*_pattern全面匹配改为索引友好的*_prefix_patternLIKE term%范围扫描REST API 两种形态并存每个搜索框/过滤 pill 附带可切换回*_pattern子串语义的「Match anywhere」开关。triggerer 竞态与死锁修复 子进程看门狗#64620/#64882/#66412trigger 调用同步 SDK 方法如 Google provider 的safe_to_cancel用到的get_task_states曾导致 triggerer 内部子进程崩溃却仍正常心跳——表面上健康、实际零触发最终令所有 deferred 任务超时。修复方案以「响应多路复用」取代基于锁的串行化每个请求携带唯一 ID响应按 ID 路由回对应调用方。即便竞态修复后阻塞事件循环的 trigger 仍可能让 triggerer 看似健康因此新增配置[triggerer] runner_health_check_threshold默认 30 秒子进程静默超过阈值父进程即停止更新心跳让 scheduler 检测到挂起并重新分配 trigger设为0可关闭看门狗。allowed_deserialization_classes_regexp改为整串匹配#66499模式改用re.fullmatch()而非re.match()防止airflow\.models\.Variable同时放行airflow.models.Variable_Malicious这类前缀名。默认值为空开箱部署不受影响依赖前缀语义如用airflow\.models\.表示「其下任意类」的部署需补.*。自定义 DeadlineReference 需注册#66737必须通过AirflowPlugin新的deadline_references属性注册否则反序列化时报DeadlineReferenceNotRegistered。3.2.x 其他修复亮点包括LocalExecutor未释放文件描述符锁导致的内存泄漏#65121、macOS 上任务执行改用forkexec修复SIGSEGV#64874、ti_update_state的FOR UPDATE死锁#67246、调度器对verify_integrity中StaleDataError的兜底#64503、API 层默认拒绝策略#66505以及「两 token 机制」防止任务在 executor 队列等待期间 token 过期#60108。五、3.1 与 3.0为 3.3 铺路的架构变革3.1.x 的关键主题Human-in-the-LoopHITL将人工参与步骤嵌入 DAG 执行见文档 L2385教程位于 airflow-core/docs/tutorial3.3.0 进一步为其新增awaiting_input状态与专门 UI。Task SDK 与 Airflow Core 进一步解耦推进任务运行时与调度内核的边界划分。全面的 i18n 支持React UI 引入多语言框架3.3.1 中文zh-CN等翻译持续补齐。现代插件架构与 React 组件集成Calendar、Gantt 等 UI 视图重做。streaming wait API允许应用以流式方式等待 DAG run 直至完成后续 3.3.0 为 wait 端点加入结果返回与稳定排序。运行时升级为 structlog3.1.0 要求 Python 3.10-3.13。3.0.x 的关键主题3.0 被文档描述为自 2.0 以来变更最显著的发布L3439 起包括面向服务的架构任务可经新的 Task Execution API 在传统运行环境之外的节点远程执行airflow.sdk命名空间集中暴露 DAG 编写核心接口形成稳定的公开 APIEdge Executor 正式可用GA、原生 UI/REST 的 backfill 支持、DAG 版本化DAG 结构变化产生新版本配合后续 bundle 版本机制React FastAPI 的全新 UI基于 Asset 的数据感知/事件驱动调度成为一等公民移除遗留schedule_interval与timetable参数改用统一调度声明新 DAG 默认catchup_by_default False不再支持逻辑日期在未来的 DagRun 触发回调行为澄清如on_success_callback语义、DAG 处理器独立进程化、按 key 拉取 XCom 必须显式task_ids等一致性收口。六、把发布说明落到你的升级动作上综合上述各版本「Significant Changes」可提炼出适用于本仓库当前状态以 3.3.1 为最新的四条升级行动建议排定组件升级顺序处理 pandas 3 与 DataFrame XCom 兼容性时先升级全部组件尤其 worker到 3.3.1再引入 pandas 3同时评估读取方 pandas 版本对dtype/空值语义的影响。核对配置默认值变化email.ssl_context的证书校验、[core] allowed_deserialization_classes_regexp的 fullmatch 语义、[triggerer] runner_health_check_threshold看门狗均属于默认行为收紧项需在测试环境复跑关键告警与 deferred 任务路径。所有配置项的权威模式与默认值以 airflow-core/src/airflow/config_templates/config.yml 为准解析逻辑位于 airflow-core/src/airflow/config。处理 2.x→3.x 升级残留若升级后出现Requested bundle dags-folder is not configured.先确认已运行 3.3.1其启动回填会依据文件路径修复 bundle 归属必要时执行airflow dags reserialize立即触发重解析。变更对外契约REST API 查询参数*_prefix_pattern、provider 示例 DAG 的bundle_name、敏感配置的团队级脱敏均会影响既有客户端与脚本发布前应回归验证。各功能更详尽的操作示例分别位于 assets.rst、task-and-asset-state-store.rst、dag-bundles.rst 与 language-sdks/index.rst核心示例代码集中在 airflow-core/src/airflow/example_dags官方单元与集成测试位于 airflow-core/tests。如需回溯更早版本2.5~2.9建议直接按文档开头提示查阅按版本归档的文档而非本文件的历史段落。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 7:23:19 · 阅读 1.2k Apache Airflow 3.3.x 与 3.x 系列发布说明全解读：从版本演进、重大变更到升级实操
Apache Airflow 3.3.x 与 3.x 系列发布说明全解读从版本演进、重大变更到升级实操【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 官方发布说明文档 RELEASE_NOTES.rst 记录了从 2.5.0 到 3.3.1 共数十个版本的完整演进脉络涵盖重大行为变更、新特性、Bug 修复、文档更新四类条目。本文将聚焦于当前 3.3.x 主版本线的重大变更Significant Changes逐一还原其技术背景、配置项与迁移影响并结合本仓库 airflow-core/src/airflow、task-sdk/src 的源码实现给出可验证依据。读完本文你将能快速判断每次升级对你现有 DAG、XCom、调度行为与配置的影响掌握诸如 DataFrame XCom 兼容性、Asset 分区调度、任务/资产状态存储等新机制的落地要点。一、发布说明的结构与版本覆盖该文档是 Apache Airflow 通过 towncrier 从各版本 newsfragment见 airflow-core/newsfragments、chart/newsfragments聚合生成的发行说明文件开头明确提示「旧版本的说明可在按版本归档的文档中查看」。每个版本条目按统一模板组织为Significant Changes需要用户感知的重大行为变更、弃用与迁移指引是本篇解读的重点New Features / Bug Fixes新能力与缺陷修复的逐条清单Miscellaneous内部重构、性能优化、UI 打磨Doc Only Changes纯文档修正含多语言 UI 翻译补齐如zh-CN、zh-TW、ko等。文档覆盖的版本时间轴如下均为文档标注的发布日期版本发布日期系列主题3.3.12026-08-123.3.0 的修复与兼容性收尾pandas 3、bundle 迁移回填3.3.02026-07-06Asset 分区深化、任务/资产状态存储、可插拔重试策略、Java/Go 语言 SDK3.2.2 / 3.2.12026-05-29 / 2026-04-213.2.0 稳定性修复、triggerer 看门狗3.2.02026-04-07多团队multi-team、Python 3.14、仅支持 SQLAlchemy 23.1.x2025-09 ~ 2026-03HITL、Task SDK 解耦、i18n、React 插件、streaming wait API、structlog3.0.x2025-04 ~ 2025-08面向服务的架构、Edge Executor、DAG 版本化、React/FastAPI UI、基于 Asset 的调度2.10/2.112024-08 ~ 2026-033.x 演进前的 2.x 维护线二、Airflow 3.3.1围绕 3.3.0 的兼容性与稳健性收尾3.3.12026-08-12是当前文件中的最新版本其 Significant Changes 包含三项需要部署方主动评估的内容。1. pandas 3 改变了 DataFrame XCom 的存储与读取方式#71169pandas 3 将公开类移入pandas命名空间DataFrame 的限定名从pandas.core.frame.DataFrame变为pandas.DataFrame。由于 XCom 会把该名称与序列化值一并写入元数据库写入的限定名取决于推送方组件所用的 pandas 版本。Airflow 注册了两种名称因此任一 pandas 版本写入的 DataFrame XCom 均可被另一版本读取——无需改配置存量 XCom 保持可读。但文档明确给出了三条升级纪律先在全部组件尤其 worker上升级到本版本再让任一组件接触 pandas 3。旧组件拉取 pandas 3 写入的 DataFrame XCom 会直接失败报错为ImportError: pandas.DataFrame was not found in allow list for deserialization imports. To allow it, add it to allowed_deserialization_classes in the configuration文档特别提醒报错信息指向配置但 allow list 并非原因修改配置无效数据行并未损坏升级读取方后即可恢复。降级对这些 XCom 是单向门回滚到不支持该变更的版本会使 pandas 3 期间写入的 DataFrame XCom 无法读取直到再次升级。审查依赖dtypes的下游代码读取到的 DataFrame 外观由读取方的 pandas 版本决定。pandas 3 下字符串列返回str而非object缺失值返回nan而非None。按dtype object分支、用is None判断单元格、或用DataFrame.equals()与参照帧比较的代码在升级后可能行为不同。2. 修复 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.。3.3.1 让DagFileProcessorManager在启动时执行一次性的 best-effort 回填依据文件路径把受影响的 Dag 路由到正确的 bundle无法匹配的 Dag 会在下一次成功解析时自愈也可执行airflow dags reserialize强制立即生效。3. 敏感配置项在团队作用域下被正确隐藏#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 团队段不支持解析这些条目因此连命令串/密钥路径也不再展示非团队配置不受影响display_sensitiveTrue仍返回真实值。相关实现与解析器位于 airflow-core/src/airflow/config配置模式的权威定义在 airflow-core/src/airflow/config_templates/config.yml。4. 值得关注的 Bug 修复方向3.3.1 修复量较大按主题归类便于你对照排查调度与任务生命周期defer 任务状态无法恢复时改为失败而非卡死#71183TriggerDagRunOperator收到 404 时不再跳过回调#71083heartbeat 超时重试不再误触发on_failure_callback#69824deferable 任务经TaskFailedEvent失败时尊重 retries#71163none_failed_min_one_success不再跳过 mapped task group#70318。Triggerer清理未使用 trigger 提速以避免崩溃#70668json_logs开启时的 CrashLoopBackOff 修复#70669任务-worker 通信死锁可检测并浮出#70744。数据库与 API资产监听器大扇出导致的锁竞争/语句超时修复#71065SQLite 回填创建锁冲突返回 503#69659空回填窗口返回 422 且不再遗留孤儿行#69367PostgreSQL 14 的 Dag run 时长统计崩溃修复#70964。安全与脱敏JSON 列表中的敏感Variable值、审计日志中批量更新的密钥、嵌套在 list/tuple/set 中的敏感值均被正确掩码#71069/#71043/#70189KubernetesPodOperator的 Rendered Templates 视图掩码修复#70756重定向校验拒绝畸形 URL 防 open-redirect#70515。UIDags 列表组合过滤 500、任务日志滚动选中被清除、Clear Task 对话框原文翻译键等问题#71371/#71200/#71240。三、Airflow 3.3.0分区、状态存储与多语言任务执行的里程碑3.3.02026-07-06是当前文档中特性最集中的一次发布共有六个 Significant Changes 板块。1. Asset Partitioning上游事件到下游分区运行的大规模扇出承接 3.2.0 引入的 asset partitioning3.3.0 显著扩展了「单个上游 asset 事件扇出到多个下游分区 DagRun」的能力新增分区映射器partition mapper组合RollupMapper多对一聚合将多个上游分区事件聚合成下游运行实现类见 airflow-core/src/airflow/partition_mappers/base.pyFanOutMapper一对多扇出将一个事件拆到多个下游键实现类见 airflow-core/src/airflow/partition_mappers/temporal.pyFixedKeyMapperSegmentWindow分类categorical滚动聚合见 airflow-core/src/airflow/partition_mappers/fixed_key.py 与 airflow-core/src/airflow/partition_mappers/window.py。这些映射器与时间窗口day/week/month/quarter/year可向前或向后扇出以及wait_policyWaitForAll()或MinimumCount(n)组合决定分区运行何时触发。每个上游事件的总扇出量由新增配置[scheduler] partition_mapper_max_downstream_keys限定且每个 mapper 可单独覆盖该上限max_fan_out。配置项定义 airflow-core/src/airflow/config_templates/config.yml默认 1000容量检查的强制执行在 airflow-core/src/airflow/assets/manager.py完整的组合写法可参考官方示例 DAG airflow-core/src/airflow/example_dags/example_asset_partition.py例如RollupMapper(upstream_mapperFixedKeyMapper(all_regions), windowSegmentWindow([us,eu,apac]))的分类滚动、FanOutMapper的一对多时间扇出约 L317-L490。3.3.0 还引入PartitionedAtRuntimetimetable允许 DAG 声明其分区键在运行启动时分配而非从上游事件映射。此外把上游partition_key暴露到triggering_asset_events与dag_run.consumed_asset_eventsAIP-76。详细用法见 assets.rst。2. Task and Asset State StoreAIP-1033.3.0 为任务与资产提供了一等公民的状态存储任务可通过新的task_state_store访问器持久化跨重试、跨运行的任意键值状态资产经asset_state_store携带自身状态两者均可从 Task SDK 使用状态默认保存在元数据库中也可通过[workers] state_store_backend配置自定义的 worker 侧后端配置项见 airflow-core/src/airflow/config_templates/config.yml支持按 key 设置保留期并周期性垃圾回收可选clear_on_success在成功后清空提供 Core API 与 Execution API 双端管理端点并支持按名称/URI 访问、AssetUriRef、Pydantic 模型的序列化注册等SDK 侧访问器实现在 task-sdk/src/airflow/sdk例如上下文对象 task-sdk/src/airflow/sdk/definitions/context.py 中暴露相关 accessor 的实现get()还新增了default参数以简化读取。使用文档见 core-concepts/task-and-asset-state-store.rst 与部署清理相关章节 administration-and-deployment/task-and-asset-state-store-cleanup.rst。3. Pluggable Retry PoliciesAIP-105任务重试行为可插拔化除固定retries计数外可挂载自定义重试策略由策略决定「是否重试、何时重试」从而支持诸如仅对特定异常重试、按自定义逻辑退避等场景。实现与序列化位于 task-sdk/src/airflow/sdk 的 retry 相关模块注意 3.3.0 的 Bug 修复中也提到retry_policy被序列化时应避免触发新 Dag 版本生成#69315且重试策略覆盖需持久化到任务实例历史#69241——这两点在 3.3.0 内已被修复。4. Language Task SDKCoordinator 层与 Java/Go 实现AIP-1083.3.0 新增Coordinator 层单个任务可用非 Python 语言实现而 DAG 与其调度仍留在 Python。在 DAG 中通过task.stub(queue...)声明任务worker 将其路由到配置好的 coordinatorJVM 语言用JavaCoordinatorGo 等自包含原生二进制用ExecutableCoordinator由 coordinator 在对应语言运行时中执行任务并借 Execution API 代理 Variables、Connections、XCom。文档以 warning 形式明确Coordinator 层与 Java/Go SDK 在 3.3.0 中仍属实验性可能随用户反馈变化。文档入口language-sdks/index.rstJava SDK 仓库源码位于 java-sdkGo SDK 位于 go-sdk两目录均包含 example 与完整实现。5. Dag bundle 版本clear、rerun 与 backfill 时的版本选择#63884新增rerun_with_latest_version设置控制被 clear、rerun 或 backfill 的 DagRun 是使用最新 bundle 版本还是沿用初次运行时的版本。解析优先级为显式请求参数/CLI 标志 → DAG 级rerun_with_latest_version→[core] rerun_with_latest_version→ 兜底默认clear/rerun 为Falsebackfill 为True以保持历史行为。背景是2.x 总是用最新代码重跑3.x 引入 bundle 版本化后默认沿用原版本此设置把选择权交还给用户。同样在 3.3.0TriggerDagRunOperator的 rerun 也遵循该设置#67273。完整说明见 dag-bundles.rst。6. 其余值得注意的平台级变化Provider 示例 DAG 成为独立 bundle#66161provider 发行版自带的示例 DAG 改由ProvidersManager发现并注册为独立 bundle命名apache-airflow-providers-distribution-example-dags第三方为distribution-example-dags是否注册仍受[core] load_examples控制。按dags-folder过滤的 REST 客户端需改用新 bundle 名DAG 标识符不变。远程日志解析与airflow.logging_config解耦#67056远程 task 日志 handler 的解析移交airflow_shared.logging.factory优先级固定为① 自定义[logging] logging_config_class导出REMOTE_TASK_LOG/DEFAULT_REMOTE_CONN_ID②ProvidersManager按[logging] remote_base_log_folder的 scheme 分派 provider 的RemoteLogIO类经无参from_config()实例化③ 过渡期的airflow_local_settings.py旧路径将在 Airflow 4.0 移除。airflow.logging_config.load_logging_config被弃用并发出DeprecationWarninghandler 解析改为首次使用时的惰性解析。OpenTelemetry 计时指标改用 Histogram#64207timer/timing 指标不再用 Gauge 记录从而保留 count、sum 与分桶分布。Dag 处理「seconds ago」指标打标签#62487dag_processing.last_run.seconds_ago.{dag_file}成为 legacy 指标新指标dag_processing.last_run.seconds_ago带file_path、bundle_name、file_name标签前两者唯一定位 DAG 文件legacy 指标默认仍发出可用[metrics] legacy_names_on关闭。Browse 菜单新增 Deadlines 页面#67586任何已具备 Dag Runscan_read与menu_access的角色即可访问。7. 3.3.0 新特性与修复要点速览新特性方面除上述核心机制外还包含result装饰器标记 Dag 结果任务#64563、[core] mp_start_method与mp_forkserver_preload多进程启动方式控制#68875、awaiting_input任务状态支撑 Human-in-the-Loop#68028、REST API 的批量 clear/mark/delete#67709/#67948/#67095、按分区日期范围回填分区 DAG#67537、airflow dags clear分区范围重处理#66004、mTLS 与私有 CA 支持#67214、Execution/API 层 CORSallow_credentials可配置#66503等。修复主题包括Kubernetes executor 不可 pickle 的pod_override崩溃#68831、SimpleAuthManager系列安全加固hmac.compare_digest、SameSiteLax、安全随机密码对应 CWE-208 与 #66556/#66502/#66500、executor 事件中external_executor_id的预分配#65594、迁移 0080 deadline 行升级/降级#66016、以及airflow dags clear在非 UTC 分区 timetable 下清错日期等分区相关修复#67717/#68460。四、3.2.x多团队部署与稳定性主题3.2.x 系列在 3.2.0 引入多团队支持multi-team允许在单个 Airflow 部署中运行多个相互隔离的团队同版本还加入 Python 3.14 支持、仅支持 SQLAlchemy 2、任务侧异常与序列化逻辑迁移到airflow.sdk命名空间分别见文档 L1132、L1234、L1308、L1454、L1481 对应段落。3.2.2 的 Significant Changes 体现了 UI 与底层两方面的行为变化SMTP STARTTLS 默认校验证书#65346send_email的 STARTTLS 升级默认使用系统受信 CA 校验服务器证书。面向自签名 SMTP 且需保留旧行为的部署须在airflow.cfg设置email.ssl_context none默认值default未设置时同使用ssl.create_default_context()。该选项此前只作用于SMTP_SSL路径现在同样作用于 STARTTLS。UI 搜索从子串匹配转为前缀匹配#64963/#66015列表接口查询参数由*_pattern全面匹配改为索引友好的*_prefix_patternLIKE term%范围扫描REST API 两种形态并存每个搜索框/过滤 pill 附带可切换回*_pattern子串语义的「Match anywhere」开关。triggerer 竞态与死锁修复 子进程看门狗#64620/#64882/#66412trigger 调用同步 SDK 方法如 Google provider 的safe_to_cancel用到的get_task_states曾导致 triggerer 内部子进程崩溃却仍正常心跳——表面上健康、实际零触发最终令所有 deferred 任务超时。修复方案以「响应多路复用」取代基于锁的串行化每个请求携带唯一 ID响应按 ID 路由回对应调用方。即便竞态修复后阻塞事件循环的 trigger 仍可能让 triggerer 看似健康因此新增配置[triggerer] runner_health_check_threshold默认 30 秒子进程静默超过阈值父进程即停止更新心跳让 scheduler 检测到挂起并重新分配 trigger设为0可关闭看门狗。allowed_deserialization_classes_regexp改为整串匹配#66499模式改用re.fullmatch()而非re.match()防止airflow\.models\.Variable同时放行airflow.models.Variable_Malicious这类前缀名。默认值为空开箱部署不受影响依赖前缀语义如用airflow\.models\.表示「其下任意类」的部署需补.*。自定义 DeadlineReference 需注册#66737必须通过AirflowPlugin新的deadline_references属性注册否则反序列化时报DeadlineReferenceNotRegistered。3.2.x 其他修复亮点包括LocalExecutor未释放文件描述符锁导致的内存泄漏#65121、macOS 上任务执行改用forkexec修复SIGSEGV#64874、ti_update_state的FOR UPDATE死锁#67246、调度器对verify_integrity中StaleDataError的兜底#64503、API 层默认拒绝策略#66505以及「两 token 机制」防止任务在 executor 队列等待期间 token 过期#60108。五、3.1 与 3.0为 3.3 铺路的架构变革3.1.x 的关键主题Human-in-the-LoopHITL将人工参与步骤嵌入 DAG 执行见文档 L2385教程位于 airflow-core/docs/tutorial3.3.0 进一步为其新增awaiting_input状态与专门 UI。Task SDK 与 Airflow Core 进一步解耦推进任务运行时与调度内核的边界划分。全面的 i18n 支持React UI 引入多语言框架3.3.1 中文zh-CN等翻译持续补齐。现代插件架构与 React 组件集成Calendar、Gantt 等 UI 视图重做。streaming wait API允许应用以流式方式等待 DAG run 直至完成后续 3.3.0 为 wait 端点加入结果返回与稳定排序。运行时升级为 structlog3.1.0 要求 Python 3.10-3.13。3.0.x 的关键主题3.0 被文档描述为自 2.0 以来变更最显著的发布L3439 起包括面向服务的架构任务可经新的 Task Execution API 在传统运行环境之外的节点远程执行airflow.sdk命名空间集中暴露 DAG 编写核心接口形成稳定的公开 APIEdge Executor 正式可用GA、原生 UI/REST 的 backfill 支持、DAG 版本化DAG 结构变化产生新版本配合后续 bundle 版本机制React FastAPI 的全新 UI基于 Asset 的数据感知/事件驱动调度成为一等公民移除遗留schedule_interval与timetable参数改用统一调度声明新 DAG 默认catchup_by_default False不再支持逻辑日期在未来的 DagRun 触发回调行为澄清如on_success_callback语义、DAG 处理器独立进程化、按 key 拉取 XCom 必须显式task_ids等一致性收口。六、把发布说明落到你的升级动作上综合上述各版本「Significant Changes」可提炼出适用于本仓库当前状态以 3.3.1 为最新的四条升级行动建议排定组件升级顺序处理 pandas 3 与 DataFrame XCom 兼容性时先升级全部组件尤其 worker到 3.3.1再引入 pandas 3同时评估读取方 pandas 版本对dtype/空值语义的影响。核对配置默认值变化email.ssl_context的证书校验、[core] allowed_deserialization_classes_regexp的 fullmatch 语义、[triggerer] runner_health_check_threshold看门狗均属于默认行为收紧项需在测试环境复跑关键告警与 deferred 任务路径。所有配置项的权威模式与默认值以 airflow-core/src/airflow/config_templates/config.yml 为准解析逻辑位于 airflow-core/src/airflow/config。处理 2.x→3.x 升级残留若升级后出现Requested bundle dags-folder is not configured.先确认已运行 3.3.1其启动回填会依据文件路径修复 bundle 归属必要时执行airflow dags reserialize立即触发重解析。变更对外契约REST API 查询参数*_prefix_pattern、provider 示例 DAG 的bundle_name、敏感配置的团队级脱敏均会影响既有客户端与脚本发布前应回归验证。各功能更详尽的操作示例分别位于 assets.rst、task-and-asset-state-store.rst、dag-bundles.rst 与 language-sdks/index.rst核心示例代码集中在 airflow-core/src/airflow/example_dags官方单元与集成测试位于 airflow-core/tests。如需回溯更早版本2.5~2.9建议直接按文档开头提示查阅按版本归档的文档而非本文件的历史段落。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考