企业官网建设流程全解析

OpenSearch 3.0.0-beta1 版本解析：Lucene 10、JDK 21 与下一代搜索架构的关键演进

【免费下载链接】OpenSearch🔎 Open source distributed and RESTful search engine.项目地址: https://gitcode.com/gh_mirrors/op/OpenSearch

2025-04-15 发布的 OpenSearch 3.0.0-beta1 是 3.x 主线的一个里程碑版本。本文以官方 Release Notes（release-notes/opensearch.release-notes-3.0.0-beta1.md）为核心骨架，结合当前仓库源码逐一解析其中的 Breaking Changes、新特性、依赖升级、弃用与移除项，帮助你判断升级到 3.0 的影响面，并理解 HTTP/2、pull-based Ingestion、Search 节点角色、GRPC、Views、Star Tree 等新能力的落地方式。读完本文，你将掌握 3.0.0-beta1 的完整变更清单及其在源码中的对应实现位置，可直接作为升级评估与二次开发的参考手册。

一、总览：3.0.0-beta1 在版本演进中的定位

OpenSearch 的 3.x 分支承载了多年来积累的"欠账清理"与新一代架构探索。3.0.0-beta1 集中体现了三个主题：

1. 技术栈换代：Lucene 升级到 10.1.0（当前仓库主线已演进至 gradle/libs.versions.toml 中的 Lucene 10.5.1），最低运行环境要求提升到 JDK 21。
2. 大规模清理：移除大量历史遗留 API、LegacyESVersion 常量、废弃线程池设置，为 JPMS（Java Platform Module System）支持扫清 split package 障碍。
3. 新架构落地：HTTP/2 服务端支持、pull-based Ingestion、search_only 节点角色、GRPC 端点、Views 虚拟层、Star Tree 加速等一批面向未来的功能进入主分支。

从当前仓库的版本看，buildSrc/version.properties 与gradle/libs.versions.toml中 Lucene 已推进到 10.5.1，说明仓库处于 3.x 主线 beta1 之后的持续演进状态；本文所述变更均已在 3.0.0-beta1 发布时点落地。

二、Breaking Changes：升级前必须评估的破坏性变更

3.0.0-beta1 的 Breaking Changes 主要围绕依赖升级、API 清理与行为收紧三条线展开。

2.1 运行环境与依赖基线升级

仓库佐证：当前 gradle/libs.versions.toml 中lucene = "10.5.1"，且 server/licenses 目录下所有 Lucene 组件均以 10.5.1 发布（如lucene-core-10.5.1.jar.sha1），印证了 3.x 主线全面切换 Lucene 10 的事实。

2.2 Java API 与设置项清理

• 移除 Java API 中的弃用术语（#1683）：将 "blacklist/whitelist" 类术语全面替换为中性表述，任何引用旧 API 名（如blacklist相关方法）的客户端代码都需要改。
• 清理废弃的线程池设置（#2595）：删除了历史上遗留的线程池相关设置项，elasticsearch.thread_pool.*一类的旧配置不再生效。
• 移除mmap.extensions设置（#9392）：mmap 扩展点配置被删除，改为使用 Lucene 10 内置的 mmap 能力。
• 移除 COMPAT locale provider（#13988）：配合下方"Changed"中的 CLDR 切换，-Djava.locale.providers=COMPAT场景不再支持。
• 移除 transport-nio 插件（#16887）：transport-nio模块整体移除，网络传输统一收敛到 netty4 / reactor-netty4 实现（仓库中 libs/nio 仍保留 nio 相关库，但传输插件入口已删除）。
• 从 Java API 移除废弃方法（#5214、#3346）：包括脚本场景会调用的JodaCompatibleZonedDateTime上的废弃方法等。
• 模块目录下以 Plugin 结尾的类统一改名为 Module（#4042）：影响自定义模块/插件的类名引用。

2.3 行为与校验收紧

