> ## 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.

# Cập nhật MongoDB

<Info>
  Mỗi bản phát hành mới của Server CE/Server Pro sẽ ghi rõ mọi thay đổi về phiên bản MongoDB được hỗ trợ trong [ghi chú phát hành](https://docs.overleaf.com/on-premises/release-notes) của nó.
</Info>

### Tôi có nên cập nhật MongoDB không?

Bạn **chỉ** nên cân nhắc cập nhật phiên bản MongoDB nếu bạn đang lên kế hoạch nâng cấp phiên bản Server CE/Server Pro của mình.

Nếu bạn đang chạy một phiên bản MongoDB mới hơn phiên bản được khuyến nghị cho phiên bản hiện tại (hoặc phiên bản mục tiêu) của bạn, thì không cần thực hiện bất kỳ thay đổi nào.

<Warning>
  Bạn không bao giờ nên hạ cấp phiên bản MongoDB của mình.
</Warning>

Nếu bạn gặp một vấn đề cụ thể mà bạn cho rằng có thể liên quan đến phiên bản MongoDB hiện tại, hãy thoải mái [tạo issue](https://github.com/overleaf/overleaf/issues) nếu bạn là người dùng Server CE, hoặc liên hệ với bộ phận hỗ trợ của Overleaf nếu bạn là người dùng Server Pro.

### Kiểm tra phiên bản MongoDB của bạn

Mở shell `mongo` sẽ in ra phiên bản hiện tại ngay lập tức.

Người dùng 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"
    }
}
```

Người dùng 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"
    }
}

```

### Quy trình cập nhật

Việc cập nhật phiên bản MongoDB trong quá trình nâng cấp phiên bản Server CE/Server Pro được thực hiện như sau:

1. Quyết định phiên bản Server CE/Server Pro mà bạn dự định nâng cấp lên.
2. Tìm phiên bản MongoDB được khuyến nghị cho bản phát hành Overleaf Server CE/Server Pro cụ thể đó.
3. Làm theo hướng dẫn để nâng cấp MongoDB lên phiên bản mục tiêu.
4. Nâng cấp phiên bản image Server CE/Server Pro và khởi động lại phiên bản.

Khuyến nghị của chúng tôi là luôn nâng cấp **Server CE/Server Pro** lên phiên bản mới nhất hiện có, vì phiên bản đó luôn được đảm bảo hỗ trợ (chỉ dành cho người dùng Server Pro).

<Danger>
  Khi nâng cấp Server CE/Pro, chúng tôi khuyến nghị nâng cấp lên bản phát hành mới nhất của phiên bản chính (major) đang triển khai **trước khi** nâng cấp lên bản phát hành mới nhất của phiên bản chính **tiếp theo**. Nếu bản triển khai của bạn chậm hơn bản mới nhất từ hai phiên bản chính trở lên, bạn sẽ phải thực hiện nâng cấp qua nhiều bước.

  Ví dụ, nếu bạn đang chạy 3.5.10, bạn sẽ cần nâng cấp lên 3.5.13 -> Thực hiện di chuyển Full Project History -> 4.2.9 -> 5.5.4.

  Bạn **không bao giờ** nên bỏ qua các phiên bản chính (3.5.10 -> 5.5.4). Nếu bạn đang dùng Toolkit và chậm hơn bản mới nhất từ hai phiên bản chính trở lên, bạn **không được** dùng script `bin/upgrade` vì bạn sẽ cần thực hiện nâng cấp thủ công qua nhiều bước.
</Danger>

<Warning>
  Điều quan trọng là phải đảm bảo bạn tạo một [bản sao lưu nhất quán](/vi/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) **trước** mỗi lần nâng cấp phiên bản chính để có thể khôi phục lại khi cần.
</Warning>

#### Thông tin hỗ trợ phiên bản

Trong trường hợp bạn quyết định dùng một phiên bản cũ hơn, bảng này cho thấy phiên bản MongoDB được khuyến nghị cho các bản phát hành Server CE/Server Pro trước đây, nhưng bạn **không bao giờ** nên hạ cấp phiên bản MongoDB của mình.

<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" }}>Phiên bản MongoDB</th><th style={{ textAlign: "center" }}>Phiên bản tương thích tính năng tối thiểu</th><th style={{ textAlign: "center" }}>Phiên bản tối đa được trình điều khiển Node.js hỗ trợ</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 đến 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>
  Phiên bản tương thích tính năng tối thiểu ở trên dựa trên phiên bản MongoDB tương ứng được khuyến nghị sử dụng với phiên bản Overleaf được nêu. Nếu bạn dự định sử dụng phiên bản cao hơn, MongoDB sẽ có yêu cầu tối thiểu riêng.
</Danger>

