Apache Beam 版本演进全览：基于 CHANGES.md 的 2.19～2.59 变更深度解读

• 批处理
• 流处理
• 大数据

Apache Beam 是一个统一的批流一体数据处理编程模型，本仓库（gh_mirrors/beam15/beam）根目录下的 CHANGES.md 是该项目最重要的工程文档之一：它以发布说明（Release Notes）的形式，逐版本记录了从 2.19.0 到 2.59.0（Unreleased）期间 Beam 在 SDK、Runner、I/O 连接器、机器学习、跨语言能力等各个维度的全部重要变更。阅读本文，你可以快速掌握 Beam 各版本的发布节奏、核心能力演进脉络、破坏性变更与迁移要点、已知问题与安全修复，从而在选型、升级和排障时做到心中有数。

一、CHANGES.md 在仓库中的定位与维护机制

CHANGES.md 位于仓库根目录（CHANGES.md），全文 1713 行，覆盖 2020 年 1 月的 2.19.0 至今仍在开发的 2.59.0。它不只是"历史记录"，而是 Apache Beam 社区约定的变更管理入口：

• 从 contributor-docs/committer-guide.md 可以看到，贡献者被要求将值得注意的变更（新特性、向后兼容性变化等）写入 CHANGES.md；
• 从 contributor-docs/release-guide.md 可以看到，发版流程明确规定：在 master 上手动更新 CHANGES.md 新增版本小节、将 Unreleased 改为发布日期、把对应版本内容整理为博客文章等步骤。

每个版本小节采用统一的固定模板，包含以下栏目（这也是阅读该文档的"索引键"）：

