OBShell 集群命令组 - OceanBase 数据库 V4.2.2

OBShell 集群命令组

更新时间：2026-04-10 11:58:36

编辑

本文档介绍 OBShell 的集群命令组，集群命令组可用于部署和管理 OceanBase 集群。

您可通过在命令中配置 -h/--help 选项查看命令的帮助信息；当任务执行报错时，也可配置 -v/--verbose 选项查看命令的详细执行过程。

说明

执行集群命令组命令时可能会出现需要输出集群内其他 OBServer 节点所在机器的用户名和密码的场景。

obshell cluster join

使用该命令可以将当前的 OBServer 节点加入指定集群（OceanBase 集群 init 之前使用该命令）。

${home_path}/bin/obshell cluster join -z -s [-d] [-r] [-P] [-p] [-o]

# example
/home/admin/oceanbase/bin/obshell cluster join -z zone1 -s 10.10.10.1

home_path 为 OceanBase 数据库的安装目录，OBShell 默认在 OceanBase 数据库安装目录的 bin 目录下。

命令的选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-z/--zonename	是	string	无	用于设置节点自身所属 Zone。
-s/--observer	是	string	无	用于设置希望加入的目标节点。格式为 `ip:port`，`port` 可不设置，默认为 `2886`。
-d/--data_dir	否	string	${home_path}/store	用于设置存储 SSTable 等数据的目录，需设置为绝对路径。默认为工作目录（`home_path`）下的 `store` 目录。
-r/--redo_dir	否	string	${data_dir}	用于设置存放 clog 数据的目录，需设置为绝对路径。默认与 `--data_dir` 取值相同。
-p/--mysql_port	否	int	2881	用于设置 SQL 服务协议端口号，默认为 `2881`。
-P/--rpc_port	否	int	2882	用于设置远程访问的协议端口号，默认为 `2882`。
-o/--optstr	否	string	无	用于设置 OBServer 节点的其他参数项。每个配置项的格式为 `key=value`，多个配置项之间用 `,` 分隔。`-o` 整体需要用单引号包裹，例如：`-o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'`。

obshell cluster remove

使用该命令可以将指定的 OBShell 从集群中删除（OceanBase 集群 init 之前使用该命令）。

${home_path}/bin/obshell cluster remove -s 

# example
/home/admin/oceanbase/bin/obshell cluster remove -s 10.10.10.1

home_path 为 OceanBase 数据库的安装目录，OBShell 默认在 OceanBase 数据库安装目录的 bin 目录下。

选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-s/--observer	是	string	无	用于指定希望删除的目标节点，格式为 `ip:port`，`port` 可不设置，默认为 `2886`。

obshell cluster init

使用该命令可以初始化 OceanBase 集群。

${home_path}/bin/obshell cluster init -n --rp [-i] [-d] [-r] [-P] [-p] [-o] [--rs]

# example
/home/admin/oceanbase/bin/obshell cluster init -n ob-test --rp ********

home_path 为 OceanBase 数据库的安装目录，OBShell 默认在 OceanBase 数据库安装目录的 bin 目录下。

选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-n/--appname	是	string	无	用于设置当前 OceanBase 集群的名称。
--rp/--rootpassword	是	string	无	用于设置 sys 租户的 root 用户密码。
-i/--clusterid	否	int	1	用于设置当前 OceanBase 集群的 ID，默认为 `1`。
-d/--data_dir	否	string	${home_path}/store	用于设置存储 SSTable 等数据的目录，需设置为绝对路径。默认为工作目录（`home_path`）下的 `store` 目录。
-r/--redo_dir	否	string	${data_dir}	用于设置存放 clog 数据的目录，需设置为绝对路径。默认与 `--data_dir` 取值相同。
-p/--mysql_port	否	int	2881	用于设置 SQL 服务协议端口号，默认为 `2881`。
-P/--rpc_port	否	int	2882	用于设置远程访问的协议端口号，默认为 `2882`。
--rs/--rs_list	否	string	无	rs_list 是 Root Service 列表。格式为 `observer_ip:rpc_port:mysql_port`，每个 Root Server 之间用 `;` 分隔。 `--rs` 整体需要用单引号包裹，例如 `--rs '10.10.10.1:2882:2881;10.10.10.2:2882:2881'`。
-o/--optstr	否	string	无	用于设置 OceanBase 集群的其他参数项。每个配置项的格式为 `key=value`，多个配置项之间用 `,` 分隔。`-o` 整体需要用单引号包裹，例如：`-o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'`。

