---
title: "部署 OceanBase 集群 - OceanBase 数据库 V4.3.0 | OceanBase 文档中心"
description: 部署 OceanBase 集群 obshell 部署 OceanBase 集群支持两种部署方式： 通过调用 API 部署 通过 obshell 命令部署 前提条件 在部署 OceanBase 数据库之前，请您确认以下信息： 您的机器满足软硬件要求。详细信息请参见 软硬件要求 。 生产环境下，您需要进行环境和配置检查，…
---
切换语言

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

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

# 部署 OceanBase 集群

更新时间：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/210.use-case/200.deploy-oceanbase-cluster.md)  

obshell 部署 OceanBase 集群支持两种部署方式：

- 通过调用 API 部署
 - 通过 obshell 命令部署

## 前提条件

在部署 OceanBase 数据库之前，请您确认以下信息：

- 您的机器满足软硬件要求。详细信息请参见 [软硬件要求](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000640300)。
 - 生产环境下，您需要进行环境和配置检查，具体操作请参见 [部署前配置](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000642556) 章节。

## 名词解释

- Single Agent：obshell Agent 的一种身份，obshell 的初始身份。可以通过 join 由 Single Agent 转为 Master Agent 或 Follower Agent。
 - Master Agent：obshell Agent 的一种身份。可以通过 init 由 Master Agent 转为 Cluster Agent；可以通过 remove 由 Master Agent 转为 Single Agent。
 - Follower Agent：obshell Agent 的一种身份。可以通过 init 由 Follower Agent 转为 Cluster Agent；可以通过 remove 由 Follower Agent 转为 Single Agent。
 - Cluster Agent：obshell Agent 的一种身份。
 - OceanBase 集群初始化（init）是一个中心化任务，在这个阶段 obshell Agent 有两种身份：Master Agent 和 Follower Agent。init 任务由 Master Agent 领导所有 obshell 完成。init 完成后，集群去中心化，所有 obshell 只有一个身份（Cluster Agent）。

身份转换的状态机如图所示：

 ![身份转换](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/observer-enterprise/V4.3.0/reference/deploy/Agent.png)

## 部署模式

本文采用三副本部署模式，使用三台机器，您可以根据自己实际情况选择合适的部署方案。本文中三台机器的使用情况如下：

| 角色 | 机器 | 备注 |
| --- | --- | --- |
| OBServer 节点 | 10.10.10.1 | OceanBase 数据库 zone1，init 完成前为 Master Agent |
| OBServer 节点 | 10.10.10.2 | OceanBase 数据库 zone2，init 完成前为 Follower Agent |
| OBServer 节点 | 10.10.10.3 | OceanBase 数据库 zone3，init 完成前为 Follower Agent |

## 通过 API 部署

#### 说明

通过命令行命令调用 API 时，需注意以下信息：

- 以下 API 调用后会创建异步任务，因此需要确认任务完成后才可进行下一步。详细步骤可参见 [获取任务的详细信息](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000694621)。
 - obshell 会对被调用的 API 进行安全校验。因此，您在每次调用 API 之前都需先参考 [API 混合加密](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000694620) 一文对请求进行加密，并在 curl 命令中配置加密后的请求头部（`${request_headers}`）和请求体（`${request_body}`）。

### 步骤 1：启动 obshell

1. obshell 位于 OceanBase 数据库安装目录下（`/home/admin/oceanbase/bin/obshell`）。
 2. 在每个节点上启动 obshell，命令详细介绍可参见 [obshell agent start](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000694609)。

   在 `10.10.10.1` 节点上执行如下命令：

   ```shell
   [admin@test001 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.1 -P 2886

   ```

   在 `10.10.10.2` 节点上执行如下命令：

   ```shell
   [admin@test002 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.2 -P 2886

   ```

   在 `10.10.10.3` 节点上执行如下命令：

   ```shell
   [admin@test003 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.3 -P 2886

   ```

### 步骤 2：Single Agent 成为 Master Agent

通过向 Single Agent（`10.10.10.1` 节点）调用 `/api/v1/agent/join`，且请求中指定 obshell 为其自身（`10.10.10.1:2886`），即可完成由 Single Agent 到 Master Agent 的身份切换。

    命令行命令   Python   GO

命令行中调用对应 API 接口的说明可参见 [在集群初始化前添加节点](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000694629)。

