OceanBase 主备租户切换：基于 Service Name 的 JDBC 配置全攻略

应用场景
版本信息
有关 Service Name 的详细说明
主备租户信息
JDBC配置
常见问题 FAQ

在双机房部署架构下，数据库主备切换的高可用性与业务无感知是企业核心诉求。基于 OceanBase 的 Service Name 特性，我们可以实现主备租户切换时的自动路由，业务无需修改任何连接串，轻松达成高可用架构的落地。

本文将结合实际版本环境与配置案例，详细拆解基于 Service Name 的 OceanBase 主备租户切换方案。

应用场景

双机房部署主备租户，使用服务名（Service Name）实现主备切换自动路由，业务无需修改连接串。

版本信息

observer ：OceanBase V4.2.1.11-111020032025051316
OCP ：V4.3.5-20250610160438
OBProxy：V4.3.1.6-22025072510
obclient:V2.2.6
JDBC 驱动:oceanbase-client-2.4.12.jar

有关 Service Name 的详细说明

Service Name 是 OceanBase 提供的一种新的数据库访问方式，可视其为集群 & 租户名的别名，实现应用程序通过如 mysql -h192.168.100. xxx-P2883 -uroot@SERVICE: 的连接串访问数据库。

从 OceanBase 数据库 V4.1 版本开始高可用解决方式变更为租户级主备库，集群级不再有主备角色的概念，集群名仅用于唯一标识一个集群，主备角色下放到租户级别，主备租户所属的集群可能不同，主备租户名也可能不同。从 OCP V4.3.1 版本开始支持主备租户 Service Name 创建、编辑、删除、校验以及为主备租户所在的集群绑定同一 OBProxy 集群的功能，支持用户通过设置主备租户为同一 Service Name，达到主备租户切换时 Session 自动切换的能力，同时用户也可以依据业务具体场景，如在非主备租户场景下使用 Service Name 代替集群名&租户名的连接方式以及提供灵活性支持主备租户场景下主备租户使用不同的 Service Name 等，从而帮助用户更方便地使用 Service Name 特性。

主备租户信息

主备租户IP

服务端口2883

(主机房)主租户集群名：ob_test#primary_ob04

10.xx.xx.20

10.xx.xx.26

10.xx.xx.32

（备机房）备租户集群名：ob_test#zb_test_clu01

10.xx.xx.36

10.xx.xx.37

10.xx.xx.38

JDBC配置

1. obclient 通过 Service Name 访问租户

obclient servcie name 连接方式-u@SERVICE:

obclient -h10.xx.xx.32 -P2883 -utest_user@SERVICE:svr_ob_test -p

可以根据需求选择JDBC使用url配置还是使用配置文件的方式

2. JDBC使用URL配置方式

使用配置中心连接方式的应用服务建议优先使用此配置

在连接 URL 中的拓展信息ExtendDescription字段中配置 LoadBalance 的信息。默认的配置方式如下:

jdbc:oceanbase:[oracle:][loadbalance:]//@[ExtendDescription]|[,...]]/[database][?=[&=]]

每个配置信息都有一个特定的 NET_SERVICE_NAME。
说明：JDBC URL连接属性根据应用系统需求进行配置

主备租户通用配置示例如下：

url=jdbc:oceanbase:loadbalance://@(NET_SERVICE_NAME=(DESCRIPTION=   (OBLB=ON)                                                       (OBLB_RETRY_ALL_DOWNS=120)   (OBLB_GROUP_STRATEGY=ROTATION)                                  (OBLB_BLACKLIST=                                                                                                                                                                                       (         REMOVE_STRATEGY=(           (NAME=TIMEOUT)           (TIMEOUT=100)         )       )                                 (         APPEND_STRATEGY =(           (NAME=RETRYDURATION)           (RETRYTIMES=3)           (DURATION=100)         )       )                             )     (ADDRESS_LIST=       (OBLB_STRATEGY=RANDOM)      (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.20)(port=2883))       (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.26)(port=2883)) (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.32)(port=2883))   )   (ADDRESS_LIST=       (OBLB_STRATEGY=RANDOM)      (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.36)(port=2883))       (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.37)(port=2883)) (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.38)(port=2883))   )    (CONNECT_DATA=(SERVICE_NAME=test_user)) ))/test_user?useUnicode=true&characterEncoding=utf8&nCharacterEncoding=utf8&useServerPrepStmts=true&useOraclePrepareExecute=true&continueBatchOnError=false&useArrayBinding=true&prepStmtCacheSize=1000&usePieceData=true&useCompatibleMetadata=true&autoReconnect=true

# 连接用户名  @SERVICE:
username=test_user@SERVICE:srv_ob_test

3. 使用配置文件的方式

OceanBase Connector/J 依赖于 oceanbase.tns_admin 的系统参数来指定配置文件的目录，如果没有设置该目录则会依赖于 OCEANBASE_TNS_ADMIN 环境变量来指定配置文件目录，配置文件的名字默认为tnsnames.ob，可以通过环境变量 OCEANBASE_TNS_ADMIN_NAME 来指定其他的配置文件名称。

环境变量开关 OCEANBASE_TNS_ADMIN_DEAMON 用来控制是否开启线程来监测配置文件的改变，该变量默认为 true；当指定为 false 时，则每次连接时都会从配置文件中读取信息。环境变量开关 OCEANBASE_TNS_ADMIN_NAME 用来改变 tns 配置文件的名字，默认为 tnsnames.ob。

前置条件

