1. 百万级文档导出为什么 fromsize 会先崩先说结论Elasticsearch 的from size深度分页在数据量上到十万级以后基本就不可用了。你如果做过日志导出、订单对账、全量重建索引这类活大概率踩过这个坑——翻到第 500 页请求直接超时或者协调节点内存被打爆。原因不复杂。from size的工作方式是每个分片都要把自己命中的前from size条文档取出来交给协调节点协调节点再全局排序最后丢掉前from条返回size条。也就是说你只要from100000size105 个分片每个都要吐 100010 条文档上来协调节点要排序 500050 条只为给你 10 条。这个代价随from线性增长翻得越深越慢最后必然 OOM 或超时。scroll就是为这个场景设计的。它像数据库里的游标 cursor第一次 search 时告诉 ES「帮我保持一个搜索上下文」ES 返回一个scroll_id之后你拿着这个 id 一批一批往后取直到hits数组为空。它不追求实时性返回的是 search 发生那一刻的索引快照后续的增删改不会影响这次滚动结果。所以它特别适合「一次性导出百万级文档」「用不同配置重建索引」这类离线批处理任务。这篇就聚焦一个具体场景一次性导出百万级文档。我会把三段可复制的请求配置给全——创建 scroll、续读 scroll、清理 scroll再补上怎么用_nodes/stats验证上下文真的释放了。热词里的scroll5m、size、_doc排序、clear_scroll都会落到具体参数上。适合谁看正在做数据迁移、离线报表、全量导出的后端和运维同学以及被深度分页坑过一次、想彻底搞明白 scroll 生命周期的人。需要提醒一句scroll 上下文是占资源的。它会让旧 segment 无法被合并删除持续占用文件句柄和堆内存。所以「用完必须清」不是可选项是硬性要求。下面每一步我都会把清理动作带上。2. 动手前TaoToken 接入与 scroll 环境准备在写请求之前先把调用链路搭好。很多同学本地 curl 能通一放到服务里就 401问题往往出在鉴权和 Base URL 上。这里我用 TaoToken 作为统一入口来演示它的好处是 Base URL 和 Key 管理集中切换模型或环境时不用改一堆配置。先明确三件套这是后面所有配置的基础Base URLhttps://taotoken.net/apiAPI Key在控制台生成形如sk-xxxxModel ID按你实际使用的模型填控制台入口在这里生成 Key 后复制保存页面只显示一次https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite如果你要批量跑导出脚本建议把 Key 放到环境变量里别硬编码进代码export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api验证 Key 是否可用最直接的方式是发一个最小请求。下面这个 curl 用来确认鉴权链路通了注意这是验证接入不是 ES 请求curl -sS ${TAOTOKEN_BASE_URL}/v1/models \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json返回里能看到模型列表说明 Key 和 Base URL 都没问题。如果这里就报 401先别往下走去控制台确认 Key 有没有复制全、有没有过期。API Key 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档在这里遇到路径或参数疑问可以对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite至于 Elasticsearch 本身你需要确认两件事一是集群版本7.x 和 8.x 在 scroll 的 URL 写法上略有差异8.x 推荐用请求体传scroll_id二是目标索引的文档量级。用_count先摸个底curl -sS -XGET http://localhost:9200/your_index/_count?pretty拿到总数后估算批次数总文档数 / size。比如 100 万文档、size1000大约 1000 批。这个数字决定了你脚本的循环上限也决定了 scroll 上下文要保持多久。这里有个容易忽略的点scroll 的scroll参数不是「总时长」而是「每批之间的间隔上限」。你设scroll5m意思是「如果 5 分钟内没有下一次 scroll 请求上下文就过期释放」。每次续读都会重置这个计时器。所以导出脚本只要每批间隔小于 5 分钟就不会中途失效。反过来如果你设scroll1m但每批处理要 2 分钟上下文会在你处理数据时悄悄过期下一批直接报search_context_missing_exception。环境准备好后我们进入正题。下面三段配置可以直接复制改索引名使用。3. 三段可复制配置创建、续读、清理 scroll这一节是全文的核心我把三段请求拆开讲每段都给完整可复制的配置并说明每个参数为什么这么设。3.1 创建 scrollscroll5m size _doc 排序第一段请求负责建立搜索上下文。关键参数有三个scroll5m、size、排序用_doc。curl -sS -XPOST http://localhost:9200/your_index/_search?scroll5mpretty \ -H Content-Type: application/json \ -d { size: 1000, query: { range: { create_time: { gte: 2024-01-01T00:00:00, lt: 2025-01-01T00:00:00 } } }, sort: [ _doc ], _source: [id, create_time, amount] }逐项说明scroll5m表示上下文保持 5 分钟。为什么是 5m 而不是 1m因为导出脚本每批要写文件、做转换1 分钟太紧网络抖动一下就过期。5 分钟是实践中比较稳的值既不会让上下文占太久又留足处理时间。size1000是每批返回的文档数。注意这个 size 是每个分片的不是整个请求的。如果你有 5 个分片size1000实际每批最多返回 5000 条。这一点和普通 search 不同很多人第一次用 scroll 会算错批次数。想精确控制每批总量要么按分片数折算要么用单分片索引。sort: [_doc]是最关键的一步。默认排序会走打分和全局排序代价高。用_doc排序直接按文档在索引中的物理顺序返回跳过了打分和排序开销是 scroll 导出场景下最快的排序方式。如果你确实需要按时间排序那就得接受排序代价但导出场景通常不关心顺序_doc是首选。_source字段过滤也建议加上。导出百万文档时如果每个文档都带一堆用不上的字段网络传输和序列化都是浪费。只取你真正要的字段。返回结果里你会拿到两样东西_scroll_id和第一批hits。_scroll_id是个长字符串形如c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1。每次续读都会返回一个新的_scroll_id只有最新的那个能用旧的会失效。这是新手最容易踩的坑拿着第一批的 id 一直续读读到第二批就报错。3.2 续读 scroll用最新 scroll_id 循环取批第二段请求负责往后取。注意 URL 里不能带索引名索引在创建时已经绑定了。curl -sS -XPOST http://localhost:9200/_search/scroll?pretty \ -H Content-Type: application/json \ -d { scroll: 5m, scroll_id: c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1 }每次请求都要带上scroll参数它会重置上下文的过期计时器。scroll_id用上一批返回的最新值。循环终止条件是hits.hits数组为空——不是total为 0而是这一批实际返回的文档数为 0。用 Python 写循环大概是这样import requests ES http://localhost:9200 INDEX your_index SCROLL_TTL 5m BATCH 1000 def export_all(): # 第一批 resp requests.post( f{ES}/{INDEX}/_search?scroll{SCROLL_TTL}, json{ size: BATCH, query: {match_all: {}}, sort: [_doc], _source: [id, create_time, amount], }, ).json() scroll_id resp[_scroll_id] total 0 batch_no 0 while True: hits resp[hits][hits] if not hits: break batch_no 1 total len(hits) # 这里写你的落盘/转换逻辑 print(fbatch {batch_no}, got {len(hits)}, total {total}) resp requests.post( f{ES}/_search/scroll, json{scroll: SCROLL_TTL, scroll_id: scroll_id}, ).json() # 关键更新为最新的 scroll_id scroll_id resp[_scroll_id] # 循环结束清理 requests.delete( f{ES}/_search/scroll, json{scroll_id: [scroll_id]}, ) print(fdone, total {total}) export_all()注意scroll_id resp[_scroll_id]这一行在循环里每批都更新。这是保证不报search_context_missing_exception的关键。3.3 清理 scrollclear_scroll 的三种写法第三段请求负责释放上下文。有三种写法按场景选。清理单个 scroll_idcurl -sS -XDELETE http://localhost:9200/_search/scroll?pretty \ -H Content-Type: application/json \ -d { scroll_id: [c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1] }清理多个 scroll_id批量任务里很有用curl -sS -XDELETE http://localhost:9200/_search/scroll?pretty \ -H Content-Type: application/json \ -d { scroll_id: [ c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1, aGVuRmV0Y2g7NTsxOnkxaDZ ] }清理所有 scroll 上下文慎用会清掉集群上所有人的 scrollcurl -sS -XDELETE http://localhost:9200/_search/scroll/_all?pretty_all这个操作在生产环境要非常小心。如果集群上有其他业务正在跑 scroll你一个_all把别人的上下文也清了对方直接报错。所以除非你确认这是独占集群否则永远用指定scroll_id的方式清理。还有一个细节scroll_id也可以放在查询字符串里传多个用逗号分隔curl -sS -XDELETE http://localhost:9200/_search/scroll?scroll_idid1,id2pretty但请求体方式更清晰推荐用 body。到这里三段配置就齐了。创建、续读、清理构成一个完整的生命周期。下一节我们验证它真的生效了。4. 验证请求与成功结果用 _nodes/stats 确认上下文释放写完脚本不代表就对了。scroll 上下文有没有真的释放得用数据说话。ES 提供了_nodes/stats接口能看到当前打开的搜索上下文数量。先看关键指标curl -sS -XGET http://localhost:9200/_nodes/stats/indices/search?pretty返回里关注这两个字段{ nodes: { node_id_xxx: { indices: { search: { open_contexts: 0, scroll_total: 12, scroll_time_in_millis: 3600000, scroll_current: 0 } } } } }open_contexts是当前打开的搜索上下文总数scroll_current是当前活跃的 scroll 上下文数。导出任务正常结束后这两个值应该回到 0。如果任务结束了但scroll_current还是几十上百说明你的清理没生效上下文在泄漏。验证流程建议这样走第一步任务开始前记录基线curl -sS -XGET http://localhost:9200/_nodes/stats/indices/search?pretty \ | grep -E open_contexts|scroll_current第二步跑导出脚本中途再查一次应该能看到scroll_current大于 0说明上下文确实建立了。第三步脚本跑完包含 clear_scroll后再查scroll_current应该回到基线值。如果没回检查两件事一是脚本的清理请求有没有真的发出去看日志二是清理用的scroll_id是不是最新的那个。这里有个实测经验如果你在循环里每批都更新了scroll_id但清理时用的是第一批的旧 id清理会失败。因为旧 id 早就失效了ES 找不到对应上下文返回succeeded: false。所以清理一定要用循环结束时的最新scroll_id。清理成功的返回长这样{ succeeded: true, num_freed: 1 }succeeded: true且num_freed等于你传入的 id 数量才算真清掉了。如果succeeded: false去查_nodes/stats确认上下文还在不在再决定要不要用_all兜底再次提醒_all慎用。另外scroll 上下文即使你不主动清超时后也会自动释放。但「自动释放」的代价是在超时之前它一直占着文件句柄和堆内存还会阻止旧 segment 合并。百万级导出如果每批都留一个没清的上下文跑几十批就是几十个上下文挂着节点文件句柄很快吃紧。所以别依赖自动过期主动清才是正解。5. 本篇常见错排查401、search_context_missing、OOM 逐个拆这一节把导出过程中最常撞见的几个报错列出来对照着查。报错一401 Unauthorized / local proxy failed如果你是通过 TaoToken 这类统一入口调用401 通常出在 Key 或 Base URL 上。先确认三件套是否一致{ base_url: https://taotoken.net/api, api_key: sk-你的key, model_id: 你的模型ID }local proxy failed一般是本地代理配置和 Base URL 冲突检查环境变量里有没有残留的HTTP_PROXY/HTTPS_PROXY指向了错误地址。清掉再试unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy报错二search_context_missing_exception完整报错类似{ error: { root_cause: [ { type: search_context_missing_exception, reason: No search context found for id [12345] } ], type: search_phase_execution_exception }, status: 404 }三个原因按概率排一是用了旧的scroll_id没在循环里更新二是scroll间隔设太短、处理太慢导致上下文过期三是上下文被别的_all清理误伤。对应解法循环里每批更新 id、把scroll调到 5m 或更长、别在生产用_all。报错三reading choices / 解析响应失败这类报错通常出现在客户端解析响应时比如把 scroll 响应当成普通 search 响应解析找不到hits.hits就崩了。scroll 的响应结构和普通 search 一致但第一批之后没有total字段的完整信息聚合结果也只在第一批返回。如果你的代码依赖total做进度条记得在第一批就把它存下来。报错四OOM / 协调节点内存打满如果size设得太大比如 10000或者分片数多每批返回的文档量会爆炸。size是每分片的5 分片 × 10000 每批 5 万文档协调节点要缓存这些再返回。建议size控制在 1000 到 5000 之间分片多就取小值。报错五文件句柄耗尽报错类似Too many open files。scroll 上下文会持有旧 segment 的文件句柄大量未清理的上下文会耗尽句柄。除了及时清理还要检查节点的ulimit -n配置。用_nodes/stats看open_contexts持续增长就是泄漏信号。排查顺序建议先看_nodes/stats的scroll_current确认上下文状态再看脚本日志里scroll_id有没有更新最后查网络和鉴权。大部分问题都出在scroll_id没更新和清理没执行这两点上。6. 长期跑导出任务把接入和调度固定下来单次导出跑通之后真正麻烦的是「每周都要跑一次」这种长期任务。这时候把接入配置和调度逻辑固定下来比每次手动敲 curl 靠谱得多。接入层建议统一走 TaoTokenBase URL 固定为https://taotoken.net/apiKey 放环境变量或密钥管理服务别写死在脚本里。需要长期跑编码类、Agent 类任务的话Coding Plan 的额度管理比按次调用更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite调度层把三段逻辑封装成函数create_scroll()、fetch_batch(scroll_id)、clear_scroll(scroll_id)。主流程用 try/finally 包住保证即使中途异常finally 里也会执行清理scroll_id None try: scroll_id create_scroll() while True: resp fetch_batch(scroll_id) scroll_id resp[_scroll_id] if not resp[hits][hits]: break # 处理数据 finally: if scroll_id: clear_scroll(scroll_id)这个finally是防泄漏的最后一道闸。哪怕处理逻辑抛异常清理也会执行。我见过太多脚本因为没写 finally异常退出后上下文挂在那跑几次就把节点句柄吃光了。监控层把_nodes/stats的scroll_current接进你的告警系统设个阈值比如持续 10 分钟大于 50 就告警。这样即使某次清理失败你也能第一时间发现而不是等节点崩了才去查。最后给一个实用技巧导出大索引时如果目标只是「把数据搬走」用_doc排序 _source过滤 合理size单批吞吐能比默认排序快好几倍。如果确实需要按时间排序考虑先用_doc全量导出再在本地排序通常比让 ES 全局排序更划算。scroll 的价值就在于它把「深分页」这个昂贵操作变成了「顺序读游标」这个廉价操作用对了能省下大量集群资源。