企业官网建设流程全解析

Apache Airflow 3.3.x 与 3.x 系列发布说明全解读：从版本演进、重大变更到升级实操

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow

Apache 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等）。

文档覆盖的版本时间轴如下（均为文档标注的发布日期）：

二、Airflow 3.3.1：围绕 3.3.0 的兼容性与稳健性收尾

3.3.1（2026-08-12）是当前文件中的最新版本，其 Significant Changes 包含三项需要部署方主动评估的内容。

1. pandas 3 改变了 DataFrame XCom 的存储与读取方式（#71169）

pandas 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_name='dags-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 注册为敏感项，因此通过[<team>=<section>]配置段或AIRFLOW__<TEAM>___<SECTION>__<KEY>环境变量设置的团队级覆盖不会被识别为同一选项，从而以明文返回。本版本改为先把团队级拼写解析回基础选项再判定敏感性，行为变化包括：

• AirflowConfigParser.as_dict(display_sensitive=False)、GET /config、GET /config/section/{section}/option/{option}与airflow config list对团队级敏感值一律返回< hidden >；确有需要时使用display_sensitive=True；
• 团队级_cmd/_secret条目原地替换为< hidden >（团队段不支持解析这些条目，因此连命令串/密钥路径也不再展示）；
• 非团队配置不受影响，display_sensitive=True仍返回真实值。

相关实现与解析器位于 airflow-core/src/airflow/config，配置模式的权威定义在 airflow-core/src/airflow/config_templates/config.yml。

4. 值得关注的 Bug 修复方向

3.3.1 修复量较大，按主题归类便于你对照排查：

• 调度与任务生命周期：defer 任务状态无法恢复时改为失败而非卡死（#71183）；TriggerDagRunOperator收到 404 时不再跳过回调（#71083）；heartbeat 超时重试不再误触发on_failure_callback（#69824）；deferable 任务经TaskFailedEvent失败时尊重 retries（#71163）；none_failed_min_one_success不再跳过 mapped task group（#70318）。
• Triggerer：清理未使用 trigger 提速以避免崩溃（#70668）；json_logs开启时的 CrashLoopBackOff 修复（#70669）；任务-worker 通信死锁可检测并浮出（#70744）。
• 数据库与 API：资产监听器大扇出导致的锁竞争/语句超时修复（#71065）；SQLite 回填创建锁冲突返回 503（#69659）；空回填窗口返回 422 且不再遗留孤儿行（#69367）；PostgreSQL 14+ 的 Dag run 时长统计崩溃修复（#70964）。
• 安全与脱敏：JSON 列表中的敏感Variable值、审计日志中批量更新的密钥、嵌套在 list/tuple/set 中的敏感值均被正确掩码（#71069/#71043/#70189）；KubernetesPodOperator的 Rendered Templates 视图掩码修复（#70756）；重定向校验拒绝畸形 URL 防 open-redirect（#70515）。
• UI：Dags 列表组合过滤 500、任务日志滚动选中被清除、Clear Task 对话框原文翻译键等问题（#71371/#71200/#71240）。

三、Airflow 3.3.0：分区、状态存储与多语言任务执行的里程碑

3.3.0（2026-07-06）是当前文档中特性最集中的一次发布，共有六个 Significant Changes 板块。

1. Asset Partitioning：上游事件到下游分区运行的大规模扇出

承接 3.2.0 引入的 asset partitioning，3.3.0 显著扩展了「单个上游 asset 事件扇出到多个下游分区 DagRun」的能力，新增分区映射器（partition mapper）组合：

• RollupMapper：多对一聚合，将多个上游分区事件聚合成下游运行，实现类见 airflow-core/src/airflow/partition_mappers/base.py；
• FanOutMapper：一对多扇出，将一个事件拆到多个下游键，实现类见 airflow-core/src/airflow/partition_mappers/temporal.py；
• FixedKeyMapper+SegmentWindow：分类（categorical）滚动聚合，见 airflow-core/src/airflow/partition_mappers/fixed_key.py 与 airflow-core/src/airflow/partition_mappers/window.py。

这些映射器与时间窗口（day/week/month/quarter/year，可向前或向后扇出）以及wait_policy（WaitForAll()或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_mapper=FixedKeyMapper("all_regions"), window=SegmentWindow(["us","eu","apac"]))的分类滚动、FanOutMapper的一对多时间扇出（约 L317-L490）。

3.3.0 还引入PartitionedAtRuntimetimetable，允许 DAG 声明其分区键在运行启动时分配，而非从上游事件映射。此外把上游partition_key暴露到triggering_asset_events与dag_run.consumed_asset_events（AIP-76）。详细用法见 assets.rst。

