mongodb

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MongoDB

MongoDB

Administer, optimize, and secure MongoDB NoSQL databases in development and production environments.
在开发和生产环境中管理、优化和保护MongoDB NoSQL数据库。

When to Use

适用场景

  • You need a document-oriented database with flexible schemas.
  • Your data is semi-structured or heavily nested (JSON-like documents).
  • You need horizontal scaling through sharding.
  • Your application benefits from rich querying and aggregation pipelines.
  • 你需要一个具有灵活模式的面向文档的数据库。
  • 你的数据是半结构化或高度嵌套的(类JSON文档)。
  • 你需要通过分片实现水平扩展。
  • 你的应用可从丰富的查询和聚合管道中获益。

Prerequisites

前提条件

  • Linux server (Debian/Ubuntu or RHEL-based) or Docker.
  • Root or sudo access for package installation.
  • MongoDB 7.x recommended for production (6.x still supported).
  • Linux服务器(Debian/Ubuntu或基于RHEL的系统)或Docker。
  • 安装软件包所需的Root或sudo权限。
  • 生产环境推荐使用MongoDB 7.x(6.x仍受支持)。

Installation and Setup

安装与配置

bash
undefined
bash
undefined

Debian / Ubuntu — MongoDB 7

Debian / Ubuntu — MongoDB 7

curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc |
sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ]
https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" |
sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list sudo apt update sudo apt install -y mongodb-org
curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc |
sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ]
https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" |
sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list sudo apt update sudo apt install -y mongodb-org

Start and enable

Start and enable

sudo systemctl enable --now mongod
sudo systemctl enable --now mongod

Verify

Verify

mongosh --eval "db.version()"
undefined
mongosh --eval "db.version()"
undefined

Initial User Setup

初始用户设置

javascript
// Connect without auth first
// mongosh

use admin

// Create admin user
db.createUser({
  user: "admin",
  pwd: "strong_admin_password",
  roles: [
    { role: "userAdminAnyDatabase", db: "admin" },
    { role: "readWriteAnyDatabase", db: "admin" },
    { role: "clusterAdmin", db: "admin" }
  ]
})

// Create an application-scoped user
use mydb
db.createUser({
  user: "myapp",
  pwd: "strong_app_password",
  roles: [{ role: "readWrite", db: "mydb" }]
})
Enable authentication in
/etc/mongod.conf
:
yaml
security:
  authorization: enabled
bash
sudo systemctl restart mongod
javascript
// Connect without auth first
// mongosh

use admin

// Create admin user
db.createUser({
  user: "admin",
  pwd: "strong_admin_password",
  roles: [
    { role: "userAdminAnyDatabase", db: "admin" },
    { role: "readWriteAnyDatabase", db: "admin" },
    { role: "clusterAdmin", db: "admin" }
  ]
})

// Create an application-scoped user
use mydb
db.createUser({
  user: "myapp",
  pwd: "strong_app_password",
  roles: [{ role: "readWrite", db: "mydb" }]
})
/etc/mongod.conf
中启用认证:
yaml
security:
  authorization: enabled
bash
sudo systemctl restart mongod

Now connect with credentials

Now connect with credentials

mongosh -u myapp -p strong_app_password --authenticationDatabase mydb
undefined
mongosh -u myapp -p strong_app_password --authenticationDatabase mydb
undefined

mongosh Commands Reference

mongosh命令参考

javascript
// Show databases and collections
show dbs
use mydb
show collections

// Insert documents
db.users.insertOne({ name: "Alice", email: "alice@example.com", age: 30 })
db.users.insertMany([
  { name: "Bob", email: "bob@example.com", age: 25 },
  { name: "Carol", email: "carol@example.com", age: 35 }
])

// Query documents
db.users.find({ age: { $gte: 25 } }).sort({ name: 1 }).limit(10)
db.users.findOne({ email: "alice@example.com" })
db.users.countDocuments({ age: { $gte: 30 } })