obshell cluster show

使用该命令可展示当前集群的信息。

${home_path}/bin/obshell cluster show

home_path 为 OceanBase 数据库的安装目录，OBShell 默认在 OceanBase 数据库安装目录的 bin 目录下。

根据 OceanBase 集群的状态不同，该命令有如下两种输出情况：

当 OceanBase 集群未初始化时，仅展示 OBShell 的相关信息，包括 ip、version 和 port。
当 OceanBase 集群初始化完成后，展示 OBShell 和 OceanBase 数据库的信息。OceanBase 数据库的信息包括 cluster、version、zone、sql_port、svr_port、root_server 和 status。

其中 status 状态如下：
- ACTIVE：OBServer 节点与 Root Service 心跳正常
- INACTIVE：OBServer 节点与 Root Service 失去心跳联系
- DELETING：OBServer 节点正在删除中
- STOPPED：OBServer 节点被 Stop

obshell cluster start

使用该命令可以启动指定范围内的 OBServer 节点或对 OceanBase 集群进行接管。使用该命令启动指定范围内的 OBServer 节点时，要求此时的 OceanBase 集群已完全由 OBShell 进行运维管理。

判断集群是否被 OBShell 管理，以及如何使用 OBShell 接管 OceanBase 集群的详细介绍请参见接管非 OBShell 部署集群。启动 OBServer 节点的详细使用场景可参见启动 OceanBase 集群。

${home_path}/bin/obshell cluster start [-a] [-s] [-z] [-i]

# example
/home/admin/oceanbase/bin/obshell cluster start -s 10.10.10.1:2886,10.10.10.2:2886

home_path 为 OceanBase 数据库的安装目录，OBShell 默认在 OceanBase 数据库安装目录的 bin 目录下。

选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-a/--all	否	无	无	控制是否启动所有 OBServer 节点。不需要传值。命令中未出现该选项时，默认只启动当前 OBShell 运维的 OBServer 节点。
-s/--observer	否	string	无	启动指定的 OBShell 运维的 OBServer 节点，格式为 `obshell_ip:obshell_port`，多个 OBShell 之间使用 `,` 分隔，例如 `-s x.x.x.x:2886,x.x.x.x:2886`。
-z/--zonename	否	string	无	启动指定 Zone 内的所有 OBServer 节点，多个 Zone 之间使用 `,` 分隔，例如 `-z zone1,zone2`。
-i/--id	否	string	无	指定前序启/停任务的 ID。仅在特殊情况下使用。当集群运维被一个或者多个前序启/停任务锁住时，可以使用 `-i` 将前序任务解锁，例如 `-i 22130706433028869`。

obshell cluster stop

使用该命令可以停止指定范围内的 observer 进程。命令的详细使用场景可参见停止 OceanBase 集群。

${home_path}/bin/obshell cluster stop [-a] [-s] [-z] [-i]

# example
/home/admin/oceanbase/bin/obshell cluster stop -s 10.10.10.1:2886

home_path 为 OceanBase 数据库的安装目录，OBShell 默认在 OceanBase 数据库安装目录的 bin 目录下。

