必须在MongoDB连接字符串中显式指定replicaSet参数且值与rs.conf()中_id完全一致，否则PyMongo会以单机模式连接导致读写失败；多节点地址需全部列出并显式设置directConnection=false，初始化后须用replSetGetStatus验证副本集状态。
直接用 mongodb:// 连接字符串加副本集参数就能连上，但漏掉 replicaSet 或写错名称会导致连接成功却读写失败——这不是网络问题，是驱动根本没走副本集发现逻辑。
连接字符串必须显式声明 replicaSet 名称
MongoDB Python 驱动（pymongo）不会自动探测副本集名。即使你只连一个节点，只要目标是副本集，就必须在 URI 中带上 replicaSet 参数，否则它会以单机模式连接，后续执行 read_preference 或故障转移时直接报错。
正确写法示例：
mongodb://node1:27017,node2:27017,node3:27017/?replicaSet=rs0&readPreference=secondaryPreferred
-
replicaSet值（如rs0）必须和 MongoDB 实例中rs.conf()输出的_id完全一致，区分大小写 - 所有节点地址都应列在 URI 主机部分，不能只写一个——否则驱动无法感知拓扑变化
- 不推荐省略端口（即使默认 27017），显式写出更利于排查 DNS 或代理问题
directConnection=false 是默认行为，但显式设为 false 更安全
从 PyMongo 4.0 开始，当 URI 包含多个主机且设置了 replicaSet，directConnection 默认为 False；但如果只写了一个节点地址，驱动可能误判为单机模式并启用 directConnection=true，导致副本集功能失效。
立即学习“Python免费学习笔记（深入）”；
建议始终显式关闭：
mongodb://node1:27017,node2:27017,node3:27017/?replicaSet=rs0&directConnection=false
- 显式设置后，即使未来删掉某个节点地址，也不会意外切到直连模式
- 如果连接后调用
client.admin.command("ping")成功，但client.server_info().get("hosts")返回空或只有自己，大概率是directConnection=true搞的鬼
初始化连接后务必验证副本集状态
连接成功不代表副本集通信正常。常见现象是：能连、能查、但写入卡住或报 NotPrimaryNoSecondaryOk 错误——这说明驱动连上了，但没拿到正确的主节点信息。
上线前加一段最小验证逻辑：
try:
client.admin.command("ismaster")
# 检查是否识别到全部成员
members = client.admin.command("replSetGetStatus")["members"]
assert len([m for m in members if m["stateStr"] in ("PRIMARY", "SECONDARY")]) >= 2
except Exception as e:
raise RuntimeError(f"Replica set health check failed: {e}")- 不要只依赖
client.server_info()，它只返回当前连接节点信息，不反映副本集视图 -
replSetGetStatus需要clusterAdmin权限，测试环境可临时授权，生产应使用专用监控账号 - 若应用启动时副本集中有节点宕机，只要多数派在线，这个检查仍应通过；但如果返回
NodeNotFound或超时，说明 DNS、防火墙或bindIp配置有问题
副本集连接最常卡在「以为连上了，其实没进副本集模式」——驱动静默降级成单机连接，问题往往在压测或主节点切换时才暴露。每次改连接配置，先跑通 replSetGetStatus 再交由应用使用。
