---
title: "obshell 集群命令组 - OceanBase 数据库 V4.3.0 | OceanBase 文档中心"
description: obshell 集群命令组 本文档介绍 obshell 的集群命令组，集群命令组可用于部署和管理 OceanBase 集群。 您可通过在命令中配置 -h / --help 选项查看命令的帮助信息；当任务执行报错时，也可配置 -v / --verbose 选项查看命令的详细执行过程。 obshell cluster j…
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.3.0

# obshell 集群命令组

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

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.3.0/zh-CN/700.reference/1500.Components-and-Tools/100.manage/100.obshell/300.obshell-clients/200.cluster-commands.md)  

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

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

## obshell cluster join

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

```shell
${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 之前使用该命令）。

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

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

```

选项说明见下表：

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

## obshell cluster init

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

```shell
${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 ********

```

选项说明见下表：

| 选项名 | 是否必选 | 数据类型 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| -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

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

```shell
${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 部署集群](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000671671)。启动 OBServer 节点的详细使用场景可参见 [启动 OceanBase 集群](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000671672)。

```shell
${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

```

选项说明见下表：

| 选项名 | 是否必选 | 数据类型 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| -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 集群](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000671673)。

```shell
${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

```

选项说明见下表：

| 选项名 | 是否必选 | 数据类型 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| -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` 的更多信息请参见 [隔离节点文档](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000639934)。   #### 说明    `-f` 与 `-I` 两者互斥，您需且仅需配置其一。 |
| -i/--id | 否 | string | 无 | 指定前序启/停任务的 ID。仅在特殊情况下使用。当集群运维被一个或者多个前序启/停任务锁住时，可以使用 `-i` 将前序任务解锁，例如 `-i 22130706433028869`。 |
| -y/--yes | 否 | 无 | 无 | 用于控制是否取消二次确认，无需传值。 |

## obshell cluster upgrade

使用该命令可以将 OceanBase 数据库升级到指定版本。命令的详细使用场景可参见 [升级 OceanBase 集群](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000694607)。

#### 说明

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

```shell
${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

```

选项说明见下表：

| 选项名 | 是否必选 | 数据类型 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| -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 集群](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000671674)。

```shell
${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 *****

```

选项说明见下表：

| 选项名 | 是否必选 | 数据类型 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| -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 | 否 | 无 | 无 | 用于控制是否取消二次确认，无需传值。 |

 上一篇 下一篇 ![有帮助](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) 咨询热线