Apache Phoenix 5.2 Docker Compose 部署指南

目标：本文解决用 Docker Compose 在 Ubuntu 22.04 服务器上编排部署 Apache Phoenix 5.2.1（配 HBase 2.4.18、JDK 11）的问题，覆盖镜像构建、数据卷与配置文件持久化、端口映射、健康检查、常用运维命令与故障排障；镜像内的安装步骤与 SQL 验证回显均已在 Ubuntu 22.04.5 实测通过。

一、环境信息

项	值
操作系统	Ubuntu 22.04.5 LTS（x86_64）
账号	root
Docker Engine / Compose	Docker 引擎 + `docker compose` v2 插件
基础镜像	ubuntu:22.04
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）
项目目录	`/opt/data/phoenix/`
数据卷	命名卷 `phoenix-data`（挂载容器内 `/opt/hbase/tmp`）
端口映射	2181（ZooKeeper）、16000（Master RPC）、16010（Master Web UI）、16020（RegionServer RPC）、16030（RegionServer Web UI）

二、镜像选型说明

Apache Phoenix 官方不发布 Docker 镜像，HBase 官方镜像也不包含 Phoenix 协处理器层。因此采用「基础系统镜像 + 官方二进制包」自行构建：以 ubuntu:22.04 为基础镜像，镜像内安装 JDK 11 与 Python 3，下载官方 HBase 2.4.18、Phoenix 5.2.1 tar.gz（与安装指南同一套实测产物），并把 phoenix-server-hbase-2.4-5.2.1.jar 复制进 HBase lib，最终镜像即为可直接运行的 Phoenix 单机实例。

💡 说明：构建参数 HBASE_VERSION、PHOENIX_VERSION 支持换版本；Phoenix 与 HBase 版本强绑定（Phoenix 5.2.1 配 HBase 2.4/2.5/2.6），换版本时需保证匹配。

三、前置条件

确认 Docker 引擎与 Compose 插件可用：

docker --version
docker compose version

确认宿主机端口 2181/16000/16010/16020/16030 未被占用（docker compose 启动时会映射这些端口）。
准备项目目录：

mkdir -p /opt/data/phoenix/conf

四、部署步骤

4.1 目录结构

/opt/data/phoenix/
├── Dockerfile
├── compose.yaml
└── conf/
    ├── hbase-env.sh
    └── hbase-site.xml

4.2 编写 Dockerfile

FROM ubuntu:22.04

ARG HBASE_VERSION=2.4.18
ARG PHOENIX_VERSION=5.2.1

RUN apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-11-jdk-headless wget tar python3 python-is-python3 && \
    mkdir -p /opt/src /opt/hbase /opt/phoenix && \
    wget -q -O /opt/src/hbase-$HBASE_VERSION-bin.tar.gz https://archive.apache.org/dist/hbase/$HBASE_VERSION/hbase-$HBASE_VERSION-bin.tar.gz && \
    wget -q -O /opt/src/phoenix-hbase-2.4-$PHOENIX_VERSION-bin.tar.gz https://downloads.apache.org/phoenix/phoenix-$PHOENIX_VERSION/phoenix-hbase-2.4-$PHOENIX_VERSION-bin.tar.gz && \
    tar -zxf /opt/src/hbase-$HBASE_VERSION-bin.tar.gz -C /opt && mv /opt/hbase-$HBASE_VERSION /opt/hbase && \
    tar -zxf /opt/src/phoenix-hbase-2.4-$PHOENIX_VERSION-bin.tar.gz -C /opt && mv /opt/phoenix-hbase-2.4-$PHOENIX_VERSION-bin /opt/phoenix && \
    cp /opt/phoenix/phoenix-server-hbase-2.4-$PHOENIX_VERSION.jar /opt/hbase/lib/ && \
    rm -rf /opt/src

ENV JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 \
    HBASE_HOME=/opt/hbase \
    PHOENIX_HOME=/opt/phoenix \
    PATH=$PATH:/opt/hbase/bin:/opt/phoenix/bin

EXPOSE 2181 16000 16010 16020 16030

CMD ["/bin/bash", "-c", "/opt/hbase/bin/start-hbase.sh && tail -F /opt/hbase/logs/hbase--master-*.out"]

4.3 编写 compose.yaml

