连接到部署

本页展示如何使用 MongoDB Shell 连接到 MongoDB 部署。您可以连接到 MongoDB Atlas 云托管部署、连接到本地部署，或使用 MongoDB Shell 连接到另一个远程主机。

先决条件

要使用 MongoDB Shell，您必须有一个可供连接的 MongoDB 部署。

对于免费的云托管部署，您可以使用 MongoDB Atlas。
要了解如何运行本地 MongoDB 部署，请参阅安装 MongoDB。

支持的 MongoDB 版本

您可以使用 MongoDB Shell 连接 MongoDB 4.2 或更高版本。

安装 `mongosh`

这些步骤假设您已安装 mongosh。有关安装 mongosh 的更多信息，请参阅安装 mongosh。

连接到 MongoDB Atlas 部署

您可以直接从 shell 连接到 MongoDB Atlas 部署。

获取您的 Atlas 连接字符串

您需要一个 Atlas 连接字符串才能在 MongoDB Shell 上进行连接。您可以在 Atlas UI 中获取 Atlas 连接字符串。

有关详细信息，请参阅查找您的 MongoDB Atlas 连接字符串指南。

设置数据库档案

如果尚未创建数据库用户，则必须设置用户名和密码。要连接到 Atlas，请将用户名与 Atlas 连接字符串一起传递。发出连接命令后，shell 会提示输入密码。

通过 mongosh 连接到 MongoDB Atlas `mongosh`

要建立连接，请使用连接字符串和选项运行 mongosh 命令来建立连接。

连接字符串包括以下元素：

您的集群名称
哈希值
API 版本的标志
待连接的用户名的标志

它类似于以下字符串：

mongosh "mongodb+srv://YOUR_CLUSTER_NAME.YOUR_HASH.mongodb.net/" --apiVersion YOUR_API_VERSION --username YOUR_USERNAME

注意

了解详情

您可以使用其他连接安全选项通过mongosh连接到 Atlas。有关使用私有 IP 进行对等互连或私有端点连接的信息，请参阅通过 mongosh 连接 Atlas Connect 文档。

通过默认端口连接到本地部署

要使用默认端口 27017 连接到在本地主机上运行的 MongoDB 部署，请运行不带任何选项的mongosh：

mongosh

这相当于以下命令：

mongosh "mongodb://localhost:27017"

连接到非默认端口上的本地部署

要指定在本地主机上连接到的端口，可以使用以下任一方法：

带有所选端口的连接字符串
--port 命令行选项

例如，以下命令会连接到在本地主机端口 28015 上运行的部署：

mongosh "mongodb://localhost:28015"

mongosh --port 28015

连接到远程主机上的部署

要指定远程主机和端口，可以使用以下两种方法之一：

具有所选主机和端口的连接字符串。
--host 和 --port 命令行选项。如果省略 --port 选项，mongosh 会使用默认端口 27017。

例如，以下命令连接到在主机 mongodb0.example.com 和端口 28015 上运行的 MongoDB 部署：

mongosh "mongodb://mongodb0.example.com:28015"

mongosh --host mongodb0.example.com --port 28015

注意

连接到 MongoDB Atlas

如果远程主机是 Atlas 集群，则可以从 Atlas UI 复制连接字符串。要了解更多信息，请参阅 Atlas 文档中的连接到集群。

指定连接选项

指定不同的连接选项以连接到不同类型的部署。

使用身份验证进行连接

要连接到需要身份验证的 MongoDB 部署，请使用--username和--authenticationDatabase选项。mongosh会提示您输入密码，该密码会在您键入时隐藏。

例如，要以用户 alice 的身份在 admin 数据库上进行身份验证，请运行以下命令：

mongosh "mongodb://mongodb0.example.com:28015" --username alice --authenticationDatabase admin

如要在连接命令中提供密码而不是使用提示符，请使用 --password 选项。使用此选项以编程方式使用 mongosh，类似于驱动程序。

另请参阅：

要为部署实施身份验证，请参阅启用访问控制。
要为 MongoDB 部署提供访问权限，请参阅数据库用户。

