Ubuntu 22.04 安装 Apache Phoenix 5.2 指南

目标：本文解决在 Ubuntu 22.04 服务器上从零安装 Apache Phoenix 5.2.1（HBase 之上的 SQL 层，配 HBase 2.4.18 与 JDK 11）的问题，覆盖官方 tar.gz 全新部署与既有 HBase 叠加两种方案、单机模式配置、JVM 堆内存限制、SQL 功能验证与常见故障排障；全部命令与回显已在 Ubuntu 22.04.5 LTS（root 用户）实测通过。

一、环境信息

项	值
操作系统	Ubuntu 22.04.5 LTS（x86_64，内核 6.8 系列）
账号	root
JDK	OpenJDK 11.0.32.1（`JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64`）
HBase	2.4.18（安装目录 `/opt/hbase`，单机 standalone 模式，本地文件系统）
Phoenix	5.2.1（安装目录 `/opt/phoenix`，sqlline version 1.9.0）
监听端口	2181（内嵌 ZooKeeper）、16000（HBase Master RPC）、16010（Master Web UI）、16020（RegionServer RPC）、16030（RegionServer Web UI）
数据目录	HBase 单机模式下数据落在安装目录 `./tmp`（即 `/opt/hbase/tmp`）
下载源目录	`/opt/src`

二、前置条件

Phoenix 是 HBase 之上的 SQL 层，本组件为 A 部署类（依赖 HBase），安装前需先准备 JDK 与基础工具：

更新 apt 源并安装依赖（openjdk-11-jdk-headless、wget、tar、python3、python-is-python3；Phoenix 的 sqlline.py/psql.py 脚本依赖 Python 3，实测 Python 3.10.12）：

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-11-jdk-headless wget tar python3 python-is-python3

验证 JDK 版本：

java -version

openjdk version "11.0.32.1" 2026-08-18
OpenJDK Runtime Environment (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu, mixed mode, sharing)

确认 JAVA_HOME 指向（HBase 2.4+ 支持 JDK 8/11，建议 JDK 11）：

echo $JAVA_HOME

/usr/lib/jvm/java-11-openjdk-amd64

⚠️ 注意：若 JAVA_HOME 未设置，请写入 /etc/profile（或 ~/.bashrc）并重新登录：export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64。HBase 与 Phoenix 都是 Java 进程，必须显式指定 JDK 路径。

三、版本选型说明

Phoenix 与 HBase 强绑定：Phoenix 客户端/服务端 jar 必须与 HBase 大版本匹配，选型错误会导致建表/查询报错。

项	说明
本指南选型	Phoenix 5.2.1 + HBase 2.4.18 + JDK 11
Phoenix 5.2.1 支持的 HBase	2.4 / 2.5 / 2.5.0 / 2.6
官方版本源	`https://downloads.apache.org/phoenix/`（现有 4.16.1 / 5.1.2 / 5.1.3 / 5.2.0 / 5.2.1 / 5.2.2 / 5.3.0 / 5.3.1 / 5.3.2）
HBase 归档源	`https://archive.apache.org/dist/hbase/`（2.4.x 最新为 2.4.18）

包名变化说明：Phoenix 5.2.1 起发布包改名为 phoenix-hbase-<hbase版本>-<phoenix版本>-bin.tar.gz（如 phoenix-hbase-2.4-5.2.1-bin.tar.gz）；旧版本命名不同（如 5.2.0 的 phoenix-5.2.0-HBase-2.3-bin.tar.gz）。下载时务必按新命名取包。

💡 说明：选择哪个 HBase 版本，取决于你的数据规模与现有集群。全新部署建议选 HBase 2.4.x（2.4.18 为归档源最新）；若已有 HBase 集群，则按「方案 B」叠加 Phoenix 层，Phoenix 版本选与 HBase 匹配的 5.2.x。

四、部署方案 A：官方 tar.gz 全新部署（推荐）

4.1 方案说明

方案 A 从零开始：下载 HBase 2.4.18 与 Phoenix 5.2.1 两个官方 tar.gz，解压到 /opt/hbase、/opt/phoenix，配置单机模式后启动，用 sqlline 完成 SQL 验证。适用于无既有 HBase 环境的全新服务器（开发/测试首选）。

