首批通过分布式安全可靠测评，为关键业务系统打造
负载均衡策略配置方式
更新时间：2026-07-22 17:45:58
编辑
分享
负载均衡策略可以使用 URL 进行配置，也可以使用配置文件进行配置。
使用 URL 的配置方式
用户可以在 OceanBase Connector/J 连接 URL 中的拓展信息 ExtendDescription 字段中配置 LoadBalance 的信息。默认的配置方式如下:
jdbc:oceanbase:[loadbalance:]//@[ExtendDescription]|<hostDescription>[,<hostDescription>...]]/[database][?<key1>=<value1>[&<key2>=<value2>]]
其中 ExtendDescription 字段的配置信息的参考示例如下:
注意
每个配置信息都有一个特定的 NET_SERVICE_NAME。
(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=SERVERAFFINITY)
(ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1)(WEIGHT=1))
(ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port2)(WEIGHT=10))
)
(ADDRESS_LIST=
(OBLB_STRATEGY=RANDOM)
(ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3))
(ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
)
(ADDRESS_LIST=
(OBLB_STRATEGY=ROTATION)
(ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3))
(ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
)
(CONNECT_DATA=(SERVICE_NAME=OBDATABASE))
)
)
完整示例如下：
String 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=SERVERAFFINITY)
(ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1)(WEIGHT=1))
(ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port2)(WEIGHT=10))
)
(ADDRESS_LIST=
(OBLB_STRATEGY=RANDOM)
(ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3))
(ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
)
(ADDRESS_LIST=
(OBLB_STRATEGY=ROTATION)
(ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3))
(ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
)
(CONNECT_DATA=(SERVICE_NAME=OBDATABASE))
))/OBDATABASE?rewriteBatchedStatements=true&allowSendParamTypes=true&prepStmtCacheSize=1000";
Connection = DriverManager.getConnection(url);
用户也可以通过URL Option 的拓展方式配置负载均衡策略。相关配置项如下表所示。
说明
OceanBase Connector/J 建议您使用 URL Option 扩展配置方式，在 JDBC URL 中可以填写相应的配置。
| 字段名称 | 含义 | 备注 |
|---|---|---|
| retriesAllDown | 当可用的数据库节点均连接失败时，尝试连接的最大次数。默认值是 120 次。 | 该字段与拓展配置信息中的 RETRY_ALL_DOWNS 字段含义相同，拓展配置信息中的配置会覆盖掉 URL 中的配置。 |
| loadBalanceStrategy | 策略包括 RANDOM、ROTATION 和 SERVERAFFINITY。 |
无 |
| serverAffinityOrder | 在负载平衡 SERVERAFFINITY 策略中所使用的主机和端口号对的逗号分隔列表。仅会使用此 URL 的主机 Host 部分中所列举的主机子集，并且它们的大小写和类型必须相同，即不能在一处使用 IP 地址，而在另一处使用相应的主机名。 |
无 |
| loadBalanceBlacklistTimeout | 节点黑名单的超时时间，单位为毫秒。当配置为正整数时，才启用黑名单机制，即当某个连接失败时，将 Host 加入到黑名单。默认值为 0，表示不启用黑名单。 | 无 |
示例如下：
"jdbc:oceanbase:loadbalance://host1:port1:5,host2:port2:10/" + "test?user=test@oracle&password=test"
"jdbc:oceanbase:loadbalance://host1:port1,host2:port2/" + "test?user=test@oracle&password=test&loadBalanceStrategy=serverAffinity&serverAffinityOrder=host1:port1:5,host2:port2:10"
"jdbc:oceanbase:loadbalance://host1:port1:5,host2:port2:10/" + "test?user=test@oracle&password=test&loadBalanceStrategy=serverAffinity&serverAffinityOrder=host1:port1:5,host2:port2:10"
使用配置文件的方式
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。
配置文件内容
配置文件内容与拓展配置信息内容格式保持一致，但是每个配置文件可以包含多个 DESCRIPTION 且每个 DESCRIPTION 隶属于一个 NET_SERVICE_NAME。
如下示例中，配置文件中包含 TNS_TEST_NORMAL、TNS_TEST_WEIGHT 和 TNS_TEST_GROUP 三个 NET_SERVICE_NAME。
TNS_TEST_NORMAL=
(DESCRIPTION=
(ADDRESS_LIST =
(OBLB_STRATEGY=RANDOM)
(ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1))
(ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port1))
(CONNECT_DATA=(SERVICE_NAME=ORCLCDB))
)
)
TNS_TEST_WEIGHT=
(DESCRIPTION=
(ADDRESS_LIST =
(OBLB_STRATEGY=SERVERAFFINITY)
(ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1)(WEIGHT=4))
(ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port2)(WEIGHT=10))
(CONNECT_DATA=(SERVICE_NAME=ORCLCDB))
)
)
TNS_TEST_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=SERVERAFFINITY)
(ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1)(WEIGHT=1))
(ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port2)(WEIGHT=10))
)
(ADDRESS_LIST=
(OBLB_STRATEGY=RANDOM)
(ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3))
(ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
)
(ADDRESS_LIST=
(OBLB_STRATEGY=ROTATION)
(ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3))
(ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
)
(CONNECT_DATA=(SERVICE_NAME=OBDATABASE))
)
基本使用示例
OceanBase Connector/J 的 LoadBalance 拓展配置信息的基本使用示例如下：
String connU = "jdbc:oceanbase:loadbalance://@TNS_TEST_NORMAL/test?rewriteBatchedStatements=true&allowSendParamTypes=true&prepStmtCacheSize=1000&prepStmtCacheSqlLimit=4096&cachePrepStmts=true";
Connection sharedConnection = DriverManager.getConnection(connU, "usr", "password");
上述示例的 URL 中主要包含如下关键信息：
jdbc:oceanbase:loadbalance表示使用 loadBalance 模式，是必选项。@TNS_TEST_NORMAL指定了NET_SERVICE_NAME，如果一个文件包含多个NET_SERVICE_NAME，则要使用此名字来区分并以@开头。
TNS_TEST_NORMAL 最简配置（使用默认策略和配置）示例如下：
TNS_TEST_NORMAL=
(DESCRIPTION=
(ADDRESS_LIST =
(ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1))
(ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port2))
(CONNECT_DATA=(SERVICE_NAME=ORCLCDB))
)
)
