MongoDB 8 常用 CLI 命令与工具详解

详解 MongoDB 8 常用命令行客户端与运维工具（mongosh、mongodump、mongorestore、mongoexport、mongoimport、mongostat、mongotop、bsondump），逐个给出完整命令、真实输出与参数说明。

MongoDBMongoDB数据库参数调优文档型NoSQL2026/09/27

MongoDB 8 常用 CLI 命令与工具详解

目标：详解 MongoDB 8 常用的命令行客户端与运维工具（mongosh、mongodump、mongorestore、mongoexport、mongoimport、mongostat、mongotop、bsondump），每个工具给出完整命令、真实输出与参数说明。所有命令均在真实 MongoDB 8 服务器环境实测，并以实际输出为准。

环境信息

  • 数据库服务器：MongoDB 8.0.32，主机名 mongo-srv（内网 IP 10.0.0.10）
  • 服务监听端口：27017（客户端与服务器之间需放行该端口）
  • 认证：已开启认证，管理员用户 admin，文档命令中密码以 ${MONGO_INITDB_ROOT_PASSWORD} 占位，禁止明文）
  • 测试库：app_db.employees（5 条中文文档）
  • 测试客户端：mongosh 2.11.1、数据库工具 mongodump/mongoexport 等 100.18.0

工具概览

工具主要用途版本
mongosh交互式/脚本 Shell（CRUD、聚合、索引、explain）2.11.1
mongodump逻辑备份（BSON 二进制）100.18.0
mongorestore从 mongodump 输出恢复100.18.0
mongoexport导出 JSON / CSV100.18.0
mongoimport导入 JSON / CSV100.18.0
mongostat实时运行状态采样100.18.0
mongotop各命名空间读写耗时统计100.18.0
bsondumpBSON 文件解析为可读格式100.18.0

前置条件

  • 已部署 MongoDB 8（参考《MongoDB 8.0 Docker Compose 部署指南》），认证开启
  • 连接 URI 需携带 authSource=admin（认证库）
  • 密码含特殊字符时，URI 中需 URL 编码（如 @ → %40）或改用 --username/--password 参数

1. mongosh 客户端

mongosh 是 MongoDB 官方 Shell，支持 CRUD、聚合管道、索引管理、执行计划分析。

1.1 连接与版本

mongosh --version

# URI 连接（authSource=admin 指定认证库）
mongosh "mongodb://admin:${MONGO_INITDB_ROOT_PASSWORD}@127.0.0.1:27017/?authSource=admin" --quiet

1.2 基础操作（实测输出）

# 列出数据库
mongosh "${URI}" --quiet --eval "db.adminCommand({listDatabases:1}).databases.forEach(d=>print(d.name + ' ' + (d.sizeOnDisk/1024/1024).toFixed(1) + 'MB'))"

admin 0.1MB
app_db 0.1MB
config 0.2MB
local 0.1MB

# 条件查询（--eval 非交互执行）
mongosh "${URI}" --quiet --eval "db.getSiblingDB('app_db').employees.find({dept:'研发部'},{_id:0}).toArray()"

[
  { name: '张三', dept: '研发部', salary: 25000, hired: ISODate('2022-03-01T00:00:00.000Z') },
  { name: '李四', dept: '研发部', salary: 22000, hired: ISODate('2023-05-15T00:00:00.000Z') }
]

# 聚合管道：按部门分组统计
mongosh "${URI}" --quiet --eval "db.getSiblingDB('app_db').employees.aggregate([{\$group:{_id:'\$dept',total:{\$sum:'\$salary'},avg:{\$avg:'\$salary'},n:{\$sum:1}}}]).toArray()"

[
  { _id: '研发部', total: 47000, avg: 23500, n: 2 },
  { _id: '市场部', total: 34000, avg: 17000, n: 2 },
  { _id: '财务部', total: 20000, avg: 20000, n: 1 }
]

# 创建复合索引
mongosh "${URI}" --quiet --eval "db.getSiblingDB('app_db').employees.createIndex({dept:1,salary:-1}); db.getSiblingDB('app_db').employees.getIndexes().forEach(i=>print(i.name + ' -> ' + JSON.stringify(i.key)))"

_id_ -> {"_id":1}
dept_1_salary_-1 -> {"dept":1,"salary":-1}

# 执行计划分析（explain）
mongosh "${URI}" --quiet --eval "const e=db.getSiblingDB('app_db').employees.find({dept:'市场部'}).explain('executionStats'); print('返回 ' + e.executionStats.nReturned + ' 行, 索引: ' + e.queryPlanner.winningPlan.inputStage.stage)"

