--- title: "开始升级 - OceanBase 数据库 V4.1.0 | OceanBase 文档中心" description: 开始升级 本文主要介绍使用升级脚本升级 OceanBase 数据库的操作步骤。 前提条件 OBServer 节点中安装 Python 2.7 的环境，并且已安装以下模块（Modules）： datetime sys os mysql.connector logging getopt time 操作步骤 注意 在下面步… image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original --- 切换语言 - 中文站 - 简体中文 - International - English - 日本站 - 日本語 文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.1.0 # 开始升级 更新时间：2025-10-13 15:22:02 [编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.1.0/zh-CN/600.manage/100.cluster-management/300.common-cluster-operations/1500.upgrade-guide/200.use-the-command-line-to-upgrade-the-database/200.start-upgrade.md) 本文主要介绍使用升级脚本升级 OceanBase 数据库的操作步骤。 ## 前提条件 OBServer 节点中安装 Python 2.7 的环境，并且已安装以下模块（Modules）： - `datetime` - `sys` - `os` - `mysql.connector` - `logging` - `getopt` - `time` ## 操作步骤 #### 注意 在下面步骤执行升级脚本时，指定的 `-u` 参数必须是 `sys` 租户有读写及 `SUPER` 权限的用户。 ### 步骤一：备份集群配置项 升级流程开始前需要备份下列配置项旧值，用于执行升级流程后还原： - `server_permanent_offline_time` - `enable_rebalance` - `enable_rereplication` 获取集群级别配置项的语句如下： ```shell obclient [(none)]> SELECT SVR_IP,ZONE,NAME,VALUE FROM OCEANBASE.GV$OB_PARAMETERS WHERE NAME IN ("server_permanent_offline_time", "enable_rebalance", "enable_rereplication"); +------------+-------+-------------------------------+-------+ | SVR_IP | ZONE | NAME | VALUE | +------------+-------+-------------------------------+-------+ | 10.10.10.2 | zone1 | enable_rebalance | True | | 10.10.10.2 | zone1 | enable_rereplication | True | | 10.10.10.2 | zone1 | server_permanent_offline_time | 3600s | | 10.10.10.1 | zone2 | enable_rebalance | True | | 10.10.10.1 | zone2 | enable_rereplication | True | | 10.10.10.1 | zone2 | server_permanent_offline_time | 3600s | | 10.10.10.3 | zone3 | enable_rebalance | True | | 10.10.10.3 | zone3 | enable_rereplication | True | | 10.10.10.3 | zone3 | server_permanent_offline_time | 3600s | +------------+-------+-------------------------------+-------+ 9 rows in set ``` ### 步骤二：上传并安装目标 RPM 包 1. 使用 `scp` 命令将目标版本的 RPM 包解压到 OBServer 节点中。 其中 `$rpm_name` 表示 RPM 包的名称，`observer_ip` 表示 OBServer 节点的 IP，`$rpm_dir` 表示存放 RPM 包的目录。 ```shell [root@xxx /]# scp $rpm_name admin@observer_ip:/$rpm_dir ``` #### 说明 请联系技术支持人员获取目标版本的 OceanBase 安装包。 2. 安装目标版本 RPM。 其中 `$rpm_name` 表示 RPM 包的名称 ```shell [root@xxx $rpm_dir]# rpm -Uvh $rpm_name ``` 示例如下： ```shell [root@xxx $rpm_dir]# rpm -Uvh oceanbase-4.1.0.0-100001022023032415.el7.x86_64.rpm Preparing... ################################# [100%] Updating / installing... 1:oceanbase-4.1.0.0-100001022023032################################# [ 50%] Cleaning up / removing... 2:oceanbase-4.0.0.0-102000042023022################################# [100%] ``` #### 说明 升级相关脚本和 `oceanbase_upgrade_dep.yml` 文件存放 `/home/admin/oceanbase/etc` 目录下。目录 `/home/admin/oceanbase/etc` 为 OceanBase 数据库的默认安装目录。 3. 重复步骤 1~2，直至所有 OBServer 节点中安装目标版本 RPM 包。 ### 步骤三：查看各个版本升级依赖关系 通过 `/home/admin/oceanbase/etc` 下的 `oceanbase_upgrade_dep.yml` 文件查看 OceanBase 各个版本升级依赖关系。 示例如下： ```shell [root@xxx /]# cd /home/admin/oceanbase/etc [root@xxx /home/admin/oceanbase/etc]# cat oceanbase_upgrade_dep.yml # 描述oceanbase各个版本升级依赖关系 # 参考文档 release/ptw5y7 # 对于每一个正式发布的ob版本，在下面的yaml文档中添加一项，包括如下属性： # * version: 待升级的版本，或者升级过程中经过的版本；一般用A.B.C的版本号，如果是A.B.C-D的形式，表示build号必须大于等于D # * can_be_upgraded_to: 表示该版本经过OB QA兼容性测试，可以*直接*升级到的ob版本号，是一个列表可以包括多个版本 # * deprecated: 缺省为False。如果为True，表示这个版本已经废除。可以作 # 为升级的起点，可以作为升级过度版本，但是不能作为升级目标版本。 # * require_from_binary: 缺省为False。如果为True，表示升级过程中如果作为中间版本，除了运行upgrade脚本，还需要把observer也升级到该版本 # # OCP的OB升级模块会读取本文件，给定升级的起始版本和目标版本，自动在满 # 足上述约束的情况下寻找一个升级的最短路径。基本算法是： # 基于如下描述构建一个图，每个版本一个结点，can_be_upgraded_to关系定义 # 一条边，寻找起始版本和升级目标两个版本之间的最短路径。除了起始点，其 # 他节点不能是deprecated。如果有A.B.C和A.B.C-D两种节点匹配，优先选择后 # 者。 # - version: 4.0.0.0 can_be_upgraded_to: - 4.1.0.0 require_from_binary: value: True when_come_from: [4.0.0.0] - version: 4.1.0.0 require_from_binary: value: True when_come_from: [4.0.0.0, 4.1.0.0] ``` ### 步骤四：执行脚本 upgrade_checker.py 指定系统租户直连 OBServer 节点的登录信息，执行 `upgrade_checker.py` 脚本进行升级前置检查，脚本执行成功表示可以继续升级。 示例如下： ```shell [root@xxx /]# cd /home/admin/oceanbase/etc [root@xxx /home/admin/oceanbase/etc]# python upgrade_checker.py -h 127.0.0.1 -P 2881 -u xxxx@sys -p****** ``` ## 步骤五：执行脚本 upgrade_pre.py 指定系统租户直连 OBServer 节点的登录信息，执行 `upgrade_pre.py` 脚本，脚本执行成功表示可以继续升级。 示例如下： ```shell [root@xxx /home/admin/oceanbase/etc]# python upgrade_pre.py -h 127.0.0.1 -P 2881 -u xxxx@sys -p****** ``` `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 ****** ``` ### 步骤六：集群升级 按 Zone 升级, 每个 Zone 都要按照下面的步骤执行一遍，以 `zone1` 为例。 1. 执行集群级别健康检查。 ```shell [root@xxx /home/admin/oceanbase/etc]# python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u xxxx@sys -p****** ``` 2. 停止 Zone（`STOP ZONE`）。 使用 `root` 用户登录到集群的 `sys` 租户，使用以下命令停止 Zone，其中 `zone_name` 为 Zone 的名称。 ```sql ALTER SYSTEM STOP ZONE 'zone_name'; ``` 示例如下： ```shell obclient [(none)]> ALTER SYSTEM STOP ZONE 'zone1'; Query OK, 0 rows affected ``` `STOP ZONE` 命令会等主都切走才返回成功。 3. Zone 内机器停进程，替换新版本 binary 重启。 停止 observer 进程，然后重新启动 observer 进程。 示例如下： 1. 停止 observer 进程。 ```shell [root@xxx /home/admin/oceanbase/etc]# kill -9 `pidof observer` ``` 2. 重新启动 observer 进程。 ```shell [root@xxx /home/admin/oceanbase/etc]# su - admin -bash-4.2$ cd /home/admin/oceanbase && /home/admin/oceanbase/bin/observer ``` #### 说明 再次启动 observer 进程时不需要指定启动参数，因为之前的启动参数已经写到参数文件里了。 4. 执行 Zone 级别健康检查。 ```shell [root@xxx /home/admin/oceanbase/etc]# python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u xxxx@sys -p****** -z 'zone1' ``` Zone 级别健康检查基本上复用了集群级别健康检查逻辑，主要是校验指定 Zone 的所有机器相关状态。 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'; Query OK, 0 rows affected ``` 6. 重复步骤 1~5，直至所有 Zone 升级完成。 ### 步骤七：执行脚本 upgrade_post.py 指定系统租户直连 OBServer 节点的登录信息，执行 `upgrade_post.py` 脚本完成主要的升级操作及相关检查。 示例如下： ```shell [root@xxx /home/admin/oceanbase/etc]# python upgrade_post.py -h 127.0.0.1 -P 2881 -u xxxx@sys -p****** ``` #### 注意 在执行升级脚本 `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. 重新执行升级脚本。 该脚本会完成主要的升级操作及相关检查，该脚本会完成以下升级动作。 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 ****** ``` ### 步骤六：还原集群配置项 基于 **步骤一** 备份的配置项旧值，还原相关配置项。 ```sql ALTER SYSTEM SET server_permanent_offline_time = xxx; ALTER SYSTEM SET enable_rebalance = xxx; ALTER SYSTEM SET enable_rereplication = xxx; ``` 示例如下： ```shell obclient [(none)]> ALTER SYSTEM SET server_permanent_offline_time = '3600s'; Query OK, 0 rows affected obclient [(none)]> ALTER SYSTEM SET enable_rebalance = 'True'; Query OK, 0 rows affected obclient [(none)]> ALTER SYSTEM SET enable_rereplication = 'True'; Query OK, 0 rows affected ``` ## 后续操作 ### 升级后检查 验证是否升级完成，请参见 [升级后检查](https://www.oceanbase.com/docs/common-oceanbase-database-cn-10000000001702436)。 ### 重新配置 cgroup 如果在升级前 OceanBase 集群配置了 cgroup，那么在 OceanBase 集群升级后，需要重新配置 cgroup。详细信息，参见 [配置 cgroup](https://www.oceanbase.com/docs/common-oceanbase-database-cn-10000000001699658)。 ## 相关文档 - [连接方式概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-10000000001698766) - [启动或停止 Zone](https://www.oceanbase.com/docs/common-oceanbase-database-cn-10000000001699675) - [ALTER SYSTEM PARAMETER](https://www.oceanbase.com/docs/common-oceanbase-database-cn-10000000001701410) 上一篇 下一篇 ![有帮助](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) 咨询热线