• Bulk Index API 校验增强（#6595）：强制_id大小不得超过 512 字节，超限请求将被拒绝。
• 设置空数组字符串解析（#10625）：node.roles等设置传入空数组字符串时按空数组处理，这直接支撑了"纯协调节点"能力（见下条）。
• 允许node.roles传空数组使节点成为纯协调节点（#3412）：配置node.roles: []即可让节点只承担协调（coordinating）职责，不持有任何分片。
• 限制嵌套查询的最大深度（#11670）：新增嵌套查询深度上限，防止构造过深的查询导致资源耗尽。
• Jackson 默认最大值对齐（#11811）：确保 Jackson 2.16 引入的默认流解析上限不与 OpenSearch 自身设置冲突。
• 修正total_indexing_buffer_in_bytes与total_indexing_buffer的格式互换问题（#17070）：修复了这两个节点统计字段单位/含义错位的 bug，统计消费方需重新核对。
• _bulk移除废弃的batch_size参数（#14283）：批量接口不再接受该参数。

2.4 安全权限模型收紧

• 新增ThreadContextPermission（#15039、#15016）：stashAndMergeHeaders、stashWithOrigin、markAsSystemContext等 ThreadContext 操作现在受安全权限管控，核心模块内部保留执行能力，第三方插件若调用这些方法需要显式声明权限。
• 仓库佐证：ThreadContextPermission定义位于 libs/secure-sm/src/main/java/org/opensearch/secure_sm/ThreadContextPermission.java，且已加入 Java Agent 安全策略白名单 libs/agent-sm/agent-policy/src/main/java/org/opensearch/secure_sm/policy/PolicyFile.java。

三、Added：3.0.0-beta1 引入的新能力

本节按主题分组梳理 Release Notes 中的新增项，并给出源码落点。

3.1 传输与协议层

• HTTP/2（服务端）支持（#3847）：Netty4 传输层开始支持 HTTP/2 协议，为后续更高效的客户端通信铺路。仓库中HttpRequest.HttpVersion枚举已包含HTTP_2_0与HTTP_3_0取值，见 server/src/main/java/org/opensearch/http/HttpRequest.java。
• 修复 h2c 协议压缩支持（#4944）、HTTP/2 协议版本识别（#17248）：补齐了明文 HTTP/2（h2c）下的压缩与版本判定。
• TLS 启用的 SecureNetty4GrpcServerTransport（#17796）：GRPC 传输支持 TLS 加密。
• GRPC 端点持续扩展（#17727、#17830、#17888）：新增DocumentService、Bulk、Search、TermsQuery 等 GRPC 端点，相关代码位于 modules/transport-grpc。
• Arrow Flight RPC 插件（#16962）：引入 Flight 服务器引导逻辑与节点间通信客户端，作为未来列式数据交换的基础设施。

3.2 数据接入：pull-based Ingestion

3.0.0-beta1 引入了完整的**拉模式数据接入（pull-based Ingestion）**体系：

• 基础 API 与 IngestionEngine（#16958）：引擎主动从 ingestion source 拉取数据，而不是被动等待推送。
• 偏移量管理（#17354）、错误处理（#17427）、暂停/恢复/状态查询管理 API（#17631）、版本化支持（#17918）、update/delete 支持（#17822）。
• 开箱即用的数据源插件：Kafka 插件（#16958）、Kinesis 插件（#17615）。
• 可配置性：maxPollSize与pollTimeout可在 IngestionSource 中配置（#17863）。
• 关闭 ingestion engine 的索引 API（#17768）：拉模式场景下数据由引擎写入，普通索引 API 被禁用。
• 修复分片恢复时可能跳过消息的问题（#17868）。

3.3 存储与查询优化