// Update
db.users.updateOne(
  { email: "alice@example.com" },
  { $set: { age: 31 }, $currentDate: { updatedAt: true } }
)
db.users.updateMany(
  { age: { $lt: 30 } },
  { $set: { tier: "junior" } }
)

// Delete
db.users.deleteOne({ email: "bob@example.com" })
db.users.deleteMany({ tier: "junior" })
javascript
// Show databases and collections
show dbs
use mydb
show collections

// Insert documents
db.users.insertOne({ name: "Alice", email: "alice@example.com", age: 30 })
db.users.insertMany([
  { name: "Bob", email: "bob@example.com", age: 25 },
  { name: "Carol", email: "carol@example.com", age: 35 }
])

// Query documents
db.users.find({ age: { $gte: 25 } }).sort({ name: 1 }).limit(10)
db.users.findOne({ email: "alice@example.com" })
db.users.countDocuments({ age: { $gte: 30 } })

// Update
db.users.updateOne(
  { email: "alice@example.com" },
  { $set: { age: 31 }, $currentDate: { updatedAt: true } }
)
db.users.updateMany(
  { age: { $lt: 30 } },
  { $set: { tier: "junior" } }
)

// Delete
db.users.deleteOne({ email: "bob@example.com" })
db.users.deleteMany({ tier: "junior" })

Indexing

索引配置

javascript
// Single-field index
db.users.createIndex({ email: 1 }, { unique: true })

// Compound index
db.orders.createIndex({ userId: 1, createdAt: -1 })

// Text index for search
db.articles.createIndex({ title: "text", body: "text" })
db.articles.find({ $text: { $search: "mongodb scaling" } })

// TTL index — auto-delete documents after 30 days
db.sessions.createIndex({ createdAt: 1 }, { expireAfterSeconds: 2592000 })

// List indexes
db.users.getIndexes()

// Drop an index
db.users.dropIndex("email_1")

// Explain a query to verify index usage
db.orders.find({ userId: 42 }).explain("executionStats")
javascript
// Single-field index
db.users.createIndex({ email: 1 }, { unique: true })

// Compound index
db.orders.createIndex({ userId: 1, createdAt: -1 })

// Text index for search
db.articles.createIndex({ title: "text", body: "text" })
db.articles.find({ $text: { $search: "mongodb scaling" } })

// TTL index — auto-delete documents after 30 days
db.sessions.createIndex({ createdAt: 1 }, { expireAfterSeconds: 2592000 })

// List indexes
db.users.getIndexes()

// Drop an index
db.users.dropIndex("email_1")

// Explain a query to verify index usage
db.orders.find({ userId: 42 }).explain("executionStats")

Aggregation Pipeline Examples

聚合管道示例

javascript
// Revenue per status
db.orders.aggregate([
  { $group: {
      _id: "$status",
      totalRevenue: { $sum: "$total" },
      count: { $sum: 1 }
  }},
  { $sort: { totalRevenue: -1 } }
])

// Top 5 customers by order value (with a join)
db.orders.aggregate([
  { $group: {
      _id: "$userId",
      spent: { $sum: "$total" },
      orderCount: { $sum: 1 }
  }},
  { $sort: { spent: -1 } },
  { $limit: 5 },
  { $lookup: {
      from: "users",
      localField: "_id",
      foreignField: "_id",
      as: "user"
  }},
  { $unwind: "$user" },
  { $project: {
      _id: 0,
      name: "$user.name",
      email: "$user.email",
      spent: 1,
      orderCount: 1
  }}
])

// Daily signup trend
db.users.aggregate([
  { $group: {
      _id: { $dateToString: { format: "%Y-%m-%d", date: "$createdAt" } },
      signups: { $sum: 1 }
  }},
  { $sort: { _id: 1 } },
  { $limit: 30 }
])
javascript
// Revenue per status
db.orders.aggregate([
  { $group: {
      _id: "$status",
      totalRevenue: { $sum: "$total" },
      count: { $sum: 1 }
  }},
  { $sort: { totalRevenue: -1 } }
])

