1. 从一次批量插入后的 CursorNotFound 说起
如果你在用 pymongo 往 MongoDB 里灌数据，尤其是爬虫抓完一批、准备insert_many()批量落库的时候，大概率见过这个报错：pymongo.errors.CursorNotFound: Cursor not found。它出现的位置往往很迷惑——不是插入那一步报的，而是你插完之后回头去遍历一个find()游标，遍历到一半突然断了。很多人第一反应是「MongoDB 挂了」或者「数据没写进去」，其实多数情况下是长链接在中间被服务端回收了，游标跟着失效。
这个场景特别容易出现在本地脚本和 AI 工具混用的开发者身上：一边跑着批量插入脚本，一边用 AI 编码助手帮你改查询逻辑，脚本执行时间被拉长，MongoDB 服务端默认的游标空闲超时（大约 10 分钟）一到，游标就被清掉了。你再去for data in datas就炸了。这篇就围绕「mongo 批量插入数据」和「长链接」这两个关键词，把 CursorNotFound 的复现、定位、修复讲清楚，同时给出用 TaoToken 统一 Key 管理 API 通道的配置骨架，让你在本地脚本和 AI 工具之间切换时不用来回改密钥。
先说清楚这篇适合谁：如果你写过insert_many()、调过ordered=False、被no_cursor_timeout坑过，或者你正在用 AI 助手帮你生成 pymongo 代码、需要一套统一的模型调用配置，那这篇的步骤你可以直接照着做。核心检索词就三个——批量插入、长链接超时、CursorNotFound，下面逐个拆。
2. 先把 TaoToken 的 Key 和通道配好
在排查游标问题之前，我习惯先把「模型调用」这条链路和「数据库操作」这条链路分开。原因是很多 CursorNotFound 的排查会被 AI 工具打断——你让助手改一段查询，它顺手把整个脚本重跑一遍，长链接又被拖长。用 TaoToken 统一 Key 的好处是：本地脚本、AI 编码工具、命令行助手共用一套 API 通道，配置只写一次，排查时不会因为密钥散落各处而分心。
TaoToken 在这里扮演的是统一 API 入口的角色，官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api 。你需要先去控制台拿一个 Key，控制台入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。拿到之后，下面两套配置骨架可以直接抄。
第一套是给支持settings.json的编辑器/工具用的（比如某些 AI 编码插件）：
{ "taotoken": { "api_base": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥", "default_model": "claude-sonnet", "timeout_seconds": 120, "max_retries": 2 }, "mongo": { "uri": "mongodb://127.0.0.1:27017", "db": "spider_demo", "collection": "items" } }第二套是给命令行工具或 Python 项目用的config.toml：
[taotoken] api_base = "https://taotoken.net/api" api_key = "sk-你的TaoToken密钥" default_model = "claude-sonnet" timeout_seconds = 120 [mongo] uri = "mongodb://127.0.0.1:27017" db = "spider_demo" collection = "items" cursor_timeout_ms = 600000注意cursor_timeout_ms这一项，它对应的是我们后面要处理的游标超时。把它显式写进配置，比散落在代码里更容易定位。TaoToken 的接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言 SDK 的调用示例，配 Key 遇到问题可以先翻这里。
提示：Key 不要硬编码进提交到仓库的脚本里，用环境变量或本地配置文件读取，
config.toml记得加进.gitignore。
3. 可复制的批量插入与游标配置
配置好之后，进入正题。先看批量插入的正确姿势。很多人写insert_many()时忽略了ordered参数，默认是True，也就是按序写入，一旦某条数据因为唯一索引冲突失败，后面的全部不写。改成ordered=False之后，每条插入互不影响，失败的那条单独报错，其余照常落库。
from pymongo import MongoClient, errors client = MongoClient("mongodb://127.0.0.1:27017") db = client["spider_demo"] col = db["items"] data_list = [{"url": f"https://example.com/{i}", "title": f"item-{i}"} for i in range(5000)] try: result = col.insert_many(data_list, ordered=False) print("inserted:", len(result.inserted_ids)) except errors.BulkWriteError as e: print("部分写入失败，失败条数:", len(e.details["writeErrors"]))这段跑完，数据是进去了。问题出在下一步——你去遍历一个查询游标，比如：
datas = col.find({}, {"_id": 0}) for data in datas: do_something(data) # 这一步耗时很长如果do_something每条要处理几百毫秒，5000 条就是十几分钟，远超 MongoDB 服务端默认的游标空闲超时（默认 10 分钟）。服务端一看这个游标这么久没动静，直接回收，客户端再next()就抛CursorNotFound。这就是「长链接」问题的本质：不是网络断了，是游标在服务端被判定为空闲。
修复方式有两种，按场景选。第一种是给游标设置永不超时，用完手动关闭：
datas = col.find({}, {"_id": 0}, no_cursor_timeout=True) try: for data in datas: do_something(data) finally: datas.close()第二种是分批拉取，用batch_size控制每次从服务端取多少，减少单次游标存活时间：
datas = col.find({}, {"_id": 0}).batch_size(500) for data in datas: do_something(data)两种可以叠加使用。我实测下来，no_cursor_timeout=True配合finally里close()最稳，但要注意：游标不主动关闭会一直占服务端资源，脚本异常退出时容易留下悬挂游标，所以try/finally不能省。
4. 复现一次游标失效并验证修复
光看代码不够，得亲手复现一次才知道问题出在哪。下面这段脚本故意让处理变慢，制造游标超时：
import time from pymongo import MongoClient from pymongo.errors import CursorNotFound client = MongoClient("mongodb://127.0.0.1:27017") col = client["spider_demo"]["items"] # 复现：不设 no_cursor_timeout，处理耗时拉长 datas = col.find({}, {"_id": 0}) count = 0 try: for data in datas: time.sleep(0.2) # 模拟耗时处理 count += 1 except CursorNotFound as e: print(f"游标在第 {count} 条后失效: {e}")跑起来后，如果数据量够大、处理够慢，你会在某个点看到CursorNotFound。这时候把find()改成带no_cursor_timeout=True的版本，再跑一次，同样的time.sleep(0.2)，游标不会再断。验证成功的标志是脚本完整遍历完所有数据，没有异常抛出。
如果你用 TaoToken 的模型对话能力来辅助排查，可以把报错原文贴进去让它帮你分析，入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。比如你贴CursorNotFound: Cursor not found, cursor id: 123456，它能帮你确认是超时还是集合被 drop 导致的。注意区分：如果集合在遍历过程中被drop()或rename()，游标也会失效，这种情况加no_cursor_timeout没用，得从操作顺序上解决。
验证修复时，建议同时观察 MongoDB 服务端的游标状态。连上 mongo shell 执行：
db.serverStatus().metrics.cursor看open.total和timedOut两个计数。修复前timedOut会随脚本运行增长，修复后应该保持稳定。这一步能把「长链接超时」这个模糊描述定位到具体指标上。
5. 本篇常见错误排查
排查过程中有几个坑反复出现，列出来对照。
第一个坑：把no_cursor_timeout=True当成万能药。它只解决「游标空闲超时」，解决不了「集合被删」「连接被防火墙掐断」「副本集主从切换」这几类问题。如果加了它还是报 CursorNotFound，先确认集合在遍历期间有没有被其他脚本改动。
第二个坑：insert_many()的ordered参数和游标超时混为一谈。这两个是独立问题。ordered=False解决的是批量写入时单条失败拖累整体，跟游标超时没关系。有人看到批量插入报错就以为是游标问题，方向就偏了。
第三个坑：TaoToken 的 Key 配错导致 AI 工具反复重试，间接拉长脚本运行时间。如果你在settings.json里把api_base写成了带路径的完整地址，或者 Key 前后有空格，请求会失败重试，脚本卡住，长链接问题被放大。检查api_base是否就是https://taotoken.net/api，Key 是否从 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 正确复制。
第四个坑：游标用完不关。no_cursor_timeout=True的游标不会自动过期，脚本里如果没写close()，跑几次之后服务端会堆积一堆打开游标，db.serverStatus().metrics.cursor.open.total一直涨，最终影响新查询。养成try/finally的习惯。
第五个坑：把batch_size设得过大或过小。设太大，单次网络传输压力大；设太小，往返次数多，整体更慢，反而更容易触发超时。500 到 1000 是比较稳的区间，具体看单条文档大小。
注意：如果你在副本集或分片集群上跑，游标超时行为可能和单机不同，
no_cursor_timeout在分片场景下要配合mongos的参数一起看，别只改客户端。
6. 把配置和排查动作固定下来
排查完这一轮，我的做法是把「游标超时」相关的参数全部收进config.toml，代码里只读配置，不写魔法数字。这样下次再遇到 CursorNotFound，先看配置里的cursor_timeout_ms和batch_size，再决定是调参数还是改代码逻辑。TaoToken 的 Key 也放在同一份配置里，本地脚本和 AI 工具共用，排查时不会因为密钥不一致产生额外变量。
如果你需要长期跑批量任务、还要接 AI 编码助手，可以考虑用 TaoToken 的 Coding Plan，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它把模型调用通道固定下来，配合上面的settings.json骨架，脚本和助手之间切换不用重新配 Key。Claude Code 相关的接入说明在 https://taotoken.net/claude-code?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite ，如果你用命令行助手改 pymongo 代码，可以参考。
最后留一个我踩过的坑：no_cursor_timeout=True的游标在for循环里如果break提前退出，finally里的close()一定要执行，否则那个游标会一直挂在服务端。我一开始图省事没写finally，跑了一晚上批量任务，第二天db.serverStatus().metrics.cursor.open.total上千，新查询开始变慢，排查了半天才发现是游标没关。把close()补上之后，同样的任务跑完，打开游标数回到个位数。
