跳轉到主要內容
Ayakaleaf Pro 的每個新版本,都會在其版本資訊中說明所支援的 MongoDB 版本是否有任何變更。

我應該更新 MongoDB 嗎?

只有在您計畫升級 Ayakaleaf Pro 執行個體時,才應考慮更新 MongoDB 版本。 如果您執行的 MongoDB 版本比目前(或目標)版本建議的版本更新,則不需要進行任何變更。
您絕對不應該降級 MongoDB 版本。
如果您遇到特定問題,並認為可能與目前的 MongoDB 版本有關,歡迎提出 issue。

檢查您的 MongoDB 版本

開啟 mongo shell 時應該會立即顯示目前的版本。 Overleaf Toolkit 使用者:
Docker Compose 使用者:

更新流程

在升級 Ayakaleaf Pro 執行個體的過程中更新 MongoDB 版本的步驟如下:
  1. 決定您計畫升級到的 Ayakaleaf Pro 版本。
  2. 找出該 Ayakaleaf Pro 版本所建議的 MongoDB 版本。
  3. 依照說明將 MongoDB 升級至目標版本。
  4. 升級 Ayakaleaf Pro 映像檔版本並重新啟動執行個體。
我們建議一律升級至最新的可用版本。
升級 Ayakaleaf Pro 時,我們建議先升級至目前部署之主要版本的最新發行版,然後再升級至下一個主要版本的最新發行版。如果您的部署落後最新版本超過一個主要版本,則必須進行多階段升級。例如,如果您執行的是 6.2.0,請先升級至 6.2.2,再升級至 6.3.2,請參閱升級您的部署。您絕對不應跳過版本(6.2.0 -> 6.3.2)。如果您使用 Toolkit,且落後最新版本超過一個主要版本,則不得使用 bin/upgrade 指令碼,因為您需要手動進行多階段升級。
請務必在每次主要版本升級之前進行一致性備份,以便在必要時進行回復。

版本支援資訊

如果您決定使用較早的版本,下表列出了較早版本所建議的 MongoDB 版本,但您絕對不應降級 MongoDB 版本。 此表格列出的是 Overleaf 版本。Ayakaleaf Pro 映像檔從 6.0.0 開始:6.0.0 需要 MongoDB 6.0 或更新版本,而 6.0.1 及更新版本需要 MongoDB 8.0 或更新版本,且功能相容性版本(feature compatibility version)須為 7.0。若使用較舊的 MongoDB,容器會在啟動時停止。
Overleaf 版本MongoDB 版本最低功能相容性版本Node.js 驅動程式支援的最高版本
2.0.x3.4--
2.1.x 至 2.4.x3.6--
>=2.5.04.0--
>=3.1.04.2--
>=3.2.04.4--
>=4.2.05.0--
>=5.1.06.0--
>=5.3.16.05.08.0
>=5.5.06.06.08.0
>=6.0.08.07.08.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 的更新說明連結。
5.0 及更高版本的說明指向的是副本集(replica set)安裝,而非獨立(standalone)安裝。由於 Ayakaleaf Pro 使用交易功能,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 使用者:
Docker Compose 使用者:
根據升級說明,唯一的需求是將 featureCompatibilityVersion 設為 5.0。我們可以開啟 MongoDB shell 並執行指定的指令來完成: Overleaf Toolkit 使用者:
Docker Compose 使用者可以執行 docker compose exec mongo mongosh 開啟 shell,並執行與 Toolkit 使用者相同的指令。
Overleaf Toolkit 使用者: 接著,我們使用 bin/stop 指令停止 Ayakaleaf Pro 與 MongoDB 執行個體,在 config/overleaf.rc 中設定 MONGO_VERSION=6.0,然後使用 bin/up mongo 重新啟動 mongo 服務,以確認更新順利完成。 最後,我們將 Ayakaleaf Pro 映像檔版本更新為目標版本,並使用 bin/up -d 指令重新建立所有服務。 Docker Compose 使用者: 接著,我們使用 docker compose stop 指令停止 Ayakaleaf Pro 與 MongoDB 執行個體,將 docker-compose.yml 檔案更新為使用 image: mongo:6.0,然後使用 docker compose up mongo 指令重新啟動 mongo 服務,以確認更新順利完成。 最後,我們將 Ayakaleaf Pro 映像檔版本更新為目標版本,並使用 docker compose up 指令重新建立所有服務。 首先,使用上述的 mongod --version 指令確認您正在執行 MongoDB 6.0。 根據升級說明,唯一的需求是將 featureCompatibilityVersion 設為 6.0。我們可以開啟 MongoDB shell 並執行指令 db.adminCommand({ setFeatureCompatibilityVersion: "6.0" }) 來完成。 Overleaf Toolkit 使用者:
接著,我們使用 bin/stop 指令停止 Ayakaleaf Pro 與 MongoDB 執行個體,在 config/overleaf.rc 中設定 MONGO_VERSION=7.0,然後使用 bin/up mongo 重新啟動 mongo 服務,以確認更新順利完成。 最後,我們將 Ayakaleaf Pro 映像檔版本更新為目標版本,並使用 bin/up -d 指令重新建立所有服務。 首先,使用上述的 mongod --version 指令確認您正在執行 MongoDB 7.0。 根據升級說明,唯一的需求是將 featureCompatibilityVersion 設為 7.0。我們可以開啟 MongoDB shell 並執行指令 db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true }) 來完成。請注意,現在需要額外的 confirm: true 參數。
接著,我們使用 bin/stop 指令停止 Ayakaleaf Pro 與 MongoDB 執行個體,在 config/overleaf.rc 中設定 MONGO_VERSION=8.0,然後使用 bin/up mongo 重新啟動 mongo 服務,以確認更新順利完成。 最後,我們將 Ayakaleaf 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 伺服器參數的權限,也可重複用於監控用途。

Q&A

回答:沒有。最舊的 Ayakaleaf Pro 映像檔 6.0.0 需要 MongoDB 6.0,而 6.0.1 及更新版本需要 MongoDB 8.0。若要在既有的 MongoDB 4.4 上執行 Ayakaleaf Pro,請依照升級 MongoDB 的說明,一次升級一個主要版本(4.4 → 5.0 → 6.0 → 7.0 → 8.0),並在每個步驟之前進行備份。
最後修改於 2026年11月8日