使用 OpenID Connect 进行连接

要使用 OpenID Connect 连接到部署，请使用 --authenticationMechanism 选项并将其设置为 MONGODB-OIDC。mongosh 会将您重定向到浏览器，您可以在其中输入身份提供商的登录信息。

例如，以下命令使用 MONGODB-OIDC 连接到本地部署：

mongosh "mongodb://localhost/" --authenticationMechanism MONGODB-OIDC

与 LDAP 连接

要使用 LDAP 连接到部署：

将 --username 设置为遵循 security.ldap.authz.queryTemplate 的用户名或任何已配置的 security.ldap.userToDNMapping 模板。
将--password设置为相应的密码。如果您没有为--password命令行选项指定密码，mongosh会提示您输入密码。
将 --authenticationDatabase 设置为 $external。$external 参数必须放在单引号中，而不是双引号中，以防止 Shell 将 $external 解释为变量。
将 --authenticationMechanism 设置为 PLAIN。

警告

当您使用一次性密码进行 LDAP 身份验证时，建议在连接字符串中添加连接字符串选项 maxPoolSize=1&srvMaxHosts=1，以减少连接失败的可能性。

包括 MongoDB 部署的 --host 和 --port 以及与部署相关的任何其他选项。

例如，以下操作展示了如何对一个已启用 LDAP 认证和授权的 MongoDB 部署进行身份验证：

mongosh --username alice@dba.example.com --password  --authenticationDatabase '$external' --authenticationMechanism "PLAIN"  --host "mongodb.example.com" --port 27017

连接到副本集

要连接到副本集，可以执行以下任一操作：

使用 DNS 种子列表连接格式。
在连接字符串中显式指定副本集的名称和其中节点。

选项 1：DNS 种子列表格式

要使用 DNS 种子列表连接格式，请在连接字符串中包含 +srv 修饰符。

例如，要连接到 server.example.com 上的副本集，请运行以下命令：

mongosh "mongodb+srv://server.example.com/"

注意

+srv TLS 行为

使用 +srv 连接字符串修饰符时，MongoDB 会自动将--tls连接选项设置为 true。要覆盖此行为，请将 --tls 设置为 false。

方案 2：在连接字符串中指定节点

您可以在连接字符串中指定单个副本集节点。

例如，要连接到名为replA 的三成员副本集，运行以下命令：

mongosh "mongodb://mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017/?replicaSet=replA"

注意

自动添加 directConnection 参数

在连接字符串中指定各副本集成员时，mongosh 会自动添加directConnection=true 参数，除非至少满足以下条件之一：

连接字符串中存在 replicaSet 查询参数。
连接字符串使用 mongodb+srv:// 连接字符串格式。
连接字符串包含具有多个主机的种子列表。
连接字符串已包含 directConnection 参数。

如果 directConnection=true，则所有操作都在连接 URI 中指定的主机上运行。

使用 TLS 连接

要使用 TLS 连接到部署，您可以：

使用 DNS 种子列表连接格式。+srv 连接字符串修饰符会自动将连接的 tls 选项设置为 true。
例如，要连接到已启用 tls 且由 DNS 种子列表定义的副本集，请运行以下命令：
```
mongosh "mongodb+srv://server.example.com/"
```
在连接字符串中将--tls选项设置为 true。
例如，要使用连接字符串选项启用 tls，请运行以下命令：
```
mongosh "mongodb://mongodb0.example.com:28015/?tls=true"
```
指定 --tls 命令行选项。
例如，要连接已启用 tls 的远程主机，请运行以下命令：
```
mongosh "mongodb://mongodb0.example.com:28015" --tls
```

连接到特定数据库

要连接到特定的默认数据库，请在连接字符串URI 路径中指定数据库。如果连接字符串未指定，默认数据库为 test数据库。

例如，要连接本地主机上名为 qa 的数据库，请运行以下命令：

mongosh "mongodb://localhost:27017/qa"

