obshell 集群命令组 - OceanBase 数据库 V4.3.0

obshell 集群命令组

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

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

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

obshell cluster join

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

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

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

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

命令的选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-z/--zone	是	string	无	用于设置节点自身所属 Zone。
-s/--server	是	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/--opt_str	否	string	无	用于设置 OBServer 节点的其他参数项。每个配置项的格式为 `key=value`，多个配置项之间用 `,` 分隔。`-o` 整体需要用单引号包裹，例如：`-o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'`。
-l/--log_level	否	string	无	用于设置 OBServer 节点的日志打印级别。

obshell cluster remove

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

${home_path}/bin/obshell cluster remove -s [-y]

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

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

选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-s/--server	是	string	无	用于指定希望删除的目标节点，格式为 `ip:port`，`port` 可不设置，默认为 `2886`。
-y/--yes	否	无	无	用于控制是否取消二次确认，无需传值。

obshell cluster init

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

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

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

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

选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-n/--cluster_name	是	string	无	用于设置当前 OceanBase 集群的名称。
--rp/--rootpassword	否	string	无	用于设置 sys 租户的 root 用户密码。
-i/--cluster_id	否	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/--opt_str	否	string	无	用于设置 OceanBase 集群的其他参数项。每个配置项的格式为 `key=value`，多个配置项之间用 `,` 分隔。`-o` 整体需要用单引号包裹，例如：`-o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'`。
-l/--log_level	否	string	无	用于设置 OceanBase 集群的日志打印级别。

obshell cluster show

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

${home_path}/bin/obshell cluster show [-d]

home_path 为 OceanBase 数据库的安装目录，obshell 默认在 OceanBase 数据库安装目录的 bin 目录下。-d/--show_detail 非必选项，用于控制是否展示集群的详细信息，无需传值。

根据 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] [-y] [--ssh_user] [--ssh_port] [--user_password] [--key_file] [--key_passphrase]

# 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/--server	否	string	无	启动指定的 obshell 运维的 OBServer 节点，格式为 `obshell_ip:obshell_port`，多个 obshell 之间使用 `,` 分隔，例如 `-s x.x.x.x:2886,x.x.x.x:2886`。
-z/--zone	否	string	无	启动指定 Zone 内的所有 OBServer 节点，多个 Zone 之间使用 `,` 分隔，例如 `-z zone1,zone2`。
-i/--id	否	string	无	指定前序启/停任务的 ID。仅在特殊情况下使用。当集群运维被一个或者多个前序启/停任务锁住时，可以使用 `-i` 将前序任务解锁，例如 `-i 22130706433028869`。
-y/--yes	否	无	无	用于控制是否取消二次确认，无需传值。
--ssh_user	否	string	无	设置 ssh 连接远程时使用的用户。
--ssh_port	否	string	无	设置 ssh 连接远程时使用的端口号。
--user_password	否	string	无	设置 ssh 连接远程时设置的用户密码。
--key_file	否	string	"/~/.ssh/id_rsa"	设置 ssh 连接远程时指定的私钥文件，该选项仅在 `--user_password` 未被设置时生效。
--key_passphrase	否	string	无	设置查看指定的私钥文件的口令，该选项仅在 `--key_file` 生效时生效。

obshell cluster stop

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

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

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

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

选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-a/--all	否	无	无	控制是否停止所有 observer 进程，无需传值。命令中未出现该选项时，默认仅停止当前 obshell 运维的 OBServer 节点进程。
-s/--server	否	string	无	停止指定的 obshell 运维的 OBServer 节点进程，格式为 `obshell_ip:obshell_port`，多个 obshell 中间使用 `,` 分隔，例如 `-s x.x.x.x:2886,x.x.x.x:2886`。
-z/--zone	否	string	无	停止指定 Zone 内的所有 observer 进程，多个 Zone 之间使用 `,` 分隔，例如 `-z zone1,zone2`。
-f/--force	否	bool	false	控制是否强制 kill observer 进程，无需传值。
-I/--immediate	否		无	控制是否执行 `STOP SERVER`，无需传值。`STOP SERVER` 的更多信息请参见隔离节点文档。说明 `-f` 与 `-I` 两者互斥，您需且仅需配置其一。
-i/--id	否	string	无	指定前序启/停任务的 ID。仅在特殊情况下使用。当集群运维被一个或者多个前序启/停任务锁住时，可以使用 `-i` 将前序任务解锁，例如 `-i 22130706433028869`。
-y/--yes	否	无	无	用于控制是否取消二次确认，无需传值。

obshell cluster upgrade

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

说明

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

${home_path}/bin/obshell cluster upgrade -d [-m] [-V] [-t] [-y]

# example
/home/admin/oceanbase/bin/obshell cluster upgrade -d /home/admin/oceanbase/upgrade/ -V 4.2.2.0-20231224224959

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

选项说明见下表：

选项名	是否必选	数据类型	默认值	说明
-d/--pkg_directory	是	string	无	指定升级包所在目录的绝对路径。
-m/--mode	否	string	ROLLING	指定升级模式。可设置为如下两种取值： `ROLLING`：轮转升级，升级过程中副本仍满足多数派，可提供服务。 `STOPSERVICE`：在预定时间内暂停服务进行整体更新。
-V/--target_version	否	string	无	指定目标版本。需要格式正确，例如 `4.2.2.0` 或者 `4.2.2.0-20231224224959`。不指定则选择 `-d` 目录下的最高版本的 OceanBase 数据库 RPM 包。
-t/--tmp_directory	否	string	${home_path}/upgrade	指定升级过程中的临时目录，用于存放下载的安装包及解压安装过程中产生的所有文件。需配置为绝对路径。
-y/--yes	否	无	无	用于控制是否取消二次确认，无需传值。

obshell cluster scale-out

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

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

# 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/--server	是	string	无	待扩容的集群中已存在的节点，若待扩容集群中包含多个节点，此处指定一个即可。格式为 `ip:obshell_port`，`obshell_port` 可不填，默认为 `2886`。
-z/--zone	是	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`。
-l/--log_level	否	string	无	用于设置 OBServer 节点的日志打印级别。
-o/--opt_str	否	string	无	用于设置 OBServer 节点的其他参数项。每个配置项的格式为 `key=value`，多个配置项之间用 `,` 分隔，`-o` 整体需要用单引号包裹，例如：`-o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'`。
-y/--yes	否	无	无	用于控制是否取消二次确认，无需传值。