【最佳实践】解决 Elasticsearch 8.x 滚动升级失败的问题

本文描述问题及解决方法同样适用于 php中文网 elasticsearch service（es）。

环境配置

背景

在 AI 大模型席卷全球的今天，向量检索（Vector Search）已经成为现代搜索引擎的核心能力。无论是智能问答、图像搜索、推荐系统，还是 RAG（检索增强生成）应用，都离不开高效的向量相似度计算。而 Elasticsearch 8.x 正是在这个时代背景下，将向量检索能力推向了新的高度。

为什么选择 Elasticsearch 8.x？

2023 年以来，随着 ChatGPT 等大语言模型的爆火，企业对向量检索的需求呈指数级增长。Elasticsearch 从 8.0 版本开始，就将 dense_vector（密集向量） 和 kNN 搜索作为核心特性进行了大幅优化：

升级的契机

而 Elasticsearch 8.13.1 的新特性恰好能解决这些问题：

于是，业务决定从 8.8.1 升级到 8.13.1。

升级之路的意外

Elasticsearch 官方文档明确表示，8.x 系列支持滚动升级（Rolling Upgrade） [官方文档]，然而，当我们信心满满地开始升级第一个节点时，却遭遇了一个意想不到的错误：

同样的版本号，不同的构建哈希，导致节点无法加入集群。

这个问题让我们陷入了困境：难道无法滚动升级？难道必须停机才能升级？经过一番深入的源码分析和问题排查，我们终于找到了问题的根源和解决方案。

接下来，让我们一起深入探讨这个问题的本质，以及如何优雅地解决它。

问题现象

在进行 Elasticsearch 集群滚动升级过程中，新节点启动后无法正常加入集群，日志中出现以下错误信息：

<code class="txt">[2024-10-29T10:23:45,123][WARN ][o.e.t.ClusterConnectionManager] [es-node-02] failed to connect to node [{es-node-01}{...}{8.8.1}]org.elasticsearch.transport.ConnectTransportException: [es-node-01][10.0.1.10:9300] handshake failed. unexpected remote node [es-node-01]at org.elasticsearch.transport.TransportService.lambda$connectionValidator$6(TransportService.java:567)...Caused by: org.elasticsearch.transport.TransportSerializationException: Failed to deserialize response from handler [ContextRestoreResponseHandler[...]]at org.elasticsearch.transport.InboundHandler.doHandleResponse(InboundHandler.java:423)...Caused by: java.lang.IllegalArgumentException: remote node [{es-node-01}{...}{8.8.1}] is build [a23c735933a8b1c0c3d0873c8ab96349e5101e5e] of version [8.8.1] but this node is build [6db6a780efb93cf7238a877094bd825d9b8b5fe0] of version [8.13.1] which has an incompatible wire formatat org.elasticsearch.transport.TransportService$HandshakeResponse.throwOnIncompatibleBuild(TransportService.java:712)at org.elasticsearch.transport.TransportService$HandshakeResponse.maybeThrowOnIncompatibleBuild(TransportService.java:697)at org.elasticsearch.transport.TransportService$HandshakeResponse.<init>(TransportService.java:691)...</code>

关键信息：

问题分析

为什么会出现这个问题？

这是 Elasticsearch 8.x 版本中引入的一个严格兼容性检查机制。查看 TransportService.java 源码可以发现问题根源：