选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-a/--all	否	无	无	控制是否停止所有 observer 进程，无需传值。命令中未出现该选项时，默认仅停止当前 OBShell 运维的 OBServer 节点进程。
-s/--observer	否	string	无	停止指定的 OBShell 运维的 OBServer 节点进程，格式为 `obshell_ip:obshell_port`，多个 OBShell 中间使用 `,` 分隔，例如 `-s x.x.x.x:2886,x.x.x.x:2886`。
-z/--zonename	否	string	无	停止指定 Zone 内的所有 observer 进程，多个 Zone 之间使用 `,` 分隔，例如 `-z zone1,zone2`。
-f/--force	否	bool	false	控制是否强制 kill observer 进程，无需传值。命令中未出现该选项时，默认仅隔离 OBServer 节点，隔离节点的详细介绍可参见隔离节点文档。
-i/--id	否	string	无	指定前序启/停任务的 ID。仅在特殊情况下使用。当集群运维被一个或者多个前序启/停任务锁住时，可以使用 `-i` 将前序任务解锁，例如 `-i 22130706433028869`。

obshell cluster upgrade

使用该命令可以将 OceanBase 数据库升级到指定版本。命令的详细使用场景可参见升级 OceanBase 集群。

说明

通过该命令升级 OceanBase 数据库时，obshell 将根据 OceanBase 数据库与 obshell 的版本映射关系同时升级 obshell 版本。

${home_path}/bin/obshell cluster upgrade -l [-m] [-p] [-y]

# example
/home/admin/oceanbase/bin/obshell cluster upgrade -l /home/admin/oceanbase/upgrade/ -p 4.2.2.0-20231224224959

home_path 为 OceanBase 数据库的安装目录，OBShell 默认在 OceanBase 数据库安装目录的 bin 目录下。

选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-l/--pkg-location	是	string	无	指定升级包所在目录的绝对路径。
-p, --upg-pkg	否	string	无	指定目标版本，格式为 `${name}-${build_version}`。多个之间用逗号分隔。
-m/--upg-model	否	string	rolling	指定升级模式。可设置为如下两种取值： `rolling`：轮转升级，升级过程中副本仍满足多数派，可提供服务。 `stopService`：在预定时间内暂停服务进行整体更新。
-y/--yes	否	无	无	用于控制是否取消二次确认，无需传值。

obshell cluster scale-out

使用该命令可以将当前节点扩容到指定的集群。命令的详细使用场景可参见使用 OBShell 扩容 OceanBase 集群。

${home_path}/bin/obshell cluster scale-out -z -s [--rp] [-d] [-r] [-p] [-P] [-o]

# example
/home/admin/oceanbase/bin/obshell cluster scale-out -s '10.10.10.1:2886' -z 'zone1' -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G' --rp *****

home_path 为 OceanBase 数据库的安装目录，OBShell 默认在 OceanBase 数据库安装目录的 bin 目录下。

选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-s/--observer-addr	是	string	无	待扩容的集群中已存在的节点，若待扩容集群中包含多个节点，此处指定一个即可。格式为 `ip:obshell_port`，`obshell_port` 可不填，默认为 `2886`。
-z/--zonename	是	string	无	扩容后当前节点所属的 Zone。
--rp/--rootpassword	否	string	无	待扩容的集群 sys 租户的 root 用户密码。当设置的密码错误时，将无法发起扩容。
-d/--data_dir	否	string	${home_path}/store	用于设置存储 SSTable 等数据的目录，需设置为绝对路径。默认为工作目录（`home_path`）下的 `store` 目录。
-r/--redo_dir	否	string	${data_dir}	用于设置存放 clog 数据的目录，需设置为绝对路径。默认值与 `--data_dir` 值相同。
-p/--mysql_port	否	int	2881	用于设置 SQL 服务协议端口号，默认为 `2881`。
-P/--rpc_port	否	int	2882	用于设置远程访问的协议端口号，默认为 `2882`。
-o/--optstr	否	string	无	用于设置 OBServer 节点的其他参数项。每个配置项的格式为 `key=value`，多个配置项之间用 `,` 分隔，`-o` 整体需要用单引号包裹，例如：`-o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'`。