export OCEANBASE_TNS_ADMIN=/path 或设置JVM 参数 oceanbase.tns_admin=/path 开启配置文件使用方式；

export OCEANBASE_TNS_ADMIN_NAME=/tnsyournames.ob 或设置JVM 参数 oceanbase.tns_admin_name=tnsyournames.ob设置文件名字，若不这么做则使用默认的配置文件名字tnsnames.ob，这里不建议设置；

如果不想启动守护进程则需要设置环境变量export OCEANBASE_TNS_ADMIN_DEAMON=false 或者设置 JVM参数oceanbase.tns_admin_deamon=fasle。

配置步骤如下：

# 创建tns配置文件目录
mkdir -p /home/appdy/oceanbase 
# 设置环境变量
export OCEANBASE_TNS_ADMIN=/home/appdy/oceanbase
vi tnsnames.ob 

TNS_SVC_GROUP=(DESCRIPTION=
  (OBLB=ON)                                                    
  (OBLB_RETRY_ALL_DOWNS=120)
  (OBLB_GROUP_STRATEGY=ROTATION)                               
  (OBLB_BLACKLIST=                                                                                                                                                                               
      (
        REMOVE_STRATEGY=(
          (NAME=TIMEOUT)
          (TIMEOUT=100)
        )
      )                          
      (
        APPEND_STRATEGY =(
          (NAME=RETRYDURATION)
          (RETRYTIMES=3)
          (DURATION=100)
        )
      )
  ) 
  (ADDRESS_LIST= 
     (OBLB_STRATEGY=RANDOM)
     (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.20)(port=2883)) 
     (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.26)(port=2883))
     (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.32)(port=2883))
  )
  (ADDRESS_LIST= 
     (OBLB_STRATEGY=RANDOM)
     (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.36)(port=2883)) 
     (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.37)(port=2883))
     (ADDRESS=(PROTOCOL=tcp)(HOST=10.xx.xx.38)(port=2883))
   )
   (CONNECT_DATA=(SERVICE_NAME=test_user))
)

SERVICE_NAME建议修改为相应的schema 名称。

应用连接通过JDBC Load Balance分组配置实现主备切换的自动连接。

JDBC url 连接配置

url=jdbc:oceanbase:oracle:loadbalance//@TNS_SVC_GROUP/test_user?useUnicode=true&characterEncoding=gbk&nCharacterEncoding=utf8&useServerPrepStmts=true&useOraclePrepareExecute=true&continueBatchOnError=false&useArrayBinding=true&prepStmtCacheSize=1000&usePieceData=true&useCompatibleMetadata=true&autoReconnect=true

# 连接用户名  @SERVICE:
username=test_user@SERVICE:srv_ob_test

常见问题 FAQ

未设置环境变量OCEANBASE_TNS_ADMIN报错异常如下：

数据库连接失败: Unknown TNS_ADMIN specified 
10:10:18.419 [Druid-ConnectionPool-Create-592617454] ERROR com.alibaba.druid.pool.DruidDataSource - create connection SQLException, url: jdbc:oceanbase:loadbalance://@TNS_TEST_GROUP/test?useSSL=false&useUnicode=true&characterEncoding=utf-8&autoReconnect=true&log=true, errorCode 0, state null
java.sql.SQLException: Unknown TNS_ADMIN specified 
        at com.oceanbase.jdbc.internal.failover.utils.ConfigParser.getTnsFilePath(ConfigParser.java:493)
        at com.oceanbase.jdbc.internal.failover.utils.ConfigParser.getLoadBalanceInfoFromTns(ConfigParser.java:322)
        at com.oceanbase.jdbc.internal.failover.impl.MastersFailoverListener.getGlobalLoadBalanceInfo(MastersFailoverListener.java:280)
        at com.oceanbase.jdbc.internal.failover.impl.MastersFailoverListener.reconnectFailedConnection(MastersFailoverListener.java:216)
        at com.oceanbase.jdbc.internal.failover.impl.MastersFailoverListener.initializeConnection(MastersFailoverListener.java:103)
        at com.oceanbase.jdbc.internal.failover.FailoverProxy.(FailoverProxy.java:122)
        at com.oceanbase.jdbc.internal.util.Utils.retrieveProxy(Utils.java:1428)
        at com.oceanbase.jdbc.OceanBaseConnection.newConnection(OceanBaseConnection.java:393)
        at com.oceanbase.jdbc.Driver.connect(Driver.java:93)
        at com.alibaba.druid.pool.DruidAbstractDataSource.createPhysicalConnection(DruidAbstractDataSource.java:1690)
        at com.alibaba.druid.pool.DruidAbstractDataSource.createPhysicalConnection(DruidAbstractDataSource.java:1811)
        at com.alibaba.druid.pool.DruidDataSource$CreateConnectionThread.run(DruidDataSource.java:2793)
10:10:18.419 [Druid-ConnectionPool-Create-592617454] INFO com.alibaba.druid.pool.DruidAbstractDataSource - {dataSource-1} failContinuous is true

解决方案：

确保已正确设置环境变量OCEANBASE_TNS_ADMIN，指定tnsnames.ob配置文件所在目录；若使用 JVM 参数配置，需添加-Doceanbase.tns_admin=/home/appdy/oceanbase。

以上就是基于 Service Name 的 OceanBase 主备租户切换全攻略，如果你在配置过程中遇到其他问题，或是有独到的优化经验，欢迎在评论区留言分享，下次见！

OB混合云支持服务

OB公有云支持服务

综合服务

解决方案