4.2 下载软件包

在 /opt/src 下下载两个安装包（HBase 282M、Phoenix 352M）：

mkdir -p /opt/src && cd /opt/src
wget -q https://archive.apache.org/dist/hbase/2.4.18/hbase-2.4.18-bin.tar.gz
wget -q https://downloads.apache.org/phoenix/phoenix-5.2.1/phoenix-hbase-2.4-5.2.1-bin.tar.gz

💡 说明：两个包实测大小分别为 282M（HBase）、352M（Phoenix），下载后可用 ls -lh /opt/src 核对文件名。

4.3 解压安装

tar -zxf /opt/src/hbase-2.4.18-bin.tar.gz -C /opt && mv /opt/hbase-2.4.18 /opt/hbase
tar -zxf /opt/src/phoenix-hbase-2.4-5.2.1-bin.tar.gz -C /opt && mv /opt/phoenix-* /opt/phoenix

💡 说明：tar 解压后顶层目录名可能为 hbase-2.4.18、phoenix-hbase-2.4-5.2.1-bin 等，解压后统一重命名为 /opt/hbase、/opt/phoenix，便于后续引用与配置。

验证安装目录内容（HBase lib 前 6 个 jar、Phoenix bin 下的核心脚本）：

ls /opt/hbase/lib | head -6
ls /opt/phoenix/bin | grep -E "sqlline.py|psql.py"

HikariCP-java7-2.4.12.jar
aopalliance-1.0.jar
apacheds-i18n-2.0.0-M15.jar
apacheds-kerberos-codec-2.0.0-M15.jar
api-asn1-api-1.0.0-M20.jar
api-i18n-1.0.0-M20.jar
psql.py
sqlline.py

4.4 配置 JAVA_HOME（hbase-env.sh）

编辑 /opt/hbase/conf/hbase-env.sh，显式设置 JDK 路径：

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

4.5 确认单机模式配置（hbase-site.xml）

HBase 2.4.18 默认即单机（standalone）模式，/opt/hbase/conf/hbase-site.xml 默认关键项如下（本地文件系统，无需 HDFS）：

<property>
  <name>hbase.cluster.distributed</name>
  <value>false</value>          <!-- false = 单机独立模式 -->
</property>
<property>
  <name>hbase.tmp.dir</name>
  <value>./tmp</value>
</property>
<property>
  <name>hbase.unsafe.stream.capability.enforce</name>
  <value>false</value>          <!-- 允许本地文件系统运行；生产集群禁止 -->
</property>

⚠️ 注意：hbase.cluster.distributed=false + 本地文件系统（LocalFileSystem）仅限开发/测试，不可用于生产。生产请按《Apache Phoenix 5.2 配置参数详解》篇调整。

4.6 限制 JVM 堆内存（HBASE_HEAPSIZE）

HBase/Phoenix 均为 Java 进程，为控制资源占用，堆内存统一限制在 256–512MB 区间。编辑 /opt/hbase/conf/hbase-env.sh，把注释的 HBASE_HEAPSIZE 打开并改为 512m：

export HBASE_HEAPSIZE=512m

改完先验证配置行，再重启 HBase 使生效：

grep -n "HBASE_HEAPSIZE" /opt/hbase/conf/hbase-env.sh

34:export HBASE_HEAPSIZE=512m

启动后验证实际生效的堆参数（jps -v 与 ps -ef 均可看到 -Xmx512m）：

jps -v | grep HMaster

6081 HMaster -Dproc_master -XX:OnOutOfMemoryError=kill -9 %p -Xmx512m -XX:+UseG1GC
（其余 JVM 参数省略；关键看 -Xmx512m）

ps -ef | grep [j]ava

root        6081    6079  4 11:15 ?        00:00:43 /usr/lib/jvm/java-11-openjdk-amd64/bin/java -Dproc_master -XX:OnOutOfMemoryError=kill -9 %p -Xmx512m -XX:+UseG1GC

