pingcap · hfxsd · Jul 23, 2024 · Jul 23, 2024 · Jul 23, 2024 · Jul 23, 2024
diff --git a/TOC.md b/TOC.md
@@ -158,6 +158,9 @@
     - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/upgrade-a-tidb-cluster)
     - [平滑升级 TiDB](/smooth-upgrade-tidb.md)
     - [TiFlash 升级帮助](/tiflash-upgrade-guide.md)
+  - 回退 TiDB 版本
+    - [使用 TiUP](/roll-back-tidb-using-tiup.md)
+    - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/roll-back-a-tidb-cluster)
   - 扩缩容
     - [使用 TiUP（推荐）](/scale-tidb-using-tiup.md)
     - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/scale-a-tidb-cluster)

diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md
@@ -0,0 +1,126 @@
+---
+title: 使用 TiUP 回退 TiDB 的版本
+summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回退到某个版本。
+---
+
+# 使用 TiUP 回退 TiDB 的版本
+
+本文档介绍如何使用 TiUP 将 TiDB 回退到之前的某个版本。
+
+## 支持回退的版本
+
+本文档适用于以下回退路径：
+
+- 从 v7.5.Y 版本回退至 v7.5.X，其中 Y > 0, X ≥ 0, 且 Y > X。
+
+> **警告：**
+>
+> 其他补丁版本的回退未经验证，如直接回退，可能会产生非预期的问题。
+
+## 注意事项
+
+回退版本时，请注意以下事项：
+
+- 对于无法进行连接重试的客户端，版本回退会导致连接到被关闭的 TiDB 节点的数据库的连接失效，造成部分业务请求失败。对于这类业务，推荐在客户端添加重试功能，或者在低峰期进行 TiDB 的滚动更新操作。
+- 在回退 TiDB 集群的过程中，请勿执行 DDL 语句，否则可能会出现行为未定义的问题。
+- 回退的集群内的各组件应该使用相同版本。 
+- Changefeed 默认配置值在回退过程中不会被更改，已经修改的值，在回退过程中也不会被修改。
+
+## 准备工作
+
+开始回退前需要[更新 TiUP 和 TiUP 集群组件版本](/tiup/tiup-component-management.md#升级组件)。同时还需要完成下面的准备工作。
+
+### 兼容性变更
+
+- TiDB 目前仅支持有限的补丁版本回退。请参见[支持回退的版本](#支持回退的版本)。
+- 仅支持 PD、TiDB、TiKV、TiFlash、TiCDC、BR、PITR 组件的补丁版本回退。
+- 查看对应版本的 [Release Notes](/releases/release-notes.md) 中的兼容性变更。如果有任何变更影响到回退，请采取相应的措施。例如，从 TiDB v7.5.2 回退至 v7.5.1 时，需查阅以下各版本的兼容性变更：
+
+    - [TiDB v7.5.1 Release Notes](/releases/release-7.5.1.md#兼容性变更) 中的兼容性变更
+    - [TiDB v7.5.2 Release Notes](/releases/release-7.5.2.md#兼容性变更) 中的兼容性变更
+
+### 检查当前集群的 DDL
+
+集群中有 DDL 语句正在被执行时，请勿进行版本回退操作。被执行的 DDL 语句通常为 [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) 和列类型变更等耗时较久的 DDL 语句。
+
+在回退前，为避免回退过程中出现未定义行为或其他故障，建议执行下列操作：
+
+1. 使用 [`ADMIN SHOW DDL`](/sql-statements/sql-statement-admin-show-ddl.md) 命令查看集群中是否有正在进行的 DDL Job。
+
+2. 如需回退，请等待 DDL 执行完成，或使用 [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) 命令取消该 DDL Job。
+
+### 检查当前集群的健康状况
+
+为避免回退过程中出现未定义行为或其他故障，建议在回退前对使用 `check` 子命令检查集群的 Region 健康状态。
+
+```shell
+tiup cluster check <cluster-name> --cluster
+```
+
+执行结束后，会输出 `region status` 检查结果。
+
+- 如果结果为 `All regions are healthy`，说明当前集群中所有 Region 均为健康状态，可以继续执行回退。
+- 如果结果为 `Regions are not fully healthy: m miss-peer, n pending-peer`，并提示 `Please fix unhealthy regions before other operations.`，说明当前集群中有 Region 处于异常状态。此时应先解决异常状态问题，并再次检查，直到结果为 `All regions are healthy` 后再继续回退。
+
+### 修改配置项 `server-version`
+
+配置项 [`server-version`](/tidb-configuration-file.md#server-version) 的值会被 TiDB 节点用于验证当前 TiDB 的版本。因此在回退 TiDB 版本前，需要将 `server-version` 的值设置为空或当前 TiDB 真实的版本值，避免出现非预期行为。
+
+### 修改配置项 `performance.force-init-stats`
+
+配置项 [`performance.force-init-stats`](/tidb-configuration-file.md#force-init-stats-从-v657-和-v710-版本开始引入) 设置为 `true` 会延长 TiDB 的启动时间，这可能会造成启动超时，回退失败。
+
+为避免这种情况，建议为 TiUP 设置更长的等待超时。
+
+设置 TiUP 的等待超时的步骤如下：
+
+1. 查看配置项 `performance.force-init-stats` 的值。通常情况下，`20` 分钟超时等待能满足绝大部分场景的需求。如果需要更准确的预估，可以在 TiDB 日志中搜索 `init stats info time` 关键字，获取上次启动的统计信息加载时间作为参考。
+
+2. 使用命令行选项 [`--wait-timeout`](/tiup/tiup-component-dm.md#--wait-timeoutuint默认-120) 设置 TiUP 超时等待时间。如下命令可将超时等待设置为 `1200` 秒（即 20 分钟）:
+
+    ```shell
+    tiup update cluster --wait-timeout 1200 [other options]
+    ```
+
+### 使用选项 `--transfer-timeout` 修改最长等待时间
+
+如果希望回退过程保持性能稳定，则需要保证 TiKV 上的所有 Leader 驱逐完成后再停止该 TiKV 实例，可以使用选项 [`--transfer-timeout`](/tiup/tiup-component-cluster-reload.md#--transfer-timeoutuint默认-600) 将最长等待时间设置为更大的值，如 `--transfer-timeout 3600`，单位为秒。
+
+## 执行回退操作
+
+回退补丁版本仅支持不停机回退，回退过程中集群仍然可以对外提供服务。
+
+回退时，TiDB 会对各节点逐个迁移 leader 后再回退和重启。对于大规模集群需要较长时间才能完成整个回退操作，因此请提前预留足够的时间。
+
+以 v7.5.1 回退到 v7.5.0 版本为例，执行下列命令：
+
+```shell
+tiup ctl:v7.5.0 pd config set cluster-version "v7.5.0" -u \"pd-1-peer:2379\"
+tiup cluster patch {cluster_name} {/tmp/cdc-v7.5.0-linux-amd64.tar.gz} -R cdc -y
+tiup cluster patch {cluster_name} {/tmp/tidb-v7.5.0-linux-amd64.tar.gz} -R tidb -y
+tiup cluster patch {cluster_name} {/tmp/tikv-v7.5.0-linux-amd64.tar.gz} -R tikv -y
+tiup cluster patch {cluster_name} {/tmp/pd-v7.5.0-linux-amd64.tar.gz} -R pd -y
+tiup cluster patch {cluster_name} {/tmp/tiflash-v7.5.0-linux-amd64.tar.gz} -R tiflash -y
+```
+
+> **注意：**
+>
+> - 必须按上面命令行的顺序执行回退操作。
+> - 滚动回退会逐个回退所有的组件。回退 TiKV 期间，会逐个将 TiKV 上的所有 Leader 切走再停止该 TiKV 实例。默认超时时间为 5 分钟（300 秒），超时后会直接停止该实例。
+> - 使用 [`--force`](/tiup//tiup-component-cluster-upgrade.md#--force) 参数可以在不驱逐 Leader 的前提下快速回退集群至指定版本，但是该方式会忽略所有回退中的错误，在回退失败后得不到有效提示，请谨慎使用。
+
+## 验证回退结果
+
+执行 `display` 命令来查看最新的集群版本 TiDB 版本：
+
+```shell
+tiup cluster display <cluster-name>
+```
-执行 `display` 命令来查看最新的集群版本 TiDB 版本：
-
-```shell
-tiup cluster display <cluster-name>
-```
+登录 TiDB，查看最新的集群版本 TiDB 版本：
+
+```shell
+SELECT VERSION();
-执行 `display` 命令来查看最新的集群版本 TiDB 版本：
-
-```shell
-tiup cluster display <cluster-name>
-```
+登录 TiDB，查看最新的集群版本 TiDB 版本：
+
+```shell
+SELECT VERSION();
+
+输出结果如下，版本成功回退到 v7.5.0：
+
+```shell
+Cluster type:       tidb
+Cluster name:       <cluster-name>
+Cluster version:    v7.5.0
-Cluster type:       tidb
-Cluster name:       <cluster-name>
-Cluster version:    v7.5.0
+--------------------+
+| version()          |
+--------------------+
+| 5.7.25-TiDB-v7.5.0 |
+--------------------+
+1 row in set (0.00 sec)
-Cluster type:       tidb
-Cluster name:       <cluster-name>
-Cluster version:    v7.5.0
+--------------------+
+| version()          |
+--------------------+
+| 5.7.25-TiDB-v7.5.0 |
+--------------------+
+1 row in set (0.00 sec)
+```