// Top 5 customers by order value (with a join)
db.orders.aggregate([
  { $group: {
      _id: "$userId",
      spent: { $sum: "$total" },
      orderCount: { $sum: 1 }
  }},
  { $sort: { spent: -1 } },
  { $limit: 5 },
  { $lookup: {
      from: "users",
      localField: "_id",
      foreignField: "_id",
      as: "user"
  }},
  { $unwind: "$user" },
  { $project: {
      _id: 0,
      name: "$user.name",
      email: "$user.email",
      spent: 1,
      orderCount: 1
  }}
])

// Daily signup trend
db.users.aggregate([
  { $group: {
      _id: { $dateToString: { format: "%Y-%m-%d", date: "$createdAt" } },
      signups: { $sum: 1 }
  }},
  { $sort: { _id: 1 } },
  { $limit: 30 }
])

Replica Set Setup

副本集配置

A replica set requires a minimum of three members (or two data-bearing nodes plus an arbiter).
副本集至少需要三个成员(或两个数据节点加一个仲裁节点)。

Configuration File for Each Member

每个成员的配置文件

yaml
undefined
yaml
undefined

/etc/mongod.conf (adjust port and dbPath per member)

/etc/mongod.conf (adjust port and dbPath per member)

storage: dbPath: /var/lib/mongodb net: port: 27017 bindIp: 0.0.0.0 replication: replSetName: rs0 security: authorization: enabled keyFile: /etc/mongodb-keyfile

```bash
storage: dbPath: /var/lib/mongodb net: port: 27017 bindIp: 0.0.0.0 replication: replSetName: rs0 security: authorization: enabled keyFile: /etc/mongodb-keyfile

```bash

Generate a shared keyfile for internal auth

Generate a shared keyfile for internal auth

openssl rand -base64 756 > /etc/mongodb-keyfile chmod 400 /etc/mongodb-keyfile chown mongodb:mongodb /etc/mongodb-keyfile
openssl rand -base64 756 > /etc/mongodb-keyfile chmod 400 /etc/mongodb-keyfile chown mongodb:mongodb /etc/mongodb-keyfile

Copy this file to all replica set members

Copy this file to all replica set members

undefined
undefined

Initialize the Replica Set

初始化副本集

javascript
// Connect to the first member
// mongosh --port 27017

rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "mongo1:27017", priority: 2 },
    { _id: 1, host: "mongo2:27017", priority: 1 },
    { _id: 2, host: "mongo3:27017", priority: 1 }
  ]
})

// Check status
rs.status()

// View replication lag per member
rs.printReplicationInfo()
rs.printSecondaryReplicationInfo()
javascript
// Connect to the first member
// mongosh --port 27017

rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "mongo1:27017", priority: 2 },
    { _id: 1, host: "mongo2:27017", priority: 1 },
    { _id: 2, host: "mongo3:27017", priority: 1 }
  ]
})

// Check status
rs.status()

// View replication lag per member
rs.printReplicationInfo()
rs.printSecondaryReplicationInfo()

Backup and Restore

备份与恢复

bash
undefined
bash
undefined

Full dump of all databases

Full dump of all databases

mongodump --uri="mongodb://admin:secret@localhost:27017" --out=/backups/full_$(date +%F)
mongodump --uri="mongodb://admin:secret@localhost:27017" --out=/backups/full_$(date +%F)

Single database

Single database

mongodump --uri="mongodb://myapp:secret@localhost:27017/mydb" --out=/backups/mydb_$(date +%F)
mongodump --uri="mongodb://myapp:secret@localhost:27017/mydb" --out=/backups/mydb_$(date +%F)

Compressed dump

Compressed dump

mongodump --uri="mongodb://admin:secret@localhost:27017" --gzip --out=/backups/gz_$(date +%F)
mongodump --uri="mongodb://admin:secret@localhost:27017" --gzip --out=/backups/gz_$(date +%F)

Restore all databases

Restore all databases

mongorestore --uri="mongodb://admin:secret@localhost:27017" /backups/full_2025-01-15/
mongorestore --uri="mongodb://admin:secret@localhost:27017" /backups/full_2025-01-15/

