更新 MongoDB

Server CE/Server Pro 的每个新版本都会在其发行说明中注明所支持的 MongoDB 版本的任何变化。

​

我应该更新 MongoDB 吗？

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

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

切勿降级你的 MongoDB 版本。

如果你遇到了某个你认为可能与当前 MongoDB 版本有关的具体问题，Server CE 用户可以随时提交 issue，Server Pro 用户可以联系 Overleaf 支持团队。

​

检查你的 MongoDB 版本

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

Overleaf Toolkit 用户：

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 用户：

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 用户）。

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

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

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

请务必在每次主版本升级之前进行一致性备份，以便在需要时进行回滚。

​

版本支持信息

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

Server CE/Server Pro	MongoDB 版本	最低功能兼容版本	Node.js 驱动支持的最高版本
2.0.x	3.4	-	-
2.1.x 至 2.4.x	3.6	-	-
>=2.5.0	4.0	-	-
>=3.1.0	4.2	-	-
>=3.2.0	4.4	-	-
>=4.2.0	5.0	-	-
>=5.1.0	6.0	-	-
>=5.3.1	6.0	5.0	8.0
>=5.5.0	6.0	6.0	8.0
6.0.0	8.0	8.0	8.0

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

你可以在这里查看兼容性表格，其中列出了可与 MongoDB 配合使用的 MongoDB Node.js 驱动版本。

你可以在这里查看每个 MongoDB 版本的生命周期终止状态。

​

升级 MongoDB

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

MongoDB 的稳定版本使用偶数版本号。

​

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

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

• MongoDB 发行说明 - 将 MongoDB 从 4.2 升级到 4.4
• MongoDB 发行说明 - 将 MongoDB 从 4.4 升级到 5.0
• MongoDB 发行说明 - 将 MongoDB 从 5.0 升级到 6.0
• MongoDB 发行说明 - 将 MongoDB 从 6.0 升级到 7.0
• MongoDB 发行说明 - 将 MongoDB 从 7.0 升级到 8.0

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

MongoDB 3.2 至 4.2 的文档现在可通过 https://www.mongodb.com/docs/legacy/ 获取

基本说明

在大多数情况下，更新需要在实际更新 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 用户：

bin/docker-compose exec mongo mongod --version
# db version v5.0.24

Docker Compose 用户：

docker compose exec mongo mongod --version
# db version v5.0.24

根据升级说明，唯一的要求是将 featureCompatibilityVersion 设置为 5.0。为此，我们打开 MongoDB shell 并运行指定的命令：

Overleaf Toolkit 用户：

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

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

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 文件以使用 image: mongo:6.0，然后使用 docker compose up mongo 命令重启 mongo 服务，以验证更新是否顺利完成。

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

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

根据升级说明，唯一的要求是将 featureCompatibilityVersion 设置为 6.0。为此，我们打开 MongoDB shell 并运行命令 db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })。

Overleaf Toolkit 用户：

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 命令重新创建所有服务。

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

根据升级说明，唯一的要求是将 featureCompatibilityVersion 设置为 7.0。为此，我们打开 MongoDB shell 并运行命令 db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true })。请注意，现在需要额外的 confirm: true 参数。

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 文件，使用 image: mongo:6.0 来升级 mongo 版本
• docker compose up mongo 用于重启 mongo 服务并验证更新是否顺利完成
• 编辑 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，允许检查失败而不阻止部署启动。

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

# 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