services:
  phoenix:
    build:
      context: .
      args:
        HBASE_VERSION: 2.4.18
        PHOENIX_VERSION: 5.2.1
    container_name: phoenix-5-2-1
    hostname: phoenix-node1
    ports:
      - "2181:2181"
      - "16000:16000"
      - "16010:16010"
      - "16020:16020"
      - "16030:16030"
    environment:
      JAVA_HOME: /usr/lib/jvm/java-11-openjdk-amd64
      HBASE_HOME: /opt/hbase
      PHOENIX_HOME: /opt/phoenix
      HBASE_HEAPSIZE: "512m"
      PHOENIX_OPTS: "-Xms256m -Xmx256m"
      HBASE_CONF_DIR: /opt/hbase/conf-custom
    volumes:
      - phoenix-data:/opt/hbase/tmp
      - ./conf:/opt/hbase/conf-custom
    healthcheck:
      test: ["CMD-SHELL", "jps | grep -q HMaster"]
      interval: 15s
      timeout: 5s
      retries: 10

volumes:
  phoenix-data:

💡 说明：服务端堆由 HBASE_HEAPSIZE=512m 控制（镜像内 HBase 进程），客户端（sqlline/psql）堆由 PHOENIX_OPTS=-Xms256m -Xmx256m 控制，两端均限制在 256–512MB 区间。

4.4 编写配置目录 conf/

conf/hbase-site.xml（单机 standalone 模式，本地文件系统）：

<configuration>
  <property>
    <name>hbase.cluster.distributed</name>
    <value>false</value>
  </property>
  <property>
    <name>hbase.tmp.dir</name>
    <value>./tmp</value>
  </property>
  <property>
    <name>hbase.unsafe.stream.capability.enforce</name>
    <value>false</value>
  </property>
</configuration>

conf/hbase-env.sh（JDK 与堆设置）：

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

⚠️ 注意：hbase.cluster.distributed=false + 本地文件系统仅限开发/测试，生产请切换分布式模式并去掉 hbase.unsafe.stream.capability.enforce=false。

4.5 构建并启动

在 /opt/data/phoenix 目录下执行：

cd /opt/data/phoenix
docker compose up -d --build

查看状态（应为 running + healthy）：

docker compose ps

4.6 SQL 功能验证（sqlline）

进入实例执行 sqlline（容器内已含 Phoenix 客户端脚本）：

docker compose exec phoenix /opt/phoenix/bin/sqlline.py localhost:2181

在 sqlline 终端内依次执行（非 TTY 下先 !set 调整列宽）：

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。

五、数据持久化说明

挂载	类型	容器内路径	作用
`phoenix-data`	命名卷	`/opt/hbase/tmp`	HBase 单机模式的数据/元数据根目录（`hbase.tmp.dir=./tmp`），表数据、ZooKeeper 数据、WAL 均在此
`./conf`	绑定挂载	`/opt/hbase/conf-custom`	配置文件目录，宿主机直接编辑，重启容器生效

数据卷验证：写入数据后执行 docker compose restart phoenix，再查表数据仍在（实测重启后 SELECT 仍能读到 1 | Alice）。命名卷数据位于宿主机 Docker 数据目录，docker compose down 不会删除命名卷；如需彻底清理数据用 docker compose down -v。

六、常用环境变量表

环境变量	示例值	说明
`JAVA_HOME`	`/usr/lib/jvm/java-11-openjdk-amd64`	JDK 路径，HBase 与 Phoenix 均依赖
`HBASE_HOME`	`/opt/hbase`	HBase 安装目录
`PHOENIX_HOME`	`/opt/phoenix`	Phoenix 安装目录
`HBASE_HEAPSIZE`	`512m`	HBase 服务端 JVM 堆（限制 256–512MB）
`PHOENIX_OPTS`	`-Xms256m -Xmx256m`	Phoenix 客户端（sqlline/psql）JVM 参数
`HBASE_CONF_DIR`	`/opt/hbase/conf-custom`	HBase 配置目录覆盖（配合 `./conf` 挂载）

七、常用配置参数说明（command）

启动命令：镜像默认 CMD 为 start-hbase.sh 启动 HBase，随后 tail -F 跟随 master 日志使进程常驻（start-hbase.sh 本身启动后台守护进程后会返回，必须保活）。
健康检查：compose 中 healthcheck 每 15 秒执行 jps | grep -q HMaster，HMaster 进程存在即 healthy。
覆盖 command 调试：临时进入容器排查可覆盖默认命令，例如 docker compose run --rm phoenix /bin/bash。
Web UI：HBase Master Web UI 映射在宿主机 16010 端口，浏览器访问 http://<宿主机IP>:16010 可查看集群状态。

