跨分片事务失败主因是分片间配置或版本不一致：readConcern必须全为"majority"且enableMajorityReadConcern=true，MongoDB小版本（含补丁号）须完全统一，否则prepare阶段静默失败。
跨分片事务失败，大概率不是代码写错了，而是参与事务的分片之间版本或配置不一致——尤其是 readConcern 级别和 MongoDB 小版本号。
为什么不同分片的 readConcern 配置不一致会导致事务直接失败
MongoDB 跨分片事务要求所有参与分片（shard）必须启用相同的 readConcern 级别，且该级别需为 "majority"。如果某个分片在启动时未开启 enableMajorityReadConcern=true（例如通过 --enableMajorityReadConcern 参数或配置文件），或者其副本集未完成初始同步、oplog 不足以支撑 majority 读，那么该分片在 prepare 阶段就会拒绝加入事务，mongos 收到类似 NotMasterOrSecondary: not master or secondary 或 ReadConcernMajorityNotAvailableYet 的错误。
常见现象：
- 事务在本地测试通过，一上分片集群就报错，但错误信息里没提
readConcern - 部分分片能成功写入，另一些分片返回空响应或超时
-
db.runCommand({ replSetGetStatus: 1 })显示某分片成员状态为STARTUP2或ROLLBACK，说明它还没准备好支持 majority 读
实操建议：
- 逐个连接每个 shard 的 primary，执行
db.runCommand({ getCmdLineOpts: 1 })，检查返回中parsed.enableMajorityReadConcern是否为true - 确认该分片副本集已初始化完成：
rs.status()中所有成员stateStr应为PRIMARY或SECONDARY，且optimes.lastCommittedOpTime与主节点接近 - 若用 Docker 或编排工具部署，确保所有 shard 容器启动参数一致，不要漏掉
--enableMajorityReadConcern
如何快速验证各分片 MongoDB 小版本是否统一
4.2+ 分布式事务依赖两阶段提交（2PC）协议的严格实现，而不同小版本（如 5.0.15 vs 5.0.20）之间可能存在事务协调逻辑差异，导致 txnNumber 解析失败、prepare 响应格式不兼容等静默问题。这类问题不会立刻报错，但会在高并发或特定操作组合下触发 TransactionTooOld 或 UnknownTransactionCommitResult。
实操建议：
- 对每个 shard 的 primary 执行
db.version()，注意不只是主版本（5.0），还要比对补丁号（如5.0.20和5.0.15不可混用） - 检查
db.runCommand({ buildInfo: 1 })中的gitVersion，同一集群内所有分片应完全一致；若出现gitVersion: "xxx-xxx-dirty"，说明是自编译或非官方包，风险极高 - 滚动升级分片时，必须先升级 config server 副本集，再逐个升级 shard，且禁止跨大版本（如 4.4 → 5.0）在线升级事务集群
事务启动时提示 "Transaction numbers are only allowed on a replica set member or mongos" 的真实原因
这个错误常被误认为是客户端连错了地址，其实更可能是：你连的是某个 shard 的 mongod 实例（比如直接连了 shard01:27018），而不是 mongos（mongos:27017）。跨分片事务必须由 mongos 发起协调，不能绕过它直连分片。
容易踩的坑：
- 应用配置里写死了某个 shard 的地址，而非 mongos 地址
- 使用
mongosh测试时，误连 shard 节点后执行session.startTransaction()，此时报错是必然的 - 某些 ORM 或驱动默认 fallback 到 directConnection=true，会跳过 mongos 自动发现逻辑
验证方式：
- 在客户端连接后，执行
db.runCommand({ isMaster: 1 })，若返回中有msg: "isdbgrid"，说明连的是 mongos；若为ismaster: true且无该字段，则是直连了 mongod - 检查连接字符串是否含
&directConnection=false（显式关闭直连）且不含&directConnection=true
版本和配置一致性不是“最好有”，而是跨分片事务能跑起来的硬门槛。哪怕只有一个分片的 enableMajorityReadConcern 是 false，或 gitVersion 差一个字符，事务都可能在 prepare 阶段无声失败——日志里未必留痕，监控也难捕获。