返回 2 行, 索引: IXSCAN

💡 命令解释：db.getSiblingDB('库') 切换目标库（脚本中避免用全局 db 的默认库）；--quiet 去掉提示横幅；--eval 非交互执行 JS 脚本；聚合管道 $group 按字段分组 + $sum/$avg 聚合；createIndex 建复合索引，explain('executionStats') 查看是否走索引（IXSCAN=索引扫描、COLLSCAN=全表扫描）。

2. mongodump / mongorestore

二进制逻辑备份与恢复。

2.1 连接方式注意（真实踩坑）

密码含 @ 时 URI 需转义，推荐使用参数形式连接：

# URI 方式（密码含 @ 需转义为 %40）
mongodump "mongodb://admin:AppTest%402026@127.0.0.1:27017/?authSource=admin" --db app_db --out /tmp/backup/dump

# 参数方式（推荐，无需转义）
mongodump --host 127.0.0.1 --port 27017 \
  --username admin --password "${MONGO_INITDB_ROOT_PASSWORD}" --authenticationDatabase admin \
  --db app_db --out /tmp/backup/dump

执行结果：

2026-09-27T01:39:03.604+0800    writing `app_db.t1` to `/tmp/backup/dump/app_db/t1.bson`
2026-09-27T01:39:03.609+0800    done dumping `app_db.employees` (5 documents)

/tmp/backup/dump/app_db:
employees.bson
employees.metadata.json
t1.bson

⚠️ 密码特殊字符 URI 编码对照（mongosh 与全部数据库工具通用）：

字符URL 编码说明
@%40最常见的坑（实测报 unescaped @ sign in user info）
:%3A密码/用户内含冒号时
/%2F密码内含斜杠时
?%3F密码内含问号时（易截断查询参数）
&%26密码内含 & 时
#%23密码内含井号时

所有 MongoDB 工具（mongosh/mongodump/mongorestore/mongoexport/mongoimport/mongostat/mongotop）都支持 --username/--password --authenticationDatabase 参数形式，密码含特殊字符时优先使用参数形式，可完全规避 URI 编码问题。

2.2 mongorestore 恢复

mongorestore --host 127.0.0.1 --port 27017 \
  --username admin --password "${MONGO_INITDB_ROOT_PASSWORD}" --authenticationDatabase admin \
  --db app_db --drop /tmp/backup/dump/app_db

执行结果：

2026-09-27T01:39:03.787+0800    6 document(s) restored successfully. 0 document(s) failed to restore.

💡 命令解释：--out 指定备份输出目录（结构为 out/<库>/<集合>.bson + metadata.json）；mongorestore --drop 恢复前先删同名集合（避免主键冲突）；恢复验证：db.app_db.employees.countDocuments() 返回 5。

3. mongoexport / mongoimport

JSON / CSV 格式导入导出（跨系统交换常用）。

# 导出 JSON
mongoexport --host 127.0.0.1 --port 27017 --username admin --password "${MONGO_INITDB_ROOT_PASSWORD}" \
  --authenticationDatabase admin --db app_db --collection employees --out /tmp/backup/employees.json

# 导出 CSV（--fields 指定列）
mongoexport --host 127.0.0.1 --port 27017 --username admin --password "${MONGO_INITDB_ROOT_PASSWORD}" \
  --authenticationDatabase admin --db app_db --collection employees \
  --type=csv --fields name,dept,salary --out /tmp/backup/employees.csv

执行结果：

exported 5 records
{"_id":{"$oid":"6ab80311dc40d564c8023275"},"name":"张三","dept":"研发部","salary":25000,"hired":{"$date":"2022-03-01T00:00:00Z"}}

name,dept,salary
张三,研发部,25000
李四,研发部,22000
赵六,财务部,20000
钱七,市场部,16000

# 导入 JSON 到新集合
mongoimport --host 127.0.0.1 --port 27017 --username admin --password "${MONGO_INITDB_ROOT_PASSWORD}" \
  --authenticationDatabase admin --db app_db --collection import_test --file /tmp/backup/employees.json

# 导入 CSV（--headerline 用首行做字段名）
mongoimport --host 127.0.0.1 --port 27017 --username admin --password "${MONGO_INITDB_ROOT_PASSWORD}" \
  --authenticationDatabase admin --db app_db --collection import_csv \
  --type=csv --headerline --file /tmp/backup/employees.csv

执行结果：

5 document(s) imported successfully. 0 document(s) failed to import.
5 document(s) imported successfully. 0 document(s) failed to import.

