--- title: "升级 OceanBase 集群 - OceanBase 数据库 V4.2.5 | OceanBase 文档中心" description: 升级 OceanBase 集群 本文将介绍如何使用升级脚本升级 OceanBase 集群。 前提条件 您已在所有的 OBServer 节点中安装 Python 2 的环境，并且安装适配 Python 2 的 mysql.connector 模块。 注意 如果 OceanBase 集群关联了仲裁服务，那么在进行 Oce… --- 切换语言 - 中文站 - 简体中文 - International - English - 日本站 - 日本語 文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.2.5 LTS # 升级 OceanBase 集群 更新时间：2026-04-27 11:12:06 [编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.2.5/zh-CN/450.oceanbase-version-upgrade/200.upgrade-oceanbase-enterprise-edition/200.start-upgrade.md) 本文将介绍如何使用升级脚本升级 OceanBase 集群。 ## 前提条件 您已在所有的 OBServer 节点中安装 Python 2 的环境，并且安装适配 Python 2 的 `mysql.connector` 模块。 #### 注意 如果 OceanBase 集群关联了仲裁服务，那么在进行 OceanBase 集群版本升级时，需要确保先升级仲裁服务版本，然后再升级 OceanBase 集群版本。仲裁服务版本升级的详细信息，请参见 [升级仲裁服务](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001502710)。 可以使用系统租户查询视图 [oceanbase.DBA_OB_ARBITRATION_SERVICE](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001501287) 检查本 OceanBase 集群是否关联仲裁服务。更多升级注意信息，请参见 [升级概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001502708)。 ## 操作步骤 #### 注意 在下面步骤执行升级脚本时，指定的 `-u` 参数必须是 `sys` 租户有读写及 `SUPER` 权限的用户。 1. 分析 `oceanbase_upgrade_dep.yml` 文件。 2. 确认升级流程。 3. 备份集群配置项。 4. 上传并安装目标 RPM 包。 5. 执行脚本 `upgrade_checker.py`。 6. 执行脚本 `upgrade_pre.py`。 7. 集群升级。 8. 执行脚本 `upgrade_post.py`。 9. 还原集群配置项。 ### 步骤一：分析 oceanbase_upgrade_dep.yml 文件 解压目标版本的 OceanBase RPM 包后，可以获取 `oceanbase_upgrade_dep.yml` 文件，该文件记录了 OceanBase 集群的版本升级拓扑图。步骤如下： 1. 获取目的版本 OceanBase RPM 安装包。 请在 OceanBase 官方网站左上角，单击 **资源** > [下载中心](https://www.oceanbase.com/softwarecenter-enterprise) 获取对应版本的 RPM 包。如果未找到对应版本的安装包，请联系技术支持获取目的版本的 RPM 包。 2. 解压 OceanBase RPM 包。 您可以使用以下命令解压 OceanBase RPM 包至当前目录： ```shell [xxx@xxx $rpm_dir]# sudo rpm2cpio $rpm_name | cpio -div ``` 其中 `$rpm_name` 表示 RPM 包的名称。 #### 说明 解压 RPM 包完成后，会在存放 RPM 包的目录下生成 `home` 和 `use` 两个目录。升级相关脚本和 `oceanbase_upgrade_dep.yml` 文件存放 `home/admin/oceanbase/etc` 目录下。 3. 分析 `oceanbase_upgrade_dep.yml` 文件。 **`oceanbase_upgrade_dep.yml` 文件中相关属性含义：** - `version`：当前 OceanBase 数据库版本号，以下简称：当前版本。 - `can_be_upgraded_to`：当前 OceanBase 数据库版本可以升级到的目标版本号，以下简称：目标版本。 - `deprecated`：当前版本是否可以作为升级的目标版本。若为 `true`，表示不能作为升级的目标版本。例如：示例中的 `4.1.0.0-100000982023031415` 版本就不能作为目标版本。 - `require_from_binary`：升级序列包含当前版本时是否需要先升级到当前版本，即当前版本是否是升级序列中的 barrier 版本。 - `value`：当值为 `true` 时，和 `when_come_from` 属性联合使用。 - `when_come_from`：是一个列表，当 `when_come_from` 未定义时，表示任何版本升级到目标版本时，都要先升级到当前 barrier 版本；当 `when_come_from` 已定义，表示列表中的版本号升级到目标版本时，需要先升级到当前 barrier 版本。例如：示例中的 `4.0.0.0` 和 `4.1.0.0-100000982023031415` 版本的 OceanBase 集群在升级到 V4.2.0.0 版本时，都要先升级到 V4.1.0.1(barrier) 版本。 **示例如下：** 假设 `oceanbase_upgrade_dep.yml` 文件中 OceanBase 集群各个版本升级依赖关系如下： ```yml - version: 4.0.0.0 can_be_upgraded_to: - 4.1.0.0 - version: 4.1.0.0-100000982023031415 can_be_upgraded_to: - 4.1.0.0 deprecated: True - version: 4.1.0.0 can_be_upgraded_to: - 4.1.0.1 - version: 4.1.0.1 can_be_upgraded_to: - 4.2.0.0 require_from_binary: value: True when_come_from: [4.0.0.0, 4.1.0.0-100000982023031415] ``` 通过分析示例文件，可以得到以下升级序列： - V4.0.0.0 > V4.1.0.0 > V4.1.0.1(barrier) > V4.2.0.0 - V4.1.0.0-100000982023031415 > V4.1.0.0 > V4.1.0.1(barrier) > V4.2.0.0 - V4.1.0.0 > V4.1.0.1 > V4.2.0.0 - V4.1.0.1 > V4.2.0.0 #### 注意 如果升级序列中存在 barrier 版本，那么您还需获取升级路径中所有 barrier 版本的 OceanBase RPM 包。 ### 步骤二：确认升级流程 #### 注意 如果 OceanBase 集群当前版本和目标版本之间存在 barrier 版本，那么 OceanBase 集群应该先升级到 barrier 版本，然后再从 barrier 版本升级到目标版本。 通过 **步骤一** 示例的升级序列，可以得到如下信息： - 如果您当前使用的是 OceanBase 集群 V4.0.0.0 或者 V4.1.0.0-100000982023031415 版本，那么您在升级时 OceanBase 集群应该先升级到 V4.1.0.1（barrier）版本，然后再从 V4.1.0.1（barrier）版本升级到 V4.2.0.0 版本。 - 如果您当前使用的是 OceanBase 集群 V4.1.0.0 或者 V4.1.0.1 版本，那么您在升级时 OceanBase 集群可以直接升级到 V4.2.0.0 版本。 **示例如下：** 以下将以三副本的 OceanBase 集群为例介绍升级流程。 - 当前 OceanBase 集群版本是 V4.0.0.0 版本，升级流程如下： 1. 您需要先将 Zone1 从 V4.0.0.0 版本升级到 V4.1.0.1(barrier) 版本，再将 Zone2 从 V4.0.0.0 版本升级到 V4.1.0.1(barrier) 版本，然后将 Zone3 从 V4.0.0.0 版本升级到 V4.1.0.1(barrier) 版本；此时，整个集群已经从 V4.0.0.0 版本升级到了 V4.1.0.1（barrier）版本。 2. 您需再次按照 Zone 顺序依次将 Zone1、Zone2、Zone3 从 V4.1.0.1（barrier）版本升级到 V4.2.0.0，等到所有 Zone 均升级到 V4.2.0.0，集群升级就完成了。 - 当前 OceanBase 集群版本是 V4.1.0.0 版本，升级流程如下： 您只需要先将 Zone1 从 V4.1.0.0 版本升级到 V4.2.0.0 版本，再将 Zone2 从 V4.1.0.0 版本升级到 V4.2.0.0 版本，然后将 Zone3 从 V4.1.0.0 版本升级到 V4.2.0.0 版本，等到所有 Zone 均升级到 V4.2.0.0，集群升级就完成了。 ### 步骤三：备份集群配置项 升级流程开始前需要备份下列配置项旧值，用于执行升级流程后还原： - [server_permanent_offline_time](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001502267) - [enable_rebalance](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001502063) - [enable_rereplication](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001502335) 在 `sys` 租户（系统租户）中执行以下 SQL 语句，获取需要备份的配置项的值： ```sql SELECT SVR_IP,ZONE,NAME,VALUE FROM OCEANBASE.GV$OB_PARAMETERS WHERE NAME IN ("server_permanent_offline_time", "enable_rebalance", "enable_rereplication"); ``` ### 步骤四：上传并安装目标 RPM 包 1. 使用 `scp` 命令将升级所用到的 OceanBase RPM 包上传到 OBServer 节点中。 ```shell scp $rpm_name admin@$observer_ip:/$rpm_dir ``` **参数解释：** - `$rpm_name`：表示 RPM 包的名称。 - `$observer_ip`：表示 OBServer 节点的 IP。 - `$rpm_dir`：表示存放 RPM 包的目录。 **示例如下：** ```shell scp oceanbase-4.2.0.0-100010022023081911.el7.x86_64.rpm admin@10.10.10.1:/home/admin/rpm ``` 2. 使用以下命令安装 OceanBase RPM 包。 #### 注意 - 如果在您的升级路径中存在 barrier 版本，请先安装相应的 barrier 版本的 RPM 包。等待集群成功升级到 barrier 版本后，再安装目标版本的 RPM 包。 - 如果升级路径中有多个 barrier 版本，按照顺序依次进行安装和升级 barrier 版本，直到集群成功升级最后的 barrier 版本再安装目标版本的 RPM 包。 ```shell rpm -Uvh $rpm_name ``` #### 说明 升级相关脚本和 `oceanbase_upgrade_dep.yml` 文件存放 `/home/admin/oceanbase/etc` 目录下。目录 `/home/admin/oceanbase/etc` 为 OceanBase 数据库的默认安装目录。 3. 重复步骤 1~2，直至所有 OBServer 节点中安装目标版本 RPM 包。 ### 步骤五：执行脚本 upgrade_checker.py 在任意一个 OBServer 节点中指定 `sys` 租户直连 OBServer 节点的登录信息，执行 `upgrade_checker.py` 脚本进行升级前置检查，脚本执行成功表示可以继续升级。命令如下： ```shell python upgrade_checker.py -h 127.0.0.1 -P 2881 -u $user_name@sys -p$password ``` **参数解释：** - `$user_name`：表示 `sys` 租户有读写及修改全局系统参数的权限的用户。 - `$password`：表示是用户密码。 **示例如下：** 1. 使用以下命令切换到 `/home/admin/oceanbase/etc` 目录。 ```shell cd /home/admin/oceanbase/etc ``` 2. 使用以下命令执行 `upgrade_checker.py` 脚本进行升级前置检查。 ```shell [root@xxx /home/admin/oceanbase/etc]# python upgrade_checker.py -h 127.0.0.1 -P 2881 -u root@sys -p****** ``` ### 步骤六：执行脚本 upgrade_pre.py 在任意一个 OBServer 节点中指定 `sys` 租户直连 OBServer 节点的登录信息，执行 `upgrade_pre.py` 脚本，脚本执行成功表示可以继续升级。命令如下： ```shell python upgrade_pre.py -h 127.0.0.1 -P 2881 -u $user_name@sys -p$password ``` **参数解释：** **`upgrade_pre.py` 脚本会执行以下命令及动作：** 1. `alter system begin upgrade`。 2. `alter system begin rolling upgrade`。 3. `special pre action`：关闭及调整配置项。 4. `health check`: 集群级别健康检查。 完整的 `upgrade_pre.py` 脚本能力如下所示： ```shell ./upgrade_pre.py [OPTIONS] -I, --help Display this help and exit. -V, --version Output version information and exit. -h, --host=name Connect to host. -P, --port=name Port number to use for connection. -u, --user=name User for login. -p, --password=name Password to use when connecting to server. If password is not given it's empty string "". -t, --timeout=name Cmd/Query execute timeout(s). -m, --module=name Modules to run. Modules should be a string combined by some of the following strings: 1. begin_upgrade 2. begin_rolling_upgrade 3. special_action 4. health_check 5. all: "all" represents that all modules should be run. They are splitted by ",". For example: -m all, or --module=begin_upgrade,begin_rolling_upgrade,special_action -l, --log-file=name Log file path. If log file path is not given it's ./upgrade_pre.log Maybe you want to run cmd like that: ./upgrade_pre.py -h 127.0.0.1 -P 2881 -u ****** -p ****** ``` **示例如下：** ``` 2. 使用以下命令执行 `upgrade_pre.py` 脚本进行升级前检查。 ```shell [root@xxx /home/admin/oceanbase/etc]# python upgrade_pre.py -h 127.0.0.1 -P 2881 -u root@sys -p****** ``` ### 步骤七：集群升级 按 Zone 升级, 每个 Zone 都要按照下面的步骤执行一遍，以 `zone1` 为例。 1. 执行以下命令进行集群级别健康检查。 ```shell python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u $user_name@sys -p$password ``` **参数解释：** **示例如下：** ``` 2. 使用以下命令执行 `upgrade_health_checker.py` 脚本进行集群级别健康检查。 ```shell [root@xxx /home/admin/oceanbase/etc]# python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u root@sys -p****** ``` 2. 停止 Zone（`STOP ZONE`）。 使用 `root` 用户登录到集群的 `sys` 租户，使用以下命令停止 Zone，其中 `$zone_name` 为 Zone 的名称。命令如下： ```sql ALTER SYSTEM STOP ZONE '$zone_name'; ``` `STOP ZONE` 命令会等主副本（Leader）都切走才返回成功。 **示例如下：** ```shell obclient [(none)]> ALTER SYSTEM STOP ZONE 'zone1'; ``` 可以使用下面 SQL 命令查看 Zone 状态。 ```sql obclient [(none)]> SELECT ZONE,STATUS FROM oceanbase.DBA_OB_ZONES; ``` 返回结果如下： ```shell +-------+----------+ | ZONE | STATUS | +-------+----------+ | zone1 | INACTIVE | | zone2 | ACTIVE | | zone3 | ACTIVE | +-------+----------+ 3 rows in set ``` 3. Zone 内机器停进程，替换新版本 binary 重启。 停止 observer 进程，然后重新启动 observer 进程。 1. 切换至 `admin` 用户。 ```shell [root@xxx /home/admin/oceanbase/etc]# su - admin ``` 2. 停止 observer 进程。 ```shell -bash-4.2$ kill -9 `pidof observer` ``` 3. 重新启动 observer 进程。 ```shell -bash-4.2$ cd /home/admin/oceanbase && /home/admin/oceanbase/bin/observer ``` #### 说明 再次启动 observer 进程时不需要指定启动参数，因为之前的启动参数已经写到参数文件里了。 4. 执行 Zone 级别健康检查。 Zone 级别健康检查基本上复用了集群级别健康检查逻辑，主要是校验指定 Zone 的所有机器相关状态。命令如下： ```shell python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u $user_name@sys -p$password -z '$zone_name' ``` **参数解释：** - `$user_name`：表示 `sys` 租户有读写及修改全局系统参数的权限的用户。 - `$password`：表示是用户密码。 - `$zone_name`：表示 Zone 的名称。 **示例如下：** ``` 2. 使用以下命令执行 `upgrade_health_checker.py` 脚本进行 Zone 级别健康检查。 ```shell [root@xxx /home/admin/oceanbase/etc]# python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u root@sys -p****** -z 'zone1' ``` 5. 启动 Zone（`start zone`）。 使用 `root` 用户登录到集群的 `sys` 租户，使用以下命令启动 Zone，其中 `$zone_name` 为 Zone 的名称。命令如下： ```sql ALTER SYSTEM START ZONE '$zone_name'; ``` **示例如下：** ```shell obclient [(none)]> ALTER SYSTEM START ZONE 'zone1'; ``` 6. 重复步骤 1~5，直至所有 Zone 升级完成。 ### 步骤八：执行脚本 upgrade_post.py 在任意一个 OBServer 节点中指定 `sys` 租户直连 OBServer 节点的登录信息，执行 `upgrade_post.py` 脚本完成主要的升级操作及相关检查。命令如下： ```shell python upgrade_post.py -h 127.0.0.1 -P 2881 -u $user_name@sys -p$password ``` #### 注意 在执行升级脚本 `upgrade_post.py` 时，若出现错误，其原因很可能是 RS 切主过。建议通过以下步骤进行排查与修复： 1. 可以执行 `SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE job_type = 'upgrade_all' ORDER BY job_id DESC LIMIT 1;` 验证升级任务状态。若 `JOB_STATUS` 显示为 `inprogress`，且 `MODIFY_TIME` 为最近时间（与当前时间间隔较短），则可以手动执行一下 `ALTER SYSTEM RUN UPGRADE JOB 'UPGRADE_ALL';` 命令解决这个问题。 2. 重新执行升级脚本。 **参数解释：** **`upgrade_post.py` 脚本会完成以下升级动作：** 1. 集群级别健康检查。 2. `alter system end rolling upgrade`。 3. 按租户执行 begin upgrade。 4. 按租户执行系统变量修正。 5. 按租户执行系统表修正。 6. 按租户执行虚拟表/视图修正。 7. 按租户执行版本相关升级动作。 8. 按租户执行内部表自检操作。 9. 按租户结束 end upgrade。 10. alter system end upgrade：结束集群升级状态。 11. upgrade post check：重新打开升级过程中禁用的部分配置项，并执行检查。 上述第 3～5、7、9 步在下列升级场景下不执行： 1. 同版本升级。 2. 跨版本升级，原版本和目标版本的数据版本一致。 完整的 `upgrade_post.py` 脚本能力如下所示： ```shell ./upgrade_post.py [OPTIONS] -I, --help Display this help and exit. -V, --version Output version information and exit. -h, --host=name Connect to host. -P, --port=name Port number to use for connection. -u, --user=name User for login. -p, --password=name Password to use when connecting to server. If password is not given it's empty string "". -t, --timeout=name Cmd/Query execute timeout(s). -m, --module=name Modules to run. Modules should be a string combined by some of the following strings: 1. health_check 2. end_rolling_upgrade 3. tenant_upgrade 4. end_upgrade 5. post_check 6. all: "all" represents that all modules should be run. They are splitted by ",". For example: -m all, or --module=health_check,begin_rolling_upgrade -l, --log-file=name Log file path. If log file path is not given it's ./upgrade_pre.log Maybe you want to run cmd like that: ./upgrade_post.py -h 127.0.0.1 -P 2881 -u *** -p ****** ``` **示例如下：** ``` 2. 使用以下命令执行 `upgrade_post.py` 脚本完成主要的升级操作及相关检查。 ```shell [root@xxx /home/admin/oceanbase/etc]# python upgrade_post.py -h 127.0.0.1 -P 2881 -u root@sys -p****** ``` ### 步骤九：还原集群配置项 基于 **步骤三** 备份的配置项旧值，使用 `root` 用户登录到集群的 `sys` 租户，使用以下命令还原相关配置项。 ```sql ALTER SYSTEM SET $parameter value= $parameter_value ``` **参数解释：** - `$parameter`：表示配置项的名称 - `$parameter_value`：表示配置项的值。 **示例如下：** - 还原 `server_permanent_offline_time` 的值。 ```shell obclient [(none)]> ALTER SYSTEM SET server_permanent_offline_time = '3600s'; ``` - 还原 `enable_rebalance` 的值。 ```shell obclient [(none)]> ALTER SYSTEM SET enable_rebalance = 'True'; ``` - 还原 `enable_rereplication` 的值。 ```shell obclient [(none)]> ALTER SYSTEM SET enable_rereplication = 'True'; ``` ## 后续操作 ### 升级后检查 验证是否升级完成，请参见 [升级后检查](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001502709)。 ### 重新配置 cgroup 如果在升级前 OceanBase 集群配置了 cgroup，那么在 OceanBase 集群升级后，需要重新配置 cgroup。详细信息，参见 [配置 cgroup](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001502717)。 ## 相关文档 - 有关连接 OceanBase 数据库的详细信息，请参见 [连接方式概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001499955) - 有关启动 Zone 的详细信息，请参见 [启动 Zone](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001499813)。 - 有关修改配置型的详细信息，请参见 [ALTER SYSTEM PARAMETER](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001504087)。 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线