• Views 虚拟层（#11957）：通过一个或多个索引之上提供虚拟视图层，简化数据访问与操作。源码落点：server/src/main/java/org/opensearch/action/admin/indices/view/ViewService.java，REST 入口为 server/src/main/java/org/opensearch/rest/action/admin/indices/RestViewAction.java。
• Star Tree 聚合加速（#17165、#17273、#17275）：关键字/数值桶聚合、数值范围聚合支持通过 Star Tree 数据结构解析，并补齐 unsigned-long 支持。
• 多桶聚合（Multi Term Aggregation）延迟与内存优化（#14993）、数值项聚合避免多余排序（#17252）：提升聚合查询性能。
• cardinality 聚合新增execution_hint（#17312）：允许用户提示聚合执行策略。
• ApproximateMatchAllQuery（#17772）：针对 match_all 查询提供近似排序。
• terms_query对已排序词项加速（#17714）：当提供的词项已排序时可走快速路径。
• keyword 字段默认关闭打分（#17889）：keyword 词项搜索默认不计算打分，需use_similarity: true参数显式开启。
• 限制每节点/每索引主分片总数的集群与索引级设置（#17295）：新增容量治理设置。
• MergedSegmentWarmerFactory（#17881）：支持扩展 Lucene 的IndexWriter.IndexReaderWarmer。
• mapping transformer（#17635）：在索引/模板创建或更新时对 mapping 做变换，仓库示例见 plugins/examples/mapping-transformer。
• 动态集群设置maxMergeAtOnce（#17774）：可在集群级动态调整合并参数（默认值同时提升到 30）。

3.4 节点角色与分片放置

• 新增search节点角色（#17620）：专门承载 search-only 分片；search_only模式（#17299）支持读写分离场景的 scale-to-zero，即搜索节点可在无负载时缩容为零。
• warm角色替代search命名（#17573）：原search角色更名为warm，承载 warm 索引。
• warm tiering 术语统一（#17490）：新增 Warm 索引设置，明确 hot 与 warm 分层语义。
• Search Only 严格路由设置（#17803）：控制搜索只读节点上的分片路由。
• SearchReplica 的 AutoExpand 支持（#17741）：副本可随负载自动扩缩容。

仓库佐证：在 server/src/main/java/org/opensearch/cluster/node/DiscoveryNodeRole.java 中可以看到WARM_ROLE（角色名warm，缩写w）与SEARCH_ROLE（角色名search，缩写s）的完整定义；其中SEARCH_ROLE的validateRole强制要求 search 角色不能与任何其他角色共存于同一节点。注意当前源码同时保留两者，命名演进仍在进行。

3.5 集群管理与可观测性

• 集群状态远程下载开关（#16798）：新增设置控制 term 不匹配时是否从远程下载完整集群状态。
• 主服务性能与关键集群操作日志优化（#14795）、reroute 超时调度优先级调整（#16445）。
• 分片级 segment replication 统计（#17055）、修正倾斜的 segment replication lag 指标（#17831）。
• _id与 pipeline ID 的 512 字节上限（#17786）（搜索与 ingest pipeline 统一执行）。
• 搜索背压统计新增任务完成计数（#10028）、SearchTask 取消后长任务跟踪（#17726）。
• systemd 配置加固 OS 核心安全（#17107）并配套集成测试（#17410），相关配置见 distribution/packages/src/common 下的.service文件。

3.6 安全模型：Security Manager 替代方案（Java Agent）

• 阶段化用 Java Agent 替代 SecurityManager（#17724、#17746、#17753、#17757、#17760、#17861）：先创建拦截Socket::connect的 Java Agent，随后依次增强System::exit、Runtime::halt拦截，加入策略解析器与 File Interceptor 及集成测试，最终进入 Phase-off SecurityManager 阶段。
• 仓库佐证：Java Agent 相关实现集中在 libs/agent-sm（含agent与agent-policy子模块），安全策略文件解析见 libs/agent-sm/agent-policy/src/main/java/org/opensearch/secure_sm/policy/PolicyFile.java。

3.7 其他值得关注的新增

