DBeaver 鸿蒙 PC 适配全记录：在 HarmonyOS 桌面端原生重建一个通用数据库工具

DBeaver 鸿蒙 PC 适配全记录：在 HarmonyOS 桌面端原生重建一个通用数据库工具

• [DBeaver 鸿蒙 PC 适配全记录：在 HarmonyOS 桌面端原生重建一个通用数据库工具](#DBeaver 鸿蒙 PC 适配全记录：在 HarmonyOS 桌面端原生重建一个通用数据库工具)
• • 前言
  • [一、为什么要适配 DBeaver](#一、为什么要适配 DBeaver)
  • 二、先确定适配路线：界面重建，协议复用
  • 三、适配工程的目录组织
  • [四、HarmonyOS PC 桌面端核心功能](#四、HarmonyOS PC 桌面端核心功能)
  • • [1. 会话管理：连接的起点](#1. 会话管理：连接的起点)
    • [2. 工作台与数据库树：从实例到字段的分层导航](#2. 工作台与数据库树：从实例到字段的分层导航)
    • [3. SQL 编辑器：语法高亮与多语句执行](#3. SQL 编辑器：语法高亮与多语句执行)
    • [4. 数据网格：浏览、过滤与事务化编辑](#4. 数据网格：浏览、过滤与事务化编辑)
    • [5. 结构管理、导入导出与偏好设置](#5. 结构管理、导入导出与偏好设置)
  • 五、适配过程中遇到的主要困难
  • • [难点一：没有 Java 运行时，只能重写而不能搬运](#难点一：没有 Java 运行时，只能重写而不能搬运)
    • [难点二：把 glibc 假设的 C 客户端库编进 musl 世界](#难点二：把 glibc 假设的 C 客户端库编进 musl 世界)
    • [难点三：musl 缺失符号与三元组陷阱](#难点三：musl 缺失符号与三元组陷阱)
    • 难点四：三种数据库协议收敛成一个接口面
    • [难点五：PC 窗口的 px / vp 密度换算](#难点五：PC 窗口的 px / vp 密度换算)
    • [难点六：状态管理 V1 的嵌套对象刷新陷阱（真机实测踩到）](#难点六：状态管理 V1 的嵌套对象刷新陷阱（真机实测踩到）)
  • 六、关键适配改动
  • 七、编译、安装与启动
  • • [1. 准备项目依赖](#1. 准备项目依赖)
    • [2. 构建 HarmonyOS PC 版本](#2. 构建 HarmonyOS PC 版本)
    • [3. 安装并启动](#3. 安装并启动)
  • 八、迁移能力分级与当前边界
  • 九、总结

DBeaver 鸿蒙 PC 适配全记录：在 HarmonyOS 桌面端原生重建一个通用数据库工具

前言

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

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

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

环境说明：DevEco Studio + HarmonyOS SDK（API 12 起），真机/模拟器均以 2in1（鸿蒙 PC）形态运行。

一、为什么要适配 DBeaver

DBeaver 是目前使用最广的开源通用数据库客户端之一：连接会话管理、库表树导航、数据网格编辑、SQL 查询、结构管理、导入导出，一个工具覆盖了开发者与 DBA 的绝大部分日常。它上游基于 Java / Eclipse RCP 构建，依托 JDBC 生态支持上百种数据源，Windows、macOS、Linux 都有成熟安装包------唯独没有鸿蒙桌面端。

把 DBeaver 带到 HarmonyOS PC，价值不只是「多一个能装的软件」。数据库工具是桌面操作系统的基础设施级应用：有了它，开发者才能在鸿蒙 PC 上独立完成「连库、查数、改数据」的业务闭环，而不必为一条 SQL 切换到另一台电脑。同时，这类应用对桌面平台的考验相当全面：多窗格工作台、大数据量表格渲染、右键菜单与拖拽这类键鼠交互、C/C++ 第三方库的交叉编译与桥接、密码等敏感数据的安全存储------这些链路能否在鸿蒙 PC 上连续工作，对后续更多专业桌面软件的移植有直接的参考价值。

先交代与技术选型相关的前提：鸿蒙 PC 上没有 JVM、没有 OSGi、没有 SWT，JDBC 驱动体系也无从谈起，把 Eclipse RCP 应用整体搬过来在工程上不成立。因此本次适配没有搬运上游任何源码、图标与素材，而是走「规格参照 + 原生重建」路线：界面与领域逻辑用 ArkTS + ArkUI 全新实现，数据库协议层复用业界成熟的 C 客户端库，交叉编译成 aarch64（musl）动态库随 HAP 分发，中间用 NAPI 做一层干净的桥。最终交付形态为 arm64-v8a 签名 HAP，Bundle Name 为 com.dbeaver.ohos，版本 1.0.0，compatibleSdkVersion 5.0.0(12) / targetSdkVersion 6.1.1(24)。

二、先确定适配路线：界面重建，协议复用

决定路线前需要把上游 DBeaver 拆开看：哪些部分是「界面与工作流」，哪些部分是「跟数据库对话」。前者的交互模型（连接管理、树形导航、表格编辑、SQL 执行）本身是平台无关的，完全可以用 ArkUI 重建；后者是十几年打磨出来的协议实现，没有必要也没有能力用 ArkTS 重写------libmariadb、libpq、sqlite3 三套 C 库原样交叉编译进来，是最稳的选择。

层次	上游实现	HarmonyOS PC 侧处理
UI 框架	Eclipse RCP / SWT	ArkTS + ArkUI 声明式范式（22 个页面/视图），State Management V1
领域逻辑	Java 插件（OSGi）	ArkTS 分层：viewmodel / catalog / editor / model / dbclient
数据库驱动	JDBC 驱动	交叉编译 C 客户端库：libmariadb 3.3.3、libpq 15.7、sqlite3 3.46.0
数据库桥接	JDBC API	NAPI（C++17）统一 provider 接口，产物 libdbclient.so
TLS	JSSE	OpenSSL 3.3.1 交叉编译，libmariadb / libpq 共用
字符编码	JVM 内置	libiconv 1.17 + gettext 0.22.5（libintl，libpq 依赖）
密码存储	Eclipse secure storage	系统密钥管理（HUKS）AES-256-GCM 加密
交付形态	桌面安装包	arm64-v8a 签名 HAP，deviceTypes 含 2in1

适配后的调用链路如下：

EntryAbility（UIAbility，窗口 1280×800 vp，强制深色）
    └── MainWindowPage（ArkUI 主窗口）
          ├── SessionManagerPage        # 连接会话管理（新建/编辑/复制/测试连接）
          └── WorkbenchPage             # 多窗格工作台
                ├── DbTreeView          # 数据库树（catalog 目录服务）
                ├── TableEditorView     # 表编辑器（属性 | 数据 双子标签）
                ├── SqlEditorPage       # SQL 编辑器（高亮/多语句/历史/格式化）
                ├── StructurePage 等    # 结构与对象管理
                └── dbclient（ArkTS 连接注册表）
                      └── NAPI：libdbclient.so（C++17）
                            ├── mysql_provider    → libmariadb.so（+ OpenSSL）
                            ├── postgres_provider → libpq.so（+ OpenSSL / libiconv / libintl）
                            └── sqlite_provider   → libsqlite3.so

这条路线的边界同样是明确的：界面全部原创重写，功能按上游规格逐项对齐；数据库访问走真实客户端协议而非退化实现；上游依赖 Java 生态的部分（海量 JDBC 驱动、OSGi 扩展体系）不在本次范围内，后文能力分级一节如实列出。

三、适配工程的目录组织

鸿蒙工程即仓库根目录，DevEco Studio 直接打开即可构建；数据库客户端库的交叉编译体系独立放在 native/，与 App 构建完全解耦。平台相关代码收敛在三处：cpp/（NAPI 桥接）、native/（交叉编译）与 EntryAbility（PC 窗口配置），其余全部是平台无关的 ArkTS 分层代码。

ohos_DBeaver/
├── AppScope/                          # 应用级配置（包名 com.dbeaver.ohos、图标）
├── build-profile.json5                # 工程级构建配置（SDK 版本、模块列表）
├── README.OpenHarmony_CN.md           # 仓库内鸿蒙适配说明（编译运行 + T0/T1/T2 能力分级）
├── entry/                             # 唯一业务模块
│   └── src/main/
│       ├── ets/
│       │   ├── pages/                 # 22 个 ArkUI 页面/视图（会话管理/工作台/数据网格/SQL 编辑器...）
│       │   ├── viewmodel/             # 领域逻辑：SQL 构建、事务编排、导入导出、行编辑缓冲
│       │   ├── catalog/               # 数据库树目录服务、字段类型注册表
│       │   ├── editor/                # SQL 语法高亮内核与关键字表
│       │   ├── model/                 # 会话、连接参数、错误映射、密钥管理安全存储、查询历史
│       │   ├── dbclient/              # 连接注册表（NAPI 的 ArkTS 封装）
│       │   ├── common/                # 主题色板 Theme.ets、品牌常量、右键菜单辅助
│       │   └── entryability/          # EntryAbility（PC 窗口与主题配置）
│       ├── cpp/                       # NAPI 桥接层 → libdbclient.so
│       │   ├── db_provider.h/cpp      # 统一 provider 接口与工厂
│       │   ├── mysql_provider.cpp     # libmariadb 实现
│       │   ├── postgres_provider.cpp  # libpq 实现
│       │   ├── sqlite_provider.cpp    # sqlite3 实现
│       │   ├── napi_init.cpp          # 模块注册
│       │   ├── CMakeLists.txt         # 链接 NAPI 运行时 + 预编译客户端库
│       │   └── types/libdbclient/     # Index.d.ts（ArkTS 侧类型声明）
│       └── module.json5               # deviceTypes 含 2in1、INTERNET 权限
└── native/                            # 数据库客户端库交叉编译（独立于 App 构建）
    ├── build/
    │   ├── env.sh                     # 工具链环境（clang target/sysroot/lld）
    │   └── build_libs.sh              # 主构建脚本：按依赖顺序编 7 步
    ├── compat/
    │   └── musl_compat.h              # glibc 扩展符号在 musl 下的兼容桩（-include 注入）
    └── prebuilt/arm64-v8a/            # 交叉编译产物：lib/（.so）+ include/（随仓库附带）

native/prebuilt/arm64-v8a/ 的预编译产物随仓库分发，日常开发无需重跑交叉编译；entry 的 NAPI 构建通过 CMake 指向该目录链接，打包时把依赖 .so（含 libmariadb 的插件子目录）一并带进 HAP，装到设备上开箱即用。

四、HarmonyOS PC 桌面端核心功能

以下按用户使用路径整理应用的核心能力，截图存放于 img/ 目录。

1. 会话管理：连接的起点

应用启动后先进入会话管理页：左侧是会话列表（新建 / 保存 / 删除），右侧是「连接属性」面板，涵盖名称、类型（MySQL / MariaDB、PostgreSQL、SQLite）、主机、端口、用户、密码、数据库、字符集，以及 SSL 模式、压缩传输、查询超时、Keep-Alive、备注等高级项。连接前可以先「测试连接」，成功后显示服务器版本与 SSL 状态；确认无误后一键「连接」进入工作台。密码经系统密钥管理能力（HUKS）以 AES-256-GCM 加密存储，密钥不出安全环境，不以明文落盘。

2. 工作台与数据库树：从实例到字段的分层导航

连接成功后进入工作台：左侧数据库树按「实例 → 数据库 → 表 / 视图」分层展开，支持按名称过滤；树节点绑定统一的右键菜单（刷新、新建对象、编辑、导出等）。SQLite 这类单库数据源会自动收敛为虚拟库节点，行为与 MySQL / PostgreSQL 保持一致。

3. SQL 编辑器：语法高亮与多语句执行

工作台默认打开 SQL 脚本标签：关键字语法高亮（多主题可切换）、多语句一次提交、结果面板按语句分区展示；左侧竖排工具条提供执行、执行模式（执行全部 / 执行选中 / 执行当前语句）、清空、格式化、查询历史与数据源标识。

4. 数据网格：浏览、过滤与事务化编辑

双击表进入表编辑器，「数据」子标签即数据网格：浏览 / 编辑双模式，列宽鼠标拖拽调整，快速过滤与条件过滤（等于 / 包含 / 大小比较 / IS NULL）。行内编辑进入编辑缓冲区，由用户显式「提交 / 回滚」批量事务化落库；切换前有脏数据守卫拦截未保存修改；对无主键表启用编辑前给出风险告警；BLOB / TEXT 大字段有专用编辑器，支持文本 / 十六进制双视图。

5. 结构管理、导入导出与偏好设置

「属性」子标签覆盖表字段编辑、索引与外键 DDL 编辑、DDL 查看、字段类型映射；对象编辑器延伸到视图 / 存储过程 / 触发器 / 事件，另有用户管理。数据可导出为 SQL 文件或 CSV，CSV 亦可导入。偏好设置提供字体、字号、每页行数、NULL 显示、驱动、超时、高亮主题等个性化项。

五、适配过程中遇到的主要困难

难点一：没有 Java 运行时，只能重写而不能搬运

上游 DBeaver 的几十个插件全部构建在 Eclipse RCP 之上：UI 是 SWT、服务是 OSGi、数据库访问是 JDBC，这三样在鸿蒙上一样都不存在。任何「塞一个 JRE 进 HAP」的方案都会带来体积、性能与许可的三重问题。适配最终把上游的交互模型当作规格、把代码全部重写：在 ArkTS 严格模式下（禁用 any、对象字面量类型推断、动态属性访问）重建数据网格、树控件、SQL 解析这些本应属于框架的能力，工作量集中在 pages/ 的 22 个视图和 viewmodel/ 的领域逻辑上。

难点二：把 glibc 假设的 C 客户端库编进 musl 世界

libmariadb、libpq、OpenSSL 都是按 Linux/glibc 习惯写的代码，而鸿蒙 native 环境是 musl libc。问题逐个出现：OpenSSL 的 Configure 要显式走 linux-aarch64 目标，再靠 -D__MUSL__ 让源码切换 musl 分支；libmariadb 的 CMake 在 macOS 构建机上会把系统检测成 Darwin，必须显式指定 CMAKE_SYSTEM_NAME=Linux；它还要在交叉编译时执行 TRY_RUN 探测 OpenSSL，而目标架构的二进制根本无法在构建机上运行，导致 OPENSSL_FOUND 为空------构建脚本用 sed 给它的 CMakeLists 打了个补丁，跳过探测、直接注入库路径。这些解决方案统一集中在 native/build/build_libs.sh 里，第三方源码树保持原样。

难点三：musl 缺失符号与三元组陷阱

glibc 有不少扩展符号 musl 里没有，例如调用栈回溯用的 <execinfo.h> 在 musl 上不存在，直接编译就 undefined reference。解法是写 native/compat/musl_compat.h 兼容桩，通过 -include 强制注入到每个编译单元------补丁集中一处，不去散改第三方源码。另一个隐蔽的坑在三元组上：autoconf 系工程的 --host 必须写标准三元组 aarch64-linux-gnu（autoconf 不认识 ohos），而 clang 的 --target 才用 aarch64-linux-ohos；两个值不一致是故意的，全局编译开关还要带上 -D__linux__，否则 musl 头文件里的部分 API 根本不会暴露。libmariadb 的认证插件则全部静态链进主库，避免运行时动态加载失败。

难点四：三种数据库协议收敛成一个接口面

ArkTS 层不应该感知「底下是 MySQL 还是 PostgreSQL」。cpp/db_provider.h 定义了统一的 provider 接口（连接、ping、执行、元数据、转义），三个 provider 各自实现，napi_init.cpp 注册成 ArkTS 模块，类型声明在 Index.d.ts 与 C++ 侧一一对应。工程细节上，libdbclient.so 以 -Wl,-rpath,$ORIGIN 从自身所在目录定位依赖库；CMake 的 POST_BUILD 把 prebuilt/arm64-v8a/lib 整体拷进产物目录（含 libmariadb 插件子目录），保证 HAP 打包时依赖一个不少。

难点五：PC 窗口的 px / vp 密度换算

窗口默认 1280×800 vp，看似一行 win.resize(1280, 800) 就完事，但 resize 的单位是 px 不是 vp 。在鸿蒙 PC 的高密度屏上直接传 1280，得到的窗口只有一半大，480×520 vp 的模态对话框会超出窗口被裁剪，底部「保存 / 取消」按钮不可见也不可点------初看像个玄学 bug。正确做法是先用 display.getDefaultDisplaySync() 取 densityPixels，按 vp × density 换算成 px 再 resize。配套还有两处：启动时把窗口底色设为与主题一致的 #2B2B2B 消除启动白闪；应用级 setColorMode(COLOR_MODE_DARK) 让系统弹窗与未显式着色的控件不残留浅色样式。

难点六：状态管理 V1 的嵌套对象刷新陷阱（真机实测踩到）

会话管理页的「类型」下拉切换到 SQLite 后，MySQL 专属的「驱动类型」下拉并不会按代码里的条件分支消失------界面停滞在旧状态。排查后发现是 V1 状态管理的典型问题：editing 是挂在 @Observed ViewModel 上的普通对象，this.vm.editing.kind = ... 这种嵌套字段写入 本身不具备可观察性，组件里的手动刷新计数器又没有被 build() 读取，等于刷新机制没有生效。修复方式是把这类结构性联动收敛成 ViewModel 方法：重建 editing 对象并整体重新赋值（changeKind / changeSslMode），依赖 editing 的属性表达式随之重新求值，条件分支立即生效。这个问题在模拟器上真实复现过三次，修复后复验正常------把它写出来，是希望同样做表单型移植的后来者少绕这一圈。

六、关键适配改动

1. 三层原生架构与统一 provider 接口 ：UI（pages）→ 领域逻辑（viewmodel / catalog / editor / model / dbclient）→ NAPI 桥接（cpp）解耦；db_provider.h 是数据库无关的接口面，新增数据库类型只需在 C++ 侧增加一个 provider 并在工厂注册，上层不动。
2. 独立的客户端库交叉编译体系 ：native/build/env.sh 定义工具链（SDK 自带 LLVM clang + ld.lld + musl sysroot），build_libs.sh 按依赖顺序编 sqlite3 → libiconv → libintl → OpenSSL → libpq → libmariadb，版本号写死保证可复现，产物随仓库分发。
3. musl 兼容桩集中注入 ：native/compat/musl_compat.h 通过 -include 进入所有编译单元，集中提供 glibc 扩展符号的空实现或回退路径。
4. NAPI 模块组包细节 ：链接 ace_napi.z / hilog_ndk.z 与 sqlite3 / mariadb / ssl / crypto；$ORIGIN rpath 保证设备端依赖定位；POST_BUILD 拷贝预编译库与插件目录。
5. PC 窗口与主题适配 ：按屏幕密度换算窗口尺寸（1280×800 vp）、深色窗口底色、应用级强制深色；全部颜色引用 common/Theme.ets 集中语义色板，品牌常量收敛在 Brand.ets。
6. 右键菜单与键鼠交互组件化 ：ContextMenuHelper 统一右键菜单构建；数据网格的行与列区分鼠标按键行为，列宽拖拽独立组件（ColResizeHandle）并带悬停高亮；所有交互保持触控可用。
7. HUKS 安全存储与会话持久化：连接密码经系统密钥能力 AES-256-GCM 加密，密钥持久存储且不可导出；会话列表、查询历史、偏好设置各自独立持久化。
8. 类型切换的状态刷新修复 ：SessionManagerViewModel.changeKind / changeSslMode 以「重建 editing + 整体赋值」替代嵌套字段写入，解决 V1 状态管理下条件渲染不生效的问题。

七、编译、安装与启动

1. 准备项目依赖

需要 DevEco Studio（含 HarmonyOS SDK，默认 /Applications/DevEco-Studio.app）。仓库已附带预编译客户端库，常规开发直接进入第 2 步；如需重编或升级库版本：

cd native/build
./build_libs.sh all          # 按依赖顺序编 7 步，产物落 native/prebuilt/arm64-v8a/
# 也可单独编：./build_libs.sh sqlite | openssl | libpq | libmariadb

2. 构建 HarmonyOS PC 版本

DevEco Studio（推荐） ：打开工程根目录，在 File > Project Structure > Signing Configs 生成调试签名，连接 2in1 设备后点 Run。

命令行（可接 CI）：

export JAVA_HOME=/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
export PATH="$JAVA_HOME/bin:/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:$PATH"
hvigorw assembleHap

签名产物位于：

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

注意：若要修改 AppScope/app.json5 中的 bundleName，需先在 Signing Configs 重新生成签名、再改包名，顺序颠倒会导致签名与包名不匹配、无法安装。

3. 安装并启动

hdc list targets
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.dbeaver.ohos

启动后窗口为 1280×800 vp 深色桌面形态。首次使用在会话管理页新建连接（SQLite 只需填一个本地文件路径，最适合快速体验），测试连接通过后保存；双击会话进入工作台，即可进行数据库树导航、SQL 执行、数据网格编辑与导入导出。

八、迁移能力分级与当前边界

仓库内的 README.OpenHarmony_CN.md 按社区规范给出了完整的 T0 / T1 / T2 能力分级，这里给出结论性摘要。

T0（基础能力，已达成）：HAP 构建 / 签名 / 安装 / 启动；2in1 桌面窗口与深色主题适配；NAPI 桥接闭环；三套 C 客户端库 musl 交叉编译；MySQL / MariaDB（TCP + TLS）、PostgreSQL（TCP + TLS）、SQLite（本地文件）三类连接；密码加密存储。

T1（主要能力，已达成）：会话管理（新建 / 编辑 / 复制 / 删除 / 测试连接）；数据库树分层导航、过滤与右键菜单；数据网格浏览 / 编辑双模式、列宽拖拽、快速与条件过滤、行内编辑 + 批量事务提交 / 回滚、脏数据守卫、无主键表风险告警、BLOB / TEXT 专用编辑器；SQL 编辑器高亮、多语句执行、执行模式切换、查询历史、格式化；SQL / CSV 导出与 CSV 导入。

T2（增强能力，部分达成）：数据库 / 表对象编辑器、视图 / 存储过程 / 触发器 / 事件管理、用户管理、偏好设置、TLS 连接配置已交付；SQL 自动补全、SSH 隧道、ER 图 / 数据建模、任务调度 / 仪表盘监控未排期；Oracle / SQL Server / MongoDB / Redis 等其余数据源按 provider 模式逐步扩展；上游的 JDBC 驱动框架与 OSGi 插件体系与原生架构不兼容，以源码级 provider 扩展替代。

真机验证情况如实说明：当前签名 HAP 已在 2in1 设备完成安装启动，会话管理页、连接类型切换、下拉交互已在设备上操作验证（并据此修复了难点六的状态刷新问题）；连接后的工作台、SQL 执行与数据网格链路已完成实现，配套截图将随下一轮真机走查补充进 img/ 目录。

九、总结

DBeaver 的鸿蒙 PC 适配走的是一条与「保留前端、替换宿主」不同的路：上游的 Java / Eclipse RCP 体系在鸿蒙上没有任何可复用的运行时，因此选择「规格参照 + 原生重建」------界面与工作流用 ArkTS / ArkUI 重写，数据库协议层把 libmariadb、libpq、sqlite3 三套成熟 C 库交叉编译进 HAP，中间用 NAPI 的统一 provider 接口做干净的桥。过程中真正花时间的三件事，一是 glibc 假设的 C 库在 musl 上的交叉编译（三元组、兼容桩、逐库构建修正），二是 ArkTS 严格模式下复杂桌面交互的重建（右键菜单、悬停、拖拽、事务化表格编辑），三是桌面形态的窗口密度换算与状态管理细节。

从结果看，在鸿蒙 PC 上打开它：新建一条连接、浏览库表、跑 SQL、改数据、导出结果，是一台桌面数据库工具该有的样子。db_provider 的接口设计也为后续留好了口子------补新数据库类型不需要动上层，鸿蒙 PC 的开发者工具链也可以沿着这条路径继续向前长。欢迎在开源鸿蒙 PC 社区试用、提 issue、一起把这个工具补齐到「日常主力」的水平。