This is an automated email from the ASF dual-hosted git repository.
kassiez pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 01ef3d8f972 Upgrade doc (#1665)
01ef3d8f972 is described below
commit 01ef3d8f972f3f826a8e16b07cacf5c66d640b56
Author: wangtianyi2004 <376612...@qq.com>
AuthorDate: Thu Jan 2 14:17:07 2025 +0800
Upgrade doc (#1665)
## Versions
- [ ] dev
- [ ] 3.0
- [ ] 2.1
- [ ] 2.0
## Languages
- [ ] Chinese
- [ ] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
docs/admin-manual/cluster-management/upgrade.md | 316 +++++++++-----------
.../admin-manual/cluster-management/upgrade.md | 237 ++++++---------
.../admin-manual/cluster-management/upgrade.md | 238 ++++++---------
.../admin-manual/cluster-management/upgrade.md | 236 ++++++---------
.../admin-manual/cluster-management/upgrade.md | 318 +++++++++------------
.../admin-manual/cluster-management/upgrade.md | 316 +++++++++-----------
6 files changed, 679 insertions(+), 982 deletions(-)
diff --git a/docs/admin-manual/cluster-management/upgrade.md
b/docs/admin-manual/cluster-management/upgrade.md
index a4b61221587..f659542445c 100644
--- a/docs/admin-manual/cluster-management/upgrade.md
+++ b/docs/admin-manual/cluster-management/upgrade.md
@@ -24,270 +24,222 @@ specific language governing permissions and limitations
under the License.
-->
+Doris provides the capability for rolling upgrades, enabling step-by-step
upgrades of FE and BE nodes, minimizing downtime, and ensuring the system
remains operational during the upgrade process.
-## Overview
+## Version Compatibility
-To upgrade, please use the steps recommended in this chapter to upgrade the
cluster. The Doris cluster upgrade can be upgraded using the **rolling
upgrade** method, which does not require all cluster nodes to be shut down for
upgrade, which greatly reduces the impact on upper-layer applications.
+Doris versioning consists of three components: the first digit represents a
major milestone version, the second digit indicates a feature version, and the
third digit corresponds to a bug fix. New features are not introduced in bug
fix versions. For example, in Doris version 2.1.3, "2" indicates the second
milestone version, "1" represents the feature version under this milestone, and
"3" denotes the third bug fix for this feature version.
-## Doris Release Notes
+During version upgrades, the following rules apply:
-When upgrading Doris, please follow the principle of **not skipping two minor
versions** and upgrade sequentially.
+- **Three-digit versions:** Versions with the same first two digits can be
directly upgraded across three-digit versions. For example, version 2.1.3 can
be directly upgraded to version 2.1.7.
-For example, if you are upgrading from version 0.15.x to 2.0.x, it is
recommended to first upgrade to the latest version of 1.1, then upgrade to the
latest version of 1.2, and finally upgrade to the latest version of 2.0.
+- **Two-digit and one-digit versions:** Cross-version upgrades for two-digit
versions are not recommended due to compatibility concerns. It is advised to
upgrade sequentially through each two-digit version. For example, upgrading
from version 3.0 to 3.3 should follow the sequence 3.0 -> 3.1 -> 3.2 -> 3.3.
+The detailed version information can be found in the [versioning
rules](../../../../docusaurus-plugin-content-docs-community/current/release-versioning).
+## Upgrade Precautions
-## Upgrade Steps
-
-### Upgrade Instructions
-
-1. During the upgrade process, since Doris's RoutineLoad,
Flink-Doris-Connector, and Spark-Doris-Connector have implemented a retry
mechanism in the code, in a multi-BE node cluster, the rolling upgrade will not
cause the task to fail .
-
-2. The StreamLoad task requires you to implement a retry mechanism in your own
code, otherwise the task will fail.
-
-3. The cluster copy repair and balance function must be closed before and
opened after the completion of a single upgrade task, regardless of whether all
your cluster nodes have been upgraded.
-
-### Overview of the Upgrade Process
-
-1. Metadata backup
-
-2. Turn off the cluster copy repair and balance function
+When performing an upgrade, pay attention to the following:
-3. Compatibility testing
+- **Behavioral changes between versions:** Review the Release Notes before
upgrading to identify compatibility issues.
-4. Upgrade BE
+- **Add retry mechanisms for tasks in the cluster:** Nodes are restarted
sequentially during upgrades. Ensure that retry mechanisms are in place for
query tasks and Stream Load import jobs to avoid task failures. Routine Load
jobs using flink-doris-connector or spark-doris-connector already include retry
mechanisms in their code and do not require additional logic.
-5. Upgrade FE
+- **Disable replica repair and balance functions:** Disable these functions
during the upgrade process. Regardless of the upgrade outcome, re-enable these
functions after the upgrade is complete.
-6. Turn on the cluster replica repair and balance function
+## Metadata Compatibility Testing
-### Upgrade Pre-work
-
-Please perform the upgrade in sequence according to the upgrade process
-
-**01 Metadata Backup (Important)**
-
-**Make a full backup of the `doris-meta` directory of the FE-Master node!**
-
-**02 Turn off the cluster replica repair and balance function**
-
-There will be node restart during the upgrade process, so unnecessary cluster
balancing and replica repair logic may be triggered, first close it with the
following command:
-
-```sql
-admin set frontend config("disable_balance" = "true");
-admin set frontend config("disable_colocate_balance" = "true");
-admin set frontend config("disable_tablet_scheduler" = "true");
-```
+:::caution Note
-**03 Compatibility Testing**
+In a production environment, it is recommended to configure at least three FE
nodes for high availability. If there is only one FE node, metadata
compatibility testing must be performed before upgrading. Metadata
compatibility is critical as incompatibility may cause upgrade failures and
data loss. It is recommended to conduct metadata compatibility tests before
each upgrade, keeping in mind the following:
-:::caution Warning
+- Perform metadata compatibility testing on a development machine or BE node
whenever possible to avoid using FE nodes.
-**Metadata compatibility is very important, if the upgrade fails due to
incompatible metadata, it may lead to data loss! It is recommended to perform a
metadata compatibility test before each upgrade!**
+- If testing must be conducted on an FE node, use a non-Master node and stop
the original FE process.
:::
-1. FE Compatibility Test
-
-:::tip Important
-1. It is recommended to do FE compatibility test on your local development
machine or BE node.
-
-2. It is not recommended to test on Follower or Observer nodes to avoid link
exceptions
-
-3. If it must be on the Follower or Observer node, the started FE process
needs to be stopped
-:::
+Before upgrading, conduct metadata compatibility testing to prevent failures
caused by metadata incompatibility.
+1. **Backup metadata information:**
-a. Use the new version alone to deploy a test FE process
+ Before starting the upgrade, back up the metadata of the Master FE node.
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
- ```
+ Use the `show frontends` command and refer to the `IsMaster` column to
identify the Master FE node. FE metadata can be hot-backed up without stopping
the FE node. By default, FE metadata is stored in the `fe/doris-meta`
directory. This can be confirmed via the `meta_dir` parameter in the `fe.conf`
configuration file.
-b. Modify the FE configuration file fe.conf for testing
+2. **Modify the `fe.conf` configuration file of the test FE node:**
- ```shell
- vi ${DORIS_NEW_HOME}/conf/fe.conf
- ```
+ ```bash
+ vi ${DORIS_NEW_HOME}/conf/fe.conf
+ ```
- Modify the following port information, set **all ports** to **different
from online**
+ Modify the following port information, ensuring all ports are different
from those in the production environment, and update the `clusterID` parameter:
+ ```
+ ...
+ ## modify port
+ http_port = 18030
+ rpc_port = 19020
+ query_port = 19030
+ arrow_flight_sql_port = 19040
+ edit_log_port = 19010
+
+ ## modify clusterIP
+ clusterId=<a_new_clusterIP, such as 123456>
+ ...
+ ```
- ```shell
- ...
- http_port = 18030
- rpc_port = 19020
- query_port = 19030
- arrow_flight_sql_port = 19040
- edit_log_port = 19010
- ...
- ```
+3. Copy the backed-up Master FE metadata to the new compatibility testing
environment.
- Save and exit
+ ```bash
+ cp ${DORIS_OLD_HOME}/fe/doris-meta/* ${DORIS_NEW_HOME}/fe/doris-meta
+ ```
-c. Modify fe.conf
+4. Edit the `VERSION` file in the copied metadata directory to update the
`cluster_id` to a new cluster IP, for example, change it to `123456` as shown
in the example:
- - Add ClusterID configuration in fe.conf
+ ```bash
+ vi ${DORIS_NEW_HOME}/fe/doris-meta/image/VERSION
+ clusterId=123456
+ ```
- ```shell
- echo "cluster_id=123456" >> ${DORIS_NEW_HOME}/conf/fe.conf
- ```
+5. Start the FE process in the testing environment.
+
+ ```bash
+ sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon --metadata_failure_recovery
+ ```
- - Add metadata failover configuration in fe.conf (**>=2.0.2 + version does
not require this operation**)
- ```shell
+ For versions earlier than 2.0.2, add the `metadata_failure_recovery`
parameter to the `fe.conf` file before starting the FE process:
+ ```bash
echo "metadata_failure_recovery=true" >> ${DORIS_NEW_HOME}/conf/fe.conf
+ sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
```
-d. Copy the metadata directory doris-meta of the online environment Master FE
to the test environment
-
- ```shell
- cp ${DORIS_OLD_HOME}/fe/doris-meta/* ${DORIS_NEW_HOME}/fe/doris-meta
- ```
-
-e. Change the cluster_id in the VERSION file copied to the test environment to
123456 (that is, the same as in step 3)
-
- ```shell
- vi ${DORIS_NEW_HOME}/fe/doris-meta/image/VERSION
- clusterId=123456
- ```
-
-f. In the test environment, run the startup FE
-
-- If the version is greater than or equal to 2.0.2, run the following command
-
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon --metadata_failure_recovery
- ```
-
-- If the version is less than 2.0.2, run the following command
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
+6. Verify that the FE process has started successfully by connecting to the
current FE using the MySQL command. For example, use the query port `19030` as
mentioned above:
+
+ ```bash
+ mysql -uroot -P19030 -h127.0.0.1
```
-g. Observe whether the startup is successful through the FE log fe.log
-
- ```shell
- tail -f ${DORIS_NEW_HOME}/log/fe.log
- ```
-
-h. If the startup is successful, it means that there is no problem with the
compatibility, stop the FE process of the test environment, and prepare for the
upgrade
-
- ```
- sh ${DORIS_NEW_HOME}/bin/stop_fe.sh
- ```
+## Upgrade Steps
-2. BE Compatibility Test
+The detailed process for the upgrade is as follows:
-You can use the grayscale upgrade scheme to upgrade a single BE first. If
there is no exception or error, the compatibility is considered normal, and
subsequent upgrade actions can be performed
+1. Disable replica repair and balance functions
-### Upgrade process
+2. Upgrade BE nodes
-:::tip Tip
+3. Upgrade FE nodes
-Upgrade BE first, then FE
+4. Enable replica repair and balance functions
-Generally speaking, Doris only needs to upgrade `/bin` and `/lib` under the FE
directory and `/bin` and `/lib` under the BE directory
+During the upgrade process, the principle of upgrading BE nodes first,
followed by upgrading FE nodes, should be followed. When upgrading FE, upgrade
the Observer FE and Follower FE nodes first, and then upgrade the Master FE
node.
-In versions 2.0.2 and later, the `custom_lib/` directory is added to the FE
and BE deployment paths (if not, it can be created manually). The `custom_lib/`
directory is used to store some user-defined third-party jar packages, such as
`hadoop-lzo-*.jar`, `orai18n.jar`, etc.
+:::caution Note
-This directory does not need to be replaced during upgrade.
+In general, only the `/bin` and `/lib` directories under the FE directory and
the `/bin` and `/lib` directories under the BE directory need to be upgraded.
-However, when a major version is upgraded, new features may be added or old
functions refactored. These modifications may require **replace/add** more
directories during the upgrade to ensure the availability of all new features.
Please Carefully pay attention to the Release-Note of this version when
upgrading the version to avoid upgrade failures
+For versions 2.0.2 and later, a `custom_lib/` directory has been added under
the FE and BE deployment paths (if it doesn't exist, it can be manually
created). The `custom_lib/` directory is used to store some user-defined
third-party jar files, such as `hadoop-lzo-*.jar`, `orai18n.jar`, etc. This
directory does not need to be replaced during the upgrade.
:::
-#### Upgrade BE
+### Step 1: Disable Replica Repair and Balance Functions
-:::tip Tip
-
-In order to ensure the safety of your data, please use 3 copies to store your
data to avoid data loss caused by misoperation or failure of the upgrade
-:::
+During the upgrade process, nodes will be restarted, which may trigger
unnecessary cluster balancing and replica repair logic. Disable these functions
first using the following command:
-1. Under the premise of multiple copies, select a BE node to stop running and
perform grayscale upgrade
+```sql
+admin set frontend config("disable_balance" = "true");
+admin set frontend config("disable_colocate_balance" = "true");
+admin set frontend config("disable_tablet_scheduler" = "true");
+```
- ```shell
- sh ${DORIS_OLD_HOME}/be/bin/stop_be.sh
- ```
-2. Rename the `/bin`, `/lib` directories under the BE directory
+### Step 2: Upgrade BE Nodes
- ```shell
- mv ${DORIS_OLD_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin_back
- mv ${DORIS_OLD_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib_back
- ```
+:::info Note:
-3. Copy the new version of `/bin`, `/lib` directory to the original BE
directory
+To ensure the safety of your data, please use 3 replicas to store your data to
avoid data loss caused by upgrade mistakes or failures.
+:::
+1. In a multi-replica cluster, you can choose to stop the process on one BE
node and perform a gradual upgrade:
- ```shell
- cp -r ${DORIS_NEW_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin
- cp -r ${DORIS_NEW_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib
- ```
+ ```bash
+ sh ${DORIS_OLD_HOME}/be/bin/stop_be.sh
+ ```
-4. Start the BE node
+2. Rename the `/bin` and `/lib` directories in the BE directory:
- ```shell
- sh ${DORIS_OLD_HOME}/be/bin/start_be.sh --daemon
- ```
+ ```bash
+ mv ${DORIS_OLD_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin_back
+ mv ${DORIS_OLD_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib_back
+ ```
-5. Link the cluster to view the node information
+3. Copy the new version's `/bin` and `/lib` directories to the original BE
directory:
- ```mysql
- show backends\G
- ```
+ ```bash
+ cp -r ${DORIS_NEW_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin
+ cp -r ${DORIS_NEW_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib
+ ```
- If the `alive` status of the BE node is `true`, and the value of `Version`
is the new version, the node upgrade is successful
+4. Start the BE node:
-6. Complete the upgrade of other BE nodes in sequence
+ ```bash
+ sh ${DORIS_OLD_HOME}/be/bin/start_be.sh --daemon
+ ```
-**05 Upgrade FE**
+5. Connect to the cluster and check the node information:
-:::tip Tip
+ ```sql
+ show backends\G
+ ```
-Upgrade the non-Master nodes first, and then upgrade the Master nodes.
+ If the BE node's `alive` status is `true` and the `Version` value is the
new version, the node has been successfully upgraded.
-:::
+### Step 3: Upgrade FE Nodes
-1. In the case of multiple FE nodes, select a non-Master node to upgrade and
stop running first
+1. In a multi-FE node setup, select a non-Master node for the upgrade and stop
it first:
- ```shell
- sh ${DORIS_OLD_HOME}/fe/bin/stop_fe.sh
- ```
+ ```bash
+ sh ${DORIS_OLD_HOME}/fe/bin/stop_fe.sh
+ ```
-2. Rename the `/bin`, `/lib` directories under the FE directory
+2. Rename the `/bin`, `/lib`, and `/mysql_ssl_default_certificate` directories
in the FE directory:
- ```shell
- mv ${DORIS_OLD_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin_back
- mv ${DORIS_OLD_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib_back
- ```
+ ```bash
+ mv ${DORIS_OLD_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin_back
+ mv ${DORIS_OLD_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib_back
+ mv ${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate_back
+ ```
-3. Copy the new version of `/bin`, `/lib` directory to the original FE
directory
+3. Copy the new version's `/bin`, `/lib`, and `/mysql_ssl_default_certificate`
directories to the original FE directory:
- ```shell
- cp -r ${DORIS_NEW_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin
- cp -r ${DORIS_NEW_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib
- ```
+ ```bash
+ cp -r ${DORIS_NEW_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin
+ cp -r ${DORIS_NEW_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib
+ cp -r ${DORIS_NEW_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
+ ```
-4. Start the FE node
+4. Start the FE node:
- ```shell
- sh ${DORIS_OLD_HOME}/fe/bin/start_fe.sh --daemon
- ```
+ ```sql
+ sh ${DORIS_OLD_HOME}/fe/bin/start_fe.sh --daemon
+ ```
-5. Link the cluster to view the node information
+5. Connect to the cluster and check the node information:
- ```mysql
- show frontends\G
- ```
+ ```sql
+ show frontends\G
+ ```
- If the FE node `alive` status is `true`, and the value of `Version` is the
new version, the node is upgraded successfully
+ If the FE node's `alive` status is `true` and the `Version` value is the
new version, the node has been successfully upgraded.
-6. Complete the upgrade of other FE nodes in turn, **finally complete the
upgrade of the Master node**
+6. Complete the upgrade of the other FE nodes in sequence, and finally upgrade
the Master node.
-**06 Turn on the cluster replica repair and balance function**
+### Step 4: Enable Replica Repair and Balance Functions
-After the upgrade is complete and all BE nodes become `Alive`, enable the
cluster copy repair and balance function:
+After the upgrade is complete and all BE nodes' status is `Alive`, enable the
cluster's replica repair and balance functions:
```sql
admin set frontend config("disable_balance" = "false");
admin set frontend config("disable_colocate_balance" = "false");
admin set frontend config("disable_tablet_scheduler" = "false");
```
+
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/cluster-management/upgrade.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/cluster-management/upgrade.md
index 3f43a0d2151..13ba5d54e8b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/cluster-management/upgrade.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/cluster-management/upgrade.md
@@ -25,268 +25,215 @@ under the License.
-->
-## 概述
+Doris 提供了滚动升级的能力，在升级过程中逐步对 FE 与 BE 节点进行升级，减少停机时间，确保在升级过程中系统能够保持正常运行。
-升级请使用本章节中推荐的步骤进行集群升级，Doris 集群升级可使用**滚动升级**的方式进行升级，无需集群节点全部停机升级，极大程度上降低对上层应用的影响。
+## 版本兼容性说明
-## Doris 版本说明
+Doris 版本号由三维组成，第一位表示重大里程碑版本，第二位表示功能版本，第三位表示 bug 修复，不在三位版本中发布新的功能。如 Doris 2.1.3
版本，其中 2 表示第 2 个里程碑版本，1 表示该里程碑下的功能版本，3 表示该功能版本下的第三个 bug fix 版本。
-Doris 升级请遵守不要跨两个二位版本升级的原则，依次往后升级。
+在版本升级时，遵循以下规则：
-比如从 0.15.x 升级到 2.0.x 版本，则建议先升级至 1.1 最新版本，然后升级到最新的 1.2 版本，最后升级到最新的 2.0 版本。
+* 三位版本：相同的二位版本可以跨三位版本升级，如 2.1.3 版本可以直接升级到 2.1.7 版本；
-## 升级步骤
-
-### 升级说明
-
-1. 在升级过程中，由于 Doris 的 RoutineLoad、Flink-Doris-Connector、Spark-Doris-Connector
都已在代码中实现了重试机制，所以在多 BE 节点的集群中，滚动升级不会导致任务失败。
-
-2. StreamLoad 任务需要您在自己的代码中实现重试机制，否则会导致任务失败。
-
-3. 集群副本修复和均衡功能在单次升级任务中务必要前置关闭和结束后打开，无论您集群节点是否全部升级完成。
-
-### 升级流程概览
-
-1. 元数据备份
-
-2. 关闭集群副本修复和均衡功能
+* 二位版本及一位版本：不建议跨二位版本升级，考虑到兼容性问题，建议按照二位版本号依次升级，如 3.0 版本升级到 3.3 版本，需要按照 3.0 ->
3.1 -> 3.2 -> 3.3 的执行路径升级。
-3. 兼容性测试
+详细版本说明可以参考[版本规则](../../../../docusaurus-plugin-content-docs-community/current/release-versioning)。
-4. 升级 BE
+## 升级注意事项
-5. 升级 FE
+在升级时，需要注意以下事项：
-6. 打开集群副本修复和均衡功能
+* 版本间行为变更：在升级前需要查看 Release Note 中的行为变更以确定版本间的兼容性。
-### 升级前置工作
+* 对集群内的任务添加重试机制：升级时节点需要依次重启，对于查询任务，Stream Load 导入作业需要添加重试机制，否则会导致任务失败；在
Routine Load 作业，通过 flink-doris-connector 或 spark-doris-connector
导入的作业，已经在代码中实现了重试机制，无需添加重试逻辑；
-请按升级流程顺次执行升级
+* 关闭副本修复与均衡功能：在升级时需要关闭副本修复与均衡功能，无论升级是否成功，升级后都需要再次打开副本修复与均衡功能。
-**01 元数据备份（重要）**
-**将 FE-Master 节点的 `doris-meta` 目录进行完整备份！**
+## 元数据兼容性测试
-**02 关闭集群副本修复和均衡功能**
-
-升级过程中会有节点重启，所以可能会触发不必要的集群均衡和副本修复逻辑，先通过以下命令关闭：
-
-```sql
-admin set frontend config("disable_balance" = "true");
-admin set frontend config("disable_colocate_balance" = "true");
-admin set frontend config("disable_tablet_scheduler" = "true");
-```
+:::caution 注意
-**03 兼容性测试**
+在生产环境中，建议保持 3 个以上的 FE 做高可用配置。如果只有 1 个 FE
节点，需要先做元数据兼容性测试后，再进行升级操作。元数据兼容非常重要，如果因为元数据不兼容导致的升级失败，能会导致数据丢失。建议每次升级前都进行元数据兼容性测试，在做元数据兼容性测试时，注意以下几点：
-:::caution
-
-**元数据兼容非常重要，如果因为元数据不兼容导致的升级失败，那可能会导致数据丢失！建议每次升级前都进行元数据兼容性测试！**
+* 建议在开发机或 BE 节点上做元数据兼容性测试，尽量避免在 FE 节点上做兼容性测试
+* 如果只能在 FE 节点上做兼容性测试，建议选择非 Master 节点，并停止原有 FE 进程
:::
-1. FE 兼容性测试
-
-:::tip
-
-**重要**
-
-1. 建议在自己本地的开发机，或者 BE 节点做 FE 兼容性测试。
+在升级前，建议进行元数据兼容性测试，防止升级过程中元数据不兼容导致的升级失败。
-2. 不建议在 Follower 或者 Observer 节点上测试，避免出现链接异常
-
-3. 如果一定在 Follower 或者 Observer 节点上，需要停止已启动的 FE 进程
-
-:::
+1. 备份元数据信息：
-a. 单独使用新版本部署一个测试用的 FE 进程
+ 在开始升级工作前，需要备份 Master FE 节点的元数据信息。
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
- ```
+ 通过 `show frontends` 中 `IsMaster` 列可以判断 Master FE 节点。在备份 FE 元信息时，无需停止 FE
节点，可以直接热备份元信息。默认情况下，FE 元数据在 `fe/doris-meta` 目录下，可以通过 `fe.conf` 文件中 `meta_dir`
参数确定元数据目录。
-b. 修改测试用的 FE 的配置文件 fe.conf
+2. 修改测试用的 FE 的配置文件 fe.conf
- ```shell
+ ```bash
vi ${DORIS_NEW_HOME}/conf/fe.conf
```
- 修改以下端口信息，将**所有端口**设置为**与线上不同**
-
- ```shell
+ 修改以下端口信息，将所有端口设置为与线上不同，同时修改 clusterID 参数：
+ ```
...
+ ## modify port
http_port = 18030
rpc_port = 19020
query_port = 19030
arrow_flight_sql_port = 19040
edit_log_port = 19010
- ...
- ```
-
- 保存并退出
-
-c. 修改 fe.conf
- - 在 fe.conf 添加 ClusterID 配置
-
- ```shell
- echo "cluster_id=123456" >> ${DORIS_NEW_HOME}/conf/fe.conf
- ```
-
- - 添加元数据故障恢复配置（**2.0.2 + 版本无需进行此操作**）
-
- ```shell
- echo "metadata_failure_recovery=true" >> ${DORIS_NEW_HOME}/conf/fe.conf
+ ## modify clusterIP
+ clusterId=<a_new_clusterIP, such as 123456>
+ ...
```
-d. 拷贝线上环境 Master FE 的元数据目录 doris-meta 到测试环境
+3. 将备份的 Master FE 元数据拷贝到新的兼容性测试环境中
- ```shell
+ ```bash
cp ${DORIS_OLD_HOME}/fe/doris-meta/* ${DORIS_NEW_HOME}/fe/doris-meta
```
-e. 将拷贝到测试环境中的 VERSION 文件中的 cluster_id 修改为 123456（即与第 3 步中相同）
+4. 将拷贝的元数据目文件中的 VERSION 文件中的 cluster\_id 修改为新的 cluster IP，如在上例中修改为 123456：
- ```shell
+ ```bash
vi ${DORIS_NEW_HOME}/fe/doris-meta/image/VERSION
clusterId=123456
```
-f. 在测试环境中，运行启动 FE（**请按照版本选择启动 FE 的方式**）
-
- - 2.0.2(包含 2.0.2) + 版本
- ```shell
+5. 在测试环境中启动 FE 进程
+
+ ```bash
sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon --metadata_failure_recovery
```
-
- - 2.0.1（包含 2.0.1）以前的版本
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
- ```
-
-g. 通过 FE 日志 fe.log 观察是否启动成功
- ```shell
- tail -f ${DORIS_NEW_HOME}/log/fe.log
+ 在 2.0.2 之前的版本，需要在 fe.conf 文件中加入 `metadata_failure_recovery` 后在启动 FE 进程：
+ ```bash
+ echo "metadata_failure_recovery=true" >> ${DORIS_NEW_HOME}/conf/fe.conf
+ sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
```
-h. 如果启动成功，则代表兼容性没有问题，停止测试环境的 FE 进程，准备升级
-
- ```
- sh ${DORIS_NEW_HOME}/bin/stop_fe.sh
+6. 验证 FE 启动成功，通过 mysql 命令链接当前 FE，如上文中使用 query port 为 19030：
+
+ ```bash
+ mysql -uroot -P19030 -h127.0.0.1
```
-2. BE 兼容性测试
+## 升级步骤
+
+升级过程具体流程如下：
-可利用灰度升级方案，先升级单个 BE，无异常和报错情况下即视为兼容性正常，可执行后续升级动作
+1. 关闭副本修复与均衡功能
-### 升级流程
+2. 升级 BE 节点
-:::tip
+3. 升级 FE 节点
-先升级 BE，后升级 FE
+4. 打开副本修复与均衡功能
-一般而言，Doris 只需要升级 FE 目录下的 `/bin` 和 `/lib` 以及 BE 目录下的 `/bin` 和 `/lib`
+升级过程中，要遵循先升级 BE、在升级 FE 的原则。在升级 FE 时，先升级 Observer FE 与 Follower FE 节点，再升级
Master FE 节点。
-在 2.0.2 及之后的版本，FE 和 BE 部署路径下新增了 `custom_lib/` 目录（如没有可以手动创建）。`custom_lib/`
目录用于存放一些用户自定义的第三方 jar 包，如 `hadoop-lzo-*.jar`，`orai18n.jar` 等。
+:::caution 注意
-这个目录在升级时不需要替换。
+一般而言，Doris 只需要升级 FE 目录下的 `/bin` 和 `/lib` 以及 BE 目录下的 `/bin` 和 `/lib`
-但是在大版本升级时，可能会有新的特性增加或者老功能的重构，这些修改可能会需要升级时**替换/新增**更多的目录来保证所有新功能的可用性，请大版本升级时仔细关注该版本的
Release-Note，以免出现升级故障
+在 2.0.2 及之后的版本，FE 和 BE 部署路径下新增了 `custom_lib/` 目录（如没有可以手动创建）。`custom_lib/`
目录用于存放一些用户自定义的第三方 jar 包，如 `hadoop-lzo-*.jar`，`orai18n.jar` 等。这个目录在升级时不需要替换。
:::
-**04 升级 BE**
+### 第 1 步：关闭副本修复与均衡功能
-:::tip
+在升级过程中会有节点重启，可能会触发不必要的集群均衡和副本修复逻辑，先通过以下命令关闭：
-为了保证您的数据安全，请使用 3 副本来存储您的数据，以避免升级误操作或失败导致的数据丢失问题
+```sql
+admin set frontend config("disable_balance" = "true");
+admin set frontend config("disable_colocate_balance" = "true");
+admin set frontend config("disable_tablet_scheduler" = "true");
+```
-:::
+### 第 2 步：升级 BE 节点
-1. 在多副本的前提下，选择一台 BE 节点停止运行，进行灰度升级
+:::info 备注：
- ```shell
+为了保证您的数据安全，请使用 3 副本来存储您的数据，以避免升级误操作或失败导致的数据丢失问题。
+:::
+1. 在多副本的集群中，可以选择一台 BE 节点停止进程，进行灰度升级：
+
+ ```bash
sh ${DORIS_OLD_HOME}/be/bin/stop_be.sh
```
-2. 重命名 BE 目录下的 `/bin`，`/lib` 目录
+2. 重命名 BE 目录下的 `/bin`，`/lib` 目录：
- ```shell
+ ```bash
mv ${DORIS_OLD_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin_back
mv ${DORIS_OLD_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib_back
```
-3. 复制新版本的 `/bin`，`/lib` 目录到原 BE 目录下
+3. 复制新版本的 `/bin`，`/lib` 目录到原 BE 目录下：
- ```shell
+ ```bash
cp -r ${DORIS_NEW_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin
cp -r ${DORIS_NEW_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib
```
-4. 启动该 BE 节点
+4. 启动该 BE 节点：
- ```shell
+ ```bash
sh ${DORIS_OLD_HOME}/be/bin/start_be.sh --daemon
```
-5. 链接集群，查看该节点信息
+5. 连接集群，查看该节点信息：
- ```mysql
+ ```sql
show backends\G
```
- 若该 BE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功
-
-6. 依次完成其他 BE 节点升级
-
-**05 升级 FE**
+ 若该 BE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功。
-:::tip
-
-先升级非 Master 节点，后升级 Master 节点。
-
-:::
+### 第 3 步：升级 FE 节点
-1. 多个 FE 节点情况下，选择一个非 Master 节点进行升级，先停止运行
+1. 多个 FE 节点情况下，选择一个非 Master 节点进行升级，先停止运行：
- ```shell
+ ```bash
sh ${DORIS_OLD_HOME}/fe/bin/stop_fe.sh
```
-2. 重命名 FE 目录下的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录
+2. 重命名 FE 目录下的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录：
- ```shell
+ ```bash
mv ${DORIS_OLD_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin_back
mv ${DORIS_OLD_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib_back
mv ${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate_back
```
-3. 复制新版本的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录到原 FE 目录下
+3. 复制新版本的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录到原 FE 目录下：
- ```shell
+ ```bash
cp -r ${DORIS_NEW_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin
cp -r ${DORIS_NEW_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib
cp -r ${DORIS_NEW_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
```
-4. 启动该 FE 节点
+4. 启动该 FE 节点：
- ```shell
+ ```sql
sh ${DORIS_OLD_HOME}/fe/bin/start_fe.sh --daemon
```
-5. 链接集群，查看该节点信息
+5. 连接集群，查看该节点信息：
- ```mysql
+ ```sql
show frontends\G
```
- 若该 FE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功
+ 若该 FE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功。
-6. 依次完成其他 FE 节点升级，**最后完成 Master 节点的升级**
+6. 依次完成其他 FE 节点升级，最后完成 Master 节点的升级
-**06 打开集群副本修复和均衡功能**
+### 第 4 步：打开副本修复与均衡功能
升级完成，并且所有 BE 节点状态变为 `Alive` 后，打开集群副本修复和均衡功能：
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/cluster-management/upgrade.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/cluster-management/upgrade.md
index 4a9a6a8b117..13ba5d54e8b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/cluster-management/upgrade.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/cluster-management/upgrade.md
@@ -25,269 +25,215 @@ under the License.
-->
-## 概述
+Doris 提供了滚动升级的能力，在升级过程中逐步对 FE 与 BE 节点进行升级，减少停机时间，确保在升级过程中系统能够保持正常运行。
-升级请使用本章节中推荐的步骤进行集群升级，Doris 集群升级可使用**滚动升级**的方式进行升级，无需集群节点全部停机升级，极大程度上降低对上层应用的影响。
+## 版本兼容性说明
-## Doris 版本说明
+Doris 版本号由三维组成，第一位表示重大里程碑版本，第二位表示功能版本，第三位表示 bug 修复，不在三位版本中发布新的功能。如 Doris 2.1.3
版本，其中 2 表示第 2 个里程碑版本，1 表示该里程碑下的功能版本，3 表示该功能版本下的第三个 bug fix 版本。
-Doris 升级请遵守不要跨两个二位版本升级的原则，依次往后升级。
+在版本升级时，遵循以下规则：
-比如从 0.15.x 升级到 2.0.x 版本，则建议先升级至 1.1 最新版本，然后升级到最新的 1.2 版本，最后升级到最新的 2.0 版本。
+* 三位版本：相同的二位版本可以跨三位版本升级，如 2.1.3 版本可以直接升级到 2.1.7 版本；
+* 二位版本及一位版本：不建议跨二位版本升级，考虑到兼容性问题，建议按照二位版本号依次升级，如 3.0 版本升级到 3.3 版本，需要按照 3.0 ->
3.1 -> 3.2 -> 3.3 的执行路径升级。
-## 升级步骤
-
-### 升级说明
-
-1. 在升级过程中，由于 Doris 的 RoutineLoad、Flink-Doris-Connector、Spark-Doris-Connector
都已在代码中实现了重试机制，所以在多 BE 节点的集群中，滚动升级不会导致任务失败。
-
-2. StreamLoad 任务需要您在自己的代码中实现重试机制，否则会导致任务失败。
-
-3. 集群副本修复和均衡功能在单次升级任务中务必要前置关闭和结束后打开，无论您集群节点是否全部升级完成。
-
-### 升级流程概览
-
-1. 元数据备份
-
-2. 关闭集群副本修复和均衡功能
+详细版本说明可以参考[版本规则](../../../../docusaurus-plugin-content-docs-community/current/release-versioning)。
-3. 兼容性测试
+## 升级注意事项
-4. 升级 BE
+在升级时，需要注意以下事项：
-5. 升级 FE
+* 版本间行为变更：在升级前需要查看 Release Note 中的行为变更以确定版本间的兼容性。
-6. 打开集群副本修复和均衡功能
+* 对集群内的任务添加重试机制：升级时节点需要依次重启，对于查询任务，Stream Load 导入作业需要添加重试机制，否则会导致任务失败；在
Routine Load 作业，通过 flink-doris-connector 或 spark-doris-connector
导入的作业，已经在代码中实现了重试机制，无需添加重试逻辑；
-### 升级前置工作
+* 关闭副本修复与均衡功能：在升级时需要关闭副本修复与均衡功能，无论升级是否成功，升级后都需要再次打开副本修复与均衡功能。
-请按升级流程顺次执行升级
-**01 元数据备份（重要）**
+## 元数据兼容性测试
-**将 FE-Master 节点的 `doris-meta` 目录进行完整备份！**
+:::caution 注意
-**02 关闭集群副本修复和均衡功能**
-
-升级过程中会有节点重启，所以可能会触发不必要的集群均衡和副本修复逻辑，先通过以下命令关闭：
-
-```sql
-admin set frontend config("disable_balance" = "true");
-admin set frontend config("disable_colocate_balance" = "true");
-admin set frontend config("disable_tablet_scheduler" = "true");
-```
+在生产环境中，建议保持 3 个以上的 FE 做高可用配置。如果只有 1 个 FE
节点，需要先做元数据兼容性测试后，再进行升级操作。元数据兼容非常重要，如果因为元数据不兼容导致的升级失败，能会导致数据丢失。建议每次升级前都进行元数据兼容性测试，在做元数据兼容性测试时，注意以下几点：
-**03 兼容性测试**
-
-:::caution
-
-**元数据兼容非常重要，如果因为元数据不兼容导致的升级失败，那可能会导致数据丢失！建议每次升级前都进行元数据兼容性测试！**
+* 建议在开发机或 BE 节点上做元数据兼容性测试，尽量避免在 FE 节点上做兼容性测试
+* 如果只能在 FE 节点上做兼容性测试，建议选择非 Master 节点，并停止原有 FE 进程
:::
-1. FE 兼容性测试
-
-:::tip
-
-**重要**
-
-1. 建议在自己本地的开发机，或者 BE 节点做 FE 兼容性测试。
-
-2. 不建议在 Follower 或者 Observer 节点上测试，避免出现链接异常
-
-3. 如果一定在 Follower 或者 Observer 节点上，需要停止已启动的 FE 进程
+在升级前，建议进行元数据兼容性测试，防止升级过程中元数据不兼容导致的升级失败。
-:::
+1. 备份元数据信息：
-a. 单独使用新版本部署一个测试用的 FE 进程
+ 在开始升级工作前，需要备份 Master FE 节点的元数据信息。
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
- ```
+ 通过 `show frontends` 中 `IsMaster` 列可以判断 Master FE 节点。在备份 FE 元信息时，无需停止 FE
节点，可以直接热备份元信息。默认情况下，FE 元数据在 `fe/doris-meta` 目录下，可以通过 `fe.conf` 文件中 `meta_dir`
参数确定元数据目录。
-b. 修改测试用的 FE 的配置文件 fe.conf
+2. 修改测试用的 FE 的配置文件 fe.conf
- ```shell
+ ```bash
vi ${DORIS_NEW_HOME}/conf/fe.conf
```
- 修改以下端口信息，将**所有端口**设置为**与线上不同**
-
- ```shell
+ 修改以下端口信息，将所有端口设置为与线上不同，同时修改 clusterID 参数：
+ ```
...
+ ## modify port
http_port = 18030
rpc_port = 19020
query_port = 19030
arrow_flight_sql_port = 19040
edit_log_port = 19010
- ...
- ```
-
- 保存并退出
-c. 修改 fe.conf
-
- - 在 fe.conf 添加 ClusterID 配置
-
- ```shell
- echo "cluster_id=123456" >> ${DORIS_NEW_HOME}/conf/fe.conf
- ```
-
- - 添加元数据故障恢复配置（**2.0.2 + 版本无需进行此操作**）
-
- ```shell
- echo "metadata_failure_recovery=true" >> ${DORIS_NEW_HOME}/conf/fe.conf
+ ## modify clusterIP
+ clusterId=<a_new_clusterIP, such as 123456>
+ ...
```
-d. 拷贝线上环境 Master FE 的元数据目录 doris-meta 到测试环境
+3. 将备份的 Master FE 元数据拷贝到新的兼容性测试环境中
- ```shell
+ ```bash
cp ${DORIS_OLD_HOME}/fe/doris-meta/* ${DORIS_NEW_HOME}/fe/doris-meta
```
-e. 将拷贝到测试环境中的 VERSION 文件中的 cluster_id 修改为 123456（即与第 3 步中相同）
+4. 将拷贝的元数据目文件中的 VERSION 文件中的 cluster\_id 修改为新的 cluster IP，如在上例中修改为 123456：
- ```shell
+ ```bash
vi ${DORIS_NEW_HOME}/fe/doris-meta/image/VERSION
clusterId=123456
```
-f. 在测试环境中，运行启动 FE（**请按照版本选择启动 FE 的方式**）
-
- - 2.0.2(包含 2.0.2) + 版本
- ```shell
+5. 在测试环境中启动 FE 进程
+
+ ```bash
sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon --metadata_failure_recovery
```
-
- - 2.0.1（包含 2.0.1）以前的版本
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
- ```
-
-g. 通过 FE 日志 fe.log 观察是否启动成功
- ```shell
- tail -f ${DORIS_NEW_HOME}/log/fe.log
+ 在 2.0.2 之前的版本，需要在 fe.conf 文件中加入 `metadata_failure_recovery` 后在启动 FE 进程：
+ ```bash
+ echo "metadata_failure_recovery=true" >> ${DORIS_NEW_HOME}/conf/fe.conf
+ sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
```
-h. 如果启动成功，则代表兼容性没有问题，停止测试环境的 FE 进程，准备升级
-
- ```
- sh ${DORIS_NEW_HOME}/bin/stop_fe.sh
+6. 验证 FE 启动成功，通过 mysql 命令链接当前 FE，如上文中使用 query port 为 19030：
+
+ ```bash
+ mysql -uroot -P19030 -h127.0.0.1
```
-2. BE 兼容性测试
+## 升级步骤
-可利用灰度升级方案，先升级单个 BE，无异常和报错情况下即视为兼容性正常，可执行后续升级动作
+升级过程具体流程如下：
-### 升级流程
+1. 关闭副本修复与均衡功能
-:::tip
+2. 升级 BE 节点
-先升级 BE，后升级 FE
+3. 升级 FE 节点
-一般而言，Doris 只需要升级 FE 目录下的 `/bin` 和 `/lib` 以及 BE 目录下的 `/bin` 和 `/lib`
+4. 打开副本修复与均衡功能
-在 2.0.2 及之后的版本，FE 和 BE 部署路径下新增了 `custom_lib/` 目录（如没有可以手动创建）。`custom_lib/`
目录用于存放一些用户自定义的第三方 jar 包，如 `hadoop-lzo-*.jar`，`orai18n.jar` 等。
+升级过程中，要遵循先升级 BE、在升级 FE 的原则。在升级 FE 时，先升级 Observer FE 与 Follower FE 节点，再升级
Master FE 节点。
-这个目录在升级时不需要替换。
+:::caution 注意
-但是在大版本升级时，可能会有新的特性增加或者老功能的重构，这些修改可能会需要升级时**替换/新增**更多的目录来保证所有新功能的可用性，请大版本升级时仔细关注该版本的
Release-Note，以免出现升级故障
+一般而言，Doris 只需要升级 FE 目录下的 `/bin` 和 `/lib` 以及 BE 目录下的 `/bin` 和 `/lib`
+
+在 2.0.2 及之后的版本，FE 和 BE 部署路径下新增了 `custom_lib/` 目录（如没有可以手动创建）。`custom_lib/`
目录用于存放一些用户自定义的第三方 jar 包，如 `hadoop-lzo-*.jar`，`orai18n.jar` 等。这个目录在升级时不需要替换。
:::
-**04 升级 BE**
+### 第 1 步：关闭副本修复与均衡功能
-:::tip
+在升级过程中会有节点重启，可能会触发不必要的集群均衡和副本修复逻辑，先通过以下命令关闭：
-为了保证您的数据安全，请使用 3 副本来存储您的数据，以避免升级误操作或失败导致的数据丢失问题
+```sql
+admin set frontend config("disable_balance" = "true");
+admin set frontend config("disable_colocate_balance" = "true");
+admin set frontend config("disable_tablet_scheduler" = "true");
+```
-:::
+### 第 2 步：升级 BE 节点
-1. 在多副本的前提下，选择一台 BE 节点停止运行，进行灰度升级
+:::info 备注：
- ```shell
+为了保证您的数据安全，请使用 3 副本来存储您的数据，以避免升级误操作或失败导致的数据丢失问题。
+:::
+1. 在多副本的集群中，可以选择一台 BE 节点停止进程，进行灰度升级：
+
+ ```bash
sh ${DORIS_OLD_HOME}/be/bin/stop_be.sh
```
-2. 重命名 BE 目录下的 `/bin`，`/lib` 目录
+2. 重命名 BE 目录下的 `/bin`，`/lib` 目录：
- ```shell
+ ```bash
mv ${DORIS_OLD_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin_back
mv ${DORIS_OLD_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib_back
```
-3. 复制新版本的 `/bin`，`/lib` 目录到原 BE 目录下
+3. 复制新版本的 `/bin`，`/lib` 目录到原 BE 目录下：
- ```shell
+ ```bash
cp -r ${DORIS_NEW_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin
cp -r ${DORIS_NEW_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib
```
-4. 启动该 BE 节点
+4. 启动该 BE 节点：
- ```shell
+ ```bash
sh ${DORIS_OLD_HOME}/be/bin/start_be.sh --daemon
```
-5. 链接集群，查看该节点信息
+5. 连接集群，查看该节点信息：
- ```mysql
+ ```sql
show backends\G
```
- 若该 BE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功
-
-6. 依次完成其他 BE 节点升级
-
-**05 升级 FE**
+ 若该 BE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功。
-:::tip
-
-先升级非 Master 节点，后升级 Master 节点。
-
-:::
+### 第 3 步：升级 FE 节点
-1. 多个 FE 节点情况下，选择一个非 Master 节点进行升级，先停止运行
+1. 多个 FE 节点情况下，选择一个非 Master 节点进行升级，先停止运行：
- ```shell
+ ```bash
sh ${DORIS_OLD_HOME}/fe/bin/stop_fe.sh
```
-2. 重命名 FE 目录下的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录
+2. 重命名 FE 目录下的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录：
- ```shell
+ ```bash
mv ${DORIS_OLD_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin_back
mv ${DORIS_OLD_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib_back
mv ${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate_back
```
-3. 复制新版本的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录到原 FE 目录下
+3. 复制新版本的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录到原 FE 目录下：
- ```shell
+ ```bash
cp -r ${DORIS_NEW_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin
cp -r ${DORIS_NEW_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib
cp -r ${DORIS_NEW_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
```
-4. 启动该 FE 节点
+4. 启动该 FE 节点：
- ```shell
+ ```sql
sh ${DORIS_OLD_HOME}/fe/bin/start_fe.sh --daemon
```
-5. 链接集群，查看该节点信息
+5. 连接集群，查看该节点信息：
- ```mysql
+ ```sql
show frontends\G
```
- 若该 FE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功
+ 若该 FE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功。
-6. 依次完成其他 FE 节点升级，**最后完成 Master 节点的升级**
+6. 依次完成其他 FE 节点升级，最后完成 Master 节点的升级
-**06 打开集群副本修复和均衡功能**
+### 第 4 步：打开副本修复与均衡功能
升级完成，并且所有 BE 节点状态变为 `Alive` 后，打开集群副本修复和均衡功能：
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/admin-manual/cluster-management/upgrade.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/admin-manual/cluster-management/upgrade.md
index 3f43a0d2151..cc052a215b1 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/admin-manual/cluster-management/upgrade.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/admin-manual/cluster-management/upgrade.md
@@ -25,268 +25,216 @@ under the License.
-->
-## 概述
+Doris 提供了滚动升级的能力，在升级过程中逐步对 FE 与 BE 节点进行升级，减少停机时间，确保在升级过程中系统能够保持正常运行。
-升级请使用本章节中推荐的步骤进行集群升级，Doris 集群升级可使用**滚动升级**的方式进行升级，无需集群节点全部停机升级，极大程度上降低对上层应用的影响。
+## 版本兼容性说明
-## Doris 版本说明
+Doris 版本号由三维组成，第一位表示重大里程碑版本，第二位表示功能版本，第三位表示 bug 修复，不在三位版本中发布新的功能。如 Doris 2.1.3
版本，其中 2 表示第 2 个里程碑版本，1 表示该里程碑下的功能版本，3 表示该功能版本下的第三个 bug fix 版本。
-Doris 升级请遵守不要跨两个二位版本升级的原则，依次往后升级。
+在版本升级时，遵循以下规则：
-比如从 0.15.x 升级到 2.0.x 版本，则建议先升级至 1.1 最新版本，然后升级到最新的 1.2 版本，最后升级到最新的 2.0 版本。
+* 三位版本：相同的二位版本可以跨三位版本升级，如 2.1.3 版本可以直接升级到 2.1.7 版本；
-## 升级步骤
-
-### 升级说明
-
-1. 在升级过程中，由于 Doris 的 RoutineLoad、Flink-Doris-Connector、Spark-Doris-Connector
都已在代码中实现了重试机制，所以在多 BE 节点的集群中，滚动升级不会导致任务失败。
-
-2. StreamLoad 任务需要您在自己的代码中实现重试机制，否则会导致任务失败。
-
-3. 集群副本修复和均衡功能在单次升级任务中务必要前置关闭和结束后打开，无论您集群节点是否全部升级完成。
-
-### 升级流程概览
-
-1. 元数据备份
+* 二位版本及一位版本：不建议跨二位版本升级，考虑到兼容性问题，建议按照二位版本号依次升级，如 3.0 版本升级到 3.3 版本，需要按照 3.0 ->
3.1 -> 3.2 -> 3.3 的执行路径升级。
-2. 关闭集群副本修复和均衡功能
+详细版本说明可以参考[版本规则](../../../../docusaurus-plugin-content-docs-community/current/release-versioning)。
-3. 兼容性测试
-4. 升级 BE
+## 升级注意事项
-5. 升级 FE
+在升级时，需要注意以下事项：
-6. 打开集群副本修复和均衡功能
+* 版本间行为变更：在升级前需要查看 Release Note 中的行为变更以确定版本间的兼容性。
-### 升级前置工作
+* 对集群内的任务添加重试机制：升级时节点需要依次重启，对于查询任务，Stream Load 导入作业需要添加重试机制，否则会导致任务失败；在
Routine Load 作业，通过 flink-doris-connector 或 spark-doris-connector
导入的作业，已经在代码中实现了重试机制，无需添加重试逻辑；
-请按升级流程顺次执行升级
+* 关闭副本修复与均衡功能：在升级时需要关闭副本修复与均衡功能，无论升级是否成功，升级后都需要再次打开副本修复与均衡功能。
-**01 元数据备份（重要）**
-**将 FE-Master 节点的 `doris-meta` 目录进行完整备份！**
-
-**02 关闭集群副本修复和均衡功能**
-
-升级过程中会有节点重启，所以可能会触发不必要的集群均衡和副本修复逻辑，先通过以下命令关闭：
-
-```sql
-admin set frontend config("disable_balance" = "true");
-admin set frontend config("disable_colocate_balance" = "true");
-admin set frontend config("disable_tablet_scheduler" = "true");
-```
+## 元数据兼容性测试
-**03 兼容性测试**
+:::caution 注意
-:::caution
+在生产环境中，建议保持 3 个以上的 FE 做高可用配置。如果只有 1 个 FE
节点，需要先做元数据兼容性测试后，再进行升级操作。元数据兼容非常重要，如果因为元数据不兼容导致的升级失败，能会导致数据丢失。建议每次升级前都进行元数据兼容性测试，在做元数据兼容性测试时，注意以下几点：
-**元数据兼容非常重要，如果因为元数据不兼容导致的升级失败，那可能会导致数据丢失！建议每次升级前都进行元数据兼容性测试！**
+* 建议在开发机或 BE 节点上做元数据兼容性测试，尽量避免在 FE 节点上做兼容性测试
+* 如果只能在 FE 节点上做兼容性测试，建议选择非 Master 节点，并停止原有 FE 进程
:::
-1. FE 兼容性测试
-
-:::tip
-
-**重要**
-
-1. 建议在自己本地的开发机，或者 BE 节点做 FE 兼容性测试。
+在升级前，建议进行元数据兼容性测试，防止升级过程中元数据不兼容导致的升级失败。
-2. 不建议在 Follower 或者 Observer 节点上测试，避免出现链接异常
-
-3. 如果一定在 Follower 或者 Observer 节点上，需要停止已启动的 FE 进程
-
-:::
+1. 备份元数据信息：
-a. 单独使用新版本部署一个测试用的 FE 进程
+ 在开始升级工作前，需要备份 Master FE 节点的元数据信息。
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
- ```
+ 通过 `show frontends` 中 `IsMaster` 列可以判断 Master FE 节点。在备份 FE 元信息时，无需停止 FE
节点，可以直接热备份元信息。默认情况下，FE 元数据在 `fe/doris-meta` 目录下，可以通过 `fe.conf` 文件中 `meta_dir`
参数确定元数据目录。
-b. 修改测试用的 FE 的配置文件 fe.conf
+2. 修改测试用的 FE 的配置文件 fe.conf
- ```shell
+ ```bash
vi ${DORIS_NEW_HOME}/conf/fe.conf
```
- 修改以下端口信息，将**所有端口**设置为**与线上不同**
-
- ```shell
+ 修改以下端口信息，将所有端口设置为与线上不同，同时修改 clusterID 参数：
+ ```
...
+ ## modify port
http_port = 18030
rpc_port = 19020
query_port = 19030
arrow_flight_sql_port = 19040
edit_log_port = 19010
- ...
- ```
-
- 保存并退出
-
-c. 修改 fe.conf
- - 在 fe.conf 添加 ClusterID 配置
-
- ```shell
- echo "cluster_id=123456" >> ${DORIS_NEW_HOME}/conf/fe.conf
- ```
-
- - 添加元数据故障恢复配置（**2.0.2 + 版本无需进行此操作**）
-
- ```shell
- echo "metadata_failure_recovery=true" >> ${DORIS_NEW_HOME}/conf/fe.conf
+ ## modify clusterIP
+ clusterId=<a_new_clusterIP, such as 123456>
+ ...
```
-d. 拷贝线上环境 Master FE 的元数据目录 doris-meta 到测试环境
+3. 将备份的 Master FE 元数据拷贝到新的兼容性测试环境中
- ```shell
+ ```bash
cp ${DORIS_OLD_HOME}/fe/doris-meta/* ${DORIS_NEW_HOME}/fe/doris-meta
```
-e. 将拷贝到测试环境中的 VERSION 文件中的 cluster_id 修改为 123456（即与第 3 步中相同）
+4. 将拷贝的元数据目文件中的 VERSION 文件中的 cluster\_id 修改为新的 cluster IP，如在上例中修改为 123456：
- ```shell
+ ```bash
vi ${DORIS_NEW_HOME}/fe/doris-meta/image/VERSION
clusterId=123456
```
-f. 在测试环境中，运行启动 FE（**请按照版本选择启动 FE 的方式**）
-
- - 2.0.2(包含 2.0.2) + 版本
- ```shell
+5. 在测试环境中启动 FE 进程
+
+ ```bash
sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon --metadata_failure_recovery
```
-
- - 2.0.1（包含 2.0.1）以前的版本
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
- ```
-
-g. 通过 FE 日志 fe.log 观察是否启动成功
- ```shell
- tail -f ${DORIS_NEW_HOME}/log/fe.log
+ 在 2.0.2 之前的版本，需要在 fe.conf 文件中加入 `metadata_failure_recovery` 后在启动 FE 进程：
+ ```bash
+ echo "metadata_failure_recovery=true" >> ${DORIS_NEW_HOME}/conf/fe.conf
+ sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
```
-h. 如果启动成功，则代表兼容性没有问题，停止测试环境的 FE 进程，准备升级
-
- ```
- sh ${DORIS_NEW_HOME}/bin/stop_fe.sh
+6. 验证 FE 启动成功，通过 mysql 命令链接当前 FE，如上文中使用 query port 为 19030：
+
+ ```bash
+ mysql -uroot -P19030 -h127.0.0.1
```
-2. BE 兼容性测试
+## 升级步骤
+
+升级过程具体流程如下：
-可利用灰度升级方案，先升级单个 BE，无异常和报错情况下即视为兼容性正常，可执行后续升级动作
+1. 关闭副本修复与均衡功能
-### 升级流程
+2. 升级 BE 节点
-:::tip
+3. 升级 FE 节点
-先升级 BE，后升级 FE
+4. 打开副本修复与均衡功能
-一般而言，Doris 只需要升级 FE 目录下的 `/bin` 和 `/lib` 以及 BE 目录下的 `/bin` 和 `/lib`
+升级过程中，要遵循先升级 BE、在升级 FE 的原则。在升级 FE 时，先升级 Observer FE 与 Follower FE 节点，再升级
Master FE 节点。
-在 2.0.2 及之后的版本，FE 和 BE 部署路径下新增了 `custom_lib/` 目录（如没有可以手动创建）。`custom_lib/`
目录用于存放一些用户自定义的第三方 jar 包，如 `hadoop-lzo-*.jar`，`orai18n.jar` 等。
+:::caution 注意
-这个目录在升级时不需要替换。
+一般而言，Doris 只需要升级 FE 目录下的 `/bin` 和 `/lib` 以及 BE 目录下的 `/bin` 和 `/lib`
-但是在大版本升级时，可能会有新的特性增加或者老功能的重构，这些修改可能会需要升级时**替换/新增**更多的目录来保证所有新功能的可用性，请大版本升级时仔细关注该版本的
Release-Note，以免出现升级故障
+在 2.0.2 及之后的版本，FE 和 BE 部署路径下新增了 `custom_lib/` 目录（如没有可以手动创建）。`custom_lib/`
目录用于存放一些用户自定义的第三方 jar 包，如 `hadoop-lzo-*.jar`，`orai18n.jar` 等。这个目录在升级时不需要替换。
:::
-**04 升级 BE**
+### 第 1 步：关闭副本修复与均衡功能
-:::tip
+在升级过程中会有节点重启，可能会触发不必要的集群均衡和副本修复逻辑，先通过以下命令关闭：
-为了保证您的数据安全，请使用 3 副本来存储您的数据，以避免升级误操作或失败导致的数据丢失问题
+```sql
+admin set frontend config("disable_balance" = "true");
+admin set frontend config("disable_colocate_balance" = "true");
+admin set frontend config("disable_tablet_scheduler" = "true");
+```
-:::
+### 第 2 步：升级 BE 节点
-1. 在多副本的前提下，选择一台 BE 节点停止运行，进行灰度升级
+:::info 备注：
- ```shell
+为了保证您的数据安全，请使用 3 副本来存储您的数据，以避免升级误操作或失败导致的数据丢失问题。
+:::
+1. 在多副本的集群中，可以选择一台 BE 节点停止进程，进行灰度升级：
+
+ ```bash
sh ${DORIS_OLD_HOME}/be/bin/stop_be.sh
```
-2. 重命名 BE 目录下的 `/bin`，`/lib` 目录
+2. 重命名 BE 目录下的 `/bin`，`/lib` 目录：
- ```shell
+ ```bash
mv ${DORIS_OLD_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin_back
mv ${DORIS_OLD_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib_back
```
-3. 复制新版本的 `/bin`，`/lib` 目录到原 BE 目录下
+3. 复制新版本的 `/bin`，`/lib` 目录到原 BE 目录下：
- ```shell
+ ```bash
cp -r ${DORIS_NEW_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin
cp -r ${DORIS_NEW_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib
```
-4. 启动该 BE 节点
+4. 启动该 BE 节点：
- ```shell
+ ```bash
sh ${DORIS_OLD_HOME}/be/bin/start_be.sh --daemon
```
-5. 链接集群，查看该节点信息
+5. 连接集群，查看该节点信息：
- ```mysql
+ ```sql
show backends\G
```
- 若该 BE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功
-
-6. 依次完成其他 BE 节点升级
-
-**05 升级 FE**
+ 若该 BE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功。
-:::tip
-
-先升级非 Master 节点，后升级 Master 节点。
-
-:::
+### 第 3 步：升级 FE 节点
-1. 多个 FE 节点情况下，选择一个非 Master 节点进行升级，先停止运行
+1. 多个 FE 节点情况下，选择一个非 Master 节点进行升级，先停止运行：
- ```shell
+ ```bash
sh ${DORIS_OLD_HOME}/fe/bin/stop_fe.sh
```
-2. 重命名 FE 目录下的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录
+2. 重命名 FE 目录下的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录：
- ```shell
+ ```bash
mv ${DORIS_OLD_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin_back
mv ${DORIS_OLD_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib_back
mv ${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate_back
```
-3. 复制新版本的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录到原 FE 目录下
+3. 复制新版本的 `/bin`，`/lib`，`/mysql_ssl_default_certificate` 目录到原 FE 目录下：
- ```shell
+ ```bash
cp -r ${DORIS_NEW_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin
cp -r ${DORIS_NEW_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib
cp -r ${DORIS_NEW_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
```
-4. 启动该 FE 节点
+4. 启动该 FE 节点：
- ```shell
+ ```sql
sh ${DORIS_OLD_HOME}/fe/bin/start_fe.sh --daemon
```
-5. 链接集群，查看该节点信息
+5. 连接集群，查看该节点信息：
- ```mysql
+ ```sql
show frontends\G
```
- 若该 FE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功
+ 若该 FE 节点 `alive` 状态为 `true`，且 `Version` 值为新版本，则该节点升级成功。
-6. 依次完成其他 FE 节点升级，**最后完成 Master 节点的升级**
+6. 依次完成其他 FE 节点升级，最后完成 Master 节点的升级
-**06 打开集群副本修复和均衡功能**
+### 第 4 步：打开副本修复与均衡功能
升级完成，并且所有 BE 节点状态变为 `Alive` 后，打开集群副本修复和均衡功能：
diff --git
a/versioned_docs/version-2.1/admin-manual/cluster-management/upgrade.md
b/versioned_docs/version-2.1/admin-manual/cluster-management/upgrade.md
index 450a89c28a1..f659542445c 100644
--- a/versioned_docs/version-2.1/admin-manual/cluster-management/upgrade.md
+++ b/versioned_docs/version-2.1/admin-manual/cluster-management/upgrade.md
@@ -1,6 +1,6 @@
---
{
- "title": "Cluster Upgrade",
+ "title": "Upgrading Cluster",
"language": "en"
}
---
@@ -24,270 +24,222 @@ specific language governing permissions and limitations
under the License.
-->
+Doris provides the capability for rolling upgrades, enabling step-by-step
upgrades of FE and BE nodes, minimizing downtime, and ensuring the system
remains operational during the upgrade process.
-## Overview
+## Version Compatibility
-To upgrade, please use the steps recommended in this chapter to upgrade the
cluster. The Doris cluster upgrade can be upgraded using the **rolling
upgrade** method, which does not require all cluster nodes to be shut down for
upgrade, which greatly reduces the impact on upper-layer applications.
+Doris versioning consists of three components: the first digit represents a
major milestone version, the second digit indicates a feature version, and the
third digit corresponds to a bug fix. New features are not introduced in bug
fix versions. For example, in Doris version 2.1.3, "2" indicates the second
milestone version, "1" represents the feature version under this milestone, and
"3" denotes the third bug fix for this feature version.
-## Doris Release Notes
+During version upgrades, the following rules apply:
-When upgrading Doris, please follow the principle of **not skipping two minor
versions** and upgrade sequentially.
+- **Three-digit versions:** Versions with the same first two digits can be
directly upgraded across three-digit versions. For example, version 2.1.3 can
be directly upgraded to version 2.1.7.
-For example, if you are upgrading from version 0.15.x to 2.0.x, it is
recommended to first upgrade to the latest version of 1.1, then upgrade to the
latest version of 1.2, and finally upgrade to the latest version of 2.0.
+- **Two-digit and one-digit versions:** Cross-version upgrades for two-digit
versions are not recommended due to compatibility concerns. It is advised to
upgrade sequentially through each two-digit version. For example, upgrading
from version 3.0 to 3.3 should follow the sequence 3.0 -> 3.1 -> 3.2 -> 3.3.
+The detailed version information can be found in the [versioning
rules](../../../../docusaurus-plugin-content-docs-community/current/release-versioning).
+## Upgrade Precautions
-## Upgrade Steps
-
-### Upgrade Instructions
-
-1. During the upgrade process, since Doris's RoutineLoad,
Flink-Doris-Connector, and Spark-Doris-Connector have implemented a retry
mechanism in the code, in a multi-BE node cluster, the rolling upgrade will not
cause the task to fail .
-
-2. The StreamLoad task requires you to implement a retry mechanism in your own
code, otherwise the task will fail.
-
-3. The cluster copy repair and balance function must be closed before and
opened after the completion of a single upgrade task, regardless of whether all
your cluster nodes have been upgraded.
-
-### Overview of the Upgrade Process
-
-1. Metadata backup
-
-2. Turn off the cluster copy repair and balance function
+When performing an upgrade, pay attention to the following:
-3. Compatibility testing
+- **Behavioral changes between versions:** Review the Release Notes before
upgrading to identify compatibility issues.
-4. Upgrade BE
+- **Add retry mechanisms for tasks in the cluster:** Nodes are restarted
sequentially during upgrades. Ensure that retry mechanisms are in place for
query tasks and Stream Load import jobs to avoid task failures. Routine Load
jobs using flink-doris-connector or spark-doris-connector already include retry
mechanisms in their code and do not require additional logic.
-5. Upgrade FE
+- **Disable replica repair and balance functions:** Disable these functions
during the upgrade process. Regardless of the upgrade outcome, re-enable these
functions after the upgrade is complete.
-6. Turn on the cluster replica repair and balance function
+## Metadata Compatibility Testing
-### Upgrade Pre-work
-
-Please perform the upgrade in sequence according to the upgrade process
-
-**01 Metadata Backup (Important)**
-
-**Make a full backup of the `doris-meta` directory of the FE-Master node!**
-
-**02 Turn off the cluster replica repair and balance function**
-
-There will be node restart during the upgrade process, so unnecessary cluster
balancing and replica repair logic may be triggered, first close it with the
following command:
-
-```sql
-admin set frontend config("disable_balance" = "true");
-admin set frontend config("disable_colocate_balance" = "true");
-admin set frontend config("disable_tablet_scheduler" = "true");
-```
+:::caution Note
-**03 Compatibility Testing**
+In a production environment, it is recommended to configure at least three FE
nodes for high availability. If there is only one FE node, metadata
compatibility testing must be performed before upgrading. Metadata
compatibility is critical as incompatibility may cause upgrade failures and
data loss. It is recommended to conduct metadata compatibility tests before
each upgrade, keeping in mind the following:
-:::caution Warning
+- Perform metadata compatibility testing on a development machine or BE node
whenever possible to avoid using FE nodes.
-**Metadata compatibility is very important, if the upgrade fails due to
incompatible metadata, it may lead to data loss! It is recommended to perform a
metadata compatibility test before each upgrade!**
+- If testing must be conducted on an FE node, use a non-Master node and stop
the original FE process.
:::
-1. FE Compatibility Test
-
-:::tip Important
-1. It is recommended to do FE compatibility test on your local development
machine or BE node.
-
-2. It is not recommended to test on Follower or Observer nodes to avoid link
exceptions
-
-3. If it must be on the Follower or Observer node, the started FE process
needs to be stopped
-:::
+Before upgrading, conduct metadata compatibility testing to prevent failures
caused by metadata incompatibility.
+1. **Backup metadata information:**
-a. Use the new version alone to deploy a test FE process
+ Before starting the upgrade, back up the metadata of the Master FE node.
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
- ```
+ Use the `show frontends` command and refer to the `IsMaster` column to
identify the Master FE node. FE metadata can be hot-backed up without stopping
the FE node. By default, FE metadata is stored in the `fe/doris-meta`
directory. This can be confirmed via the `meta_dir` parameter in the `fe.conf`
configuration file.
-b. Modify the FE configuration file fe.conf for testing
+2. **Modify the `fe.conf` configuration file of the test FE node:**
- ```shell
- vi ${DORIS_NEW_HOME}/conf/fe.conf
- ```
+ ```bash
+ vi ${DORIS_NEW_HOME}/conf/fe.conf
+ ```
- Modify the following port information, set **all ports** to **different
from online**
+ Modify the following port information, ensuring all ports are different
from those in the production environment, and update the `clusterID` parameter:
+ ```
+ ...
+ ## modify port
+ http_port = 18030
+ rpc_port = 19020
+ query_port = 19030
+ arrow_flight_sql_port = 19040
+ edit_log_port = 19010
+
+ ## modify clusterIP
+ clusterId=<a_new_clusterIP, such as 123456>
+ ...
+ ```
- ```shell
- ...
- http_port = 18030
- rpc_port = 19020
- query_port = 19030
- arrow_flight_sql_port = 19040
- edit_log_port = 19010
- ...
- ```
+3. Copy the backed-up Master FE metadata to the new compatibility testing
environment.
- Save and exit
+ ```bash
+ cp ${DORIS_OLD_HOME}/fe/doris-meta/* ${DORIS_NEW_HOME}/fe/doris-meta
+ ```
-c. Modify fe.conf
+4. Edit the `VERSION` file in the copied metadata directory to update the
`cluster_id` to a new cluster IP, for example, change it to `123456` as shown
in the example:
- - Add ClusterID configuration in fe.conf
+ ```bash
+ vi ${DORIS_NEW_HOME}/fe/doris-meta/image/VERSION
+ clusterId=123456
+ ```
- ```shell
- echo "cluster_id=123456" >> ${DORIS_NEW_HOME}/conf/fe.conf
- ```
+5. Start the FE process in the testing environment.
+
+ ```bash
+ sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon --metadata_failure_recovery
+ ```
- - Add metadata failover configuration in fe.conf (**>=2.0.2 + version does
not require this operation**)
- ```shell
+ For versions earlier than 2.0.2, add the `metadata_failure_recovery`
parameter to the `fe.conf` file before starting the FE process:
+ ```bash
echo "metadata_failure_recovery=true" >> ${DORIS_NEW_HOME}/conf/fe.conf
+ sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
```
-d. Copy the metadata directory doris-meta of the online environment Master FE
to the test environment
-
- ```shell
- cp ${DORIS_OLD_HOME}/fe/doris-meta/* ${DORIS_NEW_HOME}/fe/doris-meta
- ```
-
-e. Change the cluster_id in the VERSION file copied to the test environment to
123456 (that is, the same as in step 3)
-
- ```shell
- vi ${DORIS_NEW_HOME}/fe/doris-meta/image/VERSION
- clusterId=123456
- ```
-
-f. In the test environment, run the startup FE
-
-- If the version is greater than or equal to 2.0.2, run the following command
-
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon --metadata_failure_recovery
- ```
-
-- If the version is less than 2.0.2, run the following command
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
+6. Verify that the FE process has started successfully by connecting to the
current FE using the MySQL command. For example, use the query port `19030` as
mentioned above:
+
+ ```bash
+ mysql -uroot -P19030 -h127.0.0.1
```
-g. Observe whether the startup is successful through the FE log fe.log
-
- ```shell
- tail -f ${DORIS_NEW_HOME}/log/fe.log
- ```
-
-h. If the startup is successful, it means that there is no problem with the
compatibility, stop the FE process of the test environment, and prepare for the
upgrade
-
- ```
- sh ${DORIS_NEW_HOME}/bin/stop_fe.sh
- ```
+## Upgrade Steps
-2. BE Compatibility Test
+The detailed process for the upgrade is as follows:
-You can use the grayscale upgrade scheme to upgrade a single BE first. If
there is no exception or error, the compatibility is considered normal, and
subsequent upgrade actions can be performed
+1. Disable replica repair and balance functions
-### Upgrade process
+2. Upgrade BE nodes
-:::tip Tip
+3. Upgrade FE nodes
-Upgrade BE first, then FE
+4. Enable replica repair and balance functions
-Generally speaking, Doris only needs to upgrade `/bin` and `/lib` under the FE
directory and `/bin` and `/lib` under the BE directory
+During the upgrade process, the principle of upgrading BE nodes first,
followed by upgrading FE nodes, should be followed. When upgrading FE, upgrade
the Observer FE and Follower FE nodes first, and then upgrade the Master FE
node.
-In versions 2.0.2 and later, the `custom_lib/` directory is added to the FE
and BE deployment paths (if not, it can be created manually). The `custom_lib/`
directory is used to store some user-defined third-party jar packages, such as
`hadoop-lzo-*.jar`, `orai18n.jar`, etc.
+:::caution Note
-This directory does not need to be replaced during upgrade.
+In general, only the `/bin` and `/lib` directories under the FE directory and
the `/bin` and `/lib` directories under the BE directory need to be upgraded.
-However, when a major version is upgraded, new features may be added or old
functions refactored. These modifications may require **replace/add** more
directories during the upgrade to ensure the availability of all new features.
Please Carefully pay attention to the Release-Note of this version when
upgrading the version to avoid upgrade failures
+For versions 2.0.2 and later, a `custom_lib/` directory has been added under
the FE and BE deployment paths (if it doesn't exist, it can be manually
created). The `custom_lib/` directory is used to store some user-defined
third-party jar files, such as `hadoop-lzo-*.jar`, `orai18n.jar`, etc. This
directory does not need to be replaced during the upgrade.
:::
-#### Upgrade BE
+### Step 1: Disable Replica Repair and Balance Functions
-:::tip Tip
-
-In order to ensure the safety of your data, please use 3 copies to store your
data to avoid data loss caused by misoperation or failure of the upgrade
-:::
+During the upgrade process, nodes will be restarted, which may trigger
unnecessary cluster balancing and replica repair logic. Disable these functions
first using the following command:
-1. Under the premise of multiple copies, select a BE node to stop running and
perform grayscale upgrade
+```sql
+admin set frontend config("disable_balance" = "true");
+admin set frontend config("disable_colocate_balance" = "true");
+admin set frontend config("disable_tablet_scheduler" = "true");
+```
- ```shell
- sh ${DORIS_OLD_HOME}/be/bin/stop_be.sh
- ```
-2. Rename the `/bin`, `/lib` directories under the BE directory
+### Step 2: Upgrade BE Nodes
- ```shell
- mv ${DORIS_OLD_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin_back
- mv ${DORIS_OLD_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib_back
- ```
+:::info Note:
-3. Copy the new version of `/bin`, `/lib` directory to the original BE
directory
+To ensure the safety of your data, please use 3 replicas to store your data to
avoid data loss caused by upgrade mistakes or failures.
+:::
+1. In a multi-replica cluster, you can choose to stop the process on one BE
node and perform a gradual upgrade:
- ```shell
- cp -r ${DORIS_NEW_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin
- cp -r ${DORIS_NEW_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib
- ```
+ ```bash
+ sh ${DORIS_OLD_HOME}/be/bin/stop_be.sh
+ ```
-4. Start the BE node
+2. Rename the `/bin` and `/lib` directories in the BE directory:
- ```shell
- sh ${DORIS_OLD_HOME}/be/bin/start_be.sh --daemon
- ```
+ ```bash
+ mv ${DORIS_OLD_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin_back
+ mv ${DORIS_OLD_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib_back
+ ```
-5. Link the cluster to view the node information
+3. Copy the new version's `/bin` and `/lib` directories to the original BE
directory:
- ```mysql
- show backends\G
- ```
+ ```bash
+ cp -r ${DORIS_NEW_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin
+ cp -r ${DORIS_NEW_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib
+ ```
- If the `alive` status of the BE node is `true`, and the value of `Version`
is the new version, the node upgrade is successful
+4. Start the BE node:
-6. Complete the upgrade of other BE nodes in sequence
+ ```bash
+ sh ${DORIS_OLD_HOME}/be/bin/start_be.sh --daemon
+ ```
-**05 Upgrade FE**
+5. Connect to the cluster and check the node information:
-:::tip Tip
+ ```sql
+ show backends\G
+ ```
-Upgrade the non-Master nodes first, and then upgrade the Master nodes.
+ If the BE node's `alive` status is `true` and the `Version` value is the
new version, the node has been successfully upgraded.
-:::
+### Step 3: Upgrade FE Nodes
-1. In the case of multiple FE nodes, select a non-Master node to upgrade and
stop running first
+1. In a multi-FE node setup, select a non-Master node for the upgrade and stop
it first:
- ```shell
- sh ${DORIS_OLD_HOME}/fe/bin/stop_fe.sh
- ```
+ ```bash
+ sh ${DORIS_OLD_HOME}/fe/bin/stop_fe.sh
+ ```
-2. Rename the `/bin`, `/lib` directories under the FE directory
+2. Rename the `/bin`, `/lib`, and `/mysql_ssl_default_certificate` directories
in the FE directory:
- ```shell
- mv ${DORIS_OLD_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin_back
- mv ${DORIS_OLD_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib_back
- ```
+ ```bash
+ mv ${DORIS_OLD_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin_back
+ mv ${DORIS_OLD_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib_back
+ mv ${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate_back
+ ```
-3. Copy the new version of `/bin`, `/lib` directory to the original FE
directory
+3. Copy the new version's `/bin`, `/lib`, and `/mysql_ssl_default_certificate`
directories to the original FE directory:
- ```shell
- cp -r ${DORIS_NEW_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin
- cp -r ${DORIS_NEW_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib
- ```
+ ```bash
+ cp -r ${DORIS_NEW_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin
+ cp -r ${DORIS_NEW_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib
+ cp -r ${DORIS_NEW_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
+ ```
-4. Start the FE node
+4. Start the FE node:
- ```shell
- sh ${DORIS_OLD_HOME}/fe/bin/start_fe.sh --daemon
- ```
+ ```sql
+ sh ${DORIS_OLD_HOME}/fe/bin/start_fe.sh --daemon
+ ```
-5. Link the cluster to view the node information
+5. Connect to the cluster and check the node information:
- ```mysql
- show frontends\G
- ```
+ ```sql
+ show frontends\G
+ ```
- If the FE node `alive` status is `true`, and the value of `Version` is the
new version, the node is upgraded successfully
+ If the FE node's `alive` status is `true` and the `Version` value is the
new version, the node has been successfully upgraded.
-6. Complete the upgrade of other FE nodes in turn, **finally complete the
upgrade of the Master node**
+6. Complete the upgrade of the other FE nodes in sequence, and finally upgrade
the Master node.
-**06 Turn on the cluster replica repair and balance function**
+### Step 4: Enable Replica Repair and Balance Functions
-After the upgrade is complete and all BE nodes become `Alive`, enable the
cluster copy repair and balance function:
+After the upgrade is complete and all BE nodes' status is `Alive`, enable the
cluster's replica repair and balance functions:
```sql
admin set frontend config("disable_balance" = "false");
admin set frontend config("disable_colocate_balance" = "false");
admin set frontend config("disable_tablet_scheduler" = "false");
```
+
diff --git
a/versioned_docs/version-3.0/admin-manual/cluster-management/upgrade.md
b/versioned_docs/version-3.0/admin-manual/cluster-management/upgrade.md
index a4b61221587..f659542445c 100644
--- a/versioned_docs/version-3.0/admin-manual/cluster-management/upgrade.md
+++ b/versioned_docs/version-3.0/admin-manual/cluster-management/upgrade.md
@@ -24,270 +24,222 @@ specific language governing permissions and limitations
under the License.
-->
+Doris provides the capability for rolling upgrades, enabling step-by-step
upgrades of FE and BE nodes, minimizing downtime, and ensuring the system
remains operational during the upgrade process.
-## Overview
+## Version Compatibility
-To upgrade, please use the steps recommended in this chapter to upgrade the
cluster. The Doris cluster upgrade can be upgraded using the **rolling
upgrade** method, which does not require all cluster nodes to be shut down for
upgrade, which greatly reduces the impact on upper-layer applications.
+Doris versioning consists of three components: the first digit represents a
major milestone version, the second digit indicates a feature version, and the
third digit corresponds to a bug fix. New features are not introduced in bug
fix versions. For example, in Doris version 2.1.3, "2" indicates the second
milestone version, "1" represents the feature version under this milestone, and
"3" denotes the third bug fix for this feature version.
-## Doris Release Notes
+During version upgrades, the following rules apply:
-When upgrading Doris, please follow the principle of **not skipping two minor
versions** and upgrade sequentially.
+- **Three-digit versions:** Versions with the same first two digits can be
directly upgraded across three-digit versions. For example, version 2.1.3 can
be directly upgraded to version 2.1.7.
-For example, if you are upgrading from version 0.15.x to 2.0.x, it is
recommended to first upgrade to the latest version of 1.1, then upgrade to the
latest version of 1.2, and finally upgrade to the latest version of 2.0.
+- **Two-digit and one-digit versions:** Cross-version upgrades for two-digit
versions are not recommended due to compatibility concerns. It is advised to
upgrade sequentially through each two-digit version. For example, upgrading
from version 3.0 to 3.3 should follow the sequence 3.0 -> 3.1 -> 3.2 -> 3.3.
+The detailed version information can be found in the [versioning
rules](../../../../docusaurus-plugin-content-docs-community/current/release-versioning).
+## Upgrade Precautions
-## Upgrade Steps
-
-### Upgrade Instructions
-
-1. During the upgrade process, since Doris's RoutineLoad,
Flink-Doris-Connector, and Spark-Doris-Connector have implemented a retry
mechanism in the code, in a multi-BE node cluster, the rolling upgrade will not
cause the task to fail .
-
-2. The StreamLoad task requires you to implement a retry mechanism in your own
code, otherwise the task will fail.
-
-3. The cluster copy repair and balance function must be closed before and
opened after the completion of a single upgrade task, regardless of whether all
your cluster nodes have been upgraded.
-
-### Overview of the Upgrade Process
-
-1. Metadata backup
-
-2. Turn off the cluster copy repair and balance function
+When performing an upgrade, pay attention to the following:
-3. Compatibility testing
+- **Behavioral changes between versions:** Review the Release Notes before
upgrading to identify compatibility issues.
-4. Upgrade BE
+- **Add retry mechanisms for tasks in the cluster:** Nodes are restarted
sequentially during upgrades. Ensure that retry mechanisms are in place for
query tasks and Stream Load import jobs to avoid task failures. Routine Load
jobs using flink-doris-connector or spark-doris-connector already include retry
mechanisms in their code and do not require additional logic.
-5. Upgrade FE
+- **Disable replica repair and balance functions:** Disable these functions
during the upgrade process. Regardless of the upgrade outcome, re-enable these
functions after the upgrade is complete.
-6. Turn on the cluster replica repair and balance function
+## Metadata Compatibility Testing
-### Upgrade Pre-work
-
-Please perform the upgrade in sequence according to the upgrade process
-
-**01 Metadata Backup (Important)**
-
-**Make a full backup of the `doris-meta` directory of the FE-Master node!**
-
-**02 Turn off the cluster replica repair and balance function**
-
-There will be node restart during the upgrade process, so unnecessary cluster
balancing and replica repair logic may be triggered, first close it with the
following command:
-
-```sql
-admin set frontend config("disable_balance" = "true");
-admin set frontend config("disable_colocate_balance" = "true");
-admin set frontend config("disable_tablet_scheduler" = "true");
-```
+:::caution Note
-**03 Compatibility Testing**
+In a production environment, it is recommended to configure at least three FE
nodes for high availability. If there is only one FE node, metadata
compatibility testing must be performed before upgrading. Metadata
compatibility is critical as incompatibility may cause upgrade failures and
data loss. It is recommended to conduct metadata compatibility tests before
each upgrade, keeping in mind the following:
-:::caution Warning
+- Perform metadata compatibility testing on a development machine or BE node
whenever possible to avoid using FE nodes.
-**Metadata compatibility is very important, if the upgrade fails due to
incompatible metadata, it may lead to data loss! It is recommended to perform a
metadata compatibility test before each upgrade!**
+- If testing must be conducted on an FE node, use a non-Master node and stop
the original FE process.
:::
-1. FE Compatibility Test
-
-:::tip Important
-1. It is recommended to do FE compatibility test on your local development
machine or BE node.
-
-2. It is not recommended to test on Follower or Observer nodes to avoid link
exceptions
-
-3. If it must be on the Follower or Observer node, the started FE process
needs to be stopped
-:::
+Before upgrading, conduct metadata compatibility testing to prevent failures
caused by metadata incompatibility.
+1. **Backup metadata information:**
-a. Use the new version alone to deploy a test FE process
+ Before starting the upgrade, back up the metadata of the Master FE node.
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
- ```
+ Use the `show frontends` command and refer to the `IsMaster` column to
identify the Master FE node. FE metadata can be hot-backed up without stopping
the FE node. By default, FE metadata is stored in the `fe/doris-meta`
directory. This can be confirmed via the `meta_dir` parameter in the `fe.conf`
configuration file.
-b. Modify the FE configuration file fe.conf for testing
+2. **Modify the `fe.conf` configuration file of the test FE node:**
- ```shell
- vi ${DORIS_NEW_HOME}/conf/fe.conf
- ```
+ ```bash
+ vi ${DORIS_NEW_HOME}/conf/fe.conf
+ ```
- Modify the following port information, set **all ports** to **different
from online**
+ Modify the following port information, ensuring all ports are different
from those in the production environment, and update the `clusterID` parameter:
+ ```
+ ...
+ ## modify port
+ http_port = 18030
+ rpc_port = 19020
+ query_port = 19030
+ arrow_flight_sql_port = 19040
+ edit_log_port = 19010
+
+ ## modify clusterIP
+ clusterId=<a_new_clusterIP, such as 123456>
+ ...
+ ```
- ```shell
- ...
- http_port = 18030
- rpc_port = 19020
- query_port = 19030
- arrow_flight_sql_port = 19040
- edit_log_port = 19010
- ...
- ```
+3. Copy the backed-up Master FE metadata to the new compatibility testing
environment.
- Save and exit
+ ```bash
+ cp ${DORIS_OLD_HOME}/fe/doris-meta/* ${DORIS_NEW_HOME}/fe/doris-meta
+ ```
-c. Modify fe.conf
+4. Edit the `VERSION` file in the copied metadata directory to update the
`cluster_id` to a new cluster IP, for example, change it to `123456` as shown
in the example:
- - Add ClusterID configuration in fe.conf
+ ```bash
+ vi ${DORIS_NEW_HOME}/fe/doris-meta/image/VERSION
+ clusterId=123456
+ ```
- ```shell
- echo "cluster_id=123456" >> ${DORIS_NEW_HOME}/conf/fe.conf
- ```
+5. Start the FE process in the testing environment.
+
+ ```bash
+ sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon --metadata_failure_recovery
+ ```
- - Add metadata failover configuration in fe.conf (**>=2.0.2 + version does
not require this operation**)
- ```shell
+ For versions earlier than 2.0.2, add the `metadata_failure_recovery`
parameter to the `fe.conf` file before starting the FE process:
+ ```bash
echo "metadata_failure_recovery=true" >> ${DORIS_NEW_HOME}/conf/fe.conf
+ sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
```
-d. Copy the metadata directory doris-meta of the online environment Master FE
to the test environment
-
- ```shell
- cp ${DORIS_OLD_HOME}/fe/doris-meta/* ${DORIS_NEW_HOME}/fe/doris-meta
- ```
-
-e. Change the cluster_id in the VERSION file copied to the test environment to
123456 (that is, the same as in step 3)
-
- ```shell
- vi ${DORIS_NEW_HOME}/fe/doris-meta/image/VERSION
- clusterId=123456
- ```
-
-f. In the test environment, run the startup FE
-
-- If the version is greater than or equal to 2.0.2, run the following command
-
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon --metadata_failure_recovery
- ```
-
-- If the version is less than 2.0.2, run the following command
- ```shell
- sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
+6. Verify that the FE process has started successfully by connecting to the
current FE using the MySQL command. For example, use the query port `19030` as
mentioned above:
+
+ ```bash
+ mysql -uroot -P19030 -h127.0.0.1
```
-g. Observe whether the startup is successful through the FE log fe.log
-
- ```shell
- tail -f ${DORIS_NEW_HOME}/log/fe.log
- ```
-
-h. If the startup is successful, it means that there is no problem with the
compatibility, stop the FE process of the test environment, and prepare for the
upgrade
-
- ```
- sh ${DORIS_NEW_HOME}/bin/stop_fe.sh
- ```
+## Upgrade Steps
-2. BE Compatibility Test
+The detailed process for the upgrade is as follows:
-You can use the grayscale upgrade scheme to upgrade a single BE first. If
there is no exception or error, the compatibility is considered normal, and
subsequent upgrade actions can be performed
+1. Disable replica repair and balance functions
-### Upgrade process
+2. Upgrade BE nodes
-:::tip Tip
+3. Upgrade FE nodes
-Upgrade BE first, then FE
+4. Enable replica repair and balance functions
-Generally speaking, Doris only needs to upgrade `/bin` and `/lib` under the FE
directory and `/bin` and `/lib` under the BE directory
+During the upgrade process, the principle of upgrading BE nodes first,
followed by upgrading FE nodes, should be followed. When upgrading FE, upgrade
the Observer FE and Follower FE nodes first, and then upgrade the Master FE
node.
-In versions 2.0.2 and later, the `custom_lib/` directory is added to the FE
and BE deployment paths (if not, it can be created manually). The `custom_lib/`
directory is used to store some user-defined third-party jar packages, such as
`hadoop-lzo-*.jar`, `orai18n.jar`, etc.
+:::caution Note
-This directory does not need to be replaced during upgrade.
+In general, only the `/bin` and `/lib` directories under the FE directory and
the `/bin` and `/lib` directories under the BE directory need to be upgraded.
-However, when a major version is upgraded, new features may be added or old
functions refactored. These modifications may require **replace/add** more
directories during the upgrade to ensure the availability of all new features.
Please Carefully pay attention to the Release-Note of this version when
upgrading the version to avoid upgrade failures
+For versions 2.0.2 and later, a `custom_lib/` directory has been added under
the FE and BE deployment paths (if it doesn't exist, it can be manually
created). The `custom_lib/` directory is used to store some user-defined
third-party jar files, such as `hadoop-lzo-*.jar`, `orai18n.jar`, etc. This
directory does not need to be replaced during the upgrade.
:::
-#### Upgrade BE
+### Step 1: Disable Replica Repair and Balance Functions
-:::tip Tip
-
-In order to ensure the safety of your data, please use 3 copies to store your
data to avoid data loss caused by misoperation or failure of the upgrade
-:::
+During the upgrade process, nodes will be restarted, which may trigger
unnecessary cluster balancing and replica repair logic. Disable these functions
first using the following command:
-1. Under the premise of multiple copies, select a BE node to stop running and
perform grayscale upgrade
+```sql
+admin set frontend config("disable_balance" = "true");
+admin set frontend config("disable_colocate_balance" = "true");
+admin set frontend config("disable_tablet_scheduler" = "true");
+```
- ```shell
- sh ${DORIS_OLD_HOME}/be/bin/stop_be.sh
- ```
-2. Rename the `/bin`, `/lib` directories under the BE directory
+### Step 2: Upgrade BE Nodes
- ```shell
- mv ${DORIS_OLD_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin_back
- mv ${DORIS_OLD_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib_back
- ```
+:::info Note:
-3. Copy the new version of `/bin`, `/lib` directory to the original BE
directory
+To ensure the safety of your data, please use 3 replicas to store your data to
avoid data loss caused by upgrade mistakes or failures.
+:::
+1. In a multi-replica cluster, you can choose to stop the process on one BE
node and perform a gradual upgrade:
- ```shell
- cp -r ${DORIS_NEW_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin
- cp -r ${DORIS_NEW_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib
- ```
+ ```bash
+ sh ${DORIS_OLD_HOME}/be/bin/stop_be.sh
+ ```
-4. Start the BE node
+2. Rename the `/bin` and `/lib` directories in the BE directory:
- ```shell
- sh ${DORIS_OLD_HOME}/be/bin/start_be.sh --daemon
- ```
+ ```bash
+ mv ${DORIS_OLD_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin_back
+ mv ${DORIS_OLD_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib_back
+ ```
-5. Link the cluster to view the node information
+3. Copy the new version's `/bin` and `/lib` directories to the original BE
directory:
- ```mysql
- show backends\G
- ```
+ ```bash
+ cp -r ${DORIS_NEW_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin
+ cp -r ${DORIS_NEW_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib
+ ```
- If the `alive` status of the BE node is `true`, and the value of `Version`
is the new version, the node upgrade is successful
+4. Start the BE node:
-6. Complete the upgrade of other BE nodes in sequence
+ ```bash
+ sh ${DORIS_OLD_HOME}/be/bin/start_be.sh --daemon
+ ```
-**05 Upgrade FE**
+5. Connect to the cluster and check the node information:
-:::tip Tip
+ ```sql
+ show backends\G
+ ```
-Upgrade the non-Master nodes first, and then upgrade the Master nodes.
+ If the BE node's `alive` status is `true` and the `Version` value is the
new version, the node has been successfully upgraded.
-:::
+### Step 3: Upgrade FE Nodes
-1. In the case of multiple FE nodes, select a non-Master node to upgrade and
stop running first
+1. In a multi-FE node setup, select a non-Master node for the upgrade and stop
it first:
- ```shell
- sh ${DORIS_OLD_HOME}/fe/bin/stop_fe.sh
- ```
+ ```bash
+ sh ${DORIS_OLD_HOME}/fe/bin/stop_fe.sh
+ ```
-2. Rename the `/bin`, `/lib` directories under the FE directory
+2. Rename the `/bin`, `/lib`, and `/mysql_ssl_default_certificate` directories
in the FE directory:
- ```shell
- mv ${DORIS_OLD_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin_back
- mv ${DORIS_OLD_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib_back
- ```
+ ```bash
+ mv ${DORIS_OLD_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin_back
+ mv ${DORIS_OLD_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib_back
+ mv ${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate_back
+ ```
-3. Copy the new version of `/bin`, `/lib` directory to the original FE
directory
+3. Copy the new version's `/bin`, `/lib`, and `/mysql_ssl_default_certificate`
directories to the original FE directory:
- ```shell
- cp -r ${DORIS_NEW_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin
- cp -r ${DORIS_NEW_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib
- ```
+ ```bash
+ cp -r ${DORIS_NEW_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin
+ cp -r ${DORIS_NEW_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib
+ cp -r ${DORIS_NEW_HOME}/fe/mysql_ssl_default_certificate
${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
+ ```
-4. Start the FE node
+4. Start the FE node:
- ```shell
- sh ${DORIS_OLD_HOME}/fe/bin/start_fe.sh --daemon
- ```
+ ```sql
+ sh ${DORIS_OLD_HOME}/fe/bin/start_fe.sh --daemon
+ ```
-5. Link the cluster to view the node information
+5. Connect to the cluster and check the node information:
- ```mysql
- show frontends\G
- ```
+ ```sql
+ show frontends\G
+ ```
- If the FE node `alive` status is `true`, and the value of `Version` is the
new version, the node is upgraded successfully
+ If the FE node's `alive` status is `true` and the `Version` value is the
new version, the node has been successfully upgraded.
-6. Complete the upgrade of other FE nodes in turn, **finally complete the
upgrade of the Master node**
+6. Complete the upgrade of the other FE nodes in sequence, and finally upgrade
the Master node.
-**06 Turn on the cluster replica repair and balance function**
+### Step 4: Enable Replica Repair and Balance Functions
-After the upgrade is complete and all BE nodes become `Alive`, enable the
cluster copy repair and balance function:
+After the upgrade is complete and all BE nodes' status is `Alive`, enable the
cluster's replica repair and balance functions:
```sql
admin set frontend config("disable_balance" = "false");
admin set frontend config("disable_colocate_balance" = "false");
admin set frontend config("disable_tablet_scheduler" = "false");
```
+
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@doris.apache.org
For additional commands, e-mail: commits-h...@doris.apache.org
