企业官网建设流程全解析

先交代一下背景：前阵子做一个数据迁移模块，需要从 Elasticsearch 7 里一次性拉出上百万条订单记录，同步到另一个存储。一开始我用的是 from + size 普通分页，前面几百页还能跑，越往后越慢，甚至直接超时。后来换成 Scroll 游标查询，整个导出流程才稳定下来。这篇就是我在 .NET5(C#) 项目里使用 Elasticsearch7 Scroll 的完整落地记录，包含从环境搭建到参数调优的每个细节，以及一堆只有实际跑过才知道的坑，适合正在做数据导出、迁移、批处理，或者被大数据量分页卡住的同学参考。

1. 为什么大数据量检索要用Scroll而不是普通分页

1.1 普通 from+size 分页的痛点

ES 里最常用的分页方式就是from+size。打个比方，你让 ES 查询“从第 500000 条开始，取 1000 条”，它并不是直接跳到第 500000 条的位置取数，而是把所有符合条件的结果都找出来排序，再从第 500000 个位置截断返回。这个“排序 + 丢弃”的过程在所有分片上并行发生，最后协调节点还要再做一次全局排序。所以from越大，需要排序和丢弃的数据就越多，查询延迟几乎是线性增长。

更要命的是 ES 默认index.max_result_window是 10000。也就是说，from + size一旦超过 10000，默认配置下会直接拒绝查询。这其实是一道保护性限制，防止有人用极深的翻页把协调节点的内存打爆。但很多真实业务要导出的不是一万条，而是一百万条，这时候普通分页连资格都没有。

我一开始写分页导出的时候就踩过这个坑：一个带时间过滤的查询，from翻到第 11 页就报错，日志里写着Result window is too large。后来我把max_result_window调大，倒是能查了，但每翻一页耗时从几十毫秒涨到几秒，跑到最后整个协调节点 CPU 都在报警。事后总结一句话：普通分页是用来给人“翻网页”的，不是用来给程序“拉全量数据”的。

1.2 Scroll 游标查询的工作原理

Scroll 的思路完全不一样。第一次发请求时，ES 会在索引对应的分片上创建一批“搜索上下文”，你可以理解成给这次查询生成了一张“快照”。这个快照记录了查询条件、匹配结果的状态、以及当前读到的位置。ES 返回给你的不再是一次性结果集，而是一个ScrollId，类似一个书签。

你拿着这个 ScrollId 去请求下一批数据，ES 会从上一次的位置接着往下扫，而不是重新执行整条查询。每一批数据返回后，你继续拿新的 ScrollId 或同样的 ScrollId 去换下一批，直到最后一批为空。整个过程里，ES 不会把全部匹配结果一股脑塞进内存，而是维护了指向最终结果集的游标，每次只返回你指定大小的一个批次。

这种机制有几个典型特征。第一，它是顺序快照，意味着查询开始那一刻的数据状态被固定下来，后面即使有新数据写入索引，这次 Scroll 也看不到。第二，它适合全量顺序消费，不适合随机跳页，因为游标只能往前走。第三，Scroll 上下文是有存活时间的，由请求里的scroll参数控制，比如1m表示一分钟，每次续滚都会刷新这个时间。

我用一个更生活的例子来类比：普通分页就像你反复让图书管理员从第一排书架数到你想要的那一排，每次都要从头开始；Scroll 则是你在书架上放了一个书签，管理员只负责从上次位置继续往下拿。对于“把整座图书馆的书都借一遍”这种场景，书签显然更经济。

1.3 什么场景该用 Scroll，什么时候别用

Scroll 并不是银弹，我用下来对适用场景有很清晰的边界：

尤其要注意：如果你只需要用户做一个“下一页”按钮，而不是要拉几百万条，不要用 Scroll。Scroll 会额外占 ES 资源，而且如果忘了清理，对线上集群影响很大。我在生产环境见过别人写的定时任务，每次查询都创建 Scroll 上下文，异常退出时也没有清理，最后把节点内存打爆，日志里全是too many scroll contexts。这个教训后面在排查章节再展开。

2. 环境准备与基础配置

2.1 创建 .NET5 项目并安装客户端包

这次演示用的是 .NET5 控制台项目，如果你要在 Web API 或 Worker Service 里用，代码完全一样。先创建一个新项目：

dotnet new console -n ScrollDemo cd ScrollDemo dotnet add package NEST --version 7.17.5

这里有个经验要提醒：Elasticsearch 7.x 对应的官方 .NET 客户端是NEST，不要装成 8.x 的Elastic.Clients.Elasticsearch，API 风格完全不一样。如果你用的是 ES 7.10+ 甚至 7.17，NEST 7.17.x 都兼容。

另外，.NET5 官方支持期在 2022 年已经结束。如果是老项目必须跑在 .NET5 上没问题，但新项目我建议直接用 .NET6/8 LTS 版本。NEST 7.x 在这些运行时上也能跑，核心 API 不会变，唯一要注意的是部署环境下有没有安装对应版本的 .NET Runtime。

2.2 连接配置与基础校验

加完包后，先配置连接。最简单的写法是直接指定http://localhost:9200：

var settings = new ConnectionSettings(new Uri("http://localhost:9200")) .DefaultIndex("orders") .BasicAuthentication("elastic", "你的密码") .RequestTimeout(TimeSpan.FromMinutes(2)); var client = new ElasticClient(settings);

如果是集群环境，可以传多个节点地址；如果开启了 HTTPS，不要为了省事直接跳过证书验证。我们公司在测试环境为了调试方便曾把证书校验关掉，后来某次安全扫描直接挂了红灯，线上环境我更推荐把正式证书配好。

连接建好后，第一步可以先Ping一下确认网络和认证都没问题：

var pingResponse = client.Ping(); if (!pingResponse.IsValid) { Console.WriteLine($"Elasticsearch 连接失败: {pingResponse.OriginalException?.Message}"); return; }

RequestTimeout建议给大一点。Scroll 本身虽然不会一次性查全部数据，但如果在查询里加了复杂聚合或者某些分片上负载很高，首次请求也可能超过默认的 60 秒超时。我见过明明索引只有几千万条，但磁盘比较慢，首次查询就跑了 40 多秒，默认超时差点触发。

2.3 准备测试数据

为了演示 Scroll，我建一个orders订单索引，字段不用太复杂，重点是模拟“海量数据”：

public class Order { public long Id { get; set; } public string OrderNo { get; set; } public int Status { get; set; } public DateTime CreateTime { get; set; } }

创建索引并写入一批测试数据：

if (!client.Indices.Exists("orders").Exists) { client.Indices.Create("orders", c => c .Map<Order>(m => m .AutoMap() .Properties(p => p .Date(d => d .Name(n => n.CreateTime) .Format("yyyy-MM-dd HH:mm:ss") ) ) ) ); } var random = new Random(42); var batch = new List<Order>(); for (var i = 1; i <= 10000; i++) { batch.Add(new Order { Id = i, OrderNo = $"ORDER-{i:000000}", Status = random.Next(0, 5), CreateTime = DateTime.Now.AddMinutes(-random.Next(0, 60 * 24 * 365)) }); } client.IndexMany(batch);

实际导出场景里，如果数据真的很大，建议走BulkAll或BulkAsync，不要再像测试代码一样用IndexMany。IndexMany本质上是一次 bulk，数据条数一多，请求体太大，ES 会直接拒绝。十万条以上就得拆批量，每条 batch 控制在 5000 到 10000 条比较稳。

3. Scroll 查询完整代码实现

3.1 第一次查询：初始化滚动上下文

Scroll 的第一次查询和普通Search几乎一样，但多了两个关键参数：.Scroll("1m")和.Size(500)。

var response = client.Search<Order>(s => s .Index("orders") .Scroll("1m") .Size(500) .Sort(sort => sort .Field("_doc") ) .Query(q => q .Bool(b => b .Filter(f => f .Term(t => t.Status, 1) ) ) ) );

Scroll("1m")表示当前滚动上下文保留 1 分钟。这个时间很关键，后面调优部分细说。.Size(500)是每一批返回条数，不是总返回条数，它也影响 ES 每个分片取多少数据。

这里我特意加了.Sort(sort => sort.Field("_doc"))。普通查询为了追求稳定排序，会按业务字段排序，但 Scroll 本身是顺序遍历，你不需要全局稳定的业务排序，用_doc排序可以避免协调节点做代价高昂的深排序。实测下来，百万级数据用业务字段排序和用_doc排序，第一批返回速度差好几倍。

拿到ScrollId后，先判断请求是否成功：

if (!response.IsValid) { Console.WriteLine($"首次 Scroll 查询失败: {response.DebugInformation}"); return; } var scrollId = response.ScrollId; Console.WriteLine($"首批返回 {response.Documents.Count} 条，ScrollId: {scrollId}");

3.2 循环取后续批次：ScrollId 续滚

第一次查询已经返回了第一批Documents。要想取下一批，就用返回的ScrollId去调Scroll方法：

var hasMore = true; var totalProcessed = 0; while (hasMore) { foreach (var order in response.Documents) { // 在这里处理每一条数据，比如写库、发消息、写文件 ProcessOrder(order); totalProcessed++; } if (response.Documents.Count == 0) { hasMore = false; break; } response = client.Scroll<Order>("1m", response.ScrollId); if (!response.IsValid) { Console.WriteLine($"续滚失败: {response.DebugInformation}"); break; } scrollId = response.ScrollId; }

这段逻辑里有一个容易写错的地方：Scroll的返回值里也会有Documents，但你要拿它来判断是否还有更多数据。如果返回的这批Documents为空，说明已经滚到末尾了，这时要跳出循环。

另外，每次调用Scroll后，ScrollId理论上还是同一个字符串，但出于保险，我每次都从response.ScrollId重新取值。某些 ES 版本或代理环境下，滚动上下文 id 可能会更新，千万不要在循环里写死第一次拿到的变量。

还有一个必须注意的点：千万不要在循环里对每条数据做慢操作，比如同步调用外部接口、逐条写数据库。我最初是把ProcessOrder写成同步逐条INSERT，结果一万条数据跑了半个小时，Scroll 的 1 分钟上下文早超时了，还在处理第二批就开始报错。后面改成批量入库，每条批次先攒 500 条再统一写入，速度提升了几个数量级。

3.3 查询结束必须做的清理：ClearScroll

Scroll 上下文不是自动释放的，特别是在数据正常拉完的情况下，ES 要等scroll参数指定的时间到期才会清理。如果你设置的是10m甚至更久，而循环又很快跑完了，那么这些上下文会一直占着内存，直到超时被回收。

正确的做法是在循环结束后立即清理：

var clearResponse = client.ClearScroll(c => c.ScrollId(scrollId)); if (clearResponse.IsValid) { Console.WriteLine("Scroll 上下文已清理"); }

如果是异常退出，也要用try/finally保证清理。我看到很多同学只写了主流程，忘了finally，异常一抛，Scroll 上下文就泄漏了。长周期任务频繁运行，最终会拖垮 ES。

我建议的完整结构是：

var scrollId = string.Empty; try { var response = client.Search<Order>(...); scrollId = response.ScrollId; while (true) { // 处理 response.Documents if (response.Documents.Count == 0) break; response = client.Scroll<Order>("1m", response.ScrollId); } } finally { if (!string.IsNullOrEmpty(scrollId)) { client.ClearScroll(c => c.ScrollId(scrollId)); } }

3.4 可直接运行的完整示例

下面是一个完整可运行的控制台示例，只保留了最关键的分支结构，方便直接改造成你自己的服务：

using System; using System.Collections.Generic; using System.Linq; using Nest; public class Order { public long Id { get; set; } public string OrderNo { get; set; } public int Status { get; set; } public DateTime CreateTime { get; set; } } class Program { static void Main() { var settings = new ConnectionSettings(new Uri("http://localhost:9200")) .DefaultIndex("orders") .BasicAuthentication("elastic", "你的密码") .RequestTimeout(TimeSpan.FromMinutes(2)); var client = new ElasticClient(settings); var scrollId = string.Empty; var total = 0; try { var response = client.Search<Order>(s => s .Index("orders") .Scroll("1m") .Size(500) .Sort(sort => sort.Field("_doc")) .Query(q => q.Bool(b => b .Filter(f => f.Term(t => t.Status, 1)) )) ); if (!response.IsValid) { Console.WriteLine($"无结果或查询失败: {response.DebugInformation}"); return; } scrollId = response.ScrollId; while (response.Documents.Count > 0) { foreach (var order in response.Documents) { Console.WriteLine($"处理订单: {order.OrderNo}"); total++; } response = client.Scroll<Order>("1m", response.ScrollId); } Console.WriteLine($"共处理 {total} 条数据"); } finally { if (!string.IsNullOrEmpty(scrollId)) { var clearResponse = client.ClearScroll(c => c.ScrollId(scrollId)); Console.WriteLine(clearResponse.IsValid ? "滚动上下文已清理" : $"清理失败: {clearResponse.DebugInformation}"); } } } }

这段代码跑起来，你会看到它不停地输出“处理订单”，每一批 500 条，直到把Status=1的订单全部处理完。这就是 Scroll 的最基本用法。

4. 实用参数调优与踩坑记录

4.1 Scroll Timeout 设置逻辑

Scroll("1m")里的1m代表滚动上下文存活时间为 1 分钟。很多初学者会问：是不是设置得越久越安全？其实不是。

正确逻辑是：滚动上下文从你最后一次调Scroll请求才开始计时。也就是说，如果你设置5m，那么每次续滚成功，后续 5 分钟内只要再次续滚，上下文都不会丢。但代价是，如果查询中途因为某些异常退出，或者你忘了清理，这 5 分钟内该上下文会一直占着节点资源。

我实际测试下来，Size=1000，每批数据本地写库耗时大约在 10 秒左右，那么设置1m是够用的。如果每批处理耗时接近 60 秒，就必须调大 timeout，比如2m或5m。更好的做法是把处理改成异步批量写入，减少单批耗时，而不是粗暴地把 timeout 拉长。

一个很典型的报错：No search context found for id [xxxx]。出现这个报错，基本就是这批数据处理得太慢，超出了scroll时间，ES 已经把上下文回收了。解决办法不是把 size 调小就是缩短单批处理时间，或者加大 timeout，三者根据瓶颈取舍。

4.2 Size 设置多大合适

Size是每批返回的文档数量。它不是设置越大越爽，因为 ES 每个分片会各自维护游标，协调节点要汇总各分片返回的数据。比如索引有 5 个分片，你设置Size=5000，实际每批最多可能拉到 25000 条，对你本地内存和后续处理都有压力。

我的经验是：

还要考虑_source大小。如果订单记录有很多大字段，比如备注、扩展 JSON、详细日志，建议在查询时只取出需要的字段：

.Source(sf => sf .Includes(i => i .Field(f => f.OrderNo) .Field(f => f.CreateTime) ) )

这样能显著降低网络传输和本地反序列化成本。我在导出 300 GB 索引时，只取核心字段后，同样的机器能把吞吐从 5000 条/秒提升到 3 万条/秒，效果非常明显。

4.3 常见异常与排查

下面是这一路踩坑整理出来的速查表：

关于too many scroll contexts，我特别想多说一句。ES 默认一个节点能创建的 Scroll 上下文数量是有限制的（search.max_open_scroll_context，默认 500）。如果你们有多个定时任务同时在导数据，又没有及时清理，很容易就把这个额度打满。我处理过一次线上事故，最终日志全是这个报错，排查后发现是同事一个迁移任务在finally里忘了写 ClearScroll。所以无论主流程多么简单，上下文清理请一定贯彻到底。

4.4 实战经验：对象映射、DateTime 与异步处理

Scroll 查询最终要把 JSON 反序列化成 C# 对象，这里最常见的问题是 DateTime 映射。ES 里日期字段有两种典型存法：一种是毫秒时间戳，一种是格式化字符串。如果你在 C# 模型里写的是DateTime，但 Mapping 没有配置，ES 默认可能把它映射成long，反序列化时就会失败。

我在测试数据里使用了：

.Properties(p => p .Date(d => d .Name(n => n.CreateTime) .Format("yyyy-MM-dd HH:mm:ss") ) )

这样CreateTime才能稳定映射到 C# 的DateTime。如果别人给你的索引已经存在，且字段是 long 时间戳，那就改用DateTimeOffset或在模型里定义 long 属性然后手动转换。

还有一点，Scroll 拉出来的数据不是全局有序的，除非你用自定义 Sort 强制排序。但前面我说过，尽量不要为了 Scroll 做深排序。如果你的业务要求必须按某个业务字段顺序处理，Scroll 就不合适，建议换成search_after配合稳定Sort。

关于异步，如果你的项目本身是异步接口，尽量用SearchAsync和ScrollAsync。这里有一个容易忽略的点：ScrollAsync的返回值里依然要更新ScrollId。有些同学在循环里捕获旧的scrollId变量，却忘记用response.ScrollId覆盖，最后要么拿到第一页永远重复，要么在滚动失败后找错误上下文。

最后聊一下分片和切片。如果数据量非常大，比如千万级别，单线程 Scroll 已经慢了，可以尝试 Sliced Scroll，把一个 Scroll 上下文按 slice 拆分，开多个线程并行拉取。NEST 里可以用Slice参数，但实际生产用起来对资源占用要求更高。我的建议是，先跑通单线程，压测达到瓶颈后再考虑切片并行，不要一上来就整并行。

我个人的习惯是写一个通用的ScrollHelper，内部封装try/finally和ClearScroll，外部只需要传入查询描述和一个对每批数据做处理的委托。这样调用方永远不会忘记清理上下文，逻辑也干净很多。Scroll 解决的是“取数”的问题，真正拖慢进度的往往是处理端，别在导数据时忽略数据库写入和网络开销，这两块的优化空间通常比 ES 本身更大。