Apache HBase 鸿蒙 PC 适配全记录：用 Qt 原生客户端打通 REST 管理与数据读写

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_hbase

环境搭建文章：https://blog.csdn.net/weixin_52908342/article/details/161343743

一、为什么要适配 Apache HBase

Apache HBase 是 Hadoop 生态中具有代表性的分布式列式存储系统。它面向海量稀疏数据提供低延迟随机读写，与 HDFS、ZooKeeper 及 Hadoop 周边工具形成了成熟的服务端体系。对已经在日志、时序、用户画像或在线特征场景中使用 HBase 的团队来说，客户端不只是"查一张表"的工具，还需要承担 Schema 核对、Region 状态观察、单行读写和范围扫描等高频工作。

HarmonyOS PC 进入开发、数据平台运维和企业生产力环境后，需要一个能与现有 HBase 集群共存的原生桌面入口。这次适配的目标不是在个人电脑上复制一套分布式存储集群，而是让用户在鸿蒙 PC 上完成最常用的管理与数据操作，同时保留 HBase 原有的服务边界、权限模型和部署方式。

本次适配在 HBase 主工程之外增加 ohos/ 模块。当前源码基线为 4.0.0-alpha-1-SNAPSHOT，鸿蒙应用版本为 4.0.0-ohos.1，BundleName 为 org.apache.hbase.ohos，目标 ABI 为 arm64-v8a。界面使用 Qt 5.15.12 Widgets 实现，通过 HBase REST Server 连接真实集群。

二、先划清适配边界：鸿蒙端是客户端，不是缩小版集群

HBase 的 Master、RegionServer、HDFS 和 ZooKeeper 共同组成服务端。它们需要 JVM、稳定后台进程、存储拓扑和集群资源管理，不适合与桌面应用窗口绑定生命周期。如果将"适配"等同于把所有 Java 服务塞入 HAP，包体、后台保活、数据目录、端口与权限都会成为新的不稳定因素。

因此项目选择"HarmonyOS PC 原生客户端 + HBase REST Server + 现有集群"的结构：

层次	HBase 原有职责	鸿蒙适配后的处理方式
用户入口	HBase Shell、Java API、Web UI	Qt Widgets 桌面客户端
应用宿主	传统桌面进程	Stage 模型 EntryAbility + XComponent
通信协议	Java RPC 或 REST	QNetworkAccessManager + HTTP/JSON
元数据与数据	表、Schema、Region、Row、Scanner	由 HBase REST Server 转换为稳定的 REST 资源
存储与调度	RegionServer、WAL、Compaction、HDFS	保留在服务端，不进入 HAP
高级运维	Master / RegionServer Web UI、Shell	客户端提供原生 Web UI 入口

这样处理后，鸿蒙应用只关心交互、请求编排和结果呈现，集群一侧继续使用已有的存储、认证、授权与运维体系。版本升级时，客户端与服务端也可以按 REST 兼容性分别演进。

三、鸿蒙版工程与请求链路

Stage 工程中的 ArkTS 代码负责 Ability 生命周期和窗口宿主，Index.ets 创建 XComponent，Qt for OpenHarmony 的 QPA 插件将 Qt 窗口挂载到系统表面。主窗口、表格、表单、连接状态与网络请求都在 Native Qt 层完成。

HarmonyOS PC
└── EntryAbility
    └── Index.ets / XComponent
        └── qopenharmony QPA
            └── libentry.so
                ├── 集群概览
                ├── 表、命名空间、Schema 与 Regions
                ├── Row Get / Put / Delete
                ├── 范围 Scanner 与资源清理
                └── Master / RegionServer Web UI 入口
                         │ HTTP/JSON + 可选 Basic Auth
                         ▼
                  HBase REST Server
                         │
                         ▼
             Master / RegionServer / HDFS / ZooKeeper

与适配相关的主要目录如下：

ohos_hbase/
├── README.OpenHarmony_CN.md
└── ohos/
    ├── AppScope/                         # Bundle、版本与分层图标
    ├── entry/
    │   └── src/main/
    │       ├── ets/                      # Ability 与 XComponent 宿主
    │       ├── resources/                # 字符串、启动图标与 HBase Logo
    │       └── cpp/
    │           ├── hbase_main_window.cpp # Qt 界面与用户流程
    │           ├── hbase_api_client.cpp  # REST、JSON、Basic Auth 和 Scanner
    │           └── CMakeLists.txt        # Native 构建入口
    ├── qtforharmony_sdk/                 # 项目内 Qt for OpenHarmony SDK
    └── reports/                          # 真机回归记录

REST 层对路径参数做 URL 编码，对 HBase REST 协议中的 Row Key、Column 和 Value 做 Base64 转换。列表刷新会并行请求表、集群状态、版本与命名空间；Scanner 则按"创建扫描器---读取数据---删除扫描器"的三段流程处理，避免服务端遗留长时间占用的 Scanner 资源。

四、在 HarmonyOS PC 真机上跑通核心功能

