使用 TiUP 降级 TiDB 集群

本文档适用于使用 tiup cluster downgrade 支持的降级路径。具体支持的版本范围以 TiUP 内置的降级规则为准。

i

警告：

1. tiup cluster downgrade 不是通用回退机制，仅支持 TiUP 内置规则允许的降级路径；如果目标版本未命中规则，命令会直接失败。
2. 当前仅支持标准集群降级，不支持 Fusion 类型集群。
3. 目标版本必须低于当前版本，且必须与当前版本位于同一 minor 发布线。例如，从 v8.5.4 降级到 v8.5.3 可能允许，而从 v8.5.4 降级到 v8.4.0 不支持。
4. 在降级 TiDB 集群的过程中，请勿执行 DDL 语句，否则可能会出现行为未定义的问题。
5. 集群中有 DDL 语句正在被执行时（通常为 ADD INDEX 和列类型变更等耗时较久的 DDL 语句），请勿进行降级操作。在降级前，建议使用 ADMIN SHOW DDL 命令查看集群中是否有正在进行的 DDL Job。如需降级，请等待 DDL 执行完成或使用 ADMIN CANCEL DDL 命令取消该 DDL Job 后再进行降级。
6. 目标安装包的 Edition 必须与当前集群的 Edition 一致，不支持在 Community、Enterprise、Pingkai 等不同 Edition 间交叉降级。
7. 当前平凯数据库客户均通过离线包部署。请使用离线包中的平凯发行版 TiUP；开源 TiUP 暂不支持该功能。
8. 在使用 TiUP 降级 TiDB 集群之前，建议先在测试环境验证降级路径、业务兼容性以及恢复方案。

i

注意

• 如果集群中 TiDB 实例配置了混合版本，tiup cluster downgrade 会拒绝执行。请先将 TiDB 实例收敛到同一版本。
• 降级过程中会滚动重启相关组件，并刷新监控组件配置。
• 建议在降级前先完成一次有效备份，并确认集群中没有正在进行的 Backup 或 Restore 任务。

1. 降级兼容性说明

• 当前仅支持标准集群的版本降级，不支持 Fusion 集群。
• 当前仅支持同一 minor 发布线内向低版本降级，不支持跨 major 或 minor 发布线回退。
• 只有命中 TiUP 内置降级规则的版本路径才允许执行降级。即使目标版本位于同一 minor 发布线，如果没有对应规则，仍然无法降级。
• TiUP 会校验当前集群 Edition 与目标安装包 Edition 是否一致；如果不一致，降级会失败。
• 降级过程中会按照组件更新顺序逐步替换二进制并重启实例；同时会刷新监控相关配置，并重启 Node Exporter 和 Blackbox Exporter。

1.1 当前支持范围

• 当前仅支持使用平凯发行版 TiUP 管理的标准集群。
• tiup cluster downgrade 从平凯数据库 v7.1.9-0.2 开始支持。
• 开源 TiUP 暂不支持该功能。
• 具体允许路径以实际所用 TiUP 内置规则为准。

1.2 内置降级路径

下表汇总当前代码库中的 TiUP 内置降级路径，仅作为查阅参考。是否允许降级，最终以实际所用 tiup cluster 版本内置的规则为准。

Community Edition

Enterprise Edition

Pingkai Edition

2. 降级前准备

本部分介绍实际开始降级前需要进行的更新 TiUP 和 TiUP Cluster 组件版本等准备工作。

2.1 查阅兼容性变更

查阅当前运行版本、目标版本以及中间版本的 release notes 中的兼容性变更。如果有任何变更影响到了你的降级，请采取相应的措施。

2.2 确认 TiUP 支持版本

当前平凯数据库客户均通过离线包部署。tiup cluster downgrade 从平凯数据库 v7.1.9-0.2 开始支持，请使用对应版本离线包中的平凯发行版 TiUP。开源 TiUP 暂不支持该功能。

2.3 编辑 TiUP Cluster 拓扑配置文件

i

注意

以下情况可跳过此步骤：

• 原集群没有修改过配置参数，或通过 tiup cluster 修改过参数但不需要调整。
• 降级后对未修改过的配置项希望使用目标版本默认参数。

1. 进入拓扑文件的 vi 编辑模式：

   tiup cluster edit-config <cluster-name>

2. 参考 topology 配置模板的格式，将希望修改的参数填到拓扑文件的 server_configs 下面。

修改完成后 :wq 保存并退出编辑模式，输入 Y 确认变更。

2.4 检查当前集群的 DDL 和 Backup 情况

为避免降级过程中出现未定义行为或其他故障，建议检查以下指标后再进行降级操作。