💡 说明：ps -ef 完整命令行较长（后面还有大量 --add-opens/--add-exports JVM 参数与 -Dhbase.log.dir 等），关键确认两点：Java 路径为 JDK 11，且命令行含 -Xmx512m。

4.7 复制 Phoenix server jar 到 HBase lib

Phoenix 以协处理器（coprocessor）方式接入 HBase，必须把 phoenix-server-hbase-2.4-5.2.1.jar 复制到 HBase 的 lib 目录，先复制、后启动（或重启）HBase：

cp /opt/phoenix/phoenix-server-hbase-2.4-5.2.1.jar /opt/hbase/lib/
ls /opt/hbase/lib | grep phoenix

phoenix-server-hbase-2.4-5.2.1.jar

4.8 启动 HBase

export HBASE_HOME=/opt/hbase
/opt/hbase/bin/start-hbase.sh

running master, logging to /opt/hbase/logs/hbase--master-<hostname>.out

💡 说明：HBase 通过 start-hbase.sh shell 脚本启动（不需要 systemd 托管也可运行）；单机模式下 Master 进程内同时承载 RegionServer 职责（本地文件系统）。

4.9 验证进程与端口

jps

6081 org.apache.hadoop.hbase.master.HMaster
6519 jdk.jcmd/sun.tools.jps.Jps

监听端口确认（单机模式自带内嵌 ZooKeeper）：

端口	用途
2181	HBase 内嵌 ZooKeeper（sqlline 连接入口）
16000	HBase Master RPC
16010	HBase Master Web UI
16020	RegionServer RPC
16030	RegionServer Web UI

💡 说明：sqlline 只需连 ZooKeeper 仲裁（localhost:2181）即可访问 Phoenix。

4.10 SQL 功能验证（sqlline）

启动 sqlline 客户端连接（注意非 TTY 下先调整列宽，否则列会被压缩为空）：

/opt/phoenix/bin/sqlline.py localhost:2181

进入交互终端后按顺序执行（!set 为 sqlline 元命令）：

sqlline version 1.9.0
0: jdbc:phoenix:localhost:2181> !set maxwidth 200;
0: jdbc:phoenix:localhost:2181> !set maxcolumnwidth 30;
0: jdbc:phoenix:localhost:2181> CREATE TABLE IF NOT EXISTS user (id INTEGER PRIMARY KEY, name VARCHAR);
No rows affected (0.787 seconds)
0: jdbc:phoenix:localhost:2181> UPSERT INTO user VALUES (1, 'Alice');
1 row affected (0.069 seconds)
0: jdbc:phoenix:localhost:2181> SELECT id, name FROM user;
+----+-------+
| ID | NAME  |
+----+-------+
| 1  | Alice |
+----+-------+
1 row selected (0.065 seconds)

查看表清单（含 SYSTEM 系列系统表与用户表）：

0: jdbc:phoenix:localhost:2181> !tables
+-----------+-------------+------------+--------------+---------+-----------+---------------------------+----------------+-------------+----------------+--------------+--------------+----------------+
| TABLE_CAT | TABLE_SCHEM | TABLE_NAME |  TABLE_TYPE  | REMARKS | TYPE_NAME | SELF_REFERENCING_COL_NAME | REF_GENERATION | INDEX_STATE | IMMUTABLE_ROWS | SALT_BUCKETS | MULTI_TENANT | VIEW_STATEMENT |
+-----------+-------------+------------+--------------+---------+-----------+---------------------------+----------------+-------------+----------------+--------------+--------------+----------------+
|           | SYSTEM      | CATALOG    | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | CHILD_LINK | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | FUNCTION   | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | LOG        | SYSTEM TABLE |         |           |                           |                |             | true           | 32           | false        |                |
|           | SYSTEM      | MUTEX      | SYSTEM TABLE |         |           |                           |                |             | true           | null         | false        |                |
|           | SYSTEM      | SEQUENCE   | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | STATS      | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | TASK       | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | TRANSFORM  | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           |             | USER       | TABLE        |         |           |                           |                |             | false          | null         | false        |                |
+-----------+-------------+------------+--------------+---------+-----------+---------------------------+----------------+-------------+----------------+--------------+--------------+----------------+

