必须在连接字符串URI的查询参数部分（?后）显式指定replicaSet名称，否则PyMongo将把多个节点视为独立单机，不触发选举、心跳和拓扑发现，导致主从切换失效。
不写 replicaSet 参数，PyMongo 就根本不会走副本集逻辑——它会把多个 host 当成一堆独立单机，连选举、心跳、拓扑发现都不会触发，主从切换自然不可能发生。
连接字符串里漏掉 replicaSet 查询参数
这是最常见也最隐蔽的失败原因。哪怕你写了三个节点地址："mongodb://node1:27017,node2:27017,node3:27017/"，只要 URI 后面没跟 ?replicaSet=my-rs，PyMongo 就按单机模式初始化客户端。
- 它不会向任何节点发
ismaster命令去探测角色，更不会监听hello响应里的hosts、passives、arbiters字段 - 所有写操作默认发往第一个 host（
node1），哪怕它此刻是 secondary，直接报NotPrimaryNoSecondaryOk - 读操作看似成功，但可能持续从一个 stale 的 secondary 读取旧数据，因为没有副本集上下文，
readPreference实际无效 - 主节点宕机后，客户端卡在
ServerSelectionTimeoutError，而不是自动切到新 primary
replicaSet 名称与 mongod 启动参数不一致
副本集名称必须完全匹配：大小写、连字符、数字都算在内。mongod 启动时用了 --replSet my-rs，连接串里就不能写成 my_RS 或 myrs。
- 验证方式：连上任一节点执行
rs.conf()，看返回的_id字段值 - 如果名称错，
client.admin.command("ismaster")仍可能返回成功，但"hosts"字段为空或只有自己，说明拓扑未建立 - 错误日志里通常出现
Failed to discover topology或反复重试连接却始终只识别单个节点
host 列表里节点不可达或版本不兼容
PyMongo 要启用副本集逻辑，至少需要两个可连通的节点参与初始发现。只写一个 host + replicaSet 参数，它会尝试连接，但无法完成拓扑构建。
- 确保所有节点已运行
rs.initiate()或正确加入副本集（rs.status()中health: 1） - 检查防火墙和 bind_ip：mongod 配置里
bindIp不能只写127.0.0.1，否则其他节点和 Python 客户端都连不上 - PyMongo 4.0+ 默认要求 MongoDB 4.2+ 的 wire protocol；若混用老版本（如 MongoDB 3.6 + PyMongo 4.7），握手失败导致拓扑发现中断
- 超时参数建议显式设置：
connectTimeoutMS=5000&socketTimeoutMS=10000，避免网络抖动时卡死
为什么加了 replicaSet 还看不到主从切换效果？
即使参数全对，切换也不是“瞬间完成”的。PyMongo 依赖后台心跳线程感知状态变化，有延迟，且应用层需配合处理临时性错误。
- 主节点宕机后，PyMongo 通常需要 10–30 秒才能将流量切到新 primary（取决于
heartbeatFrequencyMS和重试策略） - 正在执行的写操作若遇到
ConnectionFailure或NotPrimaryError，必须由业务代码捕获并重试，客户端不会自动重放请求 - 不要依赖
client.primary属性做路由判断——它是缓存值，可能滞后；应以实际命令抛出的异常为准 - 真正验证是否启用副本集逻辑：连上 client 后执行
client.topology_description，确认topology_type是"ReplicaSetWithPrimary"或类似值，而非"Single"
副本集不是配置开关，而是一整套协同机制。漏掉 replicaSet 参数，等于只装了方向盘却没连转向柱——看起来像能开，其实根本转不动。最容易被忽略的，就是那个小小的 ? 和它后面紧跟着的 replicaSet=xxx。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
