不写 replicaSet 会导致 PyMongo 以单机模式连接，无法发现副本集拓扑、不支持故障转移，写操作可能发到从节点报错，读操作可能读取过期数据；必须通过 URI 查询参数显式指定 replicaSet 才能启用副本集逻辑。
连接字符串里不写 replicaSet 会导致什么？
不指定 replicaSet 参数时，pymongo 会以单机模式尝试连接——哪怕你给了多个 host:port。它不会做副本集发现，也不会自动故障转移，主节点挂了就直接报 ConnectionFailure 或卡在 ServerSelectionTimeoutError。
更隐蔽的问题是：即使连接成功，写操作可能被发到从节点（如果没加 readPreference=primary），触发 NotPrimaryNoSecondaryOk 错误；读操作也可能读到过期数据，因为默认读偏好是 primary，但没 replicaSet 就无法确认谁是当前 primary。
- 必须确保所有 mongod 实例启动时都用了
--replSet <name></name>，且名称与连接串中一致 -
replicaSet值区分大小写，不能有空格或下划线以外的特殊字符（官方推荐纯字母数字） - 连接串中的 host 列表应包含至少两个可用节点（建议三个），否则副本集逻辑无法生效
MongoClient 初始化时怎么传 replicaSet？
最稳妥的方式是把 replicaSet 作为 URI 查询参数，而不是靠 kwargs 传——后者在较新版本的 pymongo 中已被弃用或行为不稳定。
正确写法：
立即学习“Python免费学习笔记（深入）”；
from pymongo import MongoClient uri = "mongodb://node1:27017,node2:27017,node3:27017/?replicaSet=my-rs&connectTimeoutMS=5000&socketTimeoutMS=10000" client = MongoClient(uri)
-
replicaSet必须出现在查询参数部分（?后），且不能拼错 - 加上
connectTimeoutMS和socketTimeoutMS能避免阻塞太久，尤其在网络抖动时 - 不要在 host 部分写
mongodb://.../my-rs——那是数据库名位置，不是 replicaSet 配置点
如何验证连接确实走的是副本集逻辑？
光看 client.admin.command("ismaster") 返回里有没有 "ismaster": true 不够，得确认它是否识别出整个拓扑。
执行以下检查：
try:
info = client.admin.command("ismaster")
print("Host:", info.get("hosts"))
print("Primary:", info.get("primary"))
print("Replica set name:", info.get("setName"))
print("Is master?", info.get("ismaster", False))
except Exception as e:
print("Failed:", e)
- 如果
"hosts"是空或只有自己，说明没发现其他节点 → 检查网络连通性、防火墙、bind_ip配置 -
"setName"必须和 URI 中的replicaSet完全一致，否则客户端会拒绝加入 - 首次连接后，
pymongo会后台定期刷新拓扑，所以ismaster结果可能随时间变化，别只看一次
副本集连接失败的典型错误和对应排查点
遇到 ServerSelectionTimeoutError 或 AutoReconnect 循环时，先盯住这几个地方：
-
dns resolution failed：URI 中的 hostname 在客户端机器上解析失败 → 改用 IP，或检查/etc/hosts -
not master and slaveOk=false：读操作发到了从节点 → 确保没手动设置read_preference=ReadPreference.SECONDARY且没关slaveOk -
Authentication failed却能连上 admin：认证数据库不是admin→ 在 URI 里显式加authSource=admin - 日志里反复出现
Topology description changed：节点状态频繁切换 → 检查 oplog 大小、心跳间隔、网络延迟是否超heartbeatFrequencyMS（默认10秒）
副本集不是“写了 replicaSet 就自动高可用”，每个节点的配置、时钟同步、网络稳定性都会直接影响客户端感知到的行为。最容易被忽略的是：客户端看到的 topology 是缓存的，重启应用比调参数更快验证改动是否生效。