• WLM 支持 search scroll API（#16981），并将QueryGroup更名为WorkloadGroup（#17901），相关实现见 plugins/workload-management。
• 规则驱动的自动打标（Rule Based Auto-tagging）三连（#17342、#17238、#17365）：内存属性值存储、规则 schema、内存规则处理服务，见 modules/autotagging-commons。
• 配置解析工具类 ConfigurationUtils（#17223）：加入 core 统一配置解析。
• flat_object字段 DocValues 取值能力（#16802）。
• AbstractQueryBuilder/BoolQueryBuilder/ConstantScoreQueryBuilder新增filter函数（#17409）、子聚合 filter 重写优化（#17447）。
• FilterFieldType（#17627）：供开发者包装MappedFieldType。
• 固定间隔 refresh 任务调度（#17777）、统一磁盘缓存管理器 Tiered caching（#17513）。
• XContentMapValues 的 dfs 变换函数（#17612）。
• 主分片约束权重可调设置（#16471）、发布 checkpoint 事务重试超时集群设置（#17749）。

四、Changed：行为与默认值调整

4.1 排序与相关性

• 默认相似度切换为BM25Similarity（#17306）：Lucene 中LegacyBM25Similarity已弃用，OpenSearch 默认使用标准 BM25。
• 不再最小化大小写不敏感匹配的 automata（#17268）：以轻微内存/构建成本换取更快的查询执行。
• 通配符字段只索引输入数据的 3-gram（#17349）：降低通配符字段索引体积。

4.2 索引与分段

• floor segment size 提升到 16MB（#17699）：减少过小分段数量，降低合并开销。
• 默认maxMergesAtOnce提升到 30（#17774），force merge 线程数提升为核心数的 1/8（#17255）。
• 副本提升时默认分段计数器步长增大（#17568）。

4.3 集群与 API

• locale provider 从 COMPAT 切换为 CLDR（#14345）：字符串排序、日期格式等行为可能与旧版本不同。
• create index API 对错误输入返回 400 而非 500（#4773）；设置更新错误汇总消息改进（#4792）。
• 并发快照执行失败返回 409 Conflict 而非 503（#8986）。
• NodesInfoRequest默认不再请求search_pipelines指标（#12497）。
• 源字段显式匹配逻辑简化（#17160）：指定明确字段名（无通配符/点路径）时使用更简单匹配。
• PEM 解析改用 BC 库（#17393），并将 BC 库迁移到 FIPS 对应版本（#17507）。
• TieredSpilloverCache 的 took-time 阈值同时作用于堆与磁盘层（#17190）。
• 单例 DocValues 解包优化（#17740、#17643）：提升 composite histogram 与 date histogram 聚合性能。
• jarHell 检查对可选扩展插件放宽（#17893）、transport-reactor-netty4迁移到 gradle version catalog（#17233）。

4.4 面向 JPMS 的包重构

3.0.0-beta1 集中消除了顶层 split package：

• :libs模块bootstrap包重构（#17117）；
• 全代码库顶层 split package 消除（#17153）；
• :server模块org.apache.lucene包重构（#17241）；
• :server模块org.opensearch.client迁移为org.opensearch.transport.client（#17272）。

重要影响：客户端类包名从org.opensearch.client变更为org.opensearch.transport.client，任何直接 import 这些类的扩展代码都需要同步修改。

五、Deprecated 与 Removed：废弃清理清单

5.1 Deprecated

本版本 Deprecated 章节为空——3.0.0-beta1 直接将大量能力放入 Removed 处理，体现了 3.x 大版本"一次性清算"的策略。

5.2 Removed 重点项

版本常量与历史兼容层：

• 移除LegacyESVersion.V_7_0_*至V_7_10_*全部常量（#2768、#4702、#4704、#4855、#4837、#5018），以及Version.V_1_*常量（#5021）。
• Snapshot/Restore 服务移除 Legacy 版本支持（#4728）：跨大版本恢复旧快照的能力被裁剪。
• 移除废弃的gateway设置（用于延迟集群恢复，#3117）。

代码与 API：