• 集群 DDL 情况：

  建议使用 ADMIN SHOW DDL 语句查看集群中是否存在正在进行的 DDL job。如果存在，请等待 DDL job 执行完成或使用 ADMIN CANCEL DDL 语句取消该 DDL job 后再进行降级。

• 集群 Backup 情况：建议使用 SHOW [BACKUPS|RESTORES] 命令查看集群中是否有正在进行的 Backup 或者 Restore 任务。如需降级，请等待 Backup 或 Restore 执行完成后，得到一个有效的备份后再执行降级。

2.5 检查当前集群的健康状况

为避免降级过程中出现未定义行为或其他故障，建议在降级前对集群当前的 region 健康状态进行检查，此操作可通过 check 子命令完成。

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" 后再继续降级。

3. 降级 TiDB 集群

本部分介绍如何滚动降级 TiDB 集群以及如何进行降级后的验证。

3.1 将集群降级到指定版本

当前 tiup cluster downgrade 仅支持滚动降级，不支持通过 --offline 执行停机降级。

滚动降级

tiup cluster downgrade <cluster-name> <version>

以降级到 v8.5.3 版本为例：

tiup cluster downgrade <cluster-name> v8.5.3

i

注意

• 滚动降级会逐个降级所有需要处理的组件。降级 PD、TiKV 和 TiCDC 期间，TiUP 会先尝试迁移 Leader 或 Drain capture，再重启目标实例。
• 使用 --force 参数可以在不等待相关迁移完成的前提下快速继续降级，但是该方式会跳过部分保护性等待，请谨慎使用。
• 如果希望保持性能稳定，则需要保证相关 Leader 迁移完成后再停止目标实例，可以指定 --transfer-timeout 为一个更大的值，如 --transfer-timeout 3600，单位为秒。
• 执行前，TiUP 会校验集群类型、版本方向、minor 发布线、Edition 一致性以及内置降级路径；如果任一检查失败，命令会直接退出。

调整 Leader 迁移等待时间

可以指定 --transfer-timeout，给 Leader 迁移预留更长等待时间。命令如下，其中 <version> 为降级的目标版本，例如 v8.5.3：

tiup cluster downgrade <cluster-name> <version> --transfer-timeout 3600

3.2 降级后验证

执行 display 命令来查看最新的集群版本 TiDB Version：

tiup cluster display <cluster-name>

Cluster type:       tidb
Cluster name:       <cluster-name>
Cluster version:    v8.5.3

4. 降级 FAQ

本部分介绍使用 TiUP 降级 TiDB 集群遇到的常见问题。

4.1 降级时报错中断，处理完报错后，如何继续降级

重新执行 tiup cluster downgrade 命令进行降级，降级操作会重启之前已经降级完成的节点。如果不希望重启已经降级过的节点，可以使用 replay 子命令来重试操作，具体方法如下：

1. 使用 tiup cluster audit 命令查看操作记录：

   tiup cluster audit

   在其中找到失败的降级操作记录，并记下该操作记录的 ID，下一步中将使用 <audit-id> 表示操作记录 ID 的值。

2. 使用 tiup cluster replay <audit-id> 命令重试对应操作：

   tiup cluster replay <audit-id>

4.2 降级前提示 no built-in downgrade rule matched，如何处理

这表示 TiUP 内置规则中不存在从当前版本到目标版本的允许路径。常见原因包括：

• 目标版本不在当前 minor 发布线内
• 当前版本与目标版本之间没有可用的内置降级规则
• 当前集群 Edition 与目标安装包 Edition 不匹配

此时不建议强行回退版本。应改为以下处理方式之一：

• 选择一个规则允许的目标版本重新执行降级
• 在测试环境验证其他可行路径
• 通过备份恢复、重新部署等方式完成回退

4.3 降级过程中 evict leader 或 transfer leader 等待时间过长，如何跳过该步骤快速降级

可以指定 --force，降级时会跳过部分保护性等待，直接重启并降级版本，对线上运行的集群性能影响较大。命令如下，其中 <version> 为降级的目标版本，例如 v8.5.3：

tiup cluster downgrade <cluster-name> <version> --force

4.4 降级完成后，如何更新 pd-ctl 等周边工具版本

可通过 TiUP 安装对应版本的 ctl 组件来更新相关工具版本：

tiup install ctl:v8.5.3

4.5 降级前提示当前集群为混合版本，如何处理

当 TiDB 实例配置了不同版本时，TiUP 无法判断一致的降级起点，因此会拒绝执行。

此时应先将 TiDB 实例版本收敛到同一版本，再重新执行降级命令。