MongoDB 客户端报出 ConnectionTimeout 异常时，第一反应通常是检查 mongod 进程是否存活，但实际上驱动连接过程包含多个阶段，DNS 解析、TCP 建连、TLS 握手、认证和拓扑发现中的任意一环超过阈值，都会抛出这个错误。不同驱动对超时的命名与默认值并不完全一致，排查前需要先区分两个核心参数：connectTimeoutMS 和 serverSelectionTimeoutMS。

一、connectTimeoutMS 与 serverSelectionTimeoutMS 的区别

很多开发者容易把这两个参数混为一谈，但它们的作用范围完全不同。connectTimeoutMS 控制的是单个网络连接建立阶段的超时，也就是 TCP 套接字建连以及可选的 TLS 握手过程。如果客户端到目标主机的网络链路非常慢，或者防火墙丢弃了 SYN 包，这个参数会在指定时间后直接中断本次连接尝试。

而 serverSelectionTimeoutMS 控制的是驱动在集群拓扑中选择可用服务器节点的总等待时间。MongoDB 驱动连接副本集或分片集群时，会先尝试连接种子节点，再执行 hello 命令获取完整拓扑。如果所有候选节点都不可达，驱动会循环尝试，直到超过 serverSelectionTimeoutMS 才最终报错。这个参数默认值通常比 connectTimeoutMS 大得多，例如 Java 驱动中默认分别为 10000 毫秒和 30000 毫秒。

下面是一个 Java 驱动 4.x 的典型连接字符串配置，分别指定了这两个参数：

import com.mongodb.ConnectionString;
import com.mongodb.MongoClientSettings;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
public class MongoConnectionExample {
    public static void main(String[] args) {
        String uri = "mongodb://dbuser:secret@10.10.20.15:27017,10.10.20.16:27017/test" +
                "?authSource=admin&connectTimeoutMS=5000&serverSelectionTimeoutMS=8000";
        MongoClientSettings settings = MongoClientSettings.builder()
                .applyConnectionString(new ConnectionString(uri))
                .build();
        try (MongoClient client = MongoClients.create(settings)) {
            client.getDatabase("admin").runCommand(new Document("ping", 1));
            System.out.println("connection ok");
        }
    }
}

在实际排查中，如果错误信息里出现 waited for server selection 字样，说明瓶颈在于 serverSelectionTimeoutMS，而不是 connectTimeoutMS。只调大 TCP 连接超时不会缩短节点选择过程，反而可能让故障拖得更久才暴露。

二、网络层和认证层触发 ConnectionTimeout 的常见原因

网络链路问题是连接超时最常见的外部因素。防火墙、安全组或云平台的网络 ACL 如果没有放行 MongoDB 端口，典型表现是 TCP 握手直接无响应。此时使用 telnet 或 nc 命令测试端口可以快速区分：如果端口不通，驱动端的超时参数无论如何调整都无法建立连接。

• 防火墙或安全组未放行端口：MongoDB 默认端口为 27017，分片集群可能还有 27018、27019 等端口。云服务器需要同时检查操作系统防火墙和云平台安全组规则。
• DNS 解析缓慢或解析结果错误：容器环境中服务名可能解析到虚拟 IP，但该 IP 无法从外部访问。如果 DNS 查询本身超过 5 秒，也会直接拖累连接超时。
• IPv6 与 IPv4 优先级不一致：部分操作系统默认优先尝试 IPv6 地址，如果 MongoDB 只监听 IPv4，连接会经过较长时间才回退，导致超时。
• TLS 证书校验失败或证书链不完整：启用 TLS 后，如果客户端不信任服务端证书，握手阶段会报超时或证书错误。此类问题通常需要检查 CA 证书和主机名验证规则。
• 认证源写错导致 SCRAM 多轮往返超时：认证数据库如果写成 test 而不是 admin，SCRAM 握手虽然能开始，但权限校验失败或多次重试后可能以超时形式表现出来。

可以用 mongosh 手工连接来缩小范围。下方命令直接指定认证源，并执行 ping 命令验证链路和认证是否正常：

