OBClient 多 IP 自动连接教程！OceanBase 运维告别手动切 IP

今天给大家带来OBClient 多 IP 自动切换连接完整版配置教程，高可用容错，解决集群连接难题！

一、基础说明

• 适用版本： OBClient V1.4.x、V2.1.x、V2.2.x、V3.1.x、V3.2.x、V4.0.x、V4.1.x、V4.2.x；OceanBase 数据库全版本

• 核心说明： OBClient 原生仅支持单 IP+Port 连接，OBClient V2.2.4 及以上版本新增 --ob-service-name 选项，支持多 IP 自动切换连接，解决分布式集群连接不便问题

二、背景说明

当前 OBClient/MySQL 客户端工具仅支持通过 -h -P 指定单个 IP+Port 连接。在分布式集群多 IP 配置场景下，若指定 IP 连接失败，需手动/代码切换 IP，使用体验较差。

三、操作步骤

步骤1：安装指定版本 OBClient

在客户端服务器通过 rpm/yum 命令安装 OBClient V2.2.4 及以上版本。

步骤2：配置 tnsnames.ora 文件

1. 进入指定路径（路径可自定义，示例为 /data/）

[root@xxxxx ~]# cd /data/

1. 创建/编辑 tnsnames.ora 文件（文件名固定，不可修改） 执行以下命令编辑文件（若文件不存在则自动创建）：

[root@xxxxx ~]# vi tnsnames.ora

1. 写入标准配置内容 配置示例如下，可根据实际集群 IP、端口、服务名修改：

   MYTEST=
   (DESCRIPTION=
     (ADDRESS_LIST=
       (ADDRESS=(PROTOCOL=tcp)(HOST=192.xxx.xxx.46)(PORT=2883)(WEIGHT=1))
       (ADDRESS=(PROTOCOL=tcp)(HOST=192.xxx.xxx.47)(PORT=2883)(WEIGHT=1))
       (ADDRESS=(PROTOCOL=tcp)(HOST=192.xxx.xxx.48)(PORT=2883)(WEIGHT=1)))
     (CONNECT_DATA=(SERVICE_NAME=TEST))
   )

注：SERVICE_NAME=TEST中 ‘TEST’ 是Oracle租户的用户名，或者MySQL租户的库名。

1. 关键配置说明

   • MYTEST：后续 --ob-service-name 选项的取值，需与配置文件中名称一致
   • ADDRESS_LIST：配置集群多个 IP+Port 地址，可按需增删
   • WEIGHT：权重值，用于连接优先级分配（示例中均为1，权重相同）
   • SERVICE_NAME：OceanBase 数据库的服务名，需与集群实际配置匹配

步骤3：配置环境变量 TNS_ADMIN

设置环境变量，指定 tnsnames.ora 文件所在路径，命令如下（路径与步骤2一致）：

[root@xxxxx ~]# export TNS_ADMIN=/data

> 说明：该环境变量仅对当前终端会话生效；若需永久生效，可将命令写入 /etc/profile 或用户目录下的 .bashrc 文件，执行 source 命令生效。

步骤4：执行多 IP 连接命令

使用 OBClient 连接命令，结合 --ob-service-name 选项实现多 IP 自动切换连接，完整命令示例：

obclient -h192.xxx.xxx.46,192.xxx.xxx.47,192.xxx.xxx.48 -uroot@sys#xxxxx -P2883 -pxxx -A -c --ob-service-name=MYTEST

命令参数说明

步骤5：验证多 IP 自动切换功能

1. 模拟 IP 连接失败 停止 OBProxy 进程，模拟其中一个 IP 无法连通：

[admin@xxxxx ~]$ /opt/taobao/install/obproxy-4.2.1.0/bin/obproxyd.sh -c stop

验证进程已停止：

[admin@xxxxx ~]$ ps -ef | grep obproxy

无 obproxy 进程则表示模拟成功。

1. 执行连接命令测试 再次执行步骤4的连接命令，观察输出结果：

[root@xxxxx ~]# obclient -h192.xxx.xxx.46,192.xxx.xxx.47,192.xxx.xxx.48 -uroot@sys#xxxxx -P2883 -pxx -A -c --ob-service-name=MYTEST

1. 验证结果 若命令成功登录，且 Connection 字段显示为其他可用 IP（如示例中的192.xxx.xxx.47），则说明多 IP 自动切换功能生效；仅当所有 IP 均无法连接时，才会返回连接错误。

四、连接成功验证

执行 \s 命令查看连接详情，确认连接状态、服务器版本、字符集等信息正常，示例输出核心片段：

obclient [(none)]> \s
--------------
obclient  Ver 2.2.4 Distrib 10.4.18-MariaDB, for Linux (aarch64) using readline 5.1

Connection id:          206544
Current user:           root@192.xxx.xxx.46
Server version:         OceanBase 4.2.1.3 (r103050012024012511-44db4190d80efddf8db98d564d661fa9417b63a6)
Connection:             192.xxx.xxx.46 via TCP/IP
--------------

五、注意事项

1. 版本要求：仅 OBClient V2.2.4 及以上版本支持 --ob-service-name 多 IP 自动切换功能，低版本无此特性。
2. 文件路径：tnsnames.ora 文件名固定，不可修改；TNS_ADMIN 环境变量需指向该文件所在目录，而非文件本身。
3. 网络连通性：需确保客户端与集群所有 IP 地址的端口（2883）网络互通，否则即使自动切换，也可能全部连接失败。
4. 权限配置：执行 OBClient 命令的用户需具备数据库连接权限，tnsnames.ora 文件需有可读权限。
5. 环境变量持久化：若需长期使用，建议将 export TNS_ADMIN=xxx 写入系统环境配置文件并生效，避免每次登录都需手动设置。