孤儿文档源于chunk迁移未完成导致同文档存在于两shard，config server仅认新shard；cleanupOrphaned须直连shard primary执行，startingFromKey在8.0+已废弃，实际扫描全命名空间异步清理。
孤儿文档是怎么产生的
分片集群里出现孤儿文档，本质是 chunk 迁移没彻底完成。Balancer 把一个 chunk 从 Shard A 复制到 Shard B 后，本该删掉 A 上的旧副本，但若此时发生网络中断、Primary 故障切换或进程被杀，删除动作就丢了。结果同一条文档在两个 shard 上都存在，而 config server 只认 Shard B 的那份——A 上那条就成了孤儿。
常见诱因包括：频繁主从切换、跨机房迁移时网络抖动、手动停 Balancer 后又误操作触发迁移、或者 mongos 节点异常断连导致命令未确认。
cleanupOrphaned 命令为什么必须连 Shard Primary 执行
cleanupOrphaned 不是 mongos 能转发的命令，它需要直接访问 shard 的本地数据和元信息。mongos 会拒绝执行，报错类似 command cleanupOrphaned not supported from mongos。
必须用 mongo --host ShardIP --port PrimaryPort 直连每个 shard 的 primary 节点（不能连 secondary，否则写入失败），且账号要有 clusterAdmin 或 root 权限。
容易踩的坑：
- 误连 mongos 或 config server，命令静默失败或返回
"ok" : 0 - 连了 secondary，命令执行但不生效，
stoppedAtKey始终为 null - 权限不足时返回
"codeName" : "Unauthorized"，但不会明确提示缺哪个角色
cleanupOrphaned 的 startingFromKey 参数现在无效
8.0+ 版本中 startingFromKey 已标记为 deprecated，传任何值都不影响清理范围。命令实际行为是：扫描整个命名空间，等待所有 orphaned 文档从所有 shard 上清除完毕才返回成功。
这意味着：
- 不用再费劲构造分片键最小值，直接传空对象
{}即可 - 命令耗时取决于孤儿文档数量和 shard 数据量，大集合可能卡住几十秒甚至更久
- 它不删数据，只是触发内部清理流程；真正删除由后台线程异步完成
示例调用：db.adminCommand({ cleanupOrphaned: "mydb.mycoll" })
别依赖 explain 查孤儿文档，直接清
有人用 find().explain("executionStats") 看 chunkSkips 来“确认”孤儿文档存在，这方法问题很大：它要全表扫描 + 分片路由解析，压力大、慢、还可能漏判（尤其当 orphaned 文档恰好落在被跳过的 chunk 边界上）。
生产环境建议跳过检查，直接在业务低峰期批量清理。脚本里用循环调用 cleanupOrphaned，靠 stoppedAtKey 判断是否扫完：
function cleanupOrphaned(coll) {
var nextKey = {};
var result;
while (nextKey != null) {
result = db.adminCommand({ cleanupOrphaned: coll, startingFromKey: nextKey });
if (result.ok != 1) print("failed or timeout");
nextKey = result.stoppedAtKey;
}
}
注意：每个数据库、每个 shard 都要单独跑一遍，不能偷懒只清一个节点。
最常被忽略的一点：cleanupOrphaned 不保证立即物理删除。它只是通知 shard 启动清理，实际删除可能延迟数秒到数分钟，期间仍可能被某些 readConcern 隔离级别读到。如果紧接着做迁移（比如用 DRS），务必等 2 分钟后再启动。
