高效排查常见MongoDB命令错误

当您放慢速度并确定故障发生位置时，MongoDB命令错误更容易修复。是mongosh无法解析您输入的内容？还是服务器因用户缺少角色而拒绝命令？客户端是否连接到了错误的数据库？主节点是否不可用？这些都是不同的问题，即使它们在shell中都显示为红色文本。

我喜欢从三个检查开始：我连接到了哪个服务器，我正在使用哪个数据库，以及我以哪个用户身份进行了认证？

db.getName()
db.hello()
db.runCommand({ connectionStatus: 1 })

这些命令可以避免大量浪费的调试时间。许多“MongoDB命令错误”实际上是上下文错误：从错误的数据库运行管理命令，针对错误的authSource进行认证，或者在打算写入主节点时对从节点进行测试。

理解MongoDB命令错误类别

MongoDB命令错误通常可以分为几个主要类型：

语法错误：MongoDB shell或驱动程序无法解析的命令格式不正确。
权限错误：尝试在没有必要用户权限的情况下执行操作。
操作错误：命令执行过程中出现的问题，例如网络问题、资源限制或数据不一致。
连接错误：建立与MongoDB服务器连接时出现问题。

常见语法错误及解决方案

语法错误通常是最容易修复的，通常源于拼写错误、缺少字符或参数使用不正确。MongoDB shell (mongosh) 通常能很好地为这些问题提供信息丰富的错误消息。

1. 无效的字段名称或文档结构

插入或更新文档时，使用不正确的字段名称或无效的文档结构可能导致错误。

示例错误：

db.users.insertOne({ "bad\u0000field": "Alice" })
// MongoServerError: The dotted field 'bad\u0000field' ... is not valid for storage

解释： MongoDB字段名称不能包含空字符。包含连字符的字段名称（例如"email-address"）是允许的，尽管查询起来可能很麻烦，因为您必须引用它们。真正的问题是无效字符或MongoDB无法存储的结构。

解决方案：

仔细检查由导入、用户输入或序列化代码生成的字段名称。选择一致的命名约定，例如emailAddress或email_address，并在数据到达MongoDB之前进行验证。

> db.users.insertOne({ name: "Alice", age: 30, emailAddress: "[email protected]" })
{ acknowledged: true, insertedId: ObjectId('...') }

2. 缺少或多余的逗号

与JavaScript类似，MongoDB shell命令对对象和数组中逗号的正确放置很敏感。

示例错误：

db.products.insertOne({ name: "Laptop", price: 1200,, })
// SyntaxError: Unexpected token

解决方案：

删除多余的逗号。确保格式一致以提高可读性。

> db.products.insertOne({ name: "Laptop", price: 1200 })
{ acknowledged: true, insertedId: ObjectId('...') }

3. 不正确的命令语法（例如，`find` vs. `findOne`）

使用错误的命令或以错误的顺序提供参数也可能导致错误。

示例：

db.inventory.find({ item: "notebook" }, { qty: 1, size: 1, _id: 0 })
// 这个命令在语法上对find是正确的，但如果您打算只查找一个文档：

解决方案：

如果您打算只检索单个文档，请使用findOne。find返回一个游标，而findOne返回文档本身。

> db.inventory.findOne({ item: "notebook" }, { qty: 1, size: 1, _id: 0 })
{
  qty: 20,
  size: { h: 14, w: 21, uom: "cm" },
  ... // 如果投影没有排除它们并且它们没有被特别投影出去，则其他字段
}

常见权限错误

权限错误通常发生在用户尝试执行其缺乏必要角色或权限的操作时。

1. 执行命令的权限不足

此错误消息明确指出了权限不足。

示例错误：

> db.adminCommand({ listDatabases: 1 })
Error: listDatabases requires authentication

解释： listDatabases是一个管理命令，需要认证和正确的权限。一个用户可能对一个应用程序数据库有效，但仍然无法检查整个部署。

解决方案：

使用适当的凭据进行认证： 使用具有必要角色的用户连接到MongoDB。对于listDatabases，您可能需要以管理员身份连接。
```
mongosh "mongodb://<adminUser>:<adminPassword>@<host>:<port>/admin?authSource=admin"
```
然后，再次尝试该命令：
```
db.adminCommand({ listDatabases: 1 })
```

授予角色： 如果您是数据库管理员，请将所需的角色授予遇到问题的用户。

// 示例：在'admin'数据库上授予用户'myUser' readAnyDatabase角色
use admin
db.grantRolesToUser("myUser", [ { role: "readAnyDatabase", db: "admin" } ])

2. 写入操作被拒绝

在没有写入权限的情况下尝试在集合或数据库中插入、更新或删除文档。

示例错误：

