Apache Airflow Alibaba 提供者包演进全解从 1.0.0 到 3.4.0 的 changelog 深度剖析【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow本篇技术指南以apache-airflow-providers-alibaba的官方 changelog.rst 为绝对主线逐版本还原 Alibaba 提供者包从 1.0.0 到 3.4.0 的功能演进、破坏性变更、远程日志机制重构与依赖升级脉络。读者读完将掌握OSS 远程日志OSSRemoteLogIO/OSSTaskHandler的底层工作流、MaxCompute 与 AnalyticDB Spark 算子的接入方式、各版本对应的 Airflow/Python 最低版本要求以及 3.0.0 破坏性变更的迁移要点——每一条结论均可在当前仓库的源码、测试与配置文件中得到印证。changelog 的定位与阅读方法在 Apache Airflow 的提供者provider体系中每个提供者包都有一份独立维护的changelog.rst它记录了该包从首个版本至今的每一次发布内容。与核心 Airflow 的发布说明不同provider changelog 具有以下特点由 release manager 半自动维护文档头部明确标注 The changelog is updated and maintained semi-automatically by release manager只收录面向用户的Features / Bug Fixes / Breaking changes / Misc条目而形如Fix doc issues found with recent moves、Prepare docs for ...之类的内部整理工作会被移入 Below changes are excluded from the changelog 注释区版本号遵循语义化版本且与 provider.yaml 中versions列表一一对应——当前仓库中该包最新版本为 3.4.0。从 provider.yaml 可以看到本提供者包的定位是 Alibaba Cloud integration覆盖三大云产品Alibaba Cloud OSS对象存储、Alibaba Cloud AnalyticDB SparkADB 湖仓 Spark 任务、Alibaba Cloud MaxCompute原 ODPS 大数据计算服务。changelog 中绝大多数条目都可以归入这三条功能线的演进。安装、依赖与版本兼容性基线在深入版本历史之前先明确当前3.4.0版本的安装与依赖要求这决定了你可以在什么环境下使用本包安装方式在已有 Airflow 环境上执行pip install apache-airflow-providers-alibaba最低 Airflow 版本2.11.0支持的 Python 版本3.10、3.11、3.12、3.13、3.14关键第三方依赖见 README.rst 与 pyproject.tomlapache-airflow-providers-common-compat1.13.0提供 SDK 兼容层alibabacloud-oss-v21.2.0OSS 官方 Python SDK v2alibabacloud_adb202112011.0.0alibabacloud_tea_openapi0.3.7AnalyticDB Spark OpenAPIpyodps0.12.2.2Python3.13或0.12.5.1Python3.13MaxCompute 客户端。这一依赖基线是多年版本迭代的结果也是下文 changelog 分析的核心线索几乎每一次主/次版本升级都伴随着最低 Airflow 版本或 Python 版本基线的抬升。从 changelog.rst 可以梳理出完整的时间线版本最低 Airflow 版本备注1.0.0—初始版本2.0.02.2引入破坏性变更2.2.0 / 2.4.0 / 2.6.0 / 2.7.0 / 2.8.0 / 2.9.0 / 3.0.0 / 3.1.0 / 3.3.02.3 / 2.4 / 2.5 / 2.6 / 2.7 / 2.8 / 2.9 / 2.10 / 2.11逐版本抬升2.4.1—移除 Python 3.7 支持3.2.1—移除 Python 3.9 支持3.3.6—新增 Python 3.14 支持版本基线抬升的政策依据是 Apache Airflow 官方的 provider 支持策略changelog 中 3.0.0/3.1.0/3.3.0 的 note 均有引用说明即社区托管 provider 只保证对有限旧版本 Airflow 的兼容。这意味着升级本提供者包时必须同步关注 Airflow 核心版本是否满足要求。功能演进主线一OSS 远程日志体系1.1.0 → 3.4.0OSS 远程日志是 changelog 中出现频次最高、迭代最持续的一条功能线。它解决的核心问题是在分布式/容器化部署中TaskInstance 日志散落在各 worker 节点本地一旦节点销毁日志即丢失将日志上传到 OSS 后Web UI 可以跨节点统一读取。诞生与早期形态1.1.0、2.0.01.1.0Add oss_task_handler into alibaba-provider and enable remote logging to OSS——首次引入OSSTaskHandler并把远程日志能力接入 Alibaba 提供者包2.0.0SSL Bucket, Light Logic Refactor and Docstring Update同时Apply per-run log templates to log handlers按运行应用日志模板2.1.0Auto tail file logs in Web UI——Web UI 自动追踪日志文件尾部对应源码中_read方法的metadata参数注释明确写着 can be used for steaming log reading and auto-tailing2.3.0Support deleting the local log files when using remote logging——上传完成后可删除本地日志副本对应配置项[logging] delete_local_logs与源码中delete_local_copy字段。向 RemoteLogIO 抽象迁移3.0.x → 3.4.0从 3.0.0 开始Airflow 核心引入了统一的远程日志 IO 抽象Alibaba 提供者随之完成了从专用 TaskHandler到通用RemoteLogIO 轻量 handler的架构迁移3.0.2Add ti to the RemoteLogIO read and upload methods与Rework remote task log handling for the structlog era——适配核心的 structlog 日志时代3.2.3[OSSTaskHandler, ...] supports log file size handling——OSSTaskHandler支持日志文件大小处理对应构造参数max_bytes、backup_count3.3.6Pass relative path to oss_write in OSSRemoteLogIO.upload——修复上传时传递相对路径的 bug单元测试 test_oss_task_handler.py 明确验证upload 只把相对路径传给 oss_write而不是完整的 OSS URI3.3.8Fix support configurable endpoint and fix task handler log reads——支持可配置 endpoint修复任务日志读取3.3.9Fix remote-log providers not satisfying RemoteLogIO upload contract——修复不满足 RemoteLogIO 上传契约的问题3.4.0Add OSSRemoteLogIO.from_config and register oss remote logging scheme——新增OSSRemoteLogIO.from_config()工厂方法并注册oss://远程日志 scheme标志着该提供者完全接入 Airflow 核心的按 scheme 分发远程日志处理器机制。源码级原理OSSRemoteLogIO 与 OSSTaskHandler当前实现位于 oss_task_handler.py由两个核心类构成OSSRemoteLogIO第 40-182 行是一个attrs.define(kw_onlyTrue)的数据类负责纯 IO 操作from_config()工厂第 48-71 行从[logging]配置段读取base_log_folder、remote_base_log_folder、delete_local_logs并通过conf.getjson(logging, remote_task_handler_kwargs)读取扩展参数——关键技巧是它用inspect.signature(FileTaskHandler.__init__)过滤出属于 FileTaskHandler 的参数只把剩余参数作为 IO 参数传入upload(path, ti)第 73-88 行读取本地日志文件全文调用oss_write()上传若delete_local_copy为真则删除本地目录oss_write()第 155-182 行追加式写入——若远程对象已存在先head_key拿到content_length作为写入位置pos再调用OSSHook.append_string(bucket, log, key, pos)从该位置追加appendFalse时则从位置 0 覆盖写read()/oss_read()/oss_log_exists()检查远程对象存在性hook.key_exist并读取内容hook.read_key读取失败时可返回错误字符串return_errorTruehook缓存属性第 100-113 行使用配置项[logging] REMOTE_LOG_CONN_ID指定的连接 ID 构造OSSHook。OSSTaskHandler第 185-281 行继承FileTaskHandler是 Airflow 日志系统实际挂载的 handlerset_context(ti)渲染出log_relative_pathdag_id.../run_id.../task_id.../attemptN.log风格并在upload_on_close时先清空本地文件避免重试场景如 rescheduled sensor上传重复数据close()调用io.upload()上传并用closed标志防止logging.shutdown触发重复上传_read()先检查 OSS 远程对象存在则直接返回远程日志失败也返回错误信息而非回退本地不存在才回退到super()._read()读本地。单元测试 test_oss_task_handler.py 对上述行为做了系统验证其中test_resolve_remote_task_log_uses_provider_dispatch_not_local_settings第 111-126 行直接断言配置remote_base_log_foldeross://...时核心的resolve_remote_task_log会通过ProvidersManager.remote_logging_handler_by_scheme(oss)分发到OSSRemoteLogIO而不再走旧版airflow_local_settings.py的发现逻辑。实操启用 OSS 远程日志官方配置指南见 oss-task-handler.rst在airflow.cfg中配置如下[logging] # Airflow can store logs remotely in Alibaba OSS. Users must supply a remote # location URL (starting with either oss://...) and an Airflow connection # id that provides access to the storage location. remote_logging True remote_base_log_folder oss://my-bucket/path/to/logs remote_log_conn_id oss_default关键前提与说明远程日志读写依赖一个已正确配置的 Airflow 连接文档明确警告If you dont have a connection properly setup, this process will fail上述示例中 Airflow 会尝试使用OSSHook(oss_default)连接类型oss默认连接名即oss_default见 oss.pyOSS 连接的凭据从连接extra中读取OSSHook.get_credential()要求extra中包含auth_type: AK、access_key_id、access_key_secretget_default_region()要求包含regionendpoint 可通过extra.endpoint覆盖默认oss-{region}.aliyuncs.com见 oss.py结合delete_local_logs配置可在上传成功后清理本地日志副本节省节点磁盘。功能演进主线二MaxCompute 接入与连接抽象3.2.0 → 3.3.xMaxCompute原 ODPS支持是 changelog 中另一条完整的功能线3.2.0Add MaxComputeSQLOperator, MaxComputeHook and AlibabaBaseHook to Alibaba Provider——一次性引入MaxComputeSQLOperator、MaxComputeHook和基类AlibabaBaseHook3.2.0同版本 Bug FixesFix MaxComputeSQLOperator Argument修复算子参数、Fix inconsistent conn_name_attr统一连接属性名3.3.4Define TaskInstanceKey in task-sdk to support client server separation——适配 task-sdk 的客户端/服务端分离3.3.7Bump pyodps for python3.13——为 Python 3.13 升级 pyodps 依赖对应 pyproject 中pyodps0.12.5.1; python_version 3.13的条件约束。源码级原理MaxComputeHook当前实现位于 maxcompute.pyMaxComputeHook继承自AlibabaBaseHook连接类型为maxcompute默认连接名maxcompute_default核心装饰器fallback_to_default_project_endpoint第 34-61 行当调用方法未显式传project/endpoint时自动回退到连接extra中配置的值若两者都缺失则抛出MaxComputeConfigurationException提示 must be passed either as keyword parameter or as extra in the MaxCompute connection definition连接 UI 元数据在 provider.yaml 中定义maxcompute连接类型隐藏了 host/schema/login/password/port/extra 等默认字段转而暴露access_key_id、access_key_secret、project、endpoint四个自定义字段——这与 3.3.5 的Migrate alibaba connection UI metadata to YAML条目相呼应。功能演进主线三AnalyticDB Spark2.5.0 → 3.0.02.5.0Add Alibaba Cloud AnalyticDB Spark Support——首次加入 ADB Spark 支持2.6.0Consolidate hook management in AnalyticDBSparkSensor与Consolidate hook management in AnalyticDBSparkBaseOperator、Deprecate get_hook in OSSKeySensor and use hook instead——统一算子/传感器中的 hook 管理方式开始废弃get_hook()2.7.2Fix assignment of template field in __init__ in analyticdb_spark.py——修复模板字段赋值3.0.0破坏性变更中明确删除AnalyticDBSparkBaseOperator.get_hook与AnalyticDBSparkSensor.get_hook统一改用self.hook属性。从 provider.yaml 可见当前 ADB Spark 相关的 Python 模块包括operators.analyticdb_spark、sensors.analyticdb_spark与hooks.analyticdb_spark系统测试示例见 example_adb_spark_batch.py 与 example_adb_spark_sql.py。3.0.0 破坏性变更与迁移指南3.0.0 是 changelog 中唯一标注 Breaking changes 的版本也是所有使用者必须关注的一个版本警告所有已废弃的类、参数与特性均已从 alibaba provider 包中移除。具体破坏点Operators移除AnalyticDBSparkBaseOperator.get_hook()方法改用self.hookSensors移除AnalyticDBSparkSensor.get_hook()方法改用self.hook。迁移方式十分直接凡是调用operator.get_hook()或sensor.get_hook()获取 hook 的 DAG 代码都需要改为直接访问self.hook或通过operator.hook属性。这一变更的铺垫工作早在 2.6.0 就已开始deprecate给了用户充足过渡期。底层依赖与工程治理演进changelog 中有大量条目反映的是提供者包自身的工程化治理虽不直接产生新功能但决定了可维护性与运行稳定性SDK 迁移3.3.7Replace oss2 with alibabacloud-oss-v2——OSS 客户端从社区版oss2切换到阿里云官方 SDK v2当前 oss.py 已使用alibabacloud_oss_v2客户端由oss.config.load_default()构建Airflow 3 兼容适配3.2.2Move Base imports to version_compat for Alibaba provider Airflow 3.0 compatibility、3.2.1Move BaseHook implementation to task SDK、3.2.1Replace models.BaseOperator to Task SDK one、3.2.1Use BaseSensorOperator from task sdk、3.3.3Migrate alibaba provider to use airflow.sdk.configuration.conf——一系列迁移把 Base 类、配置访问都指向了 task-sdk / common.compat 兼容层这与 README 中要求apache-airflow-providers-common-compat1.13.0直接对应Python 版本策略2.4.1 移除 Python 3.7、3.2.1 移除 Python 3.9、3.3.6 新增 Python 3.14——逐步收缩到当前的 3.10-3.14代码质量3.3.5Migrate alibaba connection UI metadata to YAML连接 UI 元数据 YAML 化、3.2.5Convert all airflow distributions to be compliant with ASF requirementsASF 合规、各版本的 mypy/ruff 清理、2.5.3respect soft_fail argument when exception is raised传感器软失败参数修复等。版本总览速查表基于 changelog.rst 全文整理的关键版本里程碑版本类型核心内容1.0.0初始版本提供者包诞生1.1.0Feature引入oss_task_handler支持 OSS 远程日志2.0.0Breaking最低 Airflow 2.2SSL Bucket 支持日志模板改造2.1.0FeatureWeb UI 日志自动 tail2.3.0Feature远程日志上传后支持删除本地副本2.5.0Feature新增 AnalyticDB Spark 支持2.6.0Misc统一 hook 管理deprecateget_hook3.0.0Breaking移除全部get_hook最低 Airflow 2.93.2.0Feature新增MaxComputeSQLOperator、MaxComputeHook、AlibabaBaseHook3.3.0Misc最低 Airflow 2.113.3.6Bug FixOSS 上传相对路径修复Python 3.14 支持3.3.7Miscoss2→alibabacloud-oss-v2迁移pyodps 升级3.3.9Bug Fix修复 RemoteLogIO 上传契约3.4.0FeatureOSSRemoteLogIO.from_config与ossscheme 注册延伸阅读连接类型配置见 connections/alibaba.rstOSS、ADB Spark、MaxCompute、alibaba_cloud四种连接类型与 provider.yaml 中connection-types定义OSS 算子使用指南见 operators/oss.rst覆盖OSSCreateBucketOperator、OSSDeleteBucketOperator、OSSUploadObjectOperator、OSSDownloadObjectOperator、OSSDeleteObjectOperator、OSSDeleteBatchObjectOperator及OSSKeySensor系统测试示例在 example_oss_bucket.py 与 example_oss_object.py单元测试OSSRemoteLogIO/OSSTaskHandler行为验证见 test_oss_task_handler.pyOSS Hook 测试见 test_oss.py提供者包治理与发布策略见 PROVIDERS.rst 与 PROVIDER_RELEASES.rst。综上apache-airflow-providers-alibaba的 changelog 本身就是一部浓缩的架构演进史从单一 OSS 远程日志 handler到覆盖 OSS / MaxCompute / AnalyticDB Spark 三大云产品的完整提供者从依赖 Airflow 2.x 专用 API到全面迁移至 task-sdk 与common.compat兼容层从oss2到官方 SDK v2。理解这条演进脉络能帮助你在升级版本、排查远程日志异常或迁移到 Airflow 3 时做出更准确的判断。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考