以下五张截图均来自签名 HAP 在 HarmonyOS PC 真机上的实际运行画面，截图分辨率为 3120×2080，设备系统为 HarmonyOS 6.0.2 / API 22，ABI 为 arm64-v8a。验证时在开发机启动真实 HBase standalone 服务，再通过 HDC reverse 将真机中的 127.0.0.1:8080 转发到 HBase REST Server。表、Schema、Region、Row 与 Scanner 结果均来自实际 REST 请求，不是界面内置的占位数据。

1. 连接 HBase REST 并刷新集群概览

客户端使用统一连接栏管理 REST 地址和可选 Basic Auth。点击"连接 / 刷新"后，应用同时读取集群状态、版本、表列表和命名空间。真机画面中显示 3 个 Region、18 次请求、平均负载 3.00，并列出了本次验证的 harmony_demo 表。

地址与用户名可以保存为本地设置，密码只在当次运行中保留。对生产集群，建议在 REST Server 前部署 HTTPS 反向代理，并沿用集群现有的身份和访问控制方案。

2. 读取真实表 Schema

选择 harmony_demo 后点击"查看 Schema"，客户端请求 /harmony_demo/schema，并将服务端返回的列族配置以可读 JSON 展示。本次测试表含有 profile 和 metrics 两个列族，底部请求状态为 HTTP 200。

Schema 编辑区不只用于查看，也能在修改列族属性后提交回 HBase。客户端会先验证内容是合法 JSON 对象，界面也明确提示操作前备份，避免把一个高风险变更做成无提示的普通按钮。

3. 查看表的 Region 分布

同一页面的"查看 Regions"请求 /harmony_demo/regions。真机已收到 HBase REST 的结构化返回，界面底部标记 regions:harmony_demo · HTTP 200。这一步确认了表名编码、元数据请求和 JSON 解析都已穿过真机网络链路。

Region 是 HBase 数据分布与负载分担的基本单元。将 Region 查看放在表上下文中，日常排查时就能从"表是否存在"自然下钻到"数据落在哪些 Region"，而无需手工拼接 REST 路径。

4. 完成单元格写入与 Row 读取

数据页面将表、Row Key、Column 和 Value 放在同一个操作区。本次在真机上向 harmony_demo 表的 user001 行写入 metrics:score=98，再点击"读取行"反查，底部状态返回 row:get:harmony_demo · HTTP 200。

HBase REST 的 JSON 协议使用 Base64 表示 Row Key、列名和单元格值。这层细节由 HBaseApiClient 统一封装，界面中的用户仍然输入普通 UTF-8 文本；路径和请求体中的协议转换不散落到各个按钮回调里。

5. 按 Row Key 范围执行 Scanner

最后使用 user000 到 user999 作为扫描边界，并将列限定为 metrics:score。真机画面中显示 scan:data · HTTP 200，说明客户端已完成 Scanner 创建、数据获取与结果解析。

扫描完成后，客户端会使用 REST 返回的 Location 继续读取数据，然后发送 DELETE 清理 Scanner。Limit 在端侧被约束在 1 到 10000 之间，防止一次操作无边界地拉取结果。

五、适配过程中最需要处理的问题

难点一：识别"客户端适配"与"服务端移植"的边界

HBase 不是单进程桌面软件。如果从 Master 和 RegionServer 开始整体搬迁，很快就会进入 JVM、HDFS、ZooKeeper、后台保活和存储可靠性问题，但这些并不是桌面产品的价值所在。适配最终将高频用户工作流放到 HAP，把分布式存储本体留在集群侧，从而保住了 HBase 本来的部署与故障隔离模型。

难点二：Qt 事件循环需要接入 Stage 和 XComponent

传统 Qt 程序通常由 main() 创建窗口并进入事件循环，HarmonyOS 应用则由 Ability 管理启动、前后台和窗口表面。工程通过 XComponent 提供原生绘制容器，qopenharmony QPA 负责将 Qt Widgets 树挂载到系统窗口。真机上的空白窗口往往不是界面代码本身出错，而是 Ability、XComponent、Native 库或 QPA 中某一层没有正确衔接。

难点三：HBase REST 不是普通的"表单提交"

表列表、集群状态、Schema、Regions、Row 和命名空间各有不同的资源路径和 JSON 结构，Row 数据还使用 Base64 字段。客户端为每个请求附加操作标识，再根据返回类型分发到集群、元数据或数据页面。版本接口在部分部署中可能返回纯文本，实现也为此保留了非 JSON 版本字符串的兼容分支。

难点四：Scanner 是有服务端状态的多段协议

Scanner 不是只发送一个 GET。客户端先通过 POST 创建扫描器，从响应头取得 Location，再到该地址读取数据，最后显式删除资源。任何一段遗漏都可能造成结果丢失或服务端资源泄漏。本次适配将三段请求收口在 API 客户端内部，页面只需提供范围、列和数量条件。