值得注意的是，文档头部（L19-L54）保留了模板注释，其中占位符如[#X]、[BEAM-X]、CVE-YYYY-NNNN等是供贡献者填写时参考的格式示例；2.59.0 小节也仍处于未完成状态，这正体现了 CHANGES.md "随开发滚动更新"的工作方式。

二、版本发布节奏与当前状态

从 CHANGES.md 可梳理出 Apache Beam 的发布节奏（频率约为每年 4～6 个版本）：

当前仓库的构建版本与文档完全对应：从 gradle.properties 可见version=2.59.0-SNAPSHOT、sdk_version=2.59.0.dev，并声明了受支持的 Flink 版本（flink_versions=1.15,1.16,1.17,1.18）与 Python 版本（python_versions=3.8,3.9,3.10,3.11,3.12），这些与 CHANGES.md 中逐版本增加 Flink / Python 支持的记录相互印证。

三、SDK 语言与运行时演进

3.1 Python SDK：版本支持曲线

CHANGES.md 完整记录了 Python SDK 支持版本的演进：

• 2.20.0 之前：支持 Python 2 与 3.5；
• 2.24.0：宣布为最后一个支持 Python 2 与 3.5 的版本；
• 2.25.0：正式移除 Python 2 与 3.5 支持，并明确"Pandas 1.x 是 DataFrame 操作的必要条件"；
• 2.37.0：新增 Python 3.9 支持；
• 2.39.0：宣布 Python 3.6 不再受支持；
• 2.43.0：新增 Python 3.10 支持；
• 2.47.0：新增 Python 3.11 支持；
• 2.49.0：移除 Python 3.7 支持；
• 2.57.0：新增 Python 3.12 支持。

升级提示：若你正在维护 Python 管线，应首先对照此时间线确认自己的 Python 版本仍在支持范围内。从源码结构看，SDK 的实际实现位于 sdks/python/apache_beam，其中的容器构建、依赖声明（如 sdks/python/container）与版本支持声明保持一致。

3.2 Java SDK：运行时与依赖治理

• 2.37.0：Dataflow 支持 Java 17（并注明 Runner V2 状态缓存可能因对象大小估算不准确而出问题、ZetaSql 当时暂不支持）；
• 2.52.0：开始随发布流程发布 Java 21 SDK 容器镜像，Direct Runner 与 Dataflow Runner 支持 Java 21（实验性），其余 Runner 支持状态取决于 Runner 项目；
• 2.46.0：Java SDK 容器基础镜像从已弃用的 OpenJDK 迁移到 Eclipse Temurin（基于 Ubuntu 22.04）；
• 2.52.0：Java core 包中依赖 Avro 的已弃用代码最终移除，强制迁移到beam-sdks-java-extensions-avro（对应仓库目录 sdks/java/extensions）；
• 2.57.0：Jackson Databind 升级到 2.15.4，该版本对解析器施加了缓冲区限制，自定义 PTransform/DoFn 若受影响可参考其提供的缓解方案。

迁移重点：Avro 相关的迁移路径是"导入路径整体替换"——例如org.apache.beam.sdk.coders.AvroCoder改为org.apache.beam.sdk.extensions.avro.coders.AvroCoder（2.46.0 中已给出此指引），这样可在用户代码中独立升级 Avro 版本而不受 Beam core 约束。

3.3 Go SDK：从实验到正式

Go SDK 的成熟是 2.33.0～2.50.0 之间的主线之一：

• 2.33.0：Go SDK 不再是实验性，正式纳入 Beam 发布流程；依赖管理迁移到 Go Modules，引入破坏性变更——go.mod需要改为 requiregithub.com/apache/beam/sdks/v2，所有 import 路径加v2；最低 Go 版本 v1.16；
• 2.40.0：要求 Go 1.18（泛型支持）；
• 2.46.0：要求 Go 1.19，并出现首个原生 Go 实现的便携 Runner —— Prism；
• 2.50.0：要求 Go 1.20，Prism 成为 Go SDK 的默认本地 Runner，取代并弃用 Go Direct Runner；
• 2.57.0：预构建的 Prism 二进制随发布提供，并默认以合成 ProcessingTime 快速执行测试管线（该版本尚不支持"实时"执行）；
• 2.59.0（Unreleased）：最低 Go 版本更新到 1.21，protobuf 包升级。

从仓库结构看，Go SDK 位于 sdks/go，Prism 的实现位于 runners/prism/java（Java 版）与sdks/go/pkg/beam/runners/prism（Go 原生实现），两者共同支撑"便携 Runner 逐变换执行并校验 Coder"的目标。

3.4 容器镜像

• 2.50.0：所有已发布容器镜像变为multi-arch（同时支持 x86 与 ARM），涵盖 Go / Python / Java / TypeScript SDK 容器、Flink job server 容器、Java 与 Python expansion service 容器、Transform service 控制器容器、Spark3 job server 容器；
• 2.55.0：Go SDK 基础容器迁移到 distroless（distroless/base-nossl-debian12），减少易受攻击面；但自定义容器进程若依赖额外工具则可能受影响，需按官方指南重建自定义容器。

四、Runner 生态演进

CHANGES.md 记录了各 Runner 的版本矩阵与能力扩展：

• Flink Runner：2.31.0 支持 Flink 1.13 → 2.38.0 支持 1.14 → 2.47.0 支持 1.16 → 2.56.0 支持 1.17 并移除 1.12/1.13 → 2.57.0 支持 1.18；同时不断移除旧版本（2.30.0 移除 1.8/1.9，2.31.0 移除 1.10，2.39.0 移除 1.11，2.52.0 新增UseDataStreamForBatch选项以支持 DataStream API 执行批作业）。当前仓库 runners/flink 下保留 1.15/1.16/1.17/1.18 各版本的适配源码；
• Spark Runner：2.29.0 正式支持 Spark 3；2.41.0 弃用 Spark 2.4.x；2.46.0 移除 Spark 2 Runner；2.50.0 默认使用 Spark 3.2.2。仓库中 runners/spark/3 即对应 Spark 3 适配；
• Dataflow Runner：2.45.0 起便携 Java 管线、Go 管线、Python 流式与便携批管线强制使用 Runner V2，相关disable_runner_v2等实验开关直接报错；2.54.0 起 Java 批处理管线默认迁移到便携（Runner V2）架构；
• Prism：2.46.0 出现初始实现，2.50.0 成为 Go SDK 默认本地 Runner（详见上文）；
• 其他：2.23.0 引入 Twister2 Runner；2.43.0 提供 Dask Runner 初版；2.39.0 支持 Flink Scala 2.12；2.44.0 新增"渲染管线图"的便携 Runner（python -m apache_beam.runners.render --help）。

升级提示：Flink 版本跨级升级时需按 2.56.0 给出的阶梯策略操作——先把管线升级到对应 Beam 版本（保持原 Flink 版本），再升级 Flink Runner 的目标版本。

五、I/O 连接器矩阵的扩张

CHANGES.md 的 I/Os 栏目记录了大量连接器的新增、能力增强与修复，可按主题归纳：

5.1 新增连接器（按版本）

• 2.58.0：Solace 源（Java，SolaceIO.Read）；
• 2.57.0：BigtableIO 流关闭修复、Feast 特征库 enrichment handler（Python）；
• 2.56.0：通过 Managed I/O 提供 Iceberg 读写（Java）、Avro/Kafka Schema Registry 依赖升级；
• 2.55.0：BigQueryIO / PubSubIO / FileIO / TextIO / AvroIO / BigtableIO / KafkaIO 相继支持bad records 处理；
• 2.53.0：NATS IO（Go）、KafkaIO bad records（Java）、TextIO 跳过多个表头行（Java）、Python GCSIO 迁移到 GCS Client；
• 2.52.0：Beam YAML 稳定版（含初步 IO 集）;
• 2.50.0：Java KafkaIO 支持topicPattern、Cosmos DB Core SQL API 读取、GoogleAdsIO 源；
• 2.49.0：Bigtable Change Streams（JavaBigtableIO.ReadChangeStream）；
• 2.48.0：KinesisIO enhanced fan-out（Java）、GCS rename 与本地文件 copy（Go）、textio.ReadWithFilename / fileio.MatchContinuously（Go）；
• 2.47.0：BigQuery Storage Write API 通过跨语言在 Python 可用、HbaseIO RowMutations 写入、Go fileio 三件套；
• 2.45.0：MongoDB IO（Go）；
• 2.44.0：Bigtable sink（Go）、S3 文件系统（Go）、SingleStoreDB（Java）、Azure Filesystem 默认凭据（Python）；
• 2.39.0：Apache PulsarIO、JmsIO 动态主题与任意消息映射；
• 2.38.0：Neo4j IO、amazon-web-services2达到功能对等并被推荐；
• 2.36.0：KafkaIO SDF 的stopReadTime、S3 URI scheme 注册；
• 2.34.0：Redis Streams sink（实验性）；
• 2.32.0：Firestore 连接器（Java，实验性）、Healthcare IO 升级到 GA 版本；
• 2.28.0：ParquetIO Beam Schema 支持、Parquet 表写入；
• 2.27.0：MongoDB Atlas、ReadAllFromBigQuery；
• 2.26.0：Contextual Text IO（Java，实验性）；
• 2.25.0：InfluxDbIO、KinesisIO / SnowflakeIO 跨语言（Python）；
• 2.24.0：JdbcIO 跨语言（Python）、AWS SDK v2 KinesisIO、SnowflakeIO 流式、Healthcare DICOM（Python）；
• 2.23.0：Snowflake 读取（Java）、Splunk 写入（Java）；
• 2.22.0：Dataflow Python Kafka 基础读写、Healthcare IO（Java）、DLP PTransform；
• 2.20.0：ThriftIO、KafkaIO Confluent Schema Registry、Healthcare HL7v2IO / FhirIO。

5.2 代表性 I/O 增强（值得在生产中关注）

• BigQuery 系列：2.28.0 流式插入改用 Runner 决定分片；2.34.0ReadFromBigQuery默认 BATCH 优先级、Storage Read API 实验支持（method=DIRECT_READ）；2.55.0 bad records 处理；2.58.0 Storage Write API 并发配额处理优化、multiplexing 连接数可配置；2.59.0 修复 Python BigQuery IO 的服务账号 impersonation 流程。
• Kafka 系列：2.56.0 默认 consumer 轮询超时从 1 秒增至 2 秒（可用withConsumerPollingTimeout覆盖）。
• Spanner 系列：2.58.0 为SpannerIO.read()增加"查询与表不能同时指定"的校验（此前withQuery覆盖withTable）。

六、机器学习与高级分析能力

机器学习是 2.40.0 以来 Beam 增长最快的方向之一，CHANGES.md 提供了清晰的演进路径：

• 2.40.0：引入RunInferenceAPI——框架无关的推理变换，首发支持 PyTorch 与 Scikit-learn；
• 2.46.0：RunInference 支持 ONNX runtime、TensorFlow Model Handler；模型路径可作为SideInput传入；WatchFilePattern变换用于监听模型更新；PytorchModelHandler 支持 TorchScript 模型路径；
• 2.48.0：RunInference 支持dead letter queue与自定义 pre/postprocessing 操作；
• 2.50.0：Hugging Face Model Handler 与 Hugging Face Pipelines 支持、Vertex AI 私有端点、MLTransform变换（常见 ML 预处理/后处理操作）；
• 2.51.0：KeyedModelHandler支持单变换多模型；
• 2.53.0：MLTransform 支持 Vertex AI / Hugging Face Hub 文本嵌入生成；
• 2.54.0：Enrichment Transform与 GCP BigTable handler 加入 Python SDK；
• 2.56.0：RunInference 可精确控制各进程加载的模型数量（适合内存受限场景）；Bigtable enrichment handler 支持自定义复合 row key 构建；
• 2.57.0：Feast 与 BigQuery enrichment handler；
• 2.58.0：多个 RunInference 实例可通过model_identifier共享同一模型实例。

这些能力在当前仓库中均有源码实现，例如 Python 端集中在 sdks/python/apache_beam/ml/inference（base.py定义 RunInference 核心逻辑），MLTransform 相关实现位于 sdks/python/apache_beam/ml/transforms，并配有完整测试与 notebook 示例（见 examples/notebooks/beam-ml）。

已知问题提醒：2.52.0～2.54.0 中 MLTransform 会丢弃输出 PCollection 中的重复元素（#29600），2.53.0 已修复；2.52.0 之前watch_file_pattern参数实际无效，需改用WatchFilePattern作为 SideInput。

七、全新 API 与编程模型扩展

7.1 Beam YAML（2.52.0 稳定版）

2.52.0 宣布 Beam YAML 稳定发布：管线可直接用 YAML 编写，借助 Beam YAML 框架的初步 IO 集与开箱即用变换；2.57.0 起支持jinja 模板语法，模板变量通过 JSON 格式的--jinja_variables参数传入。对应实现位于 sdks/python/apache_beam/yaml。

7.2 DataFrame API（2.32.0 不再是实验性）

• 2.25.0 首次预览；2.32.0 宣布不再是实验性并推荐生产使用；2.37.0 支持 pandas 1.4.x；2.57.0 支持 pandas 2.1.x 并新增 12 个 Series 字符串函数；
• 2.47.0 支持将带 Schema 的 PTransform 直接应用于 DataFrame；2.34.0 起建议使用pip install apache-beam[dataframe]安装；
• 2.26.0/2.28.0 等版本持续补充unstack、pivot、GroupBy.apply等操作。

7.3 Managed I/O 与 Ordered Processing（2.56.0，Java）

• Managed I/O：新 Java API，Iceberg 读写首批落地，对应仓库目录 sdks/java/managed；
• Ordered Processing PTransform：面向顺序敏感的有状态数据处理。

7.4 其他值得关注的 API

• 2.34.0：Python ParDo（Map/FlatMap 等）支持with_exception_handling，轻松实现坏记录忽略与死信模式；
• 2.57.0：PythonDoFn.SetupContextParam/DoFn.BundleContextParam，以参数方式在 setup/bundle 生命周期内调用上下文管理器；
• 2.47.0：Go SDK 新增periodic.Impulse/periodic.Sequence支持缓慢更新 SideInput 模式；Python SDK 支持 Batched DoFn（2.42.0）、Zstd 压缩（2.42.0）、LZMA 压缩（2.46.0）；
• 2.53.0：本地运行多语言管线不再需要 Docker，expansion 子进程可同时充当跨语言 worker；
• 2.21.0：Python SDK 默认把 Python 3 类型注解用作管线类型提示（可全局/局部禁用）。

八、破坏性变更与升级迁移清单

升级 Beam 时，CHANGES.md 的 Breaking Changes 栏目是最高优先级输入。以下为影响面较大的几类：

8.1 语言/依赖版本强制

8.2 API 行为变化

• 2.57.0：JavaView.asList()侧输入在全局窗口内由"索引优先"改为"迭代优先"，get()/size()变慢，可用withRandomAccess()恢复旧行为；
• 2.57.0：TypedSchemaTransformProvider 生成的配置 Schema 改为 snake_case 命名，跨 2.57.0 边界使用远程 SDK 与 SchemaTransform 时需更新参数名；
• 2.56.0：KafkaIO 默认 consumer 轮询超时 1s→2s；
• 2.55.0：Python 默认--max_cache_memory_usage_mb从 100 改回 0（恢复 2.51.0 行为，不使用状态缓存）；
• 2.48.0：PythonMultiProcessShared必须传 tag；
• 2.47.0：主会话加载失败时管线在 worker 启动即失败；单横线开头的未解析命令行参数被忽略；SmallestPerKey改为仅关键字参数；
• 2.46.0：PythonBatchElements更激进地批处理（默认上限 10 秒）；
• 2.45.0：Dataflow 强制 Runner V2（禁用实验开关会报错）；
• 2.43.0：PythonCoGroupByKey分组值类型从 List 改为 Iterable；
• 2.38.0：DoFn.infer_output_types返回值语义变化；
• 2.36.0：RedisIO jedis 3→4；AWS SQS 消息时间戳字段类型变化；
• 2.35.0：跨语言变换 URN 约定更新（自定义 expansion service 跨版本混连可能受影响）；SqlTransform SUBSTRING 行为随 Calcite 1.28.0 变化；
• 2.34.0：SQL Rows 不再被 flatten；JdbcIO 不再静默传入错误 null 数据；
• 2.31.0：Python Row 字段顺序敏感（Row(x=3, y=4)≠Row(y=4, x=3)）；Kafka Beam SQL 表 LOCATION 字段生效；移除 Flink 1.10；
• 2.30.0：移除 Flink 1.8/1.9；移除已弃用多年的 MongoDbIO/RedisIO/MqttIO API；
• 2.29.0：GroupByKey 与有状态 DoFn 强制确定性编码（可注册 fallback coder 或allow_non_deterministic_key_coders恢复）；
• 2.26.0：SDF 成为 Java 系 Runner（Spark 批）Read 变换默认实现（可用--experiments=use_deprecated_read退出）。

8.3 迁移建议

1. 先定位自己在用的 Beam 版本区间，逐版本阅读对应 Breaking Changes；
2. 关注 Deprecations 栏目中的"预告"，提前规划（例如 Euphoria DSL 自 2.53.0 起弃用、计划在 2.56.0 后移除）；
3. 涉及容器镜像（2.50.0 multi-arch、2.55.0 distroless、2.46.0 Temurin）时，检查自定义容器是否依赖被替换的基础环境。

九、已知问题与安全修复（运维视角）

9.1 反复出现的 Known Issues

CHANGES.md 中多条已知问题跨多个版本持续跟踪，升级前可重点核对：

• Python 长跑管线内存泄漏（#28246）：2.50.0～2.55.0 多个版本 Known Issues 中反复出现，2.52.0 修复了一类泄漏；
• Python 流式管线偶发崩溃/卡死（#27330、#30679）：2.47.0+ 用户建议升到 2.53.0；inactive bundle processor 关锁问题在 2.56.0 修复；
• grpcio 回归导致卡死（#30867）：Python 2.55.0 已知问题，2.56.0 修复；
• GCS 相关：2.53.0-2.54.0 Python 管线 GCS 文件操作 HTTP 请求过多（#28398）；2.37.0 前 Datastore/GCS 源偶发吞异常（#14282，建议 2.38.0+）；
• BigQuery Storage Read：部分 runner 需将fastavro钉在 1.8.3 或更早（#28811）；
• impersonation：Python BigQuery IO 服务账号模拟问题（#32030）在 2.59.0 修复；
• MLTransform：重复元素被丢弃（#29600），2.53.0 修复。

9.2 安全修复（CVE）

文档中明确记录的典型修复包括：

• 2.52.0：修复 CVE-2023-39325（Java/Python/Go）、缓解 CVE-2023-47248（Python）；
• 2.53.0：升级到 go 1.21.5，修复 CVE-2023-45285 与 CVE-2023-39326；
• 2.51.0：Python 容器更新修复 7 个 CVE（涉及 Debian/aom 相关漏洞），并升级 go 1.21.1 修复 CVE-2023-39320；
• 2.55.0：Go SDK 基础镜像迁移 distroless，缩小攻击面（#30011）；
• 2.35.0：说明 Beam 本身不依赖受 CVE-2021-44228（Log4Shell）影响的 log4j-core，但敦促用户更新自身构建中的 log4j 依赖。

十、如何高效使用 CHANGES.md 辅助升级决策

结合本仓库 contributor-docs/release-guide.md 与 contributor-docs/committer-guide.md 中描述的维护约定，建议读者按以下流程使用 CHANGES.md：

1. 定位版本区间：用文档中的# [x.y.z] - 日期标题快速确定自己的当前版本与目标版本；
2. 横向对比三列：对每个中间版本重点看Breaking Changes→Deprecations→Known Issues三栏，判断是否"踩线"；
3. 结合仓库源码验证：例如要确认 Flink Runner 能力，可直接查看 runners/flink/flink_runner.gradle 中声明的版本矩阵；要确认 RunInference 参数，可查看 sdks/python/apache_beam/ml/inference/base.py；
4. 关注版本节奏：Beam 采用"频繁小版本"策略，跨大版本升级（如 2.35→2.52）建议按"中间版本逐级迁移 + 逐条核对 Breaking Changes"的方式推进，尤其注意 2.33.0（Go Modules）、2.45.0（Dataflow Runner V2）、2.50.0（多架构镜像）这类结构性变化。

结语

CHANGES.md 是 Apache Beam 演进史的一手档案：它既是升级决策清单（Breaking Changes / Deprecations / Known Issues），也是能力发现手册（Highlights / New Features / I/Os），还记录了安全与质量的持续投入（Security Fixes）。结合仓库中 sdks、runners、examples/notebooks/beam-ml 等源码与示例，读者可以将每个版本条目落到真实的实现与用法上，从而在引入新特性、规划迁移或排查故障时获得可靠依据。对任何正在使用或计划使用 Apache Beam 的团队而言，把 CHANGES.md 纳入版本升级流程的必读清单，是成本最低、收益最直接的工程实践之一。

• 批处理
• 流处理
• 大数据