mongosh "mongodb://dbuser:secret@10.10.20.15:27017/test?authSource=admin" --eval "db.runCommand({ ping: 1 })"

如果 mongosh 能够在同样网络下正常连接，问题大概率出在应用侧连接参数、驱动版本或连接池配置。如果 mongosh 也超时，则需要集中排查网络链路、防火墙和 mongod 进程的实际监听地址。

三、副本集与分片集群中的拓扑发现超时

连接副本集或多节点分片集群时，驱动会从连接串中的种子节点开始，逐个尝试建立连接并获取拓扑信息。如果种子节点列表里混入了不可达的主机，驱动不会立刻失败，而是等待每个节点的连接尝试超时，再换下一个。这个过程的累计时间一旦超过 serverSelectionTimeoutMS，就会抛出超时异常。

容器化部署中一个非常典型的错误是使用 localhost 作为副本集成员主机名。驱动在获取拓扑后，会尝试连接成员配置里的地址，而不是连接串中的地址。如果 rs.initiate() 时使用了 localhost，后续客户端虽然能连上种子节点，但发现拓扑后仍然会尝试连接 127.0.0.1，最终导致超时。

另一个常见场景是主节点切换。副本集发生选举期间，旧主节点可能暂时不可写，驱动需要等待新主节点选出。此时如果 serverSelectionTimeoutMS 设置过短，写操作会在选举完成前就报超时。这种情况下适当加大参数可以提升容错能力，但不能解决成员地址配置错误的问题。

下面 Python 脚本可以开启驱动日志，观察拓扑发现过程中实际尝试了哪些地址：

import pymongo
import logging
logging.basicConfig(level=logging.DEBUG)
client = pymongo.MongoClient(
    "mongodb://dbuser:secret@mongo-0.mongo,mongo-1.mongo,mongo-2.mongo/test?authSource=admin",
    connectTimeoutMS=5000,
    serverSelectionTimeoutMS=8000
)
try:
    client.admin.command("ping")
except Exception as exc:
    print(type(exc).__name__, exc)

日志中如果出现多个节点被标记为 Unknown 或 Server selection timeout，可以进一步检查这些节点是否与副本集配置中的 hosts 一致。尤其在使用 Kubernetes 时，Service 名称的解析结果必须与副本集成员配置完全相同，否则驱动会反复尝试错误的地址。

四、参数调优与连接池的配合建议

连接超时问题不能只靠调大超时参数解决，但合理的参数组合可以降低抖动对业务的影响。通常建议将 connectTimeoutMS 设置在 2 到 5 秒之间，serverSelectionTimeoutMS 设置在 5 到 15 秒之间。过大的 serverSelectionTimeoutMS 会让请求在数据库不可用时长时间挂起，反而容易拖垮上游线程池。

应用侧还需要关注连接池配置。连接超时与连接池耗尽有时会同时出现，但性质不同。连接池中的连接如果长时间空闲后被服务端关闭，客户端复用旧连接时会先遇到读取超时，再触发重连流程。通过设置 maxIdleTimeMS、minPoolSize 和 maxPoolSize，可以减少无效连接积累，避免在高并发下出现偶发超时。

Node.js 驱动的配置示例如下：

const { MongoClient } = require("mongodb");
const client = new MongoClient("mongodb://dbuser:secret@10.10.20.15:27017/test?authSource=admin", {
  connectTimeoutMS: 5000,
  serverSelectionTimeoutMS: 8000,
  maxPoolSize: 50,
  minPoolSize: 5,
  maxIdleTimeMS: 60000
});
async function run() {
  await client.connect();
  const db = client.db("test");
  const result = await db.command({ ping: 1 });
  console.log(result);
  await client.close();
}
run().catch(console.error);

最终排查时建议按照网络连通性、单节点认证、副本集拓扑、应用连接池四个层级依次验证。先确认端口可达，再用 mongosh 连单节点，然后检查副本集成员地址，最后观察驱动日志中的地址列表。这样能把 ConnectionTimeout 的具体触发点快速定位出来，而不是盲目修改参数掩盖问题。