您可以使用 authSource 连接选项在连接字符串中指定身份验证数据库。如果指定，客户端将使用此数据库来验证用户身份和凭证。如果未指定 authSource，则默认为连接字符串中指定的默认数据库。如果 authSource 和默认数据库均未指定，则 authSource 默认为 admin数据库。

以下连接字符串将默认数据库设置为 myDefaultDB，并将身份验证数据库设置为 admin：

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb0.example.com:27017/myDefaultDB?authSource=admin

代理设置

要建立与代理配置的连接，您可以使用以下环境变量：

变量

说明

例子

MONGODB_PROXY

与 mongodb:// 和 mongodb+srv:// URL 的代理连接，例如数据库集群。

以下示例将 MONGODB_PROXY 环境变量设置为通过位于 example.com:8080 且启用 TLS 的 CONNECT 代理来代理所有 MongoDB 连接。

export MONGODB_PROXY=https://example.com:8080

HTTP_PROXY

与 http:// URL 的代理连接。HTTP 连接主要用于 OIDC 身份验证。

如果您还设置了 HTTPS_PROXY，则对于所有请求，HTTPS_PROXY 的值优先。

以下示例将 HTTP_PROXY 环境变量设置为通过位于 example.com:8080 的 CONNECT 代理来代理 HTTP 连接：

export HTTP_PROXY=http://example.com:8080

HTTPS_PROXY

与 https:// URL 的代理连接。HTTPS 连接主要用于 OIDC身份验证。

如果您还设置了 HTTP_PROXY，则对于所有请求，HTTPS_PROXY 的值优先。

以下示例将 HTTPS_PROXY 环境变量设置为通过位于 localhost:8080 的 CONNECT 代理来代理所有 HTTPS 连接，而无需 TLS：

export HTTPS_PROXY=http://localhost:8080

ALL_PROXY

将所有连接代理到指定的 URL。

以下示例将 ALL_PROXY 环境变量设置为通过位于 example.com:1234 且 URL 包含凭证的 Socks5 代理来代理所有出站网络连接：

export ALL_PROXY=socks5://username:password@example.com:1234

NO_PROXY

以逗号分隔的应从代理中排除的主机名列表。

以下示例将 NO_PROXY 环境变量设置为绕过代理连接到 localhost 和 internal-db.example.com。

export NO_PROXY=localhost,internal-db.example.com

注意

mongosh 支持以下代理类型：

Socks5 代理
HTTP 代理
CONNECT 代理
解析为先前列出的代理之一的 PAC URL

连接到其他部署

如果您已经连接到 MongoDB Shell 中的某个部署，您可以使用 Mongo() 或 connect() 方法连接到 MongoDB Shell 中不同的部署。

要了解如何使用这些方法连接到不同的部署，请参阅打开新连接。

验证当前连接

要验证当前的数据库连接，请使用 db.getMongo() 方法。

该方法返回您当前连接的连接字符串 URI。

断开与部署的连接

要断开与部署的连接并退出 mongosh，请执行以下操作之一：

键入 .exit、exit 或 exit()。
输入quit或quit()。
按 Ctrl + D。
按 Ctrl + C 两次。

非正版部署

当您连接到非正版的 MongoDB 实例时，shell 会显示一条警告消息。由于功能缺失、不一致或不完整，非正版实例的交互表现可能与官方的 MongoDB 实例有所差异。

限制

Kerberos 身份验证不允许在连接字符串中使用 authMechanismProperties=CANONICALIZE_HOST_NAME:true|false。请改用任一项：
- authMechanismProperties=CANONICALIZE_HOST_NAME:forward
- authMechanismProperties=CANONICALIZE_HOST_NAME:forwardAndReverse
- authMechanismProperties=CANONICALIZE_HOST_NAME:none
mongosh 目前仅支持 zlib 压缩程序。不支持以下压缩程序：
- zstd
- snappy
从mongosh 2.0.0 开始：
对于连接字符串中的布尔值，您可以：
- 必须使用true或false 。
- 不能使用 1、y、yes 或 t 代替 true。
- 不能使用 -1、0、n、no 或 f 代替 false。

后退

验证 Windows 包

来年

配置