```shell
[admin@test001 ~]$ curl -H "Content-Type: application/json" -H 'X-OCS-Header:${request_headers}' -X POST -d '${request_body}' http://10.10.10.1:2886/api/v1/agent/join

```

通过 obshell-sdk-python 请求对应 API 方法的介绍可参见 [在集群初始化前添加节点](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000904129)。

```python
···
client = ClientSet("10.10.10.1", 2886)
client.v1.join_sync("10.10.10.1", 2886, "zone1") # 调用 /api/v1/agent/join
···

```

通过 obshell-sdk-go 请求对应 API 方法的介绍可参见 [在集群初始化前添加节点](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000904156)。

```go
···
client, err := services.NewClient("10.10.10.1", 2886)
joinRequest1 := client.V1().NewJoinRequest("10.10.10.1", 2886, "zone1")
dag, err := client.V1().JoinSyncWithRequest(joinRequest1)  // 调用 /api/v1/agent/join
···

```

### 步骤 3：Single Agent 成为 Follower Agent

通过向 Single Agent（`10.10.10.2` 和 `10.10.10.3` 节点）调用 `/api/v1/agent/join`，且请求中指定 obshell 为 Master Agent（`10.10.10.1:2886`），即可完成由 Single Agent 到 Follower Agent 的身份切换。

在任一节点上执行如下命令：

- 将 `10.10.10.2` 身份切换为 Follower Agent

  ```shell
  [admin@test001 ~]$ curl -H "Content-Type: application/json" -H 'X-OCS-Header:${request_headers}' -X POST -d '${request_body}' http://10.10.10.2:2886/api/v1/agent/join

  ```
 - 将 `10.10.10.3` 身份切换为 Follower Agent

  ```shell
  [admin@test001 ~]$ curl -H "Content-Type: application/json" -H 'X-OCS-Header:${request_headers}' -X POST -d '${request_body}' http://10.10.10.3:2886/api/v1/agent/join

  ```

```python
···
client = ClientV1("10.10.10.1", 2886)
client.v1.join_sync("10.10.10.2", 2886, "zone2") # 调用 /api/v1/agent/join
client.v1.join_sync("10.10.10.3", 2886, "zone3") # 调用 /api/v1/agent/join
···

```

```go
···
client, err := v1.NewClient("10.10.10.1", 2886)

joinRequest2 := client.V1().NewJoinRequest("10.10.10.2", 2886, "zone2")
dag, err :=  client.V1().JoinSyncWithRequest(joinRequest2)  // 调用 /api/v1/agent/join

joinRequest3 := client.V1().NewJoinRequest("10.10.10.3", 2886, "zone3")
dag, err =  client.V1().JoinSyncWithRequest(joinRequest3)  // 调用 /api/v1/agent/join
···

```

### 步骤 4：设置集群级配置

通过向 obshell 身份为 Master Agent 的节点调用 `/api/v1/obcluster/config`，即可设置集群级配置。

命令行中调用对应 API 接口的说明详见 [设置集群级配置](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000694631)。

```shell
[admin@test001 ~]$ curl -H "Content-Type: application/json" -H 'X-OCS-Header:${request_headers}' -X PUT -d '${request_body}' http://10.10.10.1:2886/api/v1/obcluster/config

```

通过 obshell-sdk-python 请求对应 API 方法的介绍可参见 [设置集群级配置](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000904131)。

```python
···
client = ClientSet("10.10.10.1", 2886)
client.v1.config_obcluster_sync("ob-test", 1, "****")  # 调用 /api/v1/obcluster/config
···

```

通过 obshell-sdk-go 请求对应 API 方法的介绍可参见 [设置集群级配置](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000904158)。

```go
···
client, err := services.NewClientWithPassword("10.10.10.1", 2886)
configObclusterReq := client.V1().NewConfigObclusterRequest("ob-test", 1).SetRootPwd("****")
dag, err := client.V1().ConfigObclusterSyncWithRequest(configObclusterReq) // 调用 /api/v1/obcluster/config
···

```

### 步骤 5：设置 Server 级配置

通过向 obshell 身份为 Master Agent 的节点调用 `/api/v1/observer/config`，且请求中指定生效范围，即可为指定的 obshell 设置 Server 级配置。

命令行中调用对应 API 接口的说明详见 [设置 Server 级配置](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000694632)。

```shell
[admin@test001 ~]$ curl -H "Content-Type: application/json" -H 'X-OCS-Header:${request_headers}' -X PUT -d '${request_body}' http://10.10.10.1:2886/api/v1/observer/config

```