2. Task and Asset State Store（AIP-103）

3.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 Policies（AIP-105）

任务重试行为可插拔化：除固定retries计数外，可挂载自定义重试策略，由策略决定「是否重试、何时重试」，从而支持诸如仅对特定异常重试、按自定义逻辑退避等场景。实现与序列化位于 task-sdk/src/airflow/sdk 的 retry 相关模块；注意 3.3.0 的 Bug 修复中也提到，retry_policy被序列化时应避免触发新 Dag 版本生成（#69315），且重试策略覆盖需持久化到任务实例历史（#69241）——这两点在 3.3.0 内已被修复。

4. Language Task SDK：Coordinator 层与 Java/Go 实现（AIP-108）

3.3.0 新增Coordinator 层：单个任务可用非 Python 语言实现，而 DAG 与其调度仍留在 Python。在 DAG 中通过@task.stub(queue=...)声明任务，worker 将其路由到配置好的 coordinator（JVM 语言用JavaCoordinator，Go 等自包含原生二进制用ExecutableCoordinator），由 coordinator 在对应语言运行时中执行任务，并借 Execution API 代理 Variables、Connections、XCom。文档以 warning 形式明确：Coordinator 层与 Java/Go SDK 在 3.3.0 中仍属实验性，可能随用户反馈变化。

• 文档入口：language-sdks/index.rst；
• Java SDK 仓库源码位于 java-sdk，Go 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 为False，backfill 为True，以保持历史行为）。背景是：2.x 总是用最新代码重跑；3.x 引入 bundle 版本化后默认沿用原版本，此设置把选择权交还给用户。同样在 3.3.0，TriggerDagRunOperator的 rerun 也遵循该设置（#67273）。完整说明见 dag-bundles.rst。

6. 其余值得注意的平台级变化

• Provider 示例 DAG 成为独立 bundle（#66161）：provider 发行版自带的示例 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被弃用并发出DeprecationWarning；handler 解析改为首次使用时的惰性解析。
• OpenTelemetry 计时指标改用 Histogram（#64207）：timer/timing 指标不再用 Gauge 记录，从而保留 count、sum 与分桶分布。
• Dag 处理「seconds ago」指标打标签（#62487）：dag_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、SameSite=Lax、安全随机密码，对应 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 默认校验证书（#65346）：send_email的 STARTTLS 升级默认使用系统受信 CA 校验服务器证书。面向自签名 SMTP 且需保留旧行为的部署，须在airflow.cfg设置email.ssl_context = "none"；默认值"default"（未设置时同）使用ssl.create_default_context()。该选项此前只作用于SMTP_SSL路径，现在同样作用于 STARTTLS。
• UI 搜索从子串匹配转为前缀匹配（#64963/#66015）：列表接口查询参数由*_pattern全面匹配改为索引友好的*_prefix_pattern（LIKE 'term%'范围扫描），REST API 两种形态并存；每个搜索框/过滤 pill 附带可切换回*_pattern子串语义的「Match anywhere」开关。
• triggerer 竞态与死锁修复 + 子进程看门狗（#64620/#64882/#66412）：trigger 调用同步 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 上任务执行改用fork+exec修复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-Loop（HITL）：将人工参与步骤嵌入 DAG 执行（见文档 L2385，教程位于 airflow-core/docs/tutorial）；3.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 端点加入结果返回与稳定排序）。
• 运行时升级为 structlog（3.1.0 要求 Python 3.10-3.13）。

3.0.x 的关键主题

3.0 被文档描述为自 2.0 以来变更最显著的发布（L3439 起），包括：

• 面向服务的架构：任务可经新的 Task Execution API 在传统运行环境之外的节点远程执行；
• airflow.sdk命名空间：集中暴露 DAG 编写核心接口，形成稳定的公开 API；
• Edge 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 为最新）的四条升级行动建议：

1. 排定组件升级顺序：处理 pandas 3 与 DataFrame XCom 兼容性时，先升级全部组件（尤其 worker）到 3.3.1+，再引入 pandas 3；同时评估读取方 pandas 版本对dtype/空值语义的影响。
2. 核对配置默认值变化：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。
3. 处理 2.x→3.x 升级残留：若升级后出现Requested bundle 'dags-folder' is not configured.，先确认已运行 3.3.1（其启动回填会依据文件路径修复 bundle 归属），必要时执行airflow dags reserialize立即触发重解析。
4. 变更对外契约：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