更新 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 及更高版本的說明指向的是副本集（replica set）安裝，而非獨立（standalone）安裝。由於 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