> db.myCollection.insertOne({ name: "Test" })
WriteError: Not enough privileges to execute on "myCollection" with operation "insert"

解决方案：

以具有写入权限的用户身份进行认证 针对目标数据库/集合。
授予写入角色（例如，readWrite，dbOwner）给用户。
检查提示中的数据库。 一个在appdb上被授予readWrite的用户不会自动拥有对test的写入权限，即使集合名称相同。

认证和`authSource`错误

认证错误通常看起来很令人困惑，因为MongoDB用户属于特定的认证数据库。许多应用程序用户在应用程序数据库中创建。管理员用户通常在admin中创建。

如果您看到：

MongoServerError: Authentication failed.

在更改密码之前检查连接字符串：

mongosh "mongodb://appUser:secret@db01:27017/appdb?authSource=appdb"

如果用户是在admin中创建的，请使用：

mongosh "mongodb://adminUser:secret@db01:27017/appdb?authSource=admin"

主机后的数据库路径（/appdb）是您的shell打开的默认数据库。authSource是MongoDB查找用户帐户的位置。混淆这两者是导致从本地开发数据库迁移到安全服务器后登录失败的常见原因。

您可以使用以下命令确认当前已认证的用户：

db.runCommand({ connectionStatus: 1 })

常见操作错误及解决方案

操作错误可能更复杂，通常与MongoDB部署的状态、网络问题或资源限制有关。

1. 网络超时或连接被拒绝

这些错误表明客户端无法建立或维持与MongoDB服务器的连接。

示例错误（客户端）：

Error: connect ECONNREFUSED 127.0.0.1:27017

解释： 客户端尝试连接到指定的主机和端口，但连接被拒绝。这可能意味着MongoDB服务器未运行，正在不同的端口上运行，或者防火墙正在阻止连接。

解决方案：

验证MongoDB服务器状态： 确保mongod进程在服务器上运行。
- 在Linux上：sudo systemctl status mongod 或 sudo service mongod status
- 在macOS上（使用Homebrew）：brew services list
- 在Windows上：检查服务应用程序。
检查MongoDB配置： 确认mongod配置为监听正确的IP地址和端口（默认为27017）。检查mongod.conf文件。
防火墙规则： 确保没有防火墙（服务器级别或网络级别）阻止MongoDB端口上的流量。
正确的连接字符串： 仔细检查您的连接字符串中主机和端口的拼写错误。

对于副本集，当您的驱动程序期望时，请包含副本集名称：

mongosh "mongodb://db01:27017,db02:27017,db03:27017/appdb?replicaSet=rs0"

如果涉及DNS，请从客户端机器测试确切的主机名：

nc -vz db01.example.com 27017

从数据库服务器本身成功连接并不能证明应用程序服务器、CI运行器或堡垒主机可以访问它。

2. 文档大小限制超出

MongoDB文档有最大BSON大小限制（目前为16MB）。

示例错误：

> db.largeDocs.insertOne({ data: "... very large string ..." })
Error: BSONObj size: 17000000 bytes is too large, max 16777216 bytes

解决方案：

拆分大型文档： 将大型文档分解为更小的、相关的文档。使用引用（例如，ObjectId）来链接它们。
使用GridFS： 对于存储超过文档大小限制的大型二进制文件（如图像或视频），请使用MongoDB的GridFS规范。
避免无界数组： 一个无限增长的文档，例如一个用户文档嵌入了所有事件，最终会变慢或达到限制。将高容量的子记录存储在自己的集合中。

3. 写关注错误

写关注指定了MongoDB对写操作所需的确认保证。如果在超时内未满足这些保证，则会发生写关注错误。

示例：

// 具有特定写关注的写操作示例
db.myCollection.insertOne({ name: "Item" }, { writeConcern: { w: "majority", wtimeout: 1000 } });

潜在错误：

WriteConcernError: waiting for replication timed out

解释： 写操作失败，因为所需数量的节点（在这种情况下为majority）未在指定的wtimeout（1000毫秒）内确认写入。

解决方案：

调查副本集健康状况： 检查MongoDB副本集的健康状况和状态。节点是否滞后？节点之间是否存在网络问题？
增加wtimeout： 如果临时网络延迟或复制延迟是原因，您可以考虑增加wtimeout值，但这应谨慎进行，因为它可能掩盖根本问题。
审查写关注： 确保写关注级别（w）适合您的应用程序需求。w: 1（默认值）只需要主节点的确认，不太容易出现超时问题，但提供的持久性保证较低。

4. 非主节点或读偏好错误

写入必须发送到副本集中的主节点。如果您的shell或应用程序连接到从节点并尝试写入，您可能会看到类似于以下的错误：

MongoServerError: not primary

检查您连接的位置：

db.hello()

