一、问题背景

写在前面

在 Ambari v2.1.0 及之前版本中，使用 sqlline.py 连接 Phoenix 往往会出现卡死现象。
该问题出现在 HBase 与 Phoenix 的集成层，和配置文件中 classpath 的错误引用密切相关。

二、问题复现过程

在安装了 Phoenix Client 的机器上，直接执行：

/usr/bigtop/current/phoenix-client/bin/sqlline.py dev1:2181:/ams-hbase-unsecure

终端输出如下：

root@dev1:~# /usr/bigtop/current/phoenix-client/bin/sqlline.py dev1:2181:/ams-hbase-unsecure
Setting property: [incremental, false]
Setting property: [isolation, TRANSACTION_READ_COMMITTED]
issuing: !connect -p driver org.apache.phoenix.jdbc.PhoenixDriver -p user "none" -p password "none" "jdbc:phoenix:dev1:2181:/ams-hbase-unsecure"
Connecting to jdbc:phoenix:dev1:2181:/ams-hbase-unsecure
25/09/09 01:48:45 WARN util.NativeCodeLoader: Unable to load native-hadoop library for your platform... using builtin-java classes where applicable

此时命令行会完全卡住，既不会报错，也不会进入交互式界面。

三、排查思路

1. 初步怀疑方向

• 网络问题：Zookeeper 或 HBase 连接不通？
• 权限问题：是否有访问 /ams-hbase-unsecure 的权限？
• 依赖缺失：是否缺少 phoenix-client.jar 或 hbase-site.xml？

但以上排查均未发现异常，说明问题更深层。

2. 日志与源码对比

通过查看 hbase-env.sh，发现配置中对 Phoenix 的依赖 jar 默认写的是 phoenix-client.jar：

# 默认配置
export HBASE_CLASSPATH=$HBASE_CLASSPATH:/usr/bigtop/current/phoenix-client/phoenix-client.jar

进一步阅读 Phoenix 源码与官方文档发现：

• phoenix-client.jar 是一个 轻量级客户端 jar，缺少部分嵌入式依赖（尤其是 JDBC 相关类加载）。
• phoenix-server.jar 才包含了完整的类和资源，能保证 sqlline 启动不阻塞。

这就解释了为什么 sqlline 一直卡死： 驱动加载被卡在类初始化阶段，既不抛错，也不返回。

四、解决方案

修改 hbase-env.sh 配置，将 phoenix-client.jar 替换为 phoenix-server.jar：

# 注释掉原配置
# export HBASE_CLASSPATH=$HBASE_CLASSPATH:/usr/bigtop/current/phoenix-client/phoenix-client.jar

# 替换为 server 版本
export HBASE_CLASSPATH=$HBASE_CLASSPATH:/usr/bigtop/current/phoenix-client/phoenix-server.jar

保存文件后，执行以下步骤：

# 重启 HBase 服务
ambari-server restart   # 或者手动重启 hbase-regionserver、master

五、验证结果

再次执行 sqlline.py：

/usr/bigtop/current/phoenix-client/bin/sqlline.py dev1:2181:/ams-hbase-unsecure

这次可以顺利进入交互式命令行：