建表、写入、查询、表清单全部正常即安装成功；退出用 !quit。

五、部署方案 B：既有 HBase 2.4 集群叠加 Phoenix

5.1 方案说明

若服务器上已运行 HBase 2.4.x 集群（含生产集群），无需重装 HBase，只需下载 Phoenix 二进制包并叠加 SQL 层：Phoenix 服务端以协处理器随 HBase 加载，客户端用 sqlline/psql 访问。

5.2 下载并解压 Phoenix

mkdir -p /opt/src && cd /opt/src
wget -q https://downloads.apache.org/phoenix/phoenix-5.2.1/phoenix-hbase-2.4-5.2.1-bin.tar.gz
tar -zxf phoenix-hbase-2.4-5.2.1-bin.tar.gz -C /opt && mv /opt/phoenix-* /opt/phoenix

5.3 复制 server jar 并重启 HBase

cp /opt/phoenix/phoenix-server-hbase-2.4-5.2.1.jar /opt/hbase/lib/
ls /opt/hbase/lib | grep phoenix

phoenix-server-hbase-2.4-5.2.1.jar

⚠️ 注意：复制 jar 后必须重启 HBase（HMaster 与各 RegionServer）才能加载 Phoenix 协处理器；多节点集群需在每个节点重复上述复制操作，并逐台重启。

重启 HBase（单机为例；集群请逐节点执行对应脚本）：

/opt/hbase/bin/stop-hbase.sh
/opt/hbase/bin/start-hbase.sh

stopping hbase..............
running master, logging to /opt/hbase/logs/hbase--master-<hostname>.out

5.4 验证

与方案 A 4.10 相同：sqlline.py localhost:2181 执行 CREATE TABLE/UPSERT/SELECT，回显一致即叠加成功。若 HBase 使用独立 ZooKeeper 集群，连接串改为 <zk1>:2181,<zk2>:2181,<zk3>:2181。

六、方案对比与选择建议

维度	方案 A：tar.gz 全新部署	方案 B：既有 HBase 叠加
是否需要既有 HBase	否（一并安装 HBase 2.4.18）	是（HBase 2.4.x 已在运行）
是否联网	是（官方源下载）	是（仅下载 Phoenix 包）
操作量	大（下载两个包 + 配置 + 启动）	小（下载一个包 + 复制 jar + 重启）
生产适用性	仅限开发/测试（standalone 本地文件系统）	适合生产（叠加到现有分布式集群）
典型场景	新服务器、学习验证、功能联调	存量 HBase 集群上 SQL 化

选择建议：全新环境、以学习和功能验证为目的 → 方案 A；已有 HBase 2.4.x 集群、需要在生产环境使用 SQL → 方案 B（多节点复制 jar 并逐台重启）。

七、配置说明

7.1 配置文件位置

文件	路径	作用
HBase 主配置	`/opt/hbase/conf/hbase-site.xml`	集群模式、数据目录、ZooKeeper 等
HBase 环境脚本	`/opt/hbase/conf/hbase-env.sh`	`JAVA_HOME`、`HBASE_HEAPSIZE`（JVM 堆）
Phoenix 客户端	`sqlline.py`/`psql.py` 所在目录的环境变量 `PHOENIX_OPTS`	客户端 JVM 参数（堆内存等）
日志	`/opt/hbase/logs/hbase--master-<hostname>.log`	Master 运行日志、排障入口

7.2 客户端 JVM 堆限制（PHOENIX_OPTS）

sqlline.py/psql.py 脚本会把环境变量 PHOENIX_OPTS 拼进 Java 启动命令（实测 sqlline.py 脚本内含 ' $PHOENIX_OPTS ' 拼接）。将客户端堆限制在 256MB：

PHOENIX_OPTS="-Xms256m -Xmx256m" /opt/phoenix/bin/sqlline.py localhost:2181

💡 说明：服务端（HMaster/RegionServer）堆由 hbase-env.sh 的 HBASE_HEAPSIZE 控制（见 4.6，实测 -Xmx512m 生效）；客户端（sqlline/psql/应用 JDBC）堆由 PHOENIX_OPTS 控制。两端均不得沿用组件默认大堆。

