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