<code class="java">public static class HandshakeResponse extends TransportResponse {// ...public HandshakeResponse(StreamInput in) throws IOException {    super(in);    version = Version.readVersion(in);    buildHash = in.readString();        try {        discoveryNode = new DiscoveryNode(in);    } catch (Exception e) {        maybeThrowOnIncompatibleBuild(null, e);        throw e;    }    maybeThrowOnIncompatibleBuild(discoveryNode, null);    clusterName = new ClusterName(in);}private void maybeThrowOnIncompatibleBuild(@Nullable DiscoveryNode node, @Nullable Exception e) {    if (DiscoveryNode.isServerless() == false && isIncompatibleBuild(version, buildHash)) {        throwOnIncompatibleBuild(node, e);    }}private static boolean isIncompatibleBuild(Version version, String buildHash) {    // 关键逻辑：当版本号相同但构建哈希不同时，认为不兼容    return version == Version.CURRENT && Build.CURRENT.hash().equals(buildHash) == false;}}</code>

问题的本质

在滚动升级过程中：

这个问题在 Elasticsearch 8.x 的跨小版本升级中较为常见，特别是：

解决方案

使用 Serverless Transport 模式，这是最快速、最适合升级场景的解决方案。通过设置系统属性跳过严格的构建哈希检查。

实施步骤

步骤 1：在升级前的所有节点上配置参数

编辑 config/jvm.options 文件，添加以下参数：

<code class="bash"># 跳过构建哈希严格检查（用于滚动升级）-Des.serverless_transport=true</code>

步骤 2：重启所有现有节点（8.8.1）

逐个重启节点，确保集群状态为 green：

Cliclic AI

Cliclic商品背景图编辑器是一款功能强大的AI工具，帮助用户快速生成具有吸引力的商品图背景。

下载

<code class="bash">systemctl restart elasticsearch</code>

验证节点状态：

<code class="bash">curl -X GET "localhost:9200/_cat/nodes?v"curl -X GET "localhost:9200/_cluster/health?pretty"</code>

步骤 3：执行滚动升级

1. 停止节点

<code class="bash">systemctl stop elasticsearch</code>

2. 升级到 8.13.1

<code class="bash">下载并安装新版本wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-8.13.1-linux-x86_64.tar.gztar -xzf elasticsearch-8.13.1-linux-x86_64.tar.gz复制配置文件（确保 jvm.options 中包含 -Des.serverless_transport=true）cp /etc/elasticsearch/elasticsearch.yml /path/to/new/elasticsearch/config/cp /etc/elasticsearch/jvm.options /path/to/new/elasticsearch/config/</code>

3. 启动升级后的节点

<code class="bash">systemctl start elasticsearch</code>

4. 等待节点加入集群并恢复

<code class="bash">curl -X GET "localhost:9200/_cat/nodes?v"curl -X GET "localhost:9200/_cat/recovery?v"</code>

5. 等待集群状态变为 green

<code class="bash">watch -n 2 'curl -s "localhost:9200/_cluster/health?pretty"'</code>

6. 对其他节点重复步骤 1-5

步骤 4：升级完成后移除参数（可选）

当所有节点都升级到 8.13.1 后，可以考虑移除该参数：

<code class="bash"># 编辑 jvm.options，注释或删除该行-Des.serverless_transport=true# 逐个重启节点systemctl restart elasticsearch</code>

验证升级成功

<code class="bash"># 检查所有节点版本curl -X GET "localhost:9200/_cat/nodes?v&h=name,version,build"# 输出示例：name version buildes-node-01 8.13.1 6db6a78es-node-02 8.13.1 6db6a78es-node-03 8.13.1 6db6a78# 检查集群健康状态curl -X GET "localhost:9200/_cluster/health?pretty"</code>

常见问题 FAQ

Q1: 设置 es.serverless_transport=true 有什么风险？

A: 这个参数会跳过构建哈希的严格检查，理论上存在以下风险：

Q2: 能直接从 8.8.1 跨大版本升级到 9.x？

Elasticsearch 只支持相邻大版本之间的升级：

Q3: 升级过程中可以继续写入数据吗？

Q4: 云服务商的 ES 也会遇到这个问题吗？

总结

Elasticsearch 8.x 的跨小版本升级中，构建哈希不兼容问题是一个已知的边界情况。解决这个问题的关键是：

希望本文能帮助遇到类似问题的同学顺利完成 Elasticsearch 升级。如有疑问，欢迎在评论区讨论。

参考资料

作者：岳涛

日期：2025-10-29

标签：Elasticsearch, 升级, 8.x, 故障排查, 构建哈希, 滚动升级