Restore a single database, dropping existing data first

Restore a single database, dropping existing data first

mongorestore --uri="mongodb://admin:secret@localhost:27017"
--drop --db mydb /backups/mydb_2025-01-15/mydb/
mongorestore --uri="mongodb://admin:secret@localhost:27017"
--drop --db mydb /backups/mydb_2025-01-15/mydb/

Restore compressed dump

Restore compressed dump

mongorestore --uri="mongodb://admin:secret@localhost:27017" --gzip /backups/gz_2025-01-15/
undefined
mongorestore --uri="mongodb://admin:secret@localhost:27017" --gzip /backups/gz_2025-01-15/
undefined

Docker Compose Setup

Docker Compose配置

yaml
undefined
yaml
undefined

docker-compose.yml

docker-compose.yml

version: "3.9"
services: mongo1: image: mongo:7 restart: unless-stopped ports: - "27017:27017" environment: MONGO_INITDB_ROOT_USERNAME: admin MONGO_INITDB_ROOT_PASSWORD: secret volumes: - mongo1_data:/data/db - ./mongo-keyfile:/etc/mongodb-keyfile:ro command: > mongod --replSet rs0 --keyFile /etc/mongodb-keyfile --bind_ip_all healthcheck: test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"] interval: 10s timeout: 5s retries: 5
mongo2: image: mongo:7 restart: unless-stopped volumes: - mongo2_data:/data/db - ./mongo-keyfile:/etc/mongodb-keyfile:ro command: > mongod --replSet rs0 --keyFile /etc/mongodb-keyfile --bind_ip_all
mongo3: image: mongo:7 restart: unless-stopped volumes: - mongo3_data:/data/db - ./mongo-keyfile:/etc/mongodb-keyfile:ro command: > mongod --replSet rs0 --keyFile /etc/mongodb-keyfile --bind_ip_all
mongo-init: image: mongo:7 restart: "no" depends_on: mongo1: condition: service_healthy entrypoint: > mongosh --host mongo1 -u admin -p secret --authenticationDatabase admin --eval ' rs.initiate({ _id: "rs0", members: [ { _id: 0, host: "mongo1:27017", priority: 2 }, { _id: 1, host: "mongo2:27017", priority: 1 }, { _id: 2, host: "mongo3:27017", priority: 1 } ] }) '
volumes: mongo1_data: mongo2_data: mongo3_data:

```bash
version: "3.9"
services: mongo1: image: mongo:7 restart: unless-stopped ports: - "27017:27017" environment: MONGO_INITDB_ROOT_USERNAME: admin MONGO_INITDB_ROOT_PASSWORD: secret volumes: - mongo1_data:/data/db - ./mongo-keyfile:/etc/mongodb-keyfile:ro command: > mongod --replSet rs0 --keyFile /etc/mongodb-keyfile --bind_ip_all healthcheck: test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"] interval: 10s timeout: 5s retries: 5
mongo2: image: mongo:7 restart: unless-stopped volumes: - mongo2_data:/data/db - ./mongo-keyfile:/etc/mongodb-keyfile:ro command: > mongod --replSet rs0 --keyFile /etc/mongodb-keyfile --bind_ip_all
mongo3: image: mongo:7 restart: unless-stopped volumes: - mongo3_data:/data/db - ./mongo-keyfile:/etc/mongodb-keyfile:ro command: > mongod --replSet rs0 --keyFile /etc/mongodb-keyfile --bind_ip_all
mongo-init: image: mongo:7 restart: "no" depends_on: mongo1: condition: service_healthy entrypoint: > mongosh --host mongo1 -u admin -p secret --authenticationDatabase admin --eval ' rs.initiate({ _id: "rs0", members: [ { _id: 0, host: "mongo1:27017", priority: 2 }, { _id: 1, host: "mongo2:27017", priority: 1 }, { _id: 2, host: "mongo3:27017", priority: 1 } ] }) '
volumes: mongo1_data: mongo2_data: mongo3_data:

```bash

Generate keyfile before starting

Generate keyfile before starting