难点五：真机的 127.0.0.1 不是开发机

在鸿蒙电脑中，127.0.0.1 指向设备自身。开发机上的 HBase REST Server 即使已在 8080 端口监听，设备也不会自动访问到它。本次验证使用 HDC reverse 构建端口通道，生产环境则应填写可路由的内网地址或 HTTPS 域名。只有在真机上看到真实表、Row 与 Scanner 结果，才能证明 Qt 网络栈、端口转发、REST 协议和界面渲染整体通过。

难点六：带破坏性的管理操作必须有明确反馈

删除表、删除命名空间和删除行的语义不同，失败时也会返回不同 HTTP 状态。界面对表和命名空间删除提供确认流程，请求完成后在底部统一显示操作名、HTTP 状态和服务端错误。这种反馈方式对管理客户端很重要，它能让用户区分"按钮没反应"、"网络失败"与"HBase 拒绝操作"。

六、构建、安装与连接集群

使用 DevEco Studio 打开仓库中的 ohos/ 目录，为 org.apache.hbase.ohos 配置与目标设备匹配的本地调试签名。工程的 target SDK 与 compatible SDK 均为 HarmonyOS 6.0.2(22)，Native 编译器为 BiSheng，设备类型为 2in1 和 tablet。Qt SDK 位于 ohos/qtforharmony_sdk/，CMake 使用相对参数 -DQT_PREFIX=qtforharmony_sdk，不依赖其他适配项目的绝对路径。

命令行构建示例：

cd ohos
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
export OHOS_BASE_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk

/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  --mode module -p module=entry assembleHap --no-daemon

构建完成后，签名产物位于：

ohos/entry/build/default/outputs/default/entry-default-signed.hap

连接 HarmonyOS PC 真机后安装并启动：

HDC=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc

"$HDC" list targets
"$HDC" install -r ohos/entry/build/default/outputs/default/entry-default-signed.hap
"$HDC" shell aa start -b org.apache.hbase.ohos -a EntryAbility

本地联调时，如果 HBase REST Server 运行在开发机 8080 端口，可建立反向端口映射：

"$HDC" rport tcp:8080 tcp:8080

实际集群部署中，在客户端顶部填写 HBase REST Server 的局域网地址或域名，例如 https://hbase-rest.example.com。若使用 Basic Auth，密码不会被写入应用设置；调试签名材料与密钥也应保留在开发者本机，不作为项目可移植配置。

七、当前能力与明确边界

当前鸿蒙版本已覆盖以下核心能力：

• 签名 HAP 构建、安装、启动与 2in1 / tablet 窗口显示；
• HBase REST 地址、可选 Basic Auth 和连接状态；
• 集群 Region 数、请求数、平均负载与版本信息；
• 表列表、命名空间、Schema 和 Regions 查看；
• 创建表、修改 Schema、删除表；
• 创建和删除命名空间；
• Row 读取、Cell 写入与 Row 删除；
• Start Row、End Row、Columns 和 Limit 范围扫描；
• Scanner 读取完成后的服务端资源清理；
• Master Web UI、RegionServer Web UI 与 REST API 文档入口；
• 统一显示请求操作、HTTP 状态和错误详情；
• REST 地址与用户名持久化，密码不落盘。

当前版本没有将以下服务端或高级能力包装为已完成：

• 在 HarmonyOS PC 本地启动 HBase Master、RegionServer、HDFS 或 ZooKeeper；
• 将 HBase Java 客户端 RPC 直接嵌入 Qt 应用；
• HBase Shell、MapReduce 工具和 Thrift 客户端；
• Snapshot、Balancer、Compaction、Replication 和 Backup 的 Qt 原生管理页；
• ACL、Quota 与认证材料的图形化全量管理；
• WAL、Region 分配、压缩、复制和底层存储实现。

因此，当前版本的准确定位是"Apache HBase HarmonyOS PC 管理与数据操作客户端"。它覆盖日常连接、查看、表管理、单行读写和范围扫描，但不替代 HBase 集群本体，也不绕过集群侧的认证、授权和运维管理。

八、总结

Apache HBase 的鸿蒙适配不是一次对 Java 分布式存储引擎的简单重编译。有价值的做法，是先识别用户在 PC 上真正需要完成的工作，再选择能与既有集群稳定协作的端侧技术路线。

本项目用 Stage 模型与 XComponent 承接 HarmonyOS PC 应用生命周期，用 Qt Widgets 保留桌面管理工具的信息密度，再通过 HBase REST 将表、Schema、Region、Row 和 Scanner 串成一条完整数据链。五张真机画面记录的不只是界面能够打开，而是真实 HBase 服务已经能够被连接、查询和写入。

对同类服务端开源软件而言，这种适配思路也具有复用价值：将存储、调度和安全边界留在它们本来就擅长的服务端，把鸿蒙端的工作聚焦于高频操作和可见反馈，再用真机与真实数据链路完成验收。这样得到的鸿蒙版本更易部署、升级和长期维护。