八、配置文件持久化（conf 挂载）

宿主机 ./conf 目录通过 HBASE_CONF_DIR=/opt/hbase/conf-custom 生效（HBase 脚本优先读取 $HBASE_CONF_DIR 下的 hbase-env.sh 与 hbase-site.xml）。修改配置流程：

vim /opt/data/phoenix/conf/hbase-site.xml     # 修改配置
docker compose restart phoenix                # 重启使生效

💡 说明：配置挂载与数据卷分离——数据卷只存数据，配置文件走绑定挂载，二者互不干扰；备份/迁移时分别处理 phoenix-data 卷与 ./conf 目录即可。

九、等价 docker run 运行方式

不使用 Compose 时，等价单容器命令如下（镜像需先构建）：

docker build -t phoenix-hbase-2.4:5.2.1 /opt/data/phoenix

docker run -d --name phoenix-5-2-1 \
  --hostname phoenix-node1 \
  -p 2181:2181 -p 16000:16000 -p 16010:16010 -p 16020:16020 -p 16030:16030 \
  -e JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 \
  -e HBASE_HOME=/opt/hbase \
  -e PHOENIX_HOME=/opt/phoenix \
  -e HBASE_HEAPSIZE=512m \
  -e PHOENIX_OPTS="-Xms256m -Xmx256m" \
  -e HBASE_CONF_DIR=/opt/hbase/conf-custom \
  -v phoenix-data:/opt/hbase/tmp \
  -v /opt/data/phoenix/conf:/opt/hbase/conf-custom \
  --health-cmd "jps | grep -q HMaster" \
  phoenix-hbase-2.4:5.2.1

验证与 Compose 方式完全一致：docker exec -it phoenix-5-2-1 /opt/phoenix/bin/sqlline.py localhost:2181。

十、常用运维命令

命令	说明
`docker compose up -d --build`	构建并启动
`docker compose ps`	查看状态（healthy 为正常）
`docker compose logs -f phoenix`	跟踪 HBase 日志
`docker compose exec phoenix /opt/phoenix/bin/sqlline.py localhost:2181`	进入 sqlline
`docker compose restart phoenix`	重启实例（配置改动生效）
`docker compose stop phoenix`	停止
`docker compose down`	停止并移除容器（保留数据卷）
`docker compose down -v`	停止并删除容器与数据卷（数据清空，慎用）
`docker compose exec phoenix jps`	查看 Java 进程与 JVM 参数

十一、常见问题（FAQ）

Q1：docker compose up 报端口被占用。 HBase 单机需 2181/16000/16010/16020/16030 五个端口，宿主机上如有其他 ZooKeeper/HBase/监控进程占用，先停掉或修改 compose 的 ports 映射（如 "16010:16010" 改 "16010:16011"）。

Q2：容器状态一直 unhealthy。 说明 HMaster 未起来：执行 docker compose logs phoenix 查看日志，常见原因是 JDK 路径错误、堆设置过小（不低于 256m）、./conf 挂载覆盖了默认配置导致单机参数缺失。

Q3：sqlline 首次连接偶现 Connection refused。 首次连接 ZooKeeper 时偶现对 IPv6 地址的瞬时 Connection refused，客户端自动重连后恢复（日志出现 Attempting reconnect WARN），不影响使用，可忽略。

Q4：sqlline 查询结果列全空白。 非 TTY 下列宽被压缩，先执行 !set maxwidth 200; 与 !set maxcolumnwidth 30; 再查询。

Q5：重启后数据丢失。 确认数据卷挂载未变：docker compose ps 后执行 docker compose exec phoenix ls /opt/hbase/tmp，若目录为空说明命名卷未生效或曾被 down -v 删除。正常重启（restart/down 不带 -v）不会丢数据。

Q6：需要升级 Phoenix/HBase 版本。 修改 Dockerfile 顶部的 ARG HBASE_VERSION/ARG PHOENIX_VERSION（保持版本匹配，Phoenix 5.2.1 配 HBase 2.4.x），执行 docker compose up -d --build 重建镜像并滚动重启；数据卷保留，升级后数据仍在。

十二、参考链接

Apache Phoenix 官方下载页：https://downloads.apache.org/phoenix/
Apache Phoenix 官方文档：https://phoenix.apache.org/
HBase 归档下载：https://archive.apache.org/dist/hbase/
Docker Compose 官方文档：https://docs.docker.com/compose/