7.3 常用配置键速览

配置键	实测值/说明
hbase.cluster.distributed	false（单机）；生产设 true
hbase.rootdir	`./tmp/hbase`（单机默认，实测）
hbase.zookeeper.quorum	127.0.0.1（单机默认，实测）
hbase.zookeeper.property.clientPort	2181（实测）
hbase.unsafe.stream.capability.enforce	false（单机本地文件系统必需；生产禁止）
phoenix.query.timeoutMs	默认 600000（10 分钟），客户端查询超时

完整参数与生产模板见同专栏《Apache Phoenix 5.2 配置参数详解》篇。

八、注意事项

版本强绑定：Phoenix 与 HBase 版本必须配套，Phoenix 5.2.1 需选 phoenix-server-hbase-2.4-*.jar 配 HBase 2.4.x（本环境 2.4.18）。
JDK 版本：HBase 2.4+ 支持 JDK 8/11；务必在 hbase-env.sh 显式设置 JAVA_HOME，否则启动失败或使用错误 JDK。
jar 复制顺序：先 cp phoenix-server-hbase-2.4-5.2.1.jar 到 /opt/hbase/lib/，再启动/重启 HBase；顺序颠倒则协处理器不加载。
单机模式仅限开发：hbase.cluster.distributed=false + 本地文件系统必须配 hbase.unsafe.stream.capability.enforce=false，该组合不可用于生产。
JVM 堆控制：HBase 与 Phoenix 进程堆统一限制在 256–512MB（服务端 HBASE_HEAPSIZE、客户端 PHOENIX_OPTS），改后需重启并用 jps -v/ps -ef 确认。
端口规划：单机模式占用 2181/16000/16010/16020/16030，部署前确认未被占用。

九、常见问题（FAQ）

Q1：sqlline 查询结果列全部是空白/被压缩。 非交互终端（如管道、脚本）下 sqlline 列宽会被压缩为空。执行 !set maxwidth 200; 与 !set maxcolumnwidth 30; 后重新查询即可正常显示。

Q2：首次连接报 Connection refused，随后又自动恢复。 首次连接 ZooKeeper 时偶现对 IPv6 地址（localhost/0:0:0:0:0:0:0:1:2181）的瞬时 Connection refused，客户端会自动重连（日志出现 Attempting reconnect WARN 后恢复），不影响建表/写入/查询，可忽略。

Q3：sqlline 连接超时或连不上。 先确认 HBase 已启动：jps 应看到 HMaster 进程；再确认 ss -ltn 中 2181 端口在监听；最后核对连接串是否为 localhost:2181（或 ZK 集群地址）。

Q4：建表报错提示找不到 Phoenix 协处理器。 说明 phoenix-server-hbase-2.4-5.2.1.jar 未生效：确认已复制到 /opt/hbase/lib/（ls /opt/hbase/lib | grep phoenix），并重启 HBase。

Q5：hbase 命令报 JAVA_HOME 相关错误。 在 /opt/hbase/conf/hbase-env.sh 中设置 export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 后重新启动。

Q6：start-hbase.sh 启动后 jps 看不到进程。 查看 /opt/hbase/logs/hbase--master-<hostname>.log 定位原因（常见为端口占用、JDK 版本不符、堆设置过小）。单机模式建议堆不低于 256m。

十、卸载方式

停止 HBase：

/opt/hbase/bin/stop-hbase.sh

确认进程退出：

jps

（无 HMaster 输出即已停止）

rm -rf /opt/phoenix /opt/hbase /opt/src

（可选）清理数据：单机模式数据在 /opt/hbase/tmp 下，随安装目录一并删除；若曾把 JAVA_HOME/HBASE_HOME 写入 /etc/profile，一并删除对应 export 行。

十一、参考链接

Apache Phoenix 官方下载页：https://downloads.apache.org/phoenix/
Apache Phoenix 官方文档：https://phoenix.apache.org/
HBase 归档下载：https://archive.apache.org/dist/hbase/
HBase 参考手册（配置与重要参数）：https://hbase.apache.org/book.html