> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 更新 MongoDB

<Info>
  Server CE/Server Pro 的每个新版本都会在其[发行说明](https://docs.overleaf.com/on-premises/release-notes)中注明所支持的 MongoDB 版本的任何变化。
</Info>

### 我应该更新 MongoDB 吗？

**仅**当你计划升级 Server CE/Server Pro 实例时，才应考虑更新 MongoDB 版本。

如果你运行的 MongoDB 版本比当前（或目标）版本推荐的版本更新，则无需进行任何更改。

<Warning>
  切勿降级你的 MongoDB 版本。
</Warning>

如果你遇到了某个你认为可能与当前 MongoDB 版本有关的具体问题，Server CE 用户可以随时[提交 issue](https://github.com/overleaf/overleaf/issues)，Server Pro 用户可以联系 Overleaf 支持团队。

### 检查你的 MongoDB 版本

打开 `mongo` shell 时应会立即显示当前版本。

Overleaf Toolkit 用户：

```bash theme={null}
bin/docker-compose exec mongo mongod --version
db version v5.0.24
Build Info: {
    "version": "5.0.24",
    "gitVersion": "f034f0c51b3dffef4b8c9452d77ede9888f28f66",
    "openSSLVersion": "OpenSSL 1.1.1f  31 Mar 2020",
    "modules": [],
    "allocator": "tcmalloc",
    "environment": {
        "distmod": "ubuntu2004",
        "distarch": "x86_64",
        "target_arch": "x86_64"
    }
}
```

Docker Compose 用户：

```bash theme={null}
docker compose exec mongo mongod --version
db version v5.0.24
Build Info: {
    "version": "5.0.24",
    "gitVersion": "f034f0c51b3dffef4b8c9452d77ede9888f28f66",
    "openSSLVersion": "OpenSSL 1.1.1f  31 Mar 2020",
    "modules": [],
    "allocator": "tcmalloc",
    "environment": {
        "distmod": "ubuntu2004",
        "distarch": "x86_64",
        "target_arch": "x86_64"
    }
}

```

### 更新流程

在升级 Server CE/Server Pro 实例期间更新 MongoDB 版本的步骤如下：

1. 确定你计划升级到的 Server CE/Server Pro 版本。
2. 查找该 Overleaf Server CE/Server Pro 版本推荐的 MongoDB 版本。
3. 按照说明将 MongoDB 升级到目标版本。
4. 升级 Server CE/Server Pro 镜像版本并重启实例。

我们建议始终将 **Server CE/Server Pro** 升级到可用的最新版本，因为最新版本始终能保证得到支持（仅限 Server Pro 用户）。

<Danger>
  在升级 Server CE/Pro 时，我们建议**先**升级到当前已部署主版本的最新发行版，**然后**再升级到**下一个**主版本的最新发行版。如果你的部署落后最新版本超过一个主版本，则需要进行多步升级。

  例如，如果你运行的是 3.5.10，你需要升级到 3.5.13 -> 执行完整项目历史迁移 -> 4.2.9 -> 5.5.4。

  你**绝不**应跳过主版本（3.5.10 -> 5.5.4）。如果你使用的是 Toolkit，并且落后最新版本超过一个主版本，则**不得**使用 `bin/upgrade` 脚本，因为你需要手动执行多步升级。
</Danger>

<Warning>
  请务必在每次主版本升级**之前**进行[一致性备份](/zh-CN/on-premises/maintenance/data-and-backups#performing-a-consistent-backup)，以便在需要时进行回滚。
</Warning>

#### 版本支持信息

如果你决定使用较早的版本，下表列出了 Server CE/Server Pro 早期版本推荐的 MongoDB 版本，但你**绝不**应降级 MongoDB 版本。

<div style={{ overflowX: "auto" }}><table style={{ display: "table", width: "100%" }}><thead><tr><th width="175">Server CE/Server Pro</th><th width="139" style={{ textAlign: "center" }}>MongoDB 版本</th><th style={{ textAlign: "center" }}>最低功能兼容版本</th><th style={{ textAlign: "center" }}>Node.js 驱动支持的最高版本</th></tr></thead><tbody><tr><td>2.0.x</td><td style={{ textAlign: "center" }}>3.4</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>2.1.x 至 2.4.x</td><td style={{ textAlign: "center" }}>3.6</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=2.5.0</td><td style={{ textAlign: "center" }}>4.0</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=3.1.0</td><td style={{ textAlign: "center" }}>4.2</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=3.2.0</td><td style={{ textAlign: "center" }}>4.4</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=4.2.0</td><td style={{ textAlign: "center" }}>5.0</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=5.1.0</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=5.3.1</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>5.0</td><td style={{ textAlign: "center" }}>8.0</td></tr><tr><td>>=5.5.0</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>8.0</td></tr><tr><td>6.0.0</td><td style={{ textAlign: "center" }}>8.0</td><td style={{ textAlign: "center" }}>8.0</td><td style={{ textAlign: "center" }}>8.0</td></tr></tbody></table></div>

<Danger>
  上表中的最低功能兼容版本基于与所示 Overleaf 版本配套使用的推荐 MongoDB 版本。如果你计划使用更高版本，MongoDB 会有其自身的最低要求。
</Danger>

你可以在[这里](https://www.mongodb.com/docs/drivers/node/current/reference/compatibility/)查看兼容性表格，其中列出了可与 MongoDB 配合使用的 MongoDB Node.js 驱动版本。

你可以在[这里](https://endoflife.date/mongodb)查看每个 MongoDB 版本的生命周期终止状态。

#### 升级 MongoDB

MongoDB 需要**逐步升级**。这意味着你不能直接从 `4.0` 升级到 `5.0`。你需要先将 `4.2` 更新到 `4.4`，然后再更新到 `5.0`。

<Info>
  MongoDB 的稳定版本使用偶数版本号。
</Info>

#### **在 Docker 之外运行 MongoDB 时的更新说明**

以下是 mongodb.com 上关于升级 MongoDB 的更新说明链接。

* [MongoDB 发行说明 - 将 MongoDB 从 `4.2` 升级到 `4.4`](https://www.mongodb.com/docs/v4.4/release-notes/4.4-upgrade-standalone/)
* [MongoDB 发行说明 - 将 MongoDB 从 `4.4` 升级到 `5.0`](https://www.mongodb.com/docs/v5.0/release-notes/5.0-upgrade-replica-set/)
* [MongoDB 发行说明 - 将 MongoDB 从 `5.0` 升级到 `6.0`](https://www.mongodb.com/docs/v6.0/release-notes/6.0-upgrade-replica-set/)
* [MongoDB 发行说明 - 将 MongoDB 从 `6.0` 升级到 `7.0`](https://www.mongodb.com/docs/manual/release-notes/7.0-upgrade-replica-set/#std-label-7.0-upgrade-replica-set)
* [MongoDB 发行说明 - 将 MongoDB 从 `7.0` 升级到 `8.0`](https://www.mongodb.com/docs/manual/release-notes/8.0-upgrade-replica-set/#std-label-8.0-upgrade-replica-set)

<Info>
  `5.0` 及更高版本的说明针对的是副本集安装，而非独立部署。由于 Server Pro/CE 4.0.1+ 使用事务，MongoDB 需要以副本集方式运行。
</Info>

<Warning>
  MongoDB 3.2 至 4.2 的文档现在可通过 [https://www.mongodb.com/docs/legacy/](https://www.mongodb.com/docs/legacy/) 获取
</Warning>

**基本说明**

在大多数情况下，更新需要在实际更新 mongo 版本之前设置一个兼容性标志。步骤如下：

1. 按照 MongoDB 发行说明中的描述设置兼容性标志（参见下方示例）。
2. 然后更新 mongo 镜像：
   1. **Toolkit 用户** 更新 `MONGO_VERSION`，例如 `MONGO_VERSION=6.0`
   2. **Docker Compose 用户** 更新 `mongo` 镜像标签的版本，\
      例如 `services -> mongo -> image: mongo:6.0`；

**示例：将 MongoDB 从 `5.0` 升级到 `6.0`**

首先，确认我们正在运行 MongoDB `6.0`：

Overleaf Toolkit 用户：

```bash theme={null}
bin/docker-compose exec mongo mongod --version
# db version v5.0.24
```

Docker Compose 用户：

```bash theme={null}
docker compose exec mongo mongod --version
# db version v5.0.24
```

根据[升级说明](https://docs.mongodb.com/manual/release-notes/3.6-upgrade-standalone/#upgrade-version-path)，唯一的要求是将 `featureCompatibilityVersion` 设置为 `5.0`。为此，我们打开 MongoDB shell 并运行指定的命令：

Overleaf Toolkit 用户：

```bash theme={null}
bin/mongo
# MongoDB shell version v5.0.24
# ...
# overleaf:PRIMARY> db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )
# { 
# "ok" : 1,
# ...
# }
overleaf:PRIMARY> exit
# bye
```

<Info>
  Docker Compose 用户可以运行 `docker compose exec mongo mongosh` 打开 shell，并运行与 Toolkit 用户相同的命令。
</Info>

Overleaf Toolkit 用户：

接下来，我们使用 `bin/stop` 命令停止 Server CE/Server Pro 和 MongoDB 实例，在 `config/overleaf.rc` 中设置 `MONGO_VERSION=6.0`，然后使用 `bin/up mongo` 重启 `mongo` 服务，以验证更新是否顺利完成。

最后，我们将 Server CE/Server Pro 镜像版本更新为目标版本，并使用 `bin/up -d` 命令重新创建所有服务。

Docker Compose 用户：

接下来，我们使用 `docker compose stop` 命令停止 Server CE/Server Pro 和 MongoDB 实例，更新 [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) 文件以使用 `image: mongo:6.0`，然后使用 `docker compose up mongo` 命令重启 `mongo` 服务，以验证更新是否顺利完成。

最后，我们将 Server CE/Server Pro 镜像版本更新为目标版本，并使用 `docker compose up` 命令重新创建所有服务。

<strong>示例：将 MongoDB 从 `6.0` 升级到 `7.0`（Toolkit 用户）</strong>

首先，使用上面的 `mongod --version` 命令确认你正在运行 MongoDB `6.0`。

根据[升级说明](https://www.mongodb.com/docs/manual/release-notes/7.0-upgrade-replica-set/#std-label-7.0-upgrade-replica-set)，唯一的要求是将 `featureCompatibilityVersion` 设置为 `6.0`。为此，我们打开 MongoDB shell 并运行命令 `db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })`。

Overleaf Toolkit 用户：

```bash theme={null}
bin/mongo
# ...
# overleaf:PRIMARY> db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )
# { 
# "ok" : 1,
# ...
# }
overleaf:PRIMARY> exit
# bye
```

接下来，我们使用 `bin/stop` 命令停止 Server CE/Server Pro 和 MongoDB 实例，在 `config/overleaf.rc` 中设置 `MONGO_VERSION=7.0`，然后使用 `bin/up mongo` 重启 `mongo` 服务，以验证更新是否顺利完成。

最后，我们将 Server CE/Server Pro 镜像版本更新为目标版本，并使用 `bin/up -d` 命令重新创建所有服务。

<strong>示例：将 MongoDB 从 `7.0` 升级到 `8.0`（Toolkit 用户）</strong>

首先，使用上面的 `mongod --version` 命令确认你正在运行 MongoDB `7.0`。

根据[升级说明](https://www.mongodb.com/docs/manual/release-notes/8.0-upgrade-replica-set/#std-label-8.0-upgrade-replica-set)，唯一的要求是将 `featureCompatibilityVersion` 设置为 `7.0`。为此，我们打开 MongoDB shell 并运行命令 `db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true })`。请注意，现在需要额外的 `confirm: true` 参数。

```bash theme={null}
bin/mongo
# ...
# overleaf:PRIMARY> db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true } )
# { 
# "ok" : 1,
# ...
# }
overleaf:PRIMARY> exit
# bye
```

接下来，我们使用 `bin/stop` 命令停止 Server CE/Server Pro 和 MongoDB 实例，在 `config/overleaf.rc` 中设置 `MONGO_VERSION=8.0`，然后使用 `bin/up mongo` 重启 `mongo` 服务，以验证更新是否顺利完成。

最后，我们将 Server CE/Server Pro 镜像版本更新为目标版本，并使用 `bin/up -d` 命令重新创建所有服务。

#### Docker Compose 用户的等效命令

对于 Docker Compose 用户，等效命令如下：

* `docker compose exec mongo mongod --version` 用于显示 mongo 版本
* `docker compose exec mongo mongosh` 用于启动 mongo shell 以执行管理命令
* `docker compose stop` 命令用于停止服务器
* 编辑 [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) 文件，使用 `image: mongo:6.0` 来升级 mongo 版本
* `docker compose up mongo` 用于重启 mongo 服务并验证更新是否顺利完成
* 编辑 [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) 文件，使用 `image: sharelatex:VERSION` 来升级镜像版本
* `docker compose up` 用于重新创建所有服务。

### 创建自定义角色

在 `5.5.1` 版本中，我们引入了一项启动检查，用于验证 MongoDB 的功能兼容版本。如果你的 MongoDB 数据库使用了认证（例如基本认证），`sharelatex` 容器可能无法启动，并显示"*not authorized on admin to execute command*"权限错误。

要解决此问题，你可以按照下面的说明在 MongoDB 中创建一个新角色，并将其分配给用于访问数据库的用户账户；或者设置 `ALLOW_MONGO_ADMIN_CHECK_FAILURES=true`，允许检查失败而不阻止部署启动。

<Check>
  这个新角色**仅**授予读取 MongoDB 集群级服务器参数的权限，也可复用于监控用途。
</Check>

```bash wrap theme={null}
# Toolkit users
$ bin/docker-compose exec -it mongo mongosh -u {{YOUR-ADMIN-USERNAME}} -p

# Switch to the "admin" database using
overleaf [direct: primary] sharelatex> use admin
switched to db admin
overleaf [direct: primary] admin> 

# Create a new role with permission to use "getParamter". Copy and paste the function below into the shell and press the return key

db.createRole(
  {
    role: "clusterParameterReader",
    privileges: [
      {
        resource: { cluster: true },
        actions: ["getParameter"]    
      }
    ],
    roles: [] 
  }
);

# Switch back to the "sharelatex" database 
use sharelatex
switched to db sharelatex
overleaf [direct: primary] sharelatex> 

# Assign the new "clusterParameterReader" role to your database user by copy and pasting the function below into the shell and press the return key 
db.grantRolesToUser(
  "{{YOUR-DATABASE-USER}}",
  [
    { role: "clusterParameterReader", db: "admin" }
  ]
);

# Type exit then return to exit the MongoDB shell
# Run bin/up -d to start the deployment stack
$ bin/up -d
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.