💡 命令解释：mongoexport --type=csv --fields 指定导出列；mongoimport --headerline 以 CSV 首行作为字段名（否则需 --fields 指定）；JSON 格式默认使用扩展 JSON（$oid/$date），保证类型无损。

4. mongostat / mongotop

实时监控工具。

# 每秒采样，--rowcount 限制次数
mongostat --host 127.0.0.1 --port 27017 --username admin --password "${MONGO_INITDB_ROOT_PASSWORD}" \
  --authenticationDatabase admin --rowcount=3

执行结果：

insert query update delete getmore command dirty used flushes vsize  res qrw arw net_in net_out conn                time
    *0    *0     *0     *0       0     1|0  0.0% 0.0%       0 3.59G 194M 0|0 0|0   112b    112k    3 Sep 27 01:39:17.540
    *0    *0     *0     *0       0     1|0  0.0% 0.0%       0 3.59G 194M 0|0 0|0   112b    111k    3 Sep 27 01:39:18.538

# 各命名空间读写耗时（毫秒）
mongotop --host 127.0.0.1 --port 27017 --username admin --password "${MONGO_INITDB_ROOT_PASSWORD}" \
  --authenticationDatabase admin --rowcount=3

执行结果：

                    ns    total    read    write    2026-09-27T01:39:20+08:00
        admin.atlascli      0ms     0ms      0ms
    admin.system.users      0ms     0ms      0ms
  admin.system.version      0ms     0ms      0ms
      app_db.employees      0ms     0ms      0ms

💡 命令解释：mongostat 采样各类操作计数、dirty/used 缓存队列、qrw/arw 读写队列、res 常驻内存、net_in/out 网络字节；mongotop 按命名空间展示读写耗时（毫秒），可快速定位热点集合。*N 表示采样周期内的增量计数（--rowcount 限定采样次数，生产可 --json 输出供监控采集）。

5. bsondump

把 .bson 备份文件解析为可读格式（调试 dump 文件）。

bsondump --version
bsondump /tmp/backup/dump/app_db/employees.bson | head -2

执行结果：

bsondump version: 100.18.0
{"_id":{"$oid":"6ab80311dc40d564c8023275"},"name":"张三","dept":"研发部","salary":{"$numberInt":"25000"},"hired":{"$date":{"$numberLong":"1646092800000"}}}
{"_id":{"$oid":"6ab80311dc40d564c8023276"},"name":"李四","dept":"研发部","salary":{"$numberInt":"22000"}}

💡 说明：bsondump 输出扩展 JSON（$numberInt/$date 为类型标注），用于快速检视备份文件内容；配合 --bson-file 可指定解析对象。

注意事项

  • 密码特殊字符：URI 中 @、: 等需 URL 编码（@→%40），实测 unescaped @ sign in user info 报错即由此产生；工具连接推荐 --username/--password --authenticationDatabase 参数形式。
  • authSource=admin：管理员账号在 admin 库认证，连接 URI 必须带 authSource=admin。
  • --eval 转义：脚本中聚合 $group 等符号需按 shell 转义（bash 单引号内写 $group，双引号内写 \$group）。
  • 大库备份：mongodump 为逻辑备份较慢，大数据量推荐 mongodb://... + Oplog 或 Atlas/Cloud Manager 快照；mongorestore --drop 会删原集合，恢复前确认。
  • mongostat 无数据时：采样输出 *0 表示该周期内无该操作计数，正常现象。

常见问题

问题 1：error parsing uri: unescaped @ sign in user info

原因： 连接 URI 的密码中含 @（或其他特殊字符）未转义，URI 解析失败。

解决： 转义 @ 为 %40，或改用参数连接：

mongodump --host 127.0.0.1 --port 27017 --username admin --password "密码含@符号" --authenticationDatabase admin --db app_db

问题 2：认证失败 Authentication failed

原因： 认证库错误（默认用连接串中第一个库认证）或密码错误。

解决： URI 显式指定 authSource=admin；确认密码正确。

问题 3：mongorestore 报 duplicate key error

原因： 目标集合已存在相同 _id 的文档。

解决： 恢复前加 --drop（先删集合再恢复），或使用 --mode=upsert 覆盖式恢复：

mongorestore --drop ...

问题 4：mongoimport CSV 字段错位

原因： CSV 无表头且未指定字段顺序。

解决： CSV 文件首行放字段名并用 --headerline；或 --fields name,dept,salary 显式声明列序。

参考链接

本文档由 www.quzuo.net 平台开发

MongoDB 8 常用 CLI 命令与工具详解 - Quzuo