通过 obshell-sdk-python 请求对应 API 方法的介绍可参见 [设置 Server 级配置](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000904132)。

```python
···
client = ClientSet("10.10.10.1", 2886, PasswordAuth("****"))
configs = {"redoDir":"/data/workspace/redo", "dataDir":"/data/workspace/data",
           "datafile_size":"24G", "cpu_count":"16", "memory_limit":"16G",
           "system_memory":"4G", "log_disk_size":"40G"}
client.v1.config_observer_sync(configs, "GLOBAL", [])  # 调用 /api/v1/observer/config
···

```

通过 obshell-sdk-go 请求对应 API 方法的介绍可参见 [设置 Server 级配置](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000904159)。

```go
···
client, err := services.NewClientWithPassword("10.10.10.1", 2886, "****")
configs := map[string]string{
    "redoDir":"/data/workspace/redo", "dataDir":"/data/workspace/data",
    "datafile_size":"24G", "cpu_count":"16", "memory_limit":"16G",
    "system_memory":"4G", "log_disk_size":"40G"}
configObserverReq := client.V1().NewConfigObserverRequest(configs, v1.SCOPE_GLOBAL)
dag, err := client.V1().ConfigObserverSyncWithRequest(configObserverReq)  // 调用 /api/v1/observer/config
···

```

### 步骤 6：初始化集群

通过向 obshell 身份为 Master Agent 的节点调用 `/api/v1/ob/init`，即可执行集群初始化。

命令行中调用对应 API 接口的说明详见 [初始化集群](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000694633)。

```shell
[admin@test001 ~]$ curl -H 'X-OCS-Header:${request_headers}' -X POST http://10.10.10.1:2886/api/v1/ob/init

```

通过 obshell-sdk-python 请求对应 API 方法的介绍可参见 [初始化集群](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000904133)。

```python
···
client = ClientSet("10.10.10.1", 2886, PasswordAuth("****"))
client.v1.init_sync()  # 调用 /api/v1/ob/init
···

```

通过 obshell-sdk-go 请求对应 API 方法的介绍可参见 [初始化集群](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000904160)。

```go
···
client, err := services.NewClientWithPassword("10.10.10.1", 2886, "****")
initReq := client.V1().NewInitRequest()
dag, err := client.V1().InitSyncWithRequest(initReq)  // 调用 /api/v1/ob/init
···

```

### 步骤 7：连接 OceanBase 集群

此处以通过 OBClient 连接 OceanBase 数据库为例，命令如下：

```shell
[admin@test001 ~]$ obclient -h10.10.10.1 -uroot@sys -P2881 -p -A

```

- `-h`：提供 OceanBase 数据库连接 IP，即 obshell 启动时指定的 IP，如 `10.10.10.1`。
 - `-u`：提供租户的连接账户，格式：用户名@租户名。MySQL 租户的管理员用户名默认是 `root`。
 - `-P`：提供 OceanBase 数据库连接端口，若 **步骤 5** 中未指定，则使用默认端口 `2881`。
 - `-p`：提供连接 OceanBase 数据库账户的密码。
 - `-A`：表示在 OBClient 连接数据库时不自动获取统计信息。

更多连接 OceanBase 集群的详细操作可参见 [连接 OceanBase 数据库](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000640069) 章节。

### 完整代码示例

    Python   GO

```python
from obshell import ClientSet
from obshell.auth import PasswordAuth

client = ClientSet("10.10.10.1", 2886)

# join 自己成为 MASTER
client.v1.join_sync("10.10.10.1", 2886, "zone1")
# 加入 follower 到集群
client.v1.join_sync("10.10.10.2", 2886, "zone2")
client.v1.join_sync("10.10.10.3", 2886, "zone3")

# 设置 OceanBase 集群的配置信息
client.v1.config_obcluster_sync("test-sdk", 11, "****")

# 设置各个 OBServer 节点的配置项
configs = {
    "datafile_size": "24G", "log_disk_size": "24G",
    "cpu_count": "16", "memory_limit": "16G", "system_memory": "8G",
    "enable_syslog_recycle": "true", "enable_syslog_wf": "true"}
client.v1.config_observer_sync(configs, "GLOBAL", [])

# 初始化集群
client.v1.init_sync()

# 获取当前集群的状态信息
status = client.v1.get_status()
print(status)

```

