首批通过分布式安全可靠测评，为关键业务系统打造
部署 OceanBase 集群
更新时间：2026-04-10 11:58:35
编辑
分享
obshell 部署 OceanBase 集群支持两种部署方式：
通过调用 API 部署
通过 obshell 命令部署
前提条件
在部署 OceanBase 数据库之前，请您确认以下信息：
名词解释
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）。
身份转换的状态机如图所示：
部署模式
本文采用三副本部署模式，使用三台机器，您可以根据自己实际情况选择合适的部署方案。本文中三台机器的使用情况如下：
| 角色 | 机器 | 备注 |
|---|---|---|
| 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 时，需注意以下信息：
步骤 1：启动 obshell
obshell 位于 OceanBase 数据库安装目录下（
/home/admin/oceanbase/bin/obshell）。在每个节点上启动 obshell，命令详细介绍可参见 obshell agent start。
在
10.10.10.1节点上执行如下命令：[admin@test001 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.1 -P 2886在
10.10.10.2节点上执行如下命令：[admin@test002 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.2 -P 2886在
10.10.10.3节点上执行如下命令：[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 接口的说明可参见 在集群初始化前添加节点。
[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 方法的介绍可参见 在集群初始化前添加节点。
···
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 方法的介绍可参见 在集群初始化前添加节点。
···
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 的身份切换。
命令行命令
Python
GO
命令行中调用对应 API 接口的说明可参见 在集群初始化前添加节点。
在任一节点上执行如下命令：
将
10.10.10.2身份切换为 Follower Agent[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[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
通过 obshell-sdk-python 请求对应 API 方法的介绍可参见 在集群初始化前添加节点。
···
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
···
通过 obshell-sdk-go 请求对应 API 方法的介绍可参见 在集群初始化前添加节点。
···
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，即可设置集群级配置。
命令行命令
Python
GO
命令行中调用对应 API 接口的说明详见 设置集群级配置。
[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 方法的介绍可参见 设置集群级配置。
···
client = ClientSet("10.10.10.1", 2886)
client.v1.config_obcluster_sync("ob-test", 1, "****") # 调用 /api/v1/obcluster/config
···
通过 obshell-sdk-go 请求对应 API 方法的介绍可参见 设置集群级配置。
···
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 级配置。
命令行命令
Python
GO
命令行中调用对应 API 接口的说明详见 设置 Server 级配置。
[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 级配置。
···
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 级配置。
···
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，即可执行集群初始化。
命令行命令
Python
GO
命令行中调用对应 API 接口的说明详见 初始化集群。
[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 方法的介绍可参见 初始化集群。
···
client = ClientSet("10.10.10.1", 2886, PasswordAuth("****"))
client.v1.init_sync() # 调用 /api/v1/ob/init
···
通过 obshell-sdk-go 请求对应 API 方法的介绍可参见 初始化集群。
···
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 数据库为例，命令如下：
[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 数据库 章节。
完整代码示例
Python
GO
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)
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
obshell 位于 OceanBase 数据库安装目录下（
/home/admin/oceanbase/bin/obshell）。在每个节点上启动 obshell，详细请参见 启动 obshell。
在
10.10.10.1节点上执行如下命令：[admin@test001 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.1 -P 2886在
10.10.10.2节点上执行如下命令：[admin@test002 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.2 -P 2886在
10.10.10.3节点上执行如下命令：[admin@test003 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.3 -P 2886
步骤 2：Single Agent 成为 Master Agent，并设置 Server 级配置
在当前节点上调用 obshell cluster join 命令，且配置 -s 为 obshell 自身，即可完成由 Single Agent 到 Master Agent 的身份切换。命令详见 obshell cluster join。
在 10.10.10.1 节点上执行如下命令：
[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。
在 10.10.10.2 节点上执行如下命令：
[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'
在 10.10.10.3 节点上执行如下命令：
[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。
[admin@test001 ~]$ /home/admin/oceanbase/bin/obshell cluster init -n ob-test --rp ********
步骤 5：连接 OceanBase 集群
此处以通过 OBClient 连接 OceanBase 数据库为例，命令如下：
[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 数据库连接端口，若 步骤 4 中未指定，则使用默认端口2881。-p：提供连接 OceanBase 数据库账户的密码。-A：表示在 OBClient 连接数据库时不自动获取统计信息。
更多连接 OceanBase 集群的详细操作可参见 连接 OceanBase 数据库 章节。
