1. 亿级数据导出时游标突然失效MongoCursorNotFoundException 到底在说什么com.mongodb.MongoCursorNotFoundException: Query failed with error code -5这个报错本质上是 MongoDB 服务端告诉你你手里那个游标 ID我这边已经找不到了。它不是一个网络错误也不是权限错误而是游标生命周期管理出了问题。MongoDB 的find()返回的从来不是一份完整结果集而是一个游标句柄。服务端默认给这个句柄设了 10 分钟的空闲超时一旦超过这个时间没有getMore请求进来服务端就会回收游标及其占用的资源。等你下次再拿同一个游标 ID 去取下一批数据时服务端只能回你一句 Cursor ... not found on server。这个场景在 DataX 自定义 mongoreader、Spark 读取、离线导数任务里特别常见。数据量上亿、单批处理慢、线上业务库读限速、网络抖动任何一个因素都可能让一个 batch 的处理时间超过 10 分钟。我遇到过最典型的一次是任务前 40 分钟跑得好好的第 41 分钟开始批量报 -5日志里游标 ID 每次都不一样但错误信息结构完全一致。这说明不是某个游标坏了而是整个读取节奏已经跟不上服务端的回收节奏。要解决它核心思路只有两条要么让游标活得比你的处理时间长要么让你的处理速度快到游标来不及超时。围绕这两条思路可以展开四种可落地的处理方式no_cursor_timeout配合 try-finally 手动关闭、调整batch_size控制单批拉取量、用maxTimeMS给查询本身设上限、以及从索引和查询计划层面减少单次扫描耗时。这四种方式不是互斥的实际生产里往往是组合使用。另外还有一个容易被忽略的点多环境开发、测试、生产的 MongoDB 连接凭据散落在各个配置文件里一旦要排查是哪个环境、哪个库、哪个账号触发的游标问题光找连接串就要花半天。这篇会把连接参数和游标配置片段都给全同时演示怎么用 TaoToken 的统一 Key/API 通道把多环境凭据集中管起来让排障时能快速定位到具体环境。下面从问题复现开始一步步给可复制的配置和验证命令。2. 用 TaoToken 统一管理多环境 MongoDB 连接凭据与 API 通道在动手改游标参数之前先把连的是哪个库、用的哪个账号这件事理清楚。很多游标超时排查到最后发现是测试环境的任务误连了生产从库或者某个环境的连接串里readPreference配错了导致读请求打到了负载最高的节点上。凭据一多这种低级错误就会反复出现。TaoToken 在这里的角色是统一凭据与 API 通道。你可以把不同环境dev/staging/prod的 MongoDB 连接信息、以及调用大模型做日志分析时用的 API Key都收敛到一套 Key 管理体系下。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM。注意TaoToken 管的是凭据和调用通道不是替你连 MongoDBMongoDB 的连接还是走你自己的驱动和连接串只是连接串里的敏感字段可以从统一通道取避免硬编码散落。具体操作上先在控制台创建项目拿到一个统一的 API Key。控制台地址带 deep linkhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。然后在项目里配置环境变量把 MongoDB 的 URI 和 TaoToken 的 Key 分开存放。我习惯用.env加一层读取逻辑这样本地调试和线上部署用的是同一套代码只是环境变量不同。# .env 示例不要提交到 git MONGO_URI_PRODmongodb://reader_user:******mongo-prod-01:27017,mongo-prod-02:27017/biz_db?replicaSetrs0readPreferencesecondaryPreferred MONGO_URI_STAGINGmongodb://reader_user:******mongo-stg-01:27017/biz_db TAOTOKEN_API_KEYsk-xxxxxxxxxxxxxxxx TAOTOKEN_BASE_URLhttps://taotoken.net/api读取的时候用一段 Python 把环境变量注入到连接参数里顺便把游标相关配置也集中定义后面四种处理方式都从这里取参数import os from pymongo import MongoClient def build_client(envprod): uri os.environ[fMONGO_URI_{env.upper()}] client MongoClient( uri, maxPoolSize50, serverSelectionTimeoutMS5000, socketTimeoutMS120000, # 单次 socket 读超时别和游标超时混淆 retryWritesTrue, ) return client client build_client(prod) db client[biz_db] col db[order_archive]这里要区分两个超时socketTimeoutMS是驱动层面的网络读超时maxTimeMS是服务端查询执行超时而游标的 10 分钟空闲超时是服务端游标生命周期三者互不替代。很多人把socketTimeoutMS调大以为能解决 -5其实没用因为 -5 是服务端主动回收游标不是网络断了。如果你还要用大模型辅助分析报错日志比如把MongoCursorNotFoundException的堆栈丢给模型让它归纳触发条件可以走模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。调用时 Base URL 填https://taotoken.net/apiKey 用上面那个Model ID 按你选的填。这样日志分析和数据库连接用的是同一套凭据体系排查时不会因为 Key 混乱而误判环境。凭据集中之后接下来四种处理方式就可以在同一套连接配置上逐个验证改一个参数跑一次看日志里 -5 是否消失。3. 四种处理方式的可复制配置no_cursor_timeout、batch_size、maxTimeMS 与索引优化这一节给的是可以直接抄进项目的配置片段。四种方式我按改动成本从低到高排你可以先试成本低的不行再叠加。3.1 no_cursor_timeout 配合 try-finally 手动关闭这是最直接的解法。find()时传no_cursor_timeoutTrue服务端就不会因为空闲而回收游标。但代价是如果程序异常退出、断电、断网游标不会被自动释放会一直挂在服务端占资源。所以必须用try/finally保证close()一定执行。cursor col.find( {status: archived, created_at: {$lt: 2024-01-01}}, no_cursor_timeoutTrue, batch_size500, ) try: for doc in cursor: parse_and_write(doc) finally: cursor.close() # 无论是否异常都必须关注意no_cursor_timeoutTrue在分片集群上对 mongos 的行为要留意某些版本下 mongos 仍可能因负载均衡回收游标所以它不能 100% 保证。实测下来副本集场景下这个参数最稳。3.2 batch_size 控制单批拉取量默认第一批 101 个文档或 1MB之后每批 4MB。如果你的单文档很大4MB 可能只有几十条处理慢就容易超时。把batch_size调小让每批消费时间远小于 10 分钟是更稳妥的做法。cursor col.find( {status: archived}, batch_size200, # 每批 200 条消费时间可控 no_cursor_timeoutFalse, # 保持默认超时靠速度取胜 ) for doc in cursor: parse_and_write(doc)batch_size不是越小越好。太小会增加getMore次数网络往返变多整体吞吐下降。我一般从 200 起调观察单批耗时控制在 1 分钟以内比较安全。3.3 maxTimeMS 给查询本身设上限maxTimeMS限制的是服务端执行查询的时间超时会抛ExceededTimeLimit而不是 -5。它的作用是防止某个慢查询长时间占用资源间接减少游标被拖死的概率。适合配合索引一起用。cursor col.find( {status: archived, region: cn-east}, maxTimeMS30000, # 单次查询最多 30 秒 batch_size500, )如果maxTimeMS频繁触发说明查询本身有问题该去查索引了而不是继续调大这个值。3.4 索引优化减少单次扫描游标超时的根因往往是查询太慢。用explain()看执行计划确认是否走了索引。db.order_archive.find( { status: archived, created_at: { $lt: ISODate(2024-01-01) } } ).explain(executionStats)重点看executionStats.totalDocsExamined和totalKeysExamined。如果totalDocsExamined远大于返回条数说明在扫集合。建复合索引db.order_archive.createIndex( { status: 1, created_at: 1 }, { background: true, name: idx_status_created } )索引建好后同样的查询totalDocsExamined会大幅下降单批处理变快游标自然不容易超时。四种方式对照如下方式改动点适用场景风险no_cursor_timeoutfind 参数单批处理必然超 10 分钟游标泄漏必须 finally closebatch_sizefind 参数单文档大、批处理慢太小增加网络往返maxTimeMSfind 参数防慢查询拖死触发后抛别的异常索引优化数据库层查询本身慢建索引影响写入实际项目里我通常是索引优化 batch_size try-finally三件套no_cursor_timeout只在确实需要时开。4. 验证游标不再超时具体命令与日志检查动作改完配置不能只看没报错就完事要有明确的验证动作。下面给一套可执行的验证流程。第一步先用小批量跑通确认游标能正常关闭。在 Python 里加日志打印游标 ID 和每批耗时import time, logging logging.basicConfig(levellogging.INFO) cursor col.find({status: archived}, batch_size200, no_cursor_timeoutTrue) batch_start time.time() count 0 try: for doc in cursor: count 1 if count % 200 0: cost time.time() - batch_start logging.info(fprocessed{count} batch_cost{cost:.2f}s cursor_id{cursor.cursor_id}) batch_start time.time() finally: cursor.close() logging.info(fcursor closed, total{count})跑起来后看日志如果每批batch_cost都远小于 600 秒且最后有cursor closed说明游标生命周期可控。第二步在 MongoDB 服务端确认游标没有堆积。用db.serverStatus().metrics.cursor看当前打开的游标数db.serverStatus().metrics.cursor正常情况open.total应该在一个稳定范围任务结束后回落到基线。如果任务停了但open.total一直不降说明有游标泄漏回去检查finally是否真的执行了。第三步用currentOp查长时间运行的游标操作db.currentOp({ command.find: { $exists: true }, secs_running: { $gt: 300 } })如果能看到你的查询且secs_running很大说明单批处理确实慢需要回到第 3 节调batch_size或补索引。第四步把报错日志和验证日志一起丢给模型做归纳走模型对话入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 让它对比改前改后的日志差异确认 -5 是否真的消失。这一步不是必须但在多环境排查时能省不少时间。验证通过的标准是连续跑完一个完整任务周期日志里没有MongoCursorNotFoundExceptioncursor closed正常打印服务端open.total回落。三个条件都满足才算真的修好。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错对照排障时遇到的报错往往不止 -5 一个下面把高频错误和对应动作列清楚。401 Unauthorized如果出现在调用 TaoToken API 时说明 Key 无效或没带上。检查请求头Authorization: Bearer key确认 Key 是从控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成的且没有多余空格。如果出现在 MongoDB 连接时是数据库账号密码或认证库authSource配错了和 TaoToken 无关。local proxy failed这个通常出现在本地开发环境配置了代理但代理不可用。检查环境变量HTTP_PROXY/HTTPS_PROXY是否指向了一个已经关掉的本地端口。清掉这两个变量再试。注意这里说的是本地开发工具的代理配置问题不是让你去配什么网络通道。reading choices相关报错多出现在调用大模型接口时响应体解析失败常见原因是 Base URL 配错。确认填的是https://taotoken.net/api而不是带/v1或其他路径。Model ID 要和请求体里的model字段一致不一致会返回模型不存在或解析异常。OAuth报错如果用的是 Claude Code 或类似工具OAuth 流程失败通常是回调地址或 token 过期。重新走一遍授权确认系统时间准确时间偏差过大会导致 token 校验失败。如果工具支持 API Key 模式直接切到 Key 模式更省事。涉及 Claude Code 接入时三件套必须写全Base URL 填https://taotoken.net/apiKey 用控制台生成的Model ID 按实际选的填。缺任何一个都会报错。Cline MCP 配置同理settings.json里要把这三项都写进去。Codex 的auth.json也是同样结构Base URL、Key、Model ID 一个不能少。{ base_url: https://taotoken.net/api, api_key: sk-xxxxxxxxxxxxxxxx, model: claude-sonnet-4-20250514 }游标超时排查时如果同时出现 -5 和上面这些报错先解决凭据和通道问题再回头看游标否则日志会被干扰。6. 长期跑批量任务与 Agent 场景把游标配置和凭据管理固化下来单次修好游标超时不难难的是让长期运行的批量任务和 Agent 场景稳定。我的做法是把第 3 节的四种配置固化成一个可复用的读取函数参数从环境变量取不同任务只改查询条件和 batch_size。def safe_iterate(col, query, batch_size200, use_no_timeoutTrue): cursor col.find( query, batch_sizebatch_size, no_cursor_timeoutuse_no_timeout, maxTimeMS60000, ) try: for doc in cursor: yield doc finally: cursor.close()这样任何任务调用它都自带 try-finally 保护不会漏关游标。凭据方面多环境的 MongoDB URI 和 TaoToken Key 都走环境变量配合 Coding Plan 做长期编码和 Agent 任务时不用每次手动切 Key。Coding Plan 入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言 SDK 的 Base URL 和鉴权写法。最后提醒一个实操细节no_cursor_timeoutTrue在任务被 kill -9 时finally不会执行游标仍会泄漏。所以生产环境建议加一个定时巡检用db.currentOp找出超过阈值仍存活的游标手动 kill。这个巡检脚本本身也可以走统一 API 通道调用模型做异常归纳但核心还是靠数据库侧的监控。把读取函数、凭据管理、巡检三件事都固化下来游标超时才会从反复踩坑变成一次性解决。