```go
package main

import (
    "github.com/oceanbase/obshell-sdk-go/services"
    "github.com/oceanbase/obshell-sdk-go/services/v1"
)

func main() {
    client, err := services.NewClient("10.10.10.1", 2886)
    if err != nil {
        return
    }

    // join 自己成为 MASTER
    joinRequest1 := client.V1().NewJoinRequest("10.10.10.1", 2886, "zone1")
    dag, err :=  client.V1().JoinSyncWithRequest(joinRequest1) // 生产环境中需要处理 error，下同

    // 加入 follower 到集群
    joinRequest2 := client.V1().NewJoinRequest("10.10.10.2", 2886, "zone2")
    dag, err =  client.V1().JoinSyncWithRequest(joinRequest2)

    joinRequest3 := client.V1().NewJoinRequest("10.10.10.3", 2886, "zone3")
    dag, err =  client.V1().JoinSyncWithRequest(joinRequest3)

    // 设置 OceanBase 集群的配置信息
    configObclusterReq := client.V1().NewConfigObclusterRequest("obshell-sdk-test", 12358).SetRootPwd("****")
    dag, err =  client.V1().ConfigObclusterSyncWithRequest(configObclusterReq)

    // obshell prior to 4.2.3.0 should use mysqlPort(rpcPort) instead of mysql_port(rpc_port).
    configs := map[string]string{
        "datafile_size": "24G", "cpu_count": "16", "memory_limit": "16G", "system_memory": "8G", "log_disk_size": "24G",
    }

    // 设置各个 OBServer 节点的配置项
    configObserverReq := client.V1().NewConfigObserverRequest(configs, v1.SCOPE_GLOBAL)
    dag, err =  client.V1().ConfigObserverSyncWithRequest(configObserverReq)

    // 初始化集群
    initReq := client.V1().NewInitRequest()
    dag, err =  client.V1().InitSyncWithRequest(initReq)
}

```

## 通过命令行部署

### 步骤 1：启动 obshell

1. obshell 位于 OceanBase 数据库安装目录下（`/home/admin/oceanbase/bin/obshell`）。
 2. 在每个节点上启动 obshell，详细请参见 [启动 obshell](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000671669)。

   ```

   ```

   ```

### 步骤 2：Single Agent 成为 Master Agent，并设置 Server 级配置

在当前节点上调用 `obshell cluster join` 命令，且配置 `-s` 为 obshell 自身，即可完成由 Single Agent 到 Master Agent 的身份切换。命令详见 [obshell cluster join](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000671675)。

```shell
[admin@test001 ~]$ /home/admin/oceanbase/bin/obshell cluster join -s "10.10.10.1:2886" -z zone1 -p 2881 -P 2882 -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'

```

### 步骤 3：Single Agent 成为 Follower Agent，并设置 Server 级配置

在当前节点上调用 `obshell cluster join` 命令，且配置 `-s` 为 Master Agent（即 `10.10.10.1:2886`），即可完成由 Single Agent 到 Follower Agent 的身份切换。命令详见 [obshell cluster join](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000671675)。

```shell
[admin@test002 ~]$ /home/admin/oceanbase/bin/obshell cluster join -s "10.10.10.1:2886" -z zone2 -p 2881 -P 2882 -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'

```

```shell
[admin@test003 ~]$ /home/admin/oceanbase/bin/obshell cluster join -s "10.10.10.1:2886" -z zone3 -p 2881 -P 2882 -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'

```

### 步骤 4：设置集群级设置并初始化集群

在任一节点上调用 `obshell cluster init` 命令，即可设置集群级配置，并执行集群初始化。命令详见 [obshell cluster init](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000671675)。

```shell
[admin@test001 ~]$ /home/admin/oceanbase/bin/obshell cluster init -n ob-test --rp ********

```

### 步骤 5：连接 OceanBase 集群

此处以通过 OBClient 连接 OceanBase 数据库为例，命令如下：

```

- `-h`：提供 OceanBase 数据库连接 IP，即 obshell 启动时指定的 IP，如 `10.10.10.1`。
 - `-u`：提供租户的连接账户，格式：用户名@租户名。MySQL 租户的管理员用户名默认是 `root`。
 - `-P`：提供 OceanBase 数据库连接端口，若 **步骤 4** 中未指定，则使用默认端口 `2881`。
 - `-p`：提供连接 OceanBase 数据库账户的密码。
 - `-A`：表示在 OBClient 连接数据库时不自动获取统计信息。

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