如果isWritablePrimary为false，请通过正确的副本集URI连接或将写入路由到主节点。对于读取，请根据您的应用程序决定是否接受从节点读取。从节点读取可能包含过期数据，因此除非该用例允许读取过期数据，否则不要仅仅为了消除错误而启用它们。

5. 重复键错误

重复键错误通常意味着唯一索引正在发挥作用。

E11000 duplicate key error collection: app.users index: email_1 dup key

不要通过删除唯一索引来“修复”此问题，除非唯一性规则实际上是错误的。首先识别索引：

db.users.getIndexes()

然后决定应用程序是应该更新现有文档、拒绝重复项还是使用upsert：

db.users.updateOne(
  { email: "[email protected]" },
  { $set: { lastLoginAt: new Date() } },
  { upsert: true }
)

使用upsert时，请确保过滤器匹配您关心的唯一键。一个宽松的过滤器仍然可以在不同的唯一字段上创建重复项并失败。

6. 查询操作符错误

一些错误源于在错误的位置使用更新或查询操作符。

这对于替换样式的更新是错误的：

db.users.updateOne(
  { email: "[email protected]" },
  { lastLoginAt: new Date() }
)

MongoDB将第二个文档视为替换文档。如果您打算更改一个字段，请使用$set：

db.users.updateOne(
  { email: "[email protected]" },
  { $set: { lastLoginAt: new Date() } }
)

这种区别很重要，因为替换更新可能会删除未包含在替换文档中的字段。

实用的调试例程

当命令失败时，捕获确切的错误，然后按顺序回答以下问题：

mongosh是否连接到了预期的主机？
```
db.hello().me
```
我是否在使用预期的数据库？
```
db.getName()
```
我是否已认证，并且具有哪些角色？
```
db.runCommand({ connectionStatus: 1 })
```
这是解析错误、服务器错误还是写关注错误？

解析错误通常在命令到达服务器之前出现。权限错误、重复键错误、非主节点错误、验证错误和写关注错误来自MongoDB评估命令之后。
相同的命令是否适用于最小的文档？

如果一个小插入有效但实际插入失败，请检查文档形状、大小、字段名称、模式验证和唯一索引。
失败是否取决于节点？

副本集和分片集群问题可能只出现在某些节点上或通过某些路由器出现。对于分片集群，应用程序流量通常应通过mongos，而不是直接发送到分片成员。

无需猜测即可读取日志

MongoDB日志通常比shell输出更清晰地解释服务器端原因。在Linux软件包安装中，检查服务日志：

journalctl -u mongod --since "30 minutes ago"

或从mongod.conf中配置的MongoDB日志路径。

查找与失败命令时间戳附近的消息。有用的线索包括认证失败、连接重置、慢操作、复制状态更改、磁盘已满错误和模式验证失败。

对于慢查询或失败查询，explain()比猜测更有用：

db.orders.find({ customerId: 123, status: "open" }).explain("executionStats")

如果查询扫描大量文档以返回少量结果，则命令可能在语法上正确，但在操作上代价高昂。这不是shell问题，而是索引或查询形状问题。

预防命令错误的最佳实践

使用mongosh及其功能： 利用现代MongoDB Shell提供的Tab补全、命令历史和清晰的错误消息。
理解您的数据模型： 仔细设计您的模式和文档结构，以避免文档过大或查询效率低下等问题。
实施适当的认证和授权： 为用户定义其角色所需的最小权限。
监控您的部署： 定期检查MongoDB日志、性能指标和副本集状态，以主动识别潜在问题。
测试命令： 在将复杂命令或更改部署到生产环境之前，在开发或暂存环境中彻底测试它们。
按计划更新MongoDB： 较新的版本可能包含错误修复和行为更改。在生产环境推出之前，阅读发行说明并测试升级。

一旦您将shell语法、认证上下文、授权、拓扑结构和数据形状问题分开，大多数MongoDB命令错误就变得可控了。首先证明您连接到了哪里以及您是谁。然后让确切的错误消息将您指向下一层，而不是随机重写命令。

高效排查常见MongoDB命令错误

理解MongoDB命令错误类别

常见语法错误及解决方案

1. 无效的字段名称或文档结构

2. 缺少或多余的逗号

3. 不正确的命令语法（例如，find vs. findOne）

常见权限错误

1. 执行命令的权限不足

2. 写入操作被拒绝

认证和authSource错误

常见操作错误及解决方案

1. 网络超时或连接被拒绝

2. 文档大小限制超出

3. 写关注错误

4. 非主节点或读偏好错误

5. 重复键错误

6. 查询操作符错误

实用的调试例程

无需猜测即可读取日志

预防命令错误的最佳实践

3. 不正确的命令语法（例如，`find` vs. `findOne`）

认证和`authSource`错误