1. 从一次翻页超时说起Elasticsearch 深度分页到底卡在哪先说结论from size在浅分页时很舒服但一旦翻到几千页之后它就会变成一场灾难。我拿一个真实场景举例——日志检索系统里用户想导出最近 30 天的全部错误日志索引里大概有 800 万条文档每页 20 条。前端用from0size20翻到第 500 页时也就是from10000请求直接超时协调节点 CPU 飙到 90% 以上。原因不复杂。Elasticsearch 是分布式的一个索引默认 5 个主分片。当你执行from10000, size20时每个分片都要先取出自己前 10020 条命中的文档全部丢给协调节点协调节点再在内存里做一次全局排序最后丢掉前 10000 条只返回第 10001 到 10020 条。也就是说你只要 20 条集群却要搬运 5 × 10020 50100 条文档的排序开销。翻得越深这个数字越夸张内存和网络都被白白吃掉。这就是深度分页的代价根源结果集全局排序。只要还依赖全局排序成本就压不下来。那有没有办法绕开它有就是这篇要讲的scroll游标查询配合_doc排序把「全局排序」这个动作彻底去掉。scroll是什么、能做什么、适合谁简单说它像传统数据库里的 cursor游标先做一次查询初始化拿到一个_scroll_id然后一批一批地往后拉结果直到拉空为止。它适合大批量导出、离线全量扫描、数据迁移、批量重索引这类场景不适合给用户做实时翻页。因为它取的是某个时间点的快照初始化之后索引上的任何变化都会被忽略——这既是它的优点结果稳定、可重复也是它的限制不是实时的。如果你正在被Result window is too large或者翻页越来越慢折磨下面这套配置可以直接抄。同时我会把多工具调用时的凭证管理一起讲清楚因为实际项目里你往往不止一个脚本在查 ES统一 Key 能省掉很多麻烦。2. TaoToken 前置准备统一 Key 与 API 通道怎么配在写 scroll 脚本之前先解决一个容易被忽略的问题凭证管理。真实项目里你可能有一个 Python 导出脚本、一个定时任务、一个本地调试的 curl甚至一个接了模型能力的检索助手它们都要访问外部 API。如果每个工具各配一套 Key改一次就要改五六个地方还容易把 Key 硬编码进代码提交到仓库。我的做法是用 TaoToken 做统一入口把 Key 和 Base URL 收敛到一处。它的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 这个不加 UTM。你可以在控制台里创建和管理 Key然后所有工具都指向同一个 Base URL。具体操作路径是这样的先打开控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在里面生成一个 API Key然后到 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 复制出来。这个 Key 就是你后面所有脚本共用的凭证。这里要强调一个原则Base URL、Key、Model ID 三件套必须成组出现。不管你用的是 Cline、Codex 还是自己写的 HTTP 客户端只要涉及模型调用这三样缺一不可。Base URL 统一填https://taotoken.net/apiKey 填你刚复制的Model ID 按你实际要用的模型填。很多「连不上」的问题最后查出来都是这三者里有一个没对齐。如果你只是想先验证一下 Key 能不能用可以直接去模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条消息试试能正常返回就说明通道没问题。要是你打算长期跑编码或 Agent 类任务可以看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 把额度规划好避免跑一半断掉。把凭证这块理顺之后我们再回到 Elasticsearch 本身。下面进入正题先给可复制的 scroll DSL。3. 可复制的 scroll 查询 DSL 与 _doc 排序配置scroll 的核心就两步初始化查询拿到_scroll_id然后用这个 ID 反复拉取下一批。初始化时通过scroll参数设置游标窗口的过期时间比如1m表示一分钟。这个时间会在每次拉取时刷新所以它只需要够处理当前这一批而不是整个查询的总时长。窗口一直开着是要消耗资源的所以用完要尽早释放。先看初始化请求。注意sort用的是_doc这是整个方案里最关键的一行GET /old_index/_search?scroll1m { query: { match_all: {} }, sort: [_doc], size: 1000 }_doc是最有效的排序顺序。它让 Elasticsearch 仅仅从「还有结果的分片」返回下一批结果不需要做全局排序成本一下就降下来了。size这里设成 1000但要注意一个细节size是作用于单个分片的所以每个批次实际返回的文档数量最大是size × number_of_primary_shards。如果你有 5 个主分片一批最多可能拿到 5000 条别被这个数字吓到这是正常行为。初始化返回里会带一个_scroll_id是一串 base64 编码的长字符串。拿到它之后就可以反复调用_search/scroll接口拉下一批GET /_search/scroll { scroll: 1m, scroll_id: cXVlcnlUaGVuRmV0Y2g7NTsxMDk5NDpkUmpiR2FjOFNhNnlCM1ZDMWpWYnRROzEwOTk1OmRSamJHYWM4U2E2eUIzVkMxalZidFE7MTA5OTM6ZFJqYkdhYzhTYTZ5QjNWQzFqVmJ0UTsxMTE5MDpBVUtwN2lxc1FLZV8yRGVjWlI2QUVBOzEwOTk2OmRSamJHYWM4U2E2eUIzVkMxalZidFE7MDs }每次拉取都要重新带上scroll过期时间刷新窗口。还有一个必须记住的点每次返回都会给一个新的_scroll_id下一次请求必须用最新那个用旧的会拿不到正确结果。当某一批返回的hits.hits为空时说明所有匹配文档都处理完了。如果你用 Python 客户端封装会更省事但底层逻辑完全一样。下面这段是我常用的遍历骨架把凭证部分换成了统一入口的写法import requests BASE_URL https://taotoken.net/api # 统一 API 通道 API_KEY 你的_TaoToken_Key ES_HOST http://localhost:9200 INDEX old_index BATCH 1000 def scroll_all(): # 初始化 init requests.get( f{ES_HOST}/{INDEX}/_search?scroll1m, json{query: {match_all: {}}, sort: [_doc], size: BATCH}, ).json() scroll_id init[_scroll_id] hits init[hits][hits] total 0 while hits: for h in hits: total 1 # 这里处理你的文档比如写文件、迁移、重索引 # 用最新的 scroll_id 拉下一批 resp requests.get( f{ES_HOST}/_search/scroll, json{scroll: 1m, scroll_id: scroll_id}, ).json() scroll_id resp[_scroll_id] hits resp[hits][hits] # 用完主动清理释放游标资源 requests.delete(f{ES_HOST}/_search/scroll, json{scroll_id: [scroll_id]}) print(处理完成共, total, 条) scroll_all()注意最后那个DELETE /_search/scroll很多人会漏掉。虽然过期时间到了 ES 会自动释放但主动清理能立刻回收资源尤其在批量任务密集的时候很有用。4. 验证请求与成功结果分页遍历怎么确认没漏没重配置写完怎么确认它真的按预期工作我一般分三步验证。第一步先跑一次初始化看返回结构里有没有_scroll_id以及hits.total是不是你预期的量级。用 curl 最直观curl -X GET localhost:9200/old_index/_search?scroll1m -H Content-Type: application/json -d { query: { match_all: {} }, sort: [_doc], size: 1000 }返回里你会看到_scroll_id字段以及第一批hits.hits。如果hits.total.value是 8000000 这种量级说明查询命中正常。第二步连续拉两三批观察每批的条数和_scroll_id是否在变。正常情况下每批条数接近size × 主分片数且_scroll_id每次都是新的。如果某次返回的hits.hits是空数组说明已经到底了。第三步做一次「总数对账」。这是最容易被跳过、但最能暴露问题的一步。把遍历过程中累计的文档数和初始化时hits.total.value对比。如果两者一致说明没漏如果累计数偏少通常是中途用了旧的_scroll_id或者游标窗口过期了导致提前中断。我实测下来800 万条文档、每批 1000、5 个主分片整个遍历大概几分钟跑完内存占用平稳协调节点 CPU 也不再飙高。对比之前from size翻到第 500 页就超时差距非常明显。这里有个容易踩的坑scroll 取的是快照。初始化那一刻之后索引上的新增、更新、删除都不会反映在结果里。所以如果你在遍历过程中同时有写入最终对账可能对不上——这不是 bug是快照语义。做数据迁移时通常的做法是先停写、或者接受「迁移的是某个时间点的数据」迁移完再做增量补偿。另外_doc排序不保证跨批次的稳定顺序它只保证「不重复、不遗漏地取完所有匹配文档」。如果你需要结果有序那 scroll 就不是合适工具得换search_after配合业务字段排序。这一点要提前想清楚别等跑完才发现顺序不对。5. 本篇常见错排查401、游标失效与结果异常实际跑的时候报错基本集中在几类。我按真实遇到的频率排一下。第一类401 或鉴权失败。如果你在脚本里同时调了模型接口和 ES401 大概率出在模型侧。先检查三件套Base URL 是不是https://taotoken.net/apiKey 是不是从 API Keys 页面复制的最新值Model ID 有没有填对。三者任何一个不匹配都会 401。我见过最常见的是 Base URL 末尾多写了斜杠或者少写了/api这种低级错误排查起来最费时间。第二类local proxy failed或连接被拒。这类通常是你本地网络配置或客户端代理设置的问题不是服务端的事。检查一下你的 HTTP 客户端有没有走系统代理或者环境变量里有没有残留的代理配置。把代理相关设置清掉直连https://taotoken.net/api再试。第三类reading choices报错。这个一般出现在解析模型返回结构时说明返回体里没有预期的choices字段。多半是请求根本没成功返回的是一段错误 JSON而你的代码直接去取choices就崩了。正确做法是先判断状态码再解析。加一层if resp.status_code ! 200: print(resp.text)能立刻定位。第四类scroll 相关。典型报错是No search context found for id意思是游标已经过期或被释放了。原因通常是两批之间间隔超过了scroll设置的过期时间。解决办法是把过期时间调大一点比如5m或者检查你的处理逻辑是不是在某批上卡太久。另一个是_scroll_id用错——记住每次都要用最新返回的那个。第五类OAuth 相关报错。如果你用的是某些需要 OAuth 流程的客户端比如 Claude Code 这类报 OAuth 错误时先确认你的凭证是不是通过统一通道配置的。Claude Code 的接入可以看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的配置说明。如果是 Codex 的auth.json要确保里面的 Base URL、Key、Model ID 三件套和你在 TaoToken 控制台看到的一致。排查顺序建议固定下来先看状态码再看返回体原文最后才看业务逻辑。90% 的问题在前两步就能定位别一上来就怀疑代码。6. 把凭证和查询都收敛到一处写到这里scroll 的完整链路已经能跑通了初始化拿_scroll_id、用_doc排序去掉全局排序、循环拉取、主动清理。这套东西在批量导出和迁移场景里非常稳。最后说一个工程习惯。我现在的做法是所有外部调用的凭证都收敛到 TaoToken 一处管理ES 的连接信息走环境变量脚本里不出现任何硬编码的 Key。这样换 Key、加工具、做审计都只在一个地方改。需要新建或轮换 Key 的时候直接去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 操作就行。如果你还在用from size硬扛深度分页建议先拿一个中等规模的索引试一下 scroll感受一下 CPU 和耗时的差别。试完你大概率就不想回去了。