Bạn có thể xem bảng tương thích chỉ rõ các phiên bản trình điều khiển MongoDB Node.js được hỗ trợ để dùng với MongoDB [tại đây](https://www.mongodb.com/docs/drivers/node/current/reference/compatibility/).

Bạn có thể xem trạng thái hết vòng đời (end-of-life) của từng phiên bản MongoDB [tại đây](https://endoflife.date/mongodb).

#### Nâng cấp MongoDB

MongoDB yêu cầu **nâng cấp từng bước**. Điều đó có nghĩa là bạn không thể đi thẳng từ, chẳng hạn, `4.0` lên `5.0`. Trước tiên bạn cần cập nhật từ `4.2` lên `4.4`, rồi sau đó mới lên `5.0`.

<Info>
  MongoDB dùng số chẵn cho các phiên bản ổn định của họ.
</Info>

#### **Hướng dẫn cập nhật khi chạy MongoDB bên ngoài Docker**

Dưới đây là các liên kết đến hướng dẫn cập nhật từ mongodb.com khi nâng cấp MongoDB.

* [Ghi chú phát hành MongoDB - nâng cấp MongoDB từ `4.2` lên `4.4`](https://www.mongodb.com/docs/v4.4/release-notes/4.4-upgrade-standalone/)
* [Ghi chú phát hành MongoDB - nâng cấp MongoDB từ `4.4` lên `5.0`](https://www.mongodb.com/docs/v5.0/release-notes/5.0-upgrade-replica-set/)
* [Ghi chú phát hành MongoDB - nâng cấp MongoDB từ `5.0` lên `6.0`](https://www.mongodb.com/docs/v6.0/release-notes/6.0-upgrade-replica-set/)
* [Ghi chú phát hành MongoDB - nâng cấp MongoDB từ `6.0` lên `7.0`](https://www.mongodb.com/docs/manual/release-notes/7.0-upgrade-replica-set/#std-label-7.0-upgrade-replica-set)
* [Ghi chú phát hành MongoDB - nâng cấp MongoDB từ `7.0` lên `8.0`](https://www.mongodb.com/docs/manual/release-notes/8.0-upgrade-replica-set/#std-label-8.0-upgrade-replica-set)

<Info>
  Hướng dẫn cho `5.0` trở lên hướng đến cài đặt dạng replica set thay vì standalone. Vì Server Pro/CE 4.0.1+ sử dụng transaction, MongoDB cần được chạy dưới dạng replica set.
</Info>

<Warning>
  Tài liệu cho MongoDB 3.2 đến 4.2 hiện có tại [https://www.mongodb.com/docs/legacy/](https://www.mongodb.com/docs/legacy/)
</Warning>

**Hướng dẫn cơ bản**

Trong hầu hết các trường hợp, việc cập nhật đòi hỏi phải thiết lập một cờ tương thích trước khi thực sự cập nhật phiên bản mongo. Các bước như sau:

1. Đặt cờ tương thích như mô tả trong ghi chú phát hành của MongoDB (xem các ví dụ bên dưới).
2. Sau đó cập nhật image mongo:
   1. **Người dùng Toolkit** Cập nhật `MONGO_VERSION`, ví dụ: `MONGO_VERSION=6.0`
   2. **Người dùng Docker Compose** Cập nhật phiên bản của tag image `mongo`,\
      ví dụ: `services -> mongo -> image: mongo:6.0`;

**Ví dụ: Nâng cấp MongoDB từ `5.0` lên `6.0`**

Hãy bắt đầu bằng việc đảm bảo rằng chúng ta đang chạy MongoDB `6.0`:

Người dùng Overleaf Toolkit:

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

Người dùng Docker Compose:

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

Theo [hướng dẫn nâng cấp](https://docs.mongodb.com/manual/release-notes/3.6-upgrade-standalone/#upgrade-version-path), yêu cầu duy nhất là `featureCompatibilityVersion` phải được đặt thành `5.0`. Chúng ta thực hiện điều này bằng cách mở một shell MongoDB và chạy lệnh được chỉ định:

Người dùng 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>
  Người dùng Docker Compose có thể chạy `docker compose exec mongo mongosh` để mở shell và chạy các lệnh tương tự như người dùng Toolkit.
</Info>

Người dùng Overleaf Toolkit:

Sau đó, chúng ta sẽ dừng các phiên bản Server CE/Server Pro và MongoDB bằng lệnh `bin/stop`, đặt `MONGO_VERSION=6.0` trong `config/overleaf.rc`, rồi khởi động lại dịch vụ `mongo` bằng `bin/up mongo`) để xác nhận việc cập nhật diễn ra suôn sẻ.

Cuối cùng, chúng ta sẽ cập nhật phiên bản image Server CE/Server Pro lên phiên bản mục tiêu và tạo lại tất cả dịch vụ bằng lệnh `bin/up -d`.

Người dùng Docker Compose:

Sau đó, chúng ta sẽ dừng các phiên bản Server CE/Server Pro và MongoDB bằng lệnh `docker compose stop`, cập nhật tệp [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) để dùng `image: mongo:6.0`, rồi khởi động lại dịch vụ `mongo` bằng lệnh `docker compose up mongo` để xác nhận việc cập nhật diễn ra suôn sẻ.

Cuối cùng, chúng ta sẽ cập nhật phiên bản image Server CE/Server Pro lên phiên bản mục tiêu và tạo lại tất cả dịch vụ bằng lệnh `docker compose up`.

<strong>Ví dụ: Nâng cấp MongoDB từ `6.0` lên `7.0` (người dùng toolkit)</strong>

Bắt đầu bằng việc đảm bảo rằng bạn đang chạy MongoDB `6.0` bằng các lệnh `mongod --version` ở trên.

Theo [hướng dẫn nâng cấp](https://www.mongodb.com/docs/manual/release-notes/7.0-upgrade-replica-set/#std-label-7.0-upgrade-replica-set), yêu cầu duy nhất là `featureCompatibilityVersion` phải được đặt thành `6.0`. Chúng ta thực hiện điều này bằng cách mở một shell MongoDB và chạy lệnh `db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })`.

Người dùng Overleaf Toolkit:

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

Sau đó, chúng ta sẽ dừng các phiên bản Server CE/Server Pro và MongoDB bằng lệnh `bin/stop`, đặt `MONGO_VERSION=7.0` trong `config/overleaf.rc`, rồi khởi động lại dịch vụ `mongo` bằng `bin/up mongo`) để xác nhận việc cập nhật diễn ra suôn sẻ.

Cuối cùng, chúng ta sẽ cập nhật phiên bản image Server CE/Server Pro lên phiên bản mục tiêu và tạo lại tất cả dịch vụ bằng lệnh `bin/up -d`.

<strong>Ví dụ: Nâng cấp MongoDB từ `7.0` lên `8.0` (người dùng toolkit)</strong>

Bắt đầu bằng việc đảm bảo rằng bạn đang chạy MongoDB `7.0` bằng các lệnh `mongod --version` ở trên.

Theo [hướng dẫn nâng cấp](https://www.mongodb.com/docs/manual/release-notes/8.0-upgrade-replica-set/#std-label-8.0-upgrade-replica-set), yêu cầu duy nhất là `featureCompatibilityVersion` phải được đặt thành `7.0`. Chúng ta thực hiện điều này bằng cách mở một shell MongoDB và chạy lệnh `db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true })`. Lưu ý rằng lệnh này giờ đây yêu cầu thêm tham số `confirm: true`.

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

Sau đó, chúng ta sẽ dừng các phiên bản Server CE/Server Pro và MongoDB bằng lệnh `bin/stop`, đặt `MONGO_VERSION=8.0` trong `config/overleaf.rc`, rồi khởi động lại dịch vụ `mongo` bằng `bin/up mongo`) để xác nhận việc cập nhật diễn ra suôn sẻ.

Cuối cùng, chúng ta sẽ cập nhật phiên bản image Server CE/Server Pro lên phiên bản mục tiêu và tạo lại tất cả dịch vụ bằng lệnh `bin/up -d`.

#### Các lệnh tương đương cho người dùng docker compose

Đối với người dùng docker compose, các lệnh tương đương là:

* `docker compose exec mongo mongod --version` để hiển thị phiên bản mongo
* `docker compose exec mongo mongosh` để mở shell mongo cho các lệnh quản trị
* Lệnh `docker compose stop` để dừng máy chủ
* Chỉnh sửa tệp [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) để dùng `image: mongo:6.0` nhằm nâng cấp phiên bản mongo
* `docker compose up mongo` để khởi động lại dịch vụ mongo và xác nhận việc cập nhật diễn ra suôn sẻ
* Chỉnh sửa tệp [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) để dùng `image: sharelatex:VERSION` nhằm nâng cấp phiên bản image
* `docker compose up` để tạo lại tất cả dịch vụ.

### Tạo role tùy chỉnh

Trong phiên bản `5.5.1`, chúng tôi đã thêm một bước kiểm tra khi khởi động để xác minh phiên bản tương thích tính năng của MongoDB. Nếu cơ sở dữ liệu MongoDB của bạn sử dụng xác thực (ví dụ: xác thực cơ bản), container `sharelatex` có thể không khởi động được và hiển thị lỗi quyền "*not authorized on admin to execute command*".

Để khắc phục, bạn có thể tạo một role mới trong MongoDB và gán nó cho tài khoản người dùng được dùng để truy cập cơ sở dữ liệu theo hướng dẫn bên dưới, hoặc đặt `ALLOW_MONGO_ADMIN_CHECK_FAILURES=true` để cho phép bước kiểm tra thất bại mà không ngăn bản triển khai khởi động.

<Check>
  Role mới này **chỉ** cấp quyền đọc các tham số máy chủ MongoDB trên toàn cluster và có thể được tái sử dụng cho mục đích giám sát,
</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.