• 移除org.opensearch.action.support.master包（#4856）。
• 移除自定义 Map/List/Set 集合类（#6871）、废弃的管道聚合序列化逻辑（#4847）、未使用的私有方法（#4926）。
• 移除日志 pattern 中节点名注入的废弃代码（#4568）、TransportClusterAllocationExplainAction中未用对象与 import（#4639）。
• 移除FeatureFlags.PLUGGABLE_CACHE（#17344）与APPROXIMATE_POINT_RANGE_QUERY_SETTING（#17769）：这两个特性已不再标记为实验性，相关开关被删除。
• 洪水阶段（flood stage）block 始终自动释放（#4703）。

六、Dependencies：关键依赖升级一览

Release Notes 列出 30+ 项依赖升级，按影响面分类：

这些版本可以在 gradle/libs.versions.toml 中核对当前主线版本，例如 AWS SDK、gson 等依赖的现网取值。

七、Fixed：3.0.0-beta1 修复的关键缺陷

• HTTP 客户端协议解析：修复 JDK 16+ 下ParseException: Invalid protocol version（#4827）；修复HeapBufferedAsyncEntityConsumer过度分配（#9993）。
• 查询与聚合：修复 terms 聚合 missing 值丢桶（#17418）；修复 explain action 在查询重写时的问题（#17286）；修复FunctionScoreQueryBuilder内部查询访问（#16776）；修复 wildcard 大小写不敏感与转义查询（#16827）；修复match_only_text字段通配符搜索高亮（#17101）。
• flat_object：修复嵌套 flat_object 字段 exists 查询抛异常（#16803）。
• PIT / 统计：修复创建 PIT 时的非法参数异常（#16781）；修复 QueryGroupTasks 导致节点统计 NPE（#17576）；修复_cat/recovery的 bytes 参数（#17598）；修复 FeatureFlag 检查性能缓慢（#17611）；修复 pull-based ingestion 分片恢复跳消息（#17868）。

八、升级评估与迁移建议

结合上文，从 2.x 升级到 3.0.0-beta1（及后续 3.x）时建议按以下清单核对：

1. 运行环境：确认 JDK 21 已就绪（distribution/src/config/jvm.options 等配置需按新版本重新核对）。
2. 客户端包名：若代码 import 了org.opensearch.client，需迁移到org.opensearch.transport.client（对应 server/src/main/java/org/opensearch/transport/client 下的实现）。
3. 已删除设置：检查配置文件中是否仍在使用mmap.extensions、废弃gateway设置、旧线程池设置、_bulk的batch_size等，全部需要移除或替换。
4. 校验收紧：_id超过 512 字节的写入、超过嵌套深度上限的查询、超限的 pipeline ID 在升级后会被拒绝，需提前校验业务数据。
5. 行为变化：CLDR locale、BM25 默认相似度、create index 错误码 400/409、search_pipelines指标默认关闭、快照并发冲突 409 等变化会影响自动化脚本与监控面板。
6. 新能力评估：可结合业务场景评估 HTTP/2、pull-based Ingestion（Kafka/Kinesis 插件）、warm/search节点角色、Views、GRPC 端点与 Star Tree 加速是否值得引入。
7. 安全模型：Java Agent 替代 SecurityManager 处于阶段化推进中，涉及ThreadContextPermission的插件需要补充权限声明。

参考：本文引用的仓库关键路径

• Release Notes 原文：release-notes/opensearch.release-notes-3.0.0-beta1.md
• 依赖版本目录：gradle/libs.versions.toml
• HTTP 版本枚举：server/src/main/java/org/opensearch/http/HttpRequest.java
• 节点角色定义：server/src/main/java/org/opensearch/cluster/node/DiscoveryNodeRole.java
• Views 服务与 REST 入口：ViewService.java、RestViewAction.java
• Java Agent 安全策略：PolicyFile.java、ThreadContextPermission.java
• GRPC 模块：modules/transport-grpc
• WLM 模块：plugins/workload-management
• 自动打标模块：modules/autotagging-commons
• systemd 配置：distribution/packages/src/common

【免费下载链接】OpenSearch🔎 Open source distributed and RESTful search engine.项目地址: https://gitcode.com/gh_mirrors/op/OpenSearch