*: add more contents about supported versions and upgrade methods (#1…

…5079)

smooth-upgrade-tidb.md

@@ -5,29 +5,69 @@ summary: 本文介绍支持无需手动取消 DDL 的平滑升级集群功能。
 
 # 平滑升级 TiDB
 
-> **警告：**
->
-> 平滑升级目前为实验特性。
-
 本文档介绍 TiDB 的平滑升级集群功能，支持无需手动取消 DDL 的操作。
 
-从 v7.1.0 起，当将 TiDB 升级至更高的版本时，TiDB 支持平滑升级功能，取消了升级过程中的限制，提供更平滑的升级体验。此功能默认开启，且无开关控制。
+从 v7.1.0 起，当将 TiDB 升级至更高的版本时，TiDB 支持平滑升级功能，取消了升级过程中的限制（你需要保证升级过程中无用户发起的 DDL 操作），提供更平滑的升级体验。
+
+## 版本支持情况
+
+依据是否需要开关控制，可分为两种支持方式：
+
+* 无需开关控制，默认开启此功能的方式。目前支持此方式的版本分别是 v7.1.0，v7.1.1，v7.2.0，和 v7.3.0。具体支持升级版本的情况：
+    * 从 v7.1.0 升级到 v7.1.1、v7.2.0 或 v7.3.0 版本
+    * 从 v7.1.1 升级到 v7.2.0 或 v7.3.0 版本
+    * 从 v7.2.0 升级到 v7.3.0 版本
+
+* 通过是否发送 `/upgrade/start` HTTP 请求控制此功能开关。即此功能默认关闭，可通过发送 `/upgrade/start` 请求，开启此功能。具体方式可以参考：[TiDB HTTP API 文档](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md)。具体版本情况：
+    * 从 v7.1.2 以及它之后的 v7.1 版本（即 >= v7.1.2）升级到 v7.4.0 及更高版本
+    * 从 v7.4.0 升级到更高的版本
+
+具体版本支持的升级方式，请参考下表：
+
+| 原版本 | 升级后版本 | 升级的升级方式 | 备注 |
+|------|--------|-------------|-------------|
+| < v7.1.0  | 任意版本                  | 不支持平滑升级方式 | |
+| v7.1.0    | v7.1.1、v7.2.0 或 v7.3.0  | 无需额外操作，自动支持平滑升级 | 实验特性。可能遇到 [#44760](https://github.com/pingcap/tidb/pull/44760) 问题 |
+| v7.1.1    | v7.2.0 或 v7.3.0         | 无需额外操作，自动支持平滑升级 | 实验特性 |
+| v7.2.0    | v7.3.0                   | 无需额外操作，自动支持平滑升级 | 实验特性 |
+| [v7.1.2, v7.2.0)                     | [v7.1.2, v7.2.0) | 通过发送 `/upgrade/start` HTTP 请求开启平滑升级，具体方式有两种：[TiUP 方式](#tiup-方式)；[其它方式](#其它方式) | 不开启平滑升级时，需确保升级时无 DDL 操作。 |
+| [v7.1.2, v7.2.0) 或 >= v7.4.0             | >= v7.4.0 | 通过发送 `/upgrade/start` HTTP 请求开启平滑升级，具体方式有两种：[TiUP 方式](#tiup-方式)；[其它方式](#其它方式)    | 不开启平滑升级时，需确保升级时无 DDL 操作。 |
+| v7.1.0、v7.1.1、v7.2.0、v7.3.0     | >= v7.4.0 | 不支持平滑升级方式 | |
 
 ## 功能简介
 
-TiDB 引入平滑升级功能前，对于升级过程中的 DDL 操作有如下限制(可以参考[使用 TiUP 升级 TiDB](/upgrade-tidb-using-tiup.md#使用-tiup-升级-tidb)中警告部分)：
+TiDB 引入平滑升级功能前，对于升级过程中的 DDL 操作有如下限制：
 
 - 在升级过程中执行 DDL 操作，TiDB 可能会出现未定义的行为。
 - 在 DDL 操作执行过程中升级 TiDB，TiDB 可能会出现未定义的行为。
 
-引入平滑升级后，TiDB 升级过程不再受上述限制。
+上述限制可概括为，你需要保证在升级过程中无用户发起的 DDL 操作。引入平滑升级后，TiDB 升级过程不再受此限制。
+
+更多详情，请参考[使用 TiUP 升级 TiDB](/upgrade-tidb-using-tiup.md#使用-tiup-升级-tidb) 中的警告部分。
+
+### 升级方式及步骤
 
-升级过程中，TiDB 会自动进行以下操作，无需用户干预：
+#### TiUP 方式
 
-1. 暂停用户的 DDL 操作。
-2. 执行升级过程中的系统 DDL 操作。
-3. 恢复被暂停的用户的 DDL 操作。
-4. 完成升级。
+TiUP 会在 v1.14.0 版本自适应支持此功能，即无需特殊操作，直接使用 `tiup cluster upgrade` 操作流程即可。注意目前不支持 `tiup cluster patch` 方式。
+
+#### TiDB Operator 方式
+
+目前不支持此功能，会尽早自适应支持此功能。
+
+#### 其它方式
+
+手动升级或者使用脚本升级的操作如下：
+
+1. 给集群中的任意一台 TiDB 发送 HTTP 升级开始请求：`curl -X POST http://{TiDBIP}:10080/upgrade/start`。
+   * TiDB 集群会进入 **Upgrading** 状态。
+   * 接下来将要执行的 DDL 操作都会被暂停。
+
+2. 替换 TiDB binary，并进行滚动升级。此过程和原升级过程一致。
+   * 执行升级过程中的系统 DDL 操作。
+
+3. 等集群中所有 TiDB 升级成功后，给任意一台 TiDB 发送 HTTP 升级结束请求：`curl -X POST http://{TiDBIP}:10080/upgrade/finish`。
+   * 恢复被暂停的用户的 DDL 操作。
 
 其中，恢复的 DDL job 仍会按升级前的顺序执行。
 
@@ -56,3 +96,7 @@ TiDB 引入平滑升级功能前，对于升级过程中的 DDL 操作有如下
 * BR：BR 可能会将处于 paused 状态的 DDL 拷贝到 TiDB 中，而此状态的 DDL 不能自动 resume，可能导致后续 DDL 卡住的情况。
 
 * DM 和 TiCDC：如果在升级过程中使用 DM 和 TiCDC 向 TiDB 导入 SQL，并且其中包含 DDL 操作，则该导入操作会被阻塞，并可能出现未定义错误。
+
+### 插件使用限制
+
+TiDB 安装的插件可能自带 DDL 操作。然而，在升级过程中，如果这些插件自带的 DDL 操作针对非系统表进行，可能导致升级过程出现问题。