## **说明**

本文描述问题及解决方法同样适用于 [腾讯云 Elasticsearch Service（ES）](https://cloud.tencent.com/document/product/845?from=20421&from_column=20421)。

---
## 背景

最近线上出现了一批 scroll 查询报错，错误信息大概长这样：

```json
{
  "error": {
    "type": "search_phase_execution_exception",
    "reason": "all shards failed",
    "phase": "query",
    "root_cause": [
      {
        "type": "illegal_state_exception",
        "reason": "node [xxxxxxxxxxxxxxxx] is not available"
      }
      // ... 还有一堆类似的
    ]
  },
  "status": 500
}
```

二十个节点全部报 not available，而且是 all shards failed，直接 500。

---

## 排查过程

### 第一反应：是不是节点挂了？

看到这个报错，第一反应当然是节点出问题了。于是开始查：

- 母机状态 → 正常
- 子机（容器）状态 → 正常
- 网络连通性 → 正常
- 集群健康状态 → green

查了一圈，什么问题都没有。节点好好的，集群也是绿的，但就是报节点不可用。

### 开始怀疑是不是 scroll 的问题

折腾了一会儿之后，想到了一个关键背景：**这套业务的流量是多套 ES 集群混合承接的**，客户端会把请求打到不同的集群上。

这时候脑子里冒出一个模糊的印象——scroll 查询好像是跟节点绑定的？具体原理记得不太清楚，但直觉告诉我，如果第一次 scroll 请求打到了集群 A，拿到了一个 scroll id，然后后续的翻页请求被负载均衡到了集群 B，那集群 B 根本不认识这个 scroll id 里记录的那些节点，自然就会报 not available。

但这只是猜测，需要从代码里确认一下。

---

## 代码层面的石锤

### scroll id 里到底存了什么？

先看 scroll id 的数据结构。ES 的 scroll id 并不是一个简单的随机字符串，它是经过 Base64 编码的结构化数据，解析之后是一个 `ParsedScrollId` 对象：

```java
// ParsedScrollId.java
public class ParsedScrollId {
    private final String type;
    private final SearchContextIdForNode[] context; // 核心：每个分片对应一个 context
    // ...
}
```

每个分片的上下文信息存在 `SearchContextIdForNode` 里：

```java
// SearchContextIdForNode.java
public final class SearchContextIdForNode implements Writeable {
    private final String node;                       // 节点 ID
    private final ShardSearchContextId searchContextId; // 分片搜索上下文 ID
    private final String clusterAlias;               // 集群别名（跨集群时用）
    // ...
}
```

**结论很清晰：scroll id 里直接编码了每个分片所在的节点 ID。** 这不是一个抽象的 token，而是一份完整的"寻址表"——告诉 ES 去哪个节点找哪个分片的搜索上下文。

### 翻页时是怎么用这个信息的？

再看 `SearchScrollAsyncAction` 里的核心逻辑：

```java
// SearchScrollAsyncAction.java - run() 方法
private void run(BiFunction<String, String, DiscoveryNode> clusterNodeLookup,
                 final SearchContextIdForNode[] context) {
    for (int i = 0; i < context.length; i++) {
        SearchContextIdForNode target = context[i];
        try {
            // 关键：用 scroll id 里记录的节点 ID 去当前集群的节点列表里查找
            DiscoveryNode node = clusterNodeLookup.apply(target.getClusterAlias(), target.getNode());
            if (node == null) {
                // 找不到就直接抛异常
                throw new IllegalStateException("node [" + target.getNode() + "] is not available");
            }
            // 向目标节点发送 scroll 请求
            executeInitialPhase(connection, internalRequest, searchActionListener);
        } catch (Exception ex) {
            onShardFailure(...);
        }
    }
}
```

这里的 `clusterNodeLookup` 本质上是在当前接收请求的集群的节点列表（`DiscoveryNodes`）里做查找：

```java
// collectNodesAndRun() 方法
if (clusters.isEmpty()) { // 没有跨集群的情况
    listener.onResponse((cluster, node) -> nodes.get(node)); // 直接从本集群节点列表里找
}
```

逻辑非常直白：**拿着 scroll id 里的节点 ID，去当前集群的节点列表里找对应的节点，找不到就报 not available。**

### 整个调用链路

![Clipboard_Screenshot_1772265666.png](https://developer.qcloudimg.com/http-save/yehe-7348459/d0d1aa05da4203b570703ea9c93712b9.png)

至此，问题原因完全清楚了。

---

## 根本原因

**scroll id 是集群级别的，不能跨集群使用。** 它内部编码了产生该 scroll 的集群中各分片所在节点的 ID，当翻页请求被路由到另一个集群时，该集群的节点列表里根本不存在这些节点 ID，于是每个分片都报 not available，最终触发 all shards failed。

这个问题的特殊之处在于，报错信息看起来像是节点故障，但实际上节点完全正常，只是"认错了门"。

---

## 解决方案

核心原则：**同一个 scroll 会话的所有请求（初始查询 + 所有翻页）必须打到同一个集群。**

常见的处理方式：

**1. 客户端侧做会话保持**

在发起初始 scroll 查询时记录目标集群，后续翻页请求强制路由到同一集群，不走通用的负载均衡逻辑。

**2. 使用 search_after 替代 scroll**

`search_after` 是无状态的深翻页方案，不依赖服务端的搜索上下文，天然不存在这个问题，也是 ES 官方更推荐的方式。

**3. 网关层做 scroll id 路由**

如果有统一的接入层，可以解析 scroll id（Base64 解码后能拿到节点信息），根据节点归属判断应该路由到哪个集群。

---

## 小结

这个问题排查起来有点绕，因为表象（节点不可用）和根因（请求打错了集群）之间隔了一层。如果不了解 scroll id 的内部结构，很容易在基础设施层面兜圈子。

从代码层面看，ES 的设计其实很直接：scroll id 就是一张"寻址表"，翻页时严格按表上的地址去找节点，找不到就报错，没有任何容错或重定向的逻辑。这在单集群场景下完全没问题，但在多集群混合流量的场景下，就需要在架构层面保证请求的会话亲和性。


---

## 参考资源

- [Elasticsearch 源码 - SearchScrollAsyncAction.java](https://github.com/elastic/elasticsearch/blob/main/server/src/main/java/org/elasticsearch/action/search/SearchScrollAsyncAction.java)
- [Elasticsearch 源码 - ParsedScrollId.java](https://github.com/elastic/elasticsearch/blob/main/server/src/main/java/org/elasticsearch/action/search/ParsedScrollId.java)
- [Elasticsearch 源码 - SearchContextIdForNode.java](https://github.com/elastic/elasticsearch/blob/main/server/src/main/java/org/elasticsearch/action/search/SearchContextIdForNode.java)
- [Elasticsearch 官方文档 - Scroll search results](https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#scroll-search-results)
- [Elasticsearch 官方文档 - search_after](https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#search-after)

本文描述问题及解决方法同样适用于 腾讯云 Elasticsearch Service（ES）。

Elasticsearch 实战 | 别再怀疑你的 ES 节点了，scroll 报 node not available 可能根本不是节点的问题

线上 Elasticsearch Scroll 查询批量报 node not available，节点、网络全部正常。深入源码发现 scroll_id 内编码了节点寻址信息，跨集群请求必然失败。

大数据工程师

云计算

大数据

架构设计

腾讯云ES集群scroll查询报错排查：多集群混合流量场景下，scroll会话请求必须路由到同一集群，否则因节点ID不匹配导致allshardsfailed。解决方案包括客户端会话保持、改用search_after或网关层路由。

结构化数据

负载均衡

数据结构

容器

路由

2026新春采购季

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Elasticsearch 实战 | 别再怀疑你的 ES 节点了，scroll 报 node not available 可能根本不是节点的问题-腾讯云开发者社区-腾讯云

Elasticsearch 实战 | 别再怀疑你的 ES 节点了，scroll 报 node not available 可能根本不是节点的问题

Elasticsearch 实战 | 别再怀疑你的 ES 节点了，scroll 报 node not available 可能根本不是节点的问题

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