--- title: "升级 OceanBase 集群 - OceanBase 数据库 V4.5.0 | OceanBase 文档中心" description: 升级 OceanBase 集群 本文将介绍如何使用升级脚本升级 OceanBase 集群。 注意 OceanBase 数据库暂不支持 V4.2.x 系列或更低版本升级到 V4.3.x 版本。 前提条件 您已在所有的 OBServer 节点中安装 Python 2 的环境，并且安装适配 Python 2 的 mysql… --- 切换语言 - 中文站 - 简体中文 - International - English - 日本站 - 日本語 文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.5.0 # 升级 OceanBase 集群 更新时间：2026-03-08 10:51:58 [编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.5.0/zh-CN/600.manage/100.cluster-management/300.common-cluster-operations/1500.oceanbase-version-upgrade/200.upgrade-oceanbase-enterprise-edition/300.start-upgrade.md) 本文将介绍如何使用升级脚本升级 OceanBase 集群。 #### 注意 OceanBase 数据库暂不支持 V4.2.x 系列或更低版本升级到 V4.3.x 版本。 ## 前提条件 您已在所有的 OBServer 节点中安装 Python 2 的环境，并且安装适配 Python 2 的 `mysql.connector` 模块。 #### 注意 如果 OceanBase 集群关联了仲裁服务，那么在进行 OceanBase 集群版本升级时，需要确保先升级仲裁服务版本，然后再升级 OceanBase 集群版本。仲裁服务版本升级的详细信息，请参见 [升级仲裁服务](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004479265)。 可以使用系统租户查询视图 [oceanbase.DBA_OB_ARBITRATION_SERVICE](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004477522) 检查本 OceanBase 集群是否关联仲裁服务。更多升级注意信息，请参见 [升级概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004479264)。 ## 操作步骤 #### 注意 在下面步骤执行升级脚本时，指定的 `-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] # 4.3.0.x - version: 4.3.0.0 can_be_upgraded_to: - 4.3.0.1 - version: 4.3.0.1 can_be_upgraded_to: - 4.3.1.0 ``` 通过分析示例文件，可以得到以下升级序列： 1. V4.0.0.0 > V4.1.0.0 > V4.1.0.1(barrier) > V4.2.0.0 2. V4.1.0.0-100000982023031415 > V4.1.0.0 > V4.1.0.1(barrier) > V4.2.0.0 3. V4.1.0.0 > V4.1.0.1 > V4.2.0.0 4. V4.3.0.0 > V4.3.0.1 > V4.3.1.0 #### 注意 如果升级序列中存在 barrier 版本，那么您还需获取升级路径中所有 barrier 版本的 OceanBase RPM 包。 ### 步骤二：确认升级流程 #### 注意 如果 OceanBase 集群当前版本和目标版本之间存在 barrier 版本，那么 OceanBase 集群应该先升级到 barrier 版本，然后再从 barrier 版本升级到目标版本。 通过 **步骤一** 示例的升级序列，可以得到如下信息： 1. 如果您当前使用的是 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 版本。 2. 如果您当前使用的是 OceanBase 集群 V4.1.0.0 或者 V4.1.0.1 版本，那么您在升级时 OceanBase 集群可以直接升级到 V4.2.0.0 版本。 3. 如果您当前使用的是 OceanBase 集群 V4.3.0.0 或者 V4.3.0.1 版本，那么您在升级时 OceanBase 集群可以直接升级到 V4.3.1.0 版本。 **示例如下：** 以下将以三副本的 OceanBase 集群为例介绍升级流程。 - 升级路径中有 barrier 版本。如果当前 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，集群升级就完成了。 - 升级路径中没有 barrier 版本。如果当前 OceanBase 集群版本是 V4.3.0.0 版本，升级流程如下： 您只需要先将 Zone1 从 V4.3.0.0 版本升级到 V4.3.1.0 版本，再将 Zone2 从 V4.3.0.0 版本升级到 V4.3.1.0 版本，然后将 Zone3 从 V4.3.0.0 版本升级到 V4.3.1.0 版本，等到所有 Zone 均升级到 V4.3.1.0，集群升级就完成了。 ### 步骤三：备份集群配置项 升级流程开始前需要备份下列配置项旧值，用于执行升级流程后还原： - [server_permanent_offline_time](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004479145) - [enable_rebalance](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004478930) - [enable_rereplication](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004479037) 在 `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`）。 #### 注意 单机或单副本 OceanBase 数据库升级无需停止 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-1000000004479266)。 ### 重新配置 cgroup 如果在升级前 OceanBase 集群配置了 cgroup，那么在 OceanBase 集群升级后，需要重新配置 cgroup。详细信息，参见 [配置 cgroup](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004479257)。 ## 相关文档 - 有关连接 OceanBase 数据库的详细信息，请参见 [连接方式概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004476086) - 有关启动 Zone 的详细信息，请参见 [启动 Zone](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004476057)。 - 有关修改配置型的详细信息，请参见 [ALTER SYSTEM PARAMETER](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004480924)。 上一篇 下一篇 ![有帮助](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) 咨询热线