MongoDB 客户端连接池与超时配置及连接错误排查：按部署…

在创建、更新或审查 MongoDB 客户端/连接池配置，或排查 ECONNREFUSED、超时、池耗尽等连接问题时使用。

适用场景

解决思路

1. 遵循「先上下文后配置」：在添加连接池参数或超时设置前，先理解应用上下文，不要无理由套用任意参数值。
2. 理解连接池存在的原因：建立 MongoDB 连接成本高（TCP + TLS + auth = 50-500ms），应使用连接池，避免每个操作都承担建立连接成本。
3. 避免保持不必要的空闲连接：打开连接即使不活跃也会消耗 MongoDB 服务端内存，平均每连接约 1 MB。
4. 按连接生命周期管理：从池借用连接 → 执行操作 → 归还池 → 按 maxIdleTimeMS 清理超时空闲连接。
5. 同步驱动（PyMongo、Java sync）会阻塞线程，池大小通常匹配线程池大小。
6. 异步驱动（Node.js、Motor）使用非阻塞 I/O，较小的池通常足够。
7. 计入监控连接：每个 MongoClient 对每个副本集成员自动建立 2 个监控连接，独立于业务连接池。
8. 用公式估算总连接：Total = (minPoolSize + 2) × replica members × app instances；例：10 个实例、minPoolSize 5、3 成员副本集 = 210 个服务端连接；规划容量时必须计入。
9. 在建议任何配置变更前，确保已获得足够应用环境上下文；信息不足时提出针对性问题。
10. 提问时一次只问一个问题，先问宽泛上下文（部署类型、工作负载、并发），再深入具体项。
11. 建议配置时，基于收集到的上下文简要解释每个参数为什么取该值；用用户环境细节支撑推荐。
12. 例如 maxPoolSize: 50 可解释为「基于观测到的 40 个并发操作峰值，并留 25% 缓冲应对流量突发」。
13. 如果提供代码片段，为每个参数选择添加内联注释说明理由。
14. 若有性能数据，用公式计算初始池大小：Pool Size ≈ (Ops/sec) × (Avg duration) + 10-20% buffer；例：(10,000 ops/sec) × (10ms) + 20% = 120 个连接。
15. 当需求清晰、延迟已知、流量可预测时使用性能数据公式；当持续时间变化大时，从保守值 10-20 开始，监控后再调整。
16. 通过查询优化降低所需池大小。
17. 根据集群支持的总连接数和 MongoClient 实例数确定 poolSize 上限；例：10 个 MongoClient、size 5、3 节点副本集：10 × 5 × 3 = 150 个连接。
18. 考虑每个连接约 1 MB 物理 RAM，按应用工作负载的资源占用优化参数值。
19. 记住连接池是按每个 MongoClient 的每个服务器创建的。
20. 分片集群中，默认客户端连接到一个 mongos 路由器（由其内部管理到分片的连接），不直接连接各个分片；因此分片数量不直接影响池大小。
21. 分片分担工作负载并降低单服务器压力，提升集群容量。
22. 副本集成员不直接影响 max pool；如果驱动与多个副本集成员通信（例如使用 secondary read preference 读取），可能为每个成员创建池。
23. 副本集成员不增加写容量（只有 primary 处理写入）；但如果读偏好允许从 secondary 读取，可增加读容量。
24. 计算服务端连接上限：Total potential connections = instances × (maxPoolSize + 2) × replica set members；+2 是每个 MongoClient 每个副本集成员的 2 个监控连接。
25. 监控 connections.current，避免达到上限；按 references/monitoring-guide.md 设置监控。
26. 自管理服务器：将 net.maxIncomingConnections 设置为略高于客户端创建的最大连接数或连接池最大大小，防止 mongos 在分片造成连接尖峰，扰乱操作和内存分配。
27. 通用最佳实践：只创建一次客户端并在应用内复用；Serverless 中在 handler 外初始化。
28. 除非关闭应用，不要手动关闭连接。
29. Max pool size 必须大于预期并发。
30. 使用超时保持仅所需连接就绪，匹配工作负载需求。
31. 除非有特定需求，使用默认 max pool size（100）。
32. Serverless 场景：在 handler/function 作用域外初始化客户端，以跨热调用复用连接。
33. Serverless 推荐配置 maxPoolSize: 3-5；理由：每个 serverless 函数实例有独立池。
34. Serverless 推荐配置 minPoolSize: 0；理由：避免维护未使用连接；如需缓解冷启动可增加。
35. Serverless 推荐配置 maxIdleTimeMS: 10-30s；更快释放未使用连接。
36. Serverless 推荐配置 connectTimeoutMS: >0；设置为大于到集合成员的最长网络延迟。
37. Serverless 推荐配置 socketTimeoutMS: >0；确保 sockets 总会被关闭。
38. 传统长运行服务器（OLTP 工作负载）推荐 maxPoolSize: 50+；基于峰值并发请求，监控并调整。
39. 传统长运行服务器推荐 minPoolSize: 10-20；预热连接应对流量尖峰。
40. 传统长运行服务器推荐 maxIdleTimeMS: 5-10min；稳定服务器受益于持久连接。
41. 传统长运行服务器推荐 connectTimeoutMS: 5-10s；连接问题快速失败。
42. 传统长运行服务器推荐 socketTimeoutMS: 30s；防止挂起查询，适合短 OLTP 操作。
43. 传统长运行服务器推荐 serverSelectionTimeoutMS: 5s；副本集拓扑变化时快速故障转移。
44. 了解 MongoDB 8.0+ 在 Atlas 集群引入 defaultMaxTimeMS，提供服务端长时间运行操作保护。
45. OLAP/分析工作负载推荐 maxPoolSize: 10-20；并发操作较少，匹配预期并发分析操作数。
46. OLAP 推荐 minPoolSize: 0-5；查询不频繁，最少预热。
47. OLAP 推荐 socketTimeoutMS: >0；设置为驱动运行的最慢操作的 2-3 倍。
48. OLAP 推荐 maxIdleTimeMS: 10min；最小化连接 churn，同时不保持真正空闲连接过久；考虑中间网络设备超时。
49. 高流量/突发工作负载推荐 maxPoolSize: 100+；更高上限容纳突然流量尖峰。
50. 高流量/突发工作负载推荐 minPoolSize: 20-30；更多预热连接立即应对突发。
51. 高流量/突发工作负载推荐 maxConnecting: 2（默认）；防止突然需求造成 thundering herd。
52. 高流量/突发工作负载推荐 waitQueueTimeoutMS: 2-5s；池耗尽时快速失败而非无限排队。
53. 高流量/突发工作负载推荐 maxIdleTimeMS: 5min；平衡突发期间复用与尖峰之间清理。
54. 排查连接问题时，先判断是客户端配置问题还是基础设施问题。
55. 基础设施或网络问题不在范围内：DNS/SRV 解析失败、网络/VPC 阻断、IP 未加白名单、TLS 证书问题、认证机制不匹配；应转交公开基础设施文档。
56. 客户端配置问题在范围内：池耗尽、不适当超时、复用模式差、大小不优、缺少 serverless 缓存、连接 churn。
57. 排查时一次只问一个问题，先从宽泛上下文（部署类型、工作负载、并发）开始，再问具体项（当前配置、错误信息），快速缩小根因，避免不必要配置变更或过多问题。
58. 查看 references/monitoring-guide.md，了解如何插桩和监控相关参数。
59. 池耗尽处理：当操作排队时说明池耗尽。
60. 池耗尽症状：MongoWaitQueueTimeoutError、WaitQueueTimeoutError、MongoTimeoutException、延迟增加、操作等待。
61. 池耗尽解决方案：当 wait queue 有操作等待（size > 0）且服务器利用率低时，增加 maxPoolSize。
62. 池耗尽时不要增加 maxPoolSize：当服务器已达容量上限时；应建议查询优化。
63. 连接超时（ECONNREFUSED、SocketTimeout）客户端方案：如确有需要，增加 connectTimeoutMS/socketTimeoutMS。
64. 连接超时基础设施问题重定向：无法通过 shell 连接 -> 网络/防火墙；环境特定 -> VPC/安全；DNS 错误 -> DNS/SRV 解析。
65. 连接 churn 症状：connections.totalCreated 服务端指标快速增加，连接处理 CPU 高。
66. 连接 churn 原因：未使用池、serverless 未缓存、maxIdleTimeMS 太低、重启循环。
67. 高延迟处理：确保 minPoolSize > 0 以应对流量尖峰。
68. 高延迟处理：对高延迟（>50ms）使用网络压缩：compressors: ['snappy', 'zlib']。
69. 高延迟处理：对地理分布式设置使用 nearest read preference。
70. 强制环境上下文：在建议任何配置变更前，始终确认有足够应用环境信息。
71. 收集影响池配置的参数：服务器内存限制（每连接 1MB）。
72. 收集客户端和集群服务器数量：池按客户端和服务器分配，占用集群内存。
73. 收集 OLAP vs OLTP 及操作预期时长：短 OLTP 可能需要较低 socketTimeoutMS 快速失败；长 OLAP 可能需要更高值避免过早超时。
74. 收集服务器版本：MongoDB 8.0+ 在 Atlas 集群的 defaultMaxTimeMS 提供服务端保护。
75. 收集 Serverless vs Traditional：Serverless 在 handler 外初始化客户端；传统服务器可维护更大池和预热连接。
76. 收集并发和流量模式：高并发/突发可能需要更大池和更多预热；稳定低并发可用更小池。
77. 收集操作系统信息：某些 OS 对打开文件描述符数量有限制，会影响最大连接数，尤其高流量应用。
78. 收集驱动版本：不同驱动版本默认设置和性能特征不同；始终查阅特定驱动版本文档。
79. 只问与配置设计阶段场景相关的问题；省略不会导致明确使用配置设计内容的问题。
80. 如果用户未提供答案，做合理假设并披露。
81. 必须引导用户监控与其池配置相关参数；详见 references/monitoring-guide.md。
82. 创建代码时，对每个提供的连接参数，确保有足够环境上下文来决定值；如果没有，先问针对性问题再给具体值。
83. 如果得不到回答，做合理假设，披露它，并在代码中注释相关参数。

适用边界 · 注意事项

• 不适用于基础设施/网络层问题（如 DNS/SRV 解析失败、VPC/网络阻断、IP 未加白名单、TLS 证书问题、认证机制不匹配），应转交基础设施文档。
• 不要在未了解应用环境（部署类型、负载、并发、服务器内存/版本/驱动等）时盲目新增连接池参数或超时设置。
• 当服务端已达到容量上限时，不要仅增大 maxPoolSize；应优化查询或扩容。