一、基础说明
二、背景说明
当前 OBClient/MySQL 客户端工具仅支持通过 -h -P 指定单个 IP+Port 连接。在分布式集群多 IP 配置场景下，若指定 IP 连接失败，需手动/代码切换 IP，使用体验较差。
三、操作步骤
步骤1：安装指定版本 OBClient
在客户端服务器通过 rpm/yum 命令安装 OBClient V2.2.4 及以上版本。
步骤2：配置 tnsnames.ora 文件
-
进入指定路径（路径可自定义，示例为 /data/）
[root@xxxxx ~]# cd /data/
-
创建/编辑 tnsnames.ora 文件（文件名固定，不可修改）
执行以下命令编辑文件（若文件不存在则自动创建）：
[root@xxxxx ~]# vi tnsnames.ora
-
写入标准配置内容
配置示例如下，可根据实际集群 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租户的库名。
-
关键配置说明
-
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
命令参数说明
| 参数 |
说明 |
-h |
集群多个 IP 地址，用英文逗号分隔 |
-u |
数据库用户名（示例：root@sys#xxxxx，需替换为实际账号） |
-P |
数据库端口（OceanBase 常用端口2883） |
-p |
数据库密码（示例：xxx，需替换为实际密码） |
-A |
自动补全功能（可选） |
-c |
保留注释（可选） |
--ob-service-name |
指定 tnsnames.ora 中配置的服务名（MYTEST） |
步骤5：验证多 IP 自动切换功能
-
模拟 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 进程则表示模拟成功。
-
执行连接命令测试
再次执行步骤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
-
验证结果
若命令成功登录，且 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
--------------
五、注意事项
-
版本要求：仅 OBClient V2.2.4 及以上版本支持
--ob-service-name 多 IP 自动切换功能，低版本无此特性。
-
文件路径：
tnsnames.ora 文件名固定，不可修改；TNS_ADMIN 环境变量需指向该文件所在目录，而非文件本身。
-
网络连通性：需确保客户端与集群所有 IP 地址的端口（2883）网络互通，否则即使自动切换，也可能全部连接失败。
-
权限配置：执行 OBClient 命令的用户需具备数据库连接权限，tnsnames.ora 文件需有可读权限。
-
环境变量持久化：若需长期使用，建议将
export TNS_ADMIN=xxx 写入系统环境配置文件并生效，避免每次登录都需手动设置。
如果你在实际操作中遇到问题，可以在评论区留言交流。后续我们会持续分享更多运维干货，记得关注不迷路，下次见~
