MongoDB 部署教程
一、部署前准备（通用）
一台可用机器（本地开发机或服务器），并能运行 Docker（若选 Docker 方案）。
基本命令权限：能运行
sudo。端口：默认 MongoDB 监听
27017，Replica Set 中每个实例也通常使用 27017（或不同端口），请确保防火墙 / 安全组放行对应端口。备份计划：部署前规划好
mongodump/mongorestore或更高级的备份方案。官方工具文档：mongodump / mongorestore。(MongoDB)
二、方式 A — 使用 Docker Compose（最快上手，推荐开发/测试）
用途：本地开发、测试环境、CI、轻量部署。生产环境可容器化，但建议在运维方案（SSL、持久化存储、监控）完善后再投入生产。
2.1 单节点快速启动（最简单）
在工作目录新建 docker-compose.yml（示例会把数据保存在 Docker named volume）：
version: "3.8"
services:
mongo:
image: mongo:latest # 或指定版本: mongo:7.0 / mongo:6.0；查看官方镜像以决定版本。:contentReference[oaicite:1]{index=1}
container_name: mongo_single
restart: unless-stopped
environment:
MONGO_INITDB_ROOT_USERNAME: root
MONGO_INITDB_ROOT_PASSWORD: StrongRootPwd! # 请务必改为强密码
MONGO_INITDB_DATABASE: demo_db # 可选：初始化要创建的 DB（配合 init 脚本使用）
volumes:
- mongo-data:/data/db
- ./initdb:/docker-entrypoint-initdb.d # 可选：首次启动自动执行 .js/.sh 脚本
ports:
- "27017:27017"
volumes:
mongo-data:
启动：
docker compose up -d
# 或：docker-compose up -d （如果是老版 docker-compose）
说明与小贴士：
官方镜像支持
MONGO_INITDB_ROOT_USERNAME和MONGO_INITDB_ROOT_PASSWORD在初始化时自动创建 admin 用户并开启身份验证（entrypoint 会据此处理）。如果你用 volume 挂载已有 data 目录，初始化脚本不会重新执行。详见官方镜像说明。(Docker Hub)docker-entrypoint-initdb.d中.js/.sh文件只会在数据目录空（首次初始化）时被执行，后续重启不会再跑一次。连接（宿主机安装
mongosh）：mongosh "mongodb://root:StrongRootPwd!@127.0.0.1:27017/admin"
2.2 本地三节点 Replica Set（开发/测试用）
如果你想在本机模拟 replica set（可用于测试事务 / change streams 等），用如下 docker-compose.yml（示例把三个实例各自写入不同 volume）：
version: "3.8"
services:
mongo1:
image: mongo:latest
container_name: mongo1
command: ["--replSet", "rs0", "--bind_ip_all"]
ports:
- "27017:27017"
volumes:
- mongo1-data:/data/db
mongo2:
image: mongo:latest
container_name: mongo2
command: ["--replSet", "rs0", "--bind_ip_all"]
ports:
- "27018:27017"
volumes:
- mongo2-data:/data/db
mongo3:
image: mongo:latest
container_name: mongo3
command: ["--replSet", "rs0", "--bind_ip_all"]
ports:
- "27019:27017"
volumes:
- mongo3-data:/data/db
volumes:
mongo1-data:
mongo2-data:
mongo3-data:
启动并初始化 Replica Set：
docker compose up -d
# 等几秒钟让容器启动，再在任意一个节点上 init
docker exec -it mongo1 mongosh --eval 'rs.initiate({_id: "rs0", members: [{_id:0, host:"mongo1:27017"},{_id:1, host:"mongo2:27017"},{_id:2, host:"mongo3:27017"}]})'
# 查看状态
docker exec -it mongo1 mongosh --eval 'rs.status()'
注意与常见坑：
在官方镜像里，如果你同时用
MONGO_INITDB_ROOT_*变量和--replSet，在某些场景下 entrypoint 对参数的处理可能产生副作用（社区曾报告一些差异 / 坑），如果出现认证 / 初始化失败，建议按“先启动、init replica set、创建用户、再强制开启内部 keyfile auth”的官方推荐流程处理（下面会说明 keyfile 配置）。参考社区与官方文档了解更多。(GitHub)本地测试可以暂时不开启 keyfile（内部节点认证），但生产环境必须启用内部认证（keyfile / x.509）并启用 TLS。官方 keyfile 教程详见下文。(MongoDB)
三、方式 B — 宿主机安装（官方包：Ubuntu / RHEL/CentOS）
推荐用于生产或不想依赖容器时。优先使用官方
mongodb-org包源（而非 distro 自带的mongodb包），这样能拿到官方维护版本与工具。官方安装文档：Install on Linux。(MongoDB)
3.1 Ubuntu（官方 apt 源，示例为 22.04 / 20.04）
安装前准备并导入 GPG key：
sudo apt-get update
sudo apt-get install -y gnupg curl
curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \
sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor
添加 APT 源（以 Ubuntu 22.04 为例）：
echo "deb [ arch=amd64,arm64 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-get update
sudo apt-get install -y mongodb-org
启动并开机自启：
sudo systemctl start mongod
sudo systemctl enable mongod
sudo systemctl status mongod
（以上命令取自官方 Ubuntu 安装教程，请根据你需要安装的 MongoDB 版本把 7.0 换成合适的版本号）。(MongoDB)
3.2 RHEL / CentOS（通过官方 yum/dnf 仓库）
创建 repo 文件
/etc/yum.repos.d/mongodb-org-8.0.repo（以 8.x/7.x 版本为例，参照官方页面选择版本与 baseurl），添加官方 yum 源；官方文档提供按系统生成的 repo 配置。(MongoDB)安装：
sudo dnf install -y mongodb-org # 或 yum install -y mongodb-org 视发行版而定
启动并设置开机启动：
sudo systemctl start mongod
sudo systemctl enable mongod
sudo systemctl status mongod
3.3 启用认证（宿主机）
编辑 /etc/mongod.conf（或包安装生成的配置）：
# 片段示例
net:
bindIp: 0.0.0.0
security:
authorization: "enabled" # 启用用户认证 -- 注意：启用后必须先有 admin 用户，否则会被 localhost exception 影响
replication:
replSetName: rs0 # 若是 replica set，设置 replSetName
启用
authorization前务必先创建管理员账号或遵循“localhost exception”启动并创建第一个用户的流程（官方文档有详细步骤）。(MongoDB)
创建 admin 用户（示例）：
mongosh # 本机运行
use admin
db.createUser({
user: "admin",
pwd: passwordPrompt(), // 或在脚本中写明密码（不安全）
roles: [ { role: "userAdminAnyDatabase", db: "admin" }, { role: "root", db: "admin" } ]
})
四、Replica Set 与内部认证（生产必须）—— keyfile / x.509 概念与操作要点
为什么需要？ Replica Set 成员之间需要可信任的内部认证（避免恶意节点加入）。生产中通常用 keyfile（简单、一致）或更高级的 X.509（企业级证书方案）。官方对 keyfile 的完整流程与注意事项有详细文档，强烈推荐按官方步骤执行（包含 keyfile 权限、复制到每台节点、在 mongod 配置中启用）。(MongoDB)
关键步骤（概览）：
在一台机器上生成 keyfile（例如使用
openssl rand -base64 756 > /etc/mongo/keyfile），并chmod 400 /etc/mongo/keyfile。(MongoDB)把 keyfile 以安全方式分发到每台 replica set 成员，并确保
mongod运行用户能读取且权限严格（600/400）。在每个
mongod的 config（或命令行）中指定：
security:
keyFile: /path/to/keyfile
replication:
replSetName: rs0
或使用命令行 mongod --keyFile /path/to/keyfile --replSet rs0 --bind_ip_all，然后启动。
4. 用 mongosh 在一台节点上 rs.initiate(...) 初始化 replica set，随后创建 admin / clusterAdmin 等用户。官方文档给出了完整、逐步的示例和注意事项（例如 localhost exception、使用主机名比 IP 更稳妥等）。(MongoDB)
五、备份与恢复（基础）
备份（导出）：
使用
mongodump（官方工具）创建二进制备份：mongodump --uri="mongodb://admin:Pwd@host:27017/?authSource=admin" --out /path/to/backupdir
恢复（导入）：
使用
mongorestore：mongorestore --uri="mongodb://admin:Pwd@host:27017/?authSource=admin" /path/to/backupdir
官方工具 mongodump / mongorestore 文档：详尽说明了压缩、归档、选择 db/collection 等参数。(MongoDB)
生产备份提示：
对于大数据量或需要在线热备方案，考虑 filesystem snapshot + oplog 或专业工具（如 Ops Manager / Cloud Manager / 其它第三方解决方案）。
定期做恢复演练（restore test）以验证备份有效性。
六、常见问题与排查（小白常遇到的坑）
启动但无法连接：看
/var/log/mongodb/mongod.log或docker logs <container>，注意端口、bindIp、权限问题。auth 报错（Authentication failed）：
确认连接字符串是否包含
authSource=admin（如果你登录 admin 用户）。如果容器挂载了已有 data volume，初始化脚本不会重跑；若改了 root 密码需要手动在 mongo 中更新。社区对 Docker auth 初始化有不少讨论，遇到问题可参考官方镜像说明与社区帖子。(Docker Hub)
Replica set 成员加入失败：常见原因是 host 名称 /IP 不一致、keyfile 权限错误或节点间网络不可达。官方建议使用 DNS 名称避免 IP 变动问题。(MongoDB)
SELinux / 权限问题（CentOS/RHEL）：挂载主机目录到容器或自定义数据目录时，注意
chown mongod:mongod /path与 SELinux 上的chcon/:Z参数。存储引擎：当前默认是 WiredTiger（建议使用），它支持压缩与更好的并发控制。(MongoDB)
七、生产环境建议 checklist（精简）
启用认证（SCRAM / X.509）并限制管理账户权限。(MongoDB)
Replica Set（3+ 节点）或分片（需要时）以保证高可用与扩展性。
使用 TLS/SSL（对外与内部节点通信）并启用 keyfile / X.509 内部认证。
定期备份并验证恢复（mongodump 或更成熟方案）。(MongoDB)
监控（MongoDB 专有：Cloud Manager/Atlas；或 Prometheus + exporters）。
系统调优（ulimit、文件系统、I/O 性能、内存分配）。官方安装页有生产说明与调优建议。(MongoDB)
八、常用命令速查（复制即用）
启停（systemd）：
sudo systemctl start mongod
sudo systemctl stop mongod
sudo systemctl restart mongod
sudo systemctl status mongod
连接（本机）：
mongosh "mongodb://admin:Pwd@127.0.0.1:27017/admin"
初始化 replica set（示例）：
rs.initiate({
_id: "rs0",
members: [
{_id: 0, host: "mongo1.example.net:27017"},
{_id: 1, host: "mongo2.example.net:27017"},
{_id: 2, host: "mongo3.example.net:27017"}
]
})
备份恢复（简单）：
mongodump --uri="mongodb://admin:Pwd@host:27017/?authSource=admin" --out /backups/$(date +%F)
mongorestore --uri="mongodb://admin:Pwd@host:27017/?authSource=admin" /backups/2025-09-23
九、参考文档（官方 / 权威）
官方 Docker 镜像（mongo image on Docker Hub）。(Docker Hub)
在 Ubuntu 上使用 APT 安装 MongoDB（官方教程）。(MongoDB)
在 RHEL / CentOS 上安装 MongoDB（官方教程）。(MongoDB)
部署带 keyfile 的 Replica Set（官方详尽步骤）。(MongoDB)
mongodump / mongorestore（备份恢复工具，官方文档）。(MongoDB)
十、小结
Docker 单节点 + 本地 Replica Set 的
docker-compose.yml示例、Ubuntu / RHEL-CentOS 官方包安装 的可复制命令、keyfile/Replica Set 的生产级要点、以及备份恢复常用命令。