为MongoDB副本集配置TLS/SSL加密是保障数据传输安全的关键步骤，但实践中常因证书或配置细节问题导致部署失败。本文将深入解析配置过程中的核心要点与常见陷阱，帮助您一次性成功启用加密通讯。

成功配置的核心在于两点：一是生成包含完整SAN信息的正确证书，二是在MongoDB配置文件中完整填写所有必需的TLS参数，缺一不可。

一、证书生成：必须包含所有节点的DNS与IP地址（SAN）

在副本集环境中，每个节点可能通过多个地址被访问，例如公网域名、内网IP及本地回环地址。若证书的“使用者可选名称”未涵盖所有可能的连接地址，客户端连接时将抛出“SSL peer certificate validation failed”错误。

注意，使用mkcert或Let‘s Encrypt等工具自动生成的证书通常只包含单一域名，难以满足副本集多地址需求。因此，手动使用OpenSSL生成包含完整SAN扩展的自签名证书是更可靠的选择。

关键步骤在于生成证书签名请求时，必须显式指定SAN信息。对于OpenSSL 1.1.1及以上版本，可使用-addext参数直接添加：

openssl req -new -key node1.key -out node1.csr -addext “subjectAltName = DNS:node1.example.com,IP:192.168.1.10,IP:127.0.0.1”

对于旧版本OpenSSL，建议创建独立的sans.cnf配置文件，并在生成CSR时通过-extfile sans.cnf -extensions req_ext参数引入。

在签发证书时，务必确保证书包含关键扩展项：keyUsage = digitalSignature, keyEncipherment和extendedKeyUsage = serverAuth。证书生成后，使用以下命令验证SAN信息是否已正确嵌入：

openssl x509 -in node1.pem -text -noout | grep -A1 “Subject Alternative Name”

二、服务端配置：必须完整设置 net.tls 相关字段

仅设置net.tls.mode: requireTLS并不足以启用加密。必须同时配置以下三个关键字段，否则服务可能静默失败或拒绝TLS连接。

• net.tls.certificateKeyFile：指定包含节点私钥和证书的PEM文件。**重要提示：**该文件中的私钥必须为无密码保护格式。若私钥被加密，mongod启动时将因无法交互输入密码而报错“Failed to load certificate file: bad password”。
• net.tls.CAFile：指向自建CA的根证书文件（如ca.crt）。即使仅启用服务端认证（单向TLS），也强烈建议配置此字段。因为新版驱动（如mongosh）默认会验证服务端证书的颁发者，缺少CA文件将导致校验失败。
• net.tls.allowConnectionsWithoutCertificates：此参数控制是否允许客户端不提供证书进行连接。通常设置为true。若设置为false，则开启强制双向认证，此时**副本集内部成员间的通信也必须提供客户端证书**，除非额外配置了net.tls.clusterFile。

三、副本集内部通信：需显式启用集群TLS

一个常见误区是认为配置了requireTLS后，节点间的内部通信会自动加密。实际上，副本集的心跳检测和oplog同步默认仍使用明文。

若未专门为集群内部通信配置TLS，从节点可能持续处于STARTUP2状态，日志中反复出现“no SSL certificate provided”或“connection refused”错误，而主节点却显示正常。

解决方案是配置net.tls.clusterFile参数，并注意以下细节：

• 该文件需指向一个独立的PEM文件，包含该节点用于内部通信的私钥和证书。虽然可与certificateKeyFile复用，但为提升安全性，MongoDB官方建议使用独立的证书。
• 文件权限必须严格设置为600，否则mongod会因权限问题拒绝读取并启动失败。
• **所有节点**的clusterFile证书必须由**同一个CA**签发，以确保集群内部能完成相互认证。
• 若计划使用X.509证书进行更严格的内部身份认证，需预先在$external数据库中创建相应用户。例如：db.getSiblingDB(“$external”).createUser({user: “CN=node1.example.com”, roles: [{role:“clusterAdmin”, db:“admin”}]})

四、客户端连接：必须显式指定TLS参数

客户端驱动不会自动探测服务端是否启用了TLS。使用普通连接字符串将默认尝试明文TCP连接，导致连接建立后立即断开，并报出“connection ended”或“SSL handshake failed”等模糊错误。

正确的做法是在连接时显式启用TLS并指定CA证书：

• 命令行（mongosh）：mongosh --tls --tlsCAFile /path/to/ca.crt “mongodb://node1.example.com:27017/?replicaSet=rs0”
• Node.js驱动：MongoClient(‘mongodb://node1.example.com:27017/’, { tls: true, tlsCAFile: ‘/path/to/ca.crt’ })
• Python (PyMongo)：MongoClient(‘mongodb://node1.example.com:27017/’, tls=True, tlsCAFile=‘/path/to/ca.crt’)

**注意版本差异：**旧版驱动可能使用ssl=True参数，而新版已统一改为tls=True。参数使用错误可能导致连接看似成功，但数据仍在明文传输，存在安全风险。

最后，一个极易被忽视的关键点是**系统时间同步**。务必确保副本集所有节点的系统时间高度一致，误差最好控制在数秒内，绝对不可超过证书有效期校验的容忍范围（通常为5分钟）。否则，TLS握手会因证书时间校验失败而中断，错误信息可能仅为笼统的“SSL handshake failed”，给问题排查带来极大困难。