openssl rand -base64 756 > mongo-keyfile chmod 400 mongo-keyfile
docker compose up -d
openssl rand -base64 756 > mongo-keyfile chmod 400 mongo-keyfile
docker compose up -d

Connect

Connect

mongosh "mongodb://admin:secret@127.0.0.1:27017/?replicaSet=rs0&authSource=admin"
undefined
mongosh "mongodb://admin:secret@127.0.0.1:27017/?replicaSet=rs0&authSource=admin"
undefined

Monitoring Queries

查询监控

javascript
// Server status summary
db.serverStatus().connections
db.serverStatus().opcounters

// Current operations (look for long-running queries)
db.currentOp({ secs_running: { $gte: 5 } })

// Collection stats
db.orders.stats()

// Index sizes
db.orders.stats().indexSizes

// Profiler — log slow queries (> 100ms)
db.setProfilingLevel(1, { slowms: 100 })
db.system.profile.find().sort({ ts: -1 }).limit(5)

// Replica set lag
rs.printSecondaryReplicationInfo()
javascript
// Server status summary
db.serverStatus().connections
db.serverStatus().opcounters

// Current operations (look for long-running queries)
db.currentOp({ secs_running: { $gte: 5 } })

// Collection stats
db.orders.stats()

// Index sizes
db.orders.stats().indexSizes

// Profiler — log slow queries (> 100ms)
db.setProfilingLevel(1, { slowms: 100 })
db.system.profile.find().sort({ ts: -1 }).limit(5)

// Replica set lag
rs.printSecondaryReplicationInfo()

Configuration Tuning

配置调优

yaml
undefined
yaml
undefined

/etc/mongod.conf — production recommendations

/etc/mongod.conf — production recommendations

storage: dbPath: /var/lib/mongodb journal: enabled: true wiredTiger: engineConfig: cacheSizeGB: 4 # ~50% of RAM, leave rest for OS cache collectionConfig: blockCompressor: snappy net: port: 27017 bindIp: 0.0.0.0 maxIncomingConnections: 500 operationProfiling: mode: slowOp slowOpThresholdMs: 100
undefined
storage: dbPath: /var/lib/mongodb journal: enabled: true wiredTiger: engineConfig: cacheSizeGB: 4 # ~50% of RAM, leave rest for OS cache collectionConfig: blockCompressor: snappy net: port: 27017 bindIp: 0.0.0.0 maxIncomingConnections: 500 operationProfiling: mode: slowOp slowOpThresholdMs: 100
undefined

Troubleshooting

故障排查

SymptomLikely CauseFix
COLLSCAN
in explain output
Missing index on queried fieldCreate an appropriate index
Replica member stuck in
RECOVERING
Oplog window exceededResync by removing data and restarting the member
too many open files
OS file descriptor limit too lowSet
ulimit -n 65535
in service file
High memory usageWiredTiger cache too largeReduce
cacheSizeGB
in config
Slow aggregation pipelinesNo index on
$match
stage fields
Add index; place
$match
as early as possible in pipeline
Authentication failureWrong
authenticationDatabase
Specify
--authenticationDatabase admin
for admin users
症状可能原因解决方法
执行计划输出中出现
COLLSCAN
查询字段缺少索引创建合适的索引
副本成员卡在
RECOVERING
状态
Oplog窗口超出限制删除数据并重新启动成员以重新同步
too many open files
OS文件描述符限制过低在服务文件中设置
ulimit -n 65535
内存占用过高WiredTiger缓存过大在配置中减小
cacheSizeGB
聚合管道运行缓慢
$match
阶段字段无索引
添加索引;将
$match
放在管道尽可能靠前的位置
认证失败
authenticationDatabase
设置错误
对于管理员用户,指定
--authenticationDatabase admin

Related Skills

相关技能

  • redis - Caching layer in front of MongoDB
  • database-backups - Automated backup strategies
  • postgresql - Alternative relational database
  • redis - MongoDB前端的缓存层
  • database-backups - 自动化备份策略
  • postgresql - 可选的关系型数据库