本页概述了常见连接问题和可能的解决方案。
To learn more about connecting to an Atlas cluster, see the Get Started with Atlas tutorial.
注意
If you are an enterprise customer looking for support, file a ticket. For community support, visit MongoDB Community Resources.
您可以使用智能助手来协助调试连接错误。
集群 Connect(连接)按钮已禁用
如果您的集群处于预配状态,则集群的 Connect 按钮可能会被禁用。您的集群需要在首次部署时进行预配。当您向上或向下扩展集群时,集群也必须进行预配。
Atlas预配集群后,Connect 按钮将变为启用状态。
对于免费集群,预配所需时间少于 15 秒。
对于 Flex 和专用集群,预配可能最多需要 10 分钟。
连接 IP 地址不在 IP 访问列表中
在连接到 Atlas 集群之前,请检查是否已将主机的 IP 地址添加到集群项目的 IP 访问列表中。Atlas 仅允许来自 IP 访问列表中的 IP 地址和 CIDR 地址范围的客户端连接。
集群身份验证失败
要连接到 Atlas,您必须通过 MongoDB 数据库用户进行身份验证。要为集群创建数据库用户,请参阅配置数据库用户。
潜在解决方案
如果您已创建用户但在进行身份验证时出现问题,请尝试执行以下操作:
检查是否为数据库用户使用了正确的用户名和密码,以及是否连接到正确的集群。
检查您是否在连接字符串中指定了正确的
authSource数据库。If you have a special character in your password, see Special characters in connection string password.
集群的打开连接过多
Atlas 为集群的并发传入连接设置限制。对于集群,这基于集群层。如果您在达到此限制时尝试连接,则 MongoDB 将显示一条错误,指示 connection refused because too many open connections。
有关集群层及其最大并发连接数的详细比较,请参阅连接限制和集群层。
潜在解决方案
关闭与当前未使用的集群的任何打开连接。
将集群扩展到更高层级,以支持更多并发连接。
重新启动您的应用程序。
To prevent this issue in the future, consider using the
maxPoolSizeconnection string option to limit the number of connections in the connection pool.
要了解如何修复此问题,请参阅修复连接问题。
在连接计数达到高峰期间,分片集群的性能会下降
Atlas 可以使用私有终结点服务的负载均衡器为分片集群生成优化的 SRV 连接字符串。当您使用优化的连接字符串时,Atlas 会限制应用程序与分片集群之间每个mongos的连接数。每个mongos 的受限连接数可提高连接计数高峰期间的性能。
要学习有关通过私有端点后面的分片集群优化连接字符串的更多信息,请参阅如何使用私有端点优化分片集群的连接性能?
尝试从防火墙后面进行连接
连接到 Atlas UI
Atlas 使用 CDN 快速提供服务内容。如果您的组织使用防火墙,请将以下 Atlas CDN 托管添加到防火墙的允许列表,以防止访问 Atlas 用户界面时出现问题:
https://assets.mongodb-cdn.com/https://downloads.mongodb.com/(数据浏览器功能必需)
连接到集群
Atlas 集群在端口 27017 上运行。您必须能够通过该端口连接到您的集群。此外,确保适当的端口对以下各项开放:
- 对于分片集群,请允许访问端口 27016。
您可以使用第三方Outgoing port tester检查是否能够访问端口。
例子
要检查是否能力访问端口 27017,请访问 http://portquiz.net:27017。
如果无法访问这些端口,请检查系统防火墙设置,确保防火墙没有阻止访问这些端口。
集群可用性
如果使用的是 mongodb+srv:// 连接字符串,而驱动程序或 Shell 未找到 Atlas 集群的 DNS 主机,该集群则可能会暂停或删除。检查集群是否存在。如果这是一个已暂停的集群,则可在必要时恢复该集群。
注意
Atlas在 30 天后自动暂停没有连接的空闲免费集群(以前称为 M0)。
MongoDB Compass 故障排除
如果您在使用 MongoDB Compass 连接集群时遇到问题,请参阅:
MongoDB Compass 文档中的 Compass 连接错误。
If you use a self-managed X.509 certificate or an auto-generated X.509 certificate managed by Atlas to authenticate to the MongoDB database, when you connect to MongoDB Compass, you must:
在 MongoDB Compass 中,选择 Fill in connection fields individually。
在 Authentication 下拉菜单中,选择
X.509。选择 More Options 。
在 SSL 下拉菜单中,选择 Server and Client Validation。
将下载的 Atlas 托管证书或自管理证书(取决于您使用的证书)的相同路径添加到以下每个字段中:Certificate Authority、Client Certificate 和Client Private Key。
To learn more, see Connect to MongoDB in the MongoDB Compass documentation.
连接字符串问题
连接字符串格式不正确
The connection string format you use to connect to Atlas depends on several factors, including:
Your
mongoshversion. To learn more, see Connect to a Cluster via mongosh.您的驱动程序版本。要学习;了解更多信息,请参阅通过客户端库连接到集群。
将连接字符串投入生产前,请在测试环境中进行验证。
连接字符串密码中的特殊字符
如果您的密码包含特殊字符,且在连接字符串 URI 中使用了密码,则请对特殊字符进行编码。
如果尝试使用需要百分数编码的特殊字符更新密码,会出现以下错误信息:
This password contains special characters which will be URL-encoded.
注意
如果在用户名或密码中包含以下字符和空格字符,必须使用百分比编码转换这些字符:
: / ? # [ ] @ ! $ & ' ( ) * , ; = %
例如,如果您的纯文本密码是p@ssw0rd'9'!,您需要将密码编码为:
p%40ssw0rd%279%27%21
➤ 使用 Select your language(选择语言)下拉菜单设置本节中编码示例的语言。
1 package main 2 3 import ( 4 "context" 5 "fmt" 6 "net/url" 7 8 "go.mongodb.org/mongo-driver/bson" 9 "go.mongodb.org/mongo-driver/mongo" 10 "go.mongodb.org/mongo-driver/mongo/options" 11 ) 12 13 func main() { 14 username := "<username>" 15 password := "<password>" 16 cluster := "<clusterName>" 17 authSource := "<authSource>" 18 authMechanism := "<authMechanism>" 19 20 uri := "mongodb+srv://" + url.QueryEscape(username) + ":" + 21 url.QueryEscape(password) + "@" + cluster + 22 "/?authSource=" + authSource + 23 "&authMechanism=" + authMechanism 24 25 client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri)) 26 if err != nil { 27 panic(err) 28 } 29 defer client.Disconnect(context.TODO()) 30 31 collection := client.Database("<dbName>").Collection("<collName>") 32 33 cursor, err := collection.Find(context.TODO(), bson.D{}) 34 if err != nil { 35 panic(err) 36 } 37 38 var results []bson.D 39 if err = cursor.All(context.TODO(), &results); err != nil { 40 panic(err) 41 } 42 for _, result := range results { 43 fmt.Println(result) 44 } 45 }
1 import com.mongodb.client.MongoClient; 2 import com.mongodb.client.MongoClients; 3 import com.mongodb.client.MongoCollection; 4 import com.mongodb.client.MongoDatabase; 5 6 import org.bson.Document; 7 import java.net.URLEncoder; 8 9 public class Encoding { 10 11 public static void main(String [] args){ 12 13 try{ 14 String username = URLEncoder.encode("<username>", "UTF-8"); 15 String password = URLEncoder.encode("<password>", "UTF-8"); 16 String cluster = "<clusterName>"; 17 String authSource = "<authSource>"; 18 String authMechanism = "<authMechanism>"; 19 20 String uri = "mongodb+srv://" + username + ":" + password + "@" + cluster + 21 "/?authSource=" + authSource + "&authMechanism=" + authMechanism; 22 23 MongoClient mongoClient = MongoClients.create(uri); 24 25 MongoDatabase database = mongoClient.getDatabase("<dbName>"); 26 MongoCollection<Document> collection = database.getCollection("<collName>"); 27 28 collection.find().forEach(doc -> System.out.println(doc.toJson())); 29 30 } catch(Exception e){ 31 System.err.println(e.getCause()); 32 33 } 34 } 35 }
1 const { MongoClient } = require("mongodb"); 2 3 const username = encodeURIComponent("<username>"); 4 const password = encodeURIComponent("<password>"); 5 const cluster = "<clusterName>"; 6 const authSource = "<authSource>"; 7 const authMechanism = "<authMechanism>"; 8 9 let uri = 10 `mongodb+srv://${username}:${password}@${cluster}/?authSource=${authSource}&authMechanism=${authMechanism}`; 11 12 const client = new MongoClient(uri); 13 14 async function run() { 15 try { 16 await client.connect(); 17 18 const database = client.db("<dbName>"); 19 const ratings = database.collection("<collName>"); 20 21 const cursor = ratings.find(); 22 23 await cursor.forEach(doc => console.dir(doc)); 24 } finally { 25 await client.close(); 26 } 27 } 28 run().catch(console.dir);
1 import pymongo 2 from urllib.parse import quote_plus 3 4 username = quote_plus('<username>') 5 password = quote_plus('<password>') 6 cluster = '<clusterName>' 7 authSource = '<authSource>' 8 authMechanism = '<authMechanism>' 9 10 uri = 'mongodb+srv://' + username + ':' + password + '@' + cluster + '/?authSource=' + authSource + '&authMechanism=' + authMechanism 11 12 client = pymongo.MongoClient(uri) 13 14 result = client["<dbName"]["<collName>"].find() 15 16 # print results 17 for i in result: 18 print(i)
重要
Do not encode special characters in your password if you are using your password outside of a connection string URI (for example, pasting it into mongosh).
连接字符串与驱动程序版本不兼容
If you see this error message, your driver is likely out of date. For instructions on updating your driver, refer to your specific Driver Documentation.
互联网服务提供商 DNS 阻止连接字符串
When you use the DNS seed list connection string format to connect to Atlas, you might see the following error:
DNSHostNotFound: Failed to look up service "<MongoDB service name>"
使用 ISP 提供的默认 DNS 服务器时可能会出现此错误。该 DNS 服务器可能不支持 DNS 种子列表连接字符串格式使用的 SRV 查询。
要解决此问题,您可以尝试更改 DNS 配置,使用公共 DNS 服务器。
例子
您可将网络设置配置为使用 Google 公共 DNS,而不是 ISP 的 DNS 服务器。
更新您的网络设置以使用公共 DNS 服务器后,连接到集群。
DB Tools 的连接字符串错误
You might see the following error when using the DNS seed list connection string format (mongodb+srv://) to connect to Atlas from one of the MongoDB Database Tools (mongodump, mongorestore, etc):
lookup nta8e.mongodb.net on 123.45.67.8:27017: cannot unmarshal DNS message
设置过程中,请选择以下连接选项之一:
Use the
--urioption with a non-SRV connection string (mongodb://).使用
--host选项指定要连接的托管。
使用 SRV 连接字符串拒绝的连接
When using the DNS seed list connection string format (mongodb+srv://) with a driver or Compass, you may receive in the following error:
Error: querySrv ECONNREFUSED _mongodb._tcp.<SRV Record>
要解决此错误,请完成以下步骤。
查找 DNS SRV 名称
在连接应用程序中按照步骤 1-6 进行操作。
选择您的驱动程序和版本。
在 Use this connection string in your application 下,SRV 主机名会出现在
mongodb+srv://连接字符串中。这是主机名中以.mongodb.net结尾的部分。例如:
cluster0.dfget.mongodb.net。
查找节点的主机名和端口号
在同一个 Connect 模态中:
在 Use this connection string in your application 下,关闭 SRV Connection String 开关。
显示标准连接字符串(
mongodb://),其中列出每个节点的主机名和端口号。集群的连接字符串可能有各种主机名和端口,具体取决于其拓扑结构和连接方法。要学习;了解有关私有端点的更多信息,请参阅配置私有端点。
测试基本网络连接
在出现问题的应用程序服务器上的终端或命令提示符中运行以下命令:
DNS SRV 解析测试
对于Linux或 macOS,运行以下命令:
dig SRV _mongodb._tcp.<DNS SRV name> 对于Windows,运行以下命令:
nslookup -debug -q=SRV _mongodb._tcp.<DNS SRV name> 在响应的回答部分下,您应能看到集群中每个节点的一个结果。例如:
;; ANSWER SECTION: _mongodb._tcp.gcluster0.dfget.mongodb.net. 60 IN SRV 0 0 27017 cluster0-shard-00-00.dfget.mongodb.net. _mongodb._tcp.gcluster0.dfget.mongodb.net. 60 IN SRV 0 0 27017 cluster0-shard-00-01.dfget.mongodb.net. _mongodb._tcp.gcluster0.dfget.mongodb.net. 60 IN SRV 0 0 27017 cluster0-shard-00-02.dfget.mongodb.net. DNS节点主机名解析测试
对于集群中的每个主机名:
对于Linux或 macOS,运行以下命令:
dig <Node Hostname> 对于Windows,运行以下命令:
nslookup -debug -q=A <Node Hostname> 在响应的回答部分下,您应能看到 DNS 主机名解析到的 IP 地址。 例如:
;; ANSWER SECTION: cluster0-shard-00-00.ag9in.mongodb.net. 60 IN A 10.10.10.10 网络探测(ping)测试
注意
云提供商可能会阻止通过私有端点连接的 ICMP 请求。
对于集群中的每个主机名:
对于Linux或 macOS,运行以下命令:
ping -c 10 <Node Hostname> 对于Windows,运行以下命令:
ping /n 10 <Node Hostname> 查看输出以检查数据包丢失和往返时间 (RTT)。较高的数据包丢失或延迟可能表明服务器和集群节点之间的网络问题。
端到端网络连接测试
对于Linux或 macOS,运行以下命令:
nc -zv <Node Hostname> <Node Port Number> 对于Windows,运行以下命令:
Test-NetConnection -Port <Node Port Number> -InformationLevel "Detailed" -ComputerName "<Node Hostname>"
解决问题
运行上一步测试后,根据失败的测试,使用以下指导解决连接错误:
DNS SRV 解析测试失败: 您的 DNS 解析器不支持 SRV 记录查询,或者外发 DNS 流量被阻止。尝试以下任一种方式:
Switch to the non-SRV connection string format (
mongodb://) instead ofmongodb+srv://. To get the non-SRV connection string, open the Connect modal in Atlas, select your driver and version, and turn off the SRV Connection String toggle under Use this connection string in your application.Configure your network to use a public DNS server that supports SRV lookups, such as Google Public DNS.
DNS节点主机名解析测试失败:您的 DNS 解析程序无法解析单个节点主机名。如果您使用私有端点,请验证私有端点 DNS 配置是否正确。
网络探测(ping) 测试失败:ICMP 流量可能被防火墙或云提供商阻止。这并不一定表明存在 TCP 连接问题。继续进行端到端网络连接测试,验证端口
27017上的 TCP 连接。端到端网络连接测试失败:防火墙或网络策略阻止访问权限节点节点上的端口
27017。验证以下内容:将应用程序服务器的IP解决添加到集群的IP访问列表。
允许端口
27017上的出站 TCP 连接通过防火墙。
All tests pass but the error persists: The issue may be in your driver version. Older driver versions might not correctly support the SRV connection string format. Update your driver to the latest version. You can also switch to the standard (non-SRV) connection string format (
mongodb://) by turning off the SRV Connection String toggle under Use this connection string in your application in the Connect modal.