HeidiSQL 鸿蒙 PC 适配全记录：在 HarmonyOS PC 上原生重写一个桌面级数据库管理工具

前言

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

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

适配开源地址（AtomGit 仓库）：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_heidisql

仓库根目录附有 README.OpenHarmony_CN.md，按 T0 / T1 / T2 三个阶段说明软件迁移能力、编译运行方式与适配细节，欢迎对照阅读。

一、为什么要适配 HeidiSQL

HeidiSQL 是一款开源（GPL-2.0）的桌面数据库管理工具，从 2002 年迭代至今：连接管理、数据库树、数据网格浏览与编辑、SQL 查询、表结构管理、数据导入导出，这些能力是数据库开发与运维每天都要用的。它用 Delphi 编写，长期只面向 Windows 桌面。而鸿蒙 PC 生态正在成长，图形化的数据库客户端恰恰是这类新平台上最基础、也最容易被忽视的基础设施——把它带到开源鸿蒙 PC，价值不只是多一个工具，更在于验证这套系统对「重交互桌面应用 + 原生数据库协议栈」这类组合的承载能力。

先把项目性质说清楚，免得产生误解：这不是把 Delphi 源码逐行翻译，更不是把 Windows 程序塞进某种兼容层。而是以上游功能规格为参照，在开源鸿蒙上用 ArkTS + ArkUI 做的一次全新原生实现——上游的代码、文案与资源零复制，许可证沿用 GPL-2.0，与上游作者及项目无隶属关系，这些都在仓库中明确声明。做一个原生版本而不是壳，理由很直接：数据库工具的操作密度极高（右键菜单、双击进表、批量编辑提交、快捷键执行查询），只有原生控件和原生事件模型才撑得起桌面级的交互手感，这也正是鸿蒙 PC 需要被验证的部分。

本次适配完成的交付形态是：界面与领域逻辑全部为 ArkTS 原生实现（约 1.6 万行 .ets 代码），数据库客户端协议层由交叉编译到 OHOS ARM64 的 libmariadb / libpq / sqlite3 三个 C 库提供，通过 NAPI 桥接进 ArkTS 世界，最终打成单一签名 HAP。装上就能用，不依赖设备上有任何预装运行时。

二、先确定适配路线：界面原生重写，协议层交给 C 库

动手前先想清楚一件事：哪些必须重写，哪些可以复用。Delphi/VCL 在鸿蒙上没有任何对应物，界面层只能原生重写；但数据库客户端协议不是 UI 问题，libmariadb、libpq、sqlite3 都是成熟的 C 库，只要能交叉编译到 OHOS ARM64，协议层就不必重造轮子。于是路线定了：ArkTS 管一切看得见的，C 库只管协议，NAPI 做桥。

层次	上游实现	HarmonyOS PC 侧处理
界面与交互	Delphi + VCL 控件	ArkUI 声明式范式全新实现，键鼠优先（右键菜单、列宽拖拽、树形导航）
领域逻辑	Pascal 单元	ArkTS：SQL 构建、行编辑缓冲、事务编排、导入导出
数据库协议	随安装包分发的 libmariadb / libpq / sqlite3 DLL	交叉编译 OHOS ARM64 .so，NAPI 桥接，随 HAP 分发
密码存储	Windows 凭据管理	系统 HUKS AES 加密后落盘
主窗口	Windows 窗体	EntryAbility 拉起 1280×800 主窗口，deviceTypes 声明 2in1
交付形态	Windows 安装包	arm64-v8a 签名 HAP，Bundle Name 为 com.heidisql.ohos

适配后的连接链路如下：

EntryAbility（主窗口 1280×800）
    └── MainWindowPage
          ├── SessionManagerPage        # 会话管理：新建/编辑/测试连接
          │     └── HUKS SecureSecretStore  # 密码加密存储
          └── WorkbenchPage             # 工作台：数据库树 + 数据网格 + SQL 编辑器
                └── DbConnection / ConnRegistry     # ArkTS 连接注册表
                      └── NAPI: libdbclient.so
                            └── DbProvider 统一接口
                                  ├── mysql_provider    → libmariadb → MySQL / MariaDB
                                  ├── sqlite_provider   → sqlite3（桩，待集成）
                                  └── postgres_provider → libpq（桩，待集成）

这条路线的最大好处是隔离：换数据库只动 provider 一层，UI 与领域逻辑一行不改；反过来，ArkTS 侧的任何演进也不触碰 C 库。代价则是必须打通两端——一套 musl 下的 C 库交叉编译体系，和一个干净的跨语言接口。后文按此展开。

三、适配工程的目录组织

整个工程就是一个标准 DevEco 工程，native 交叉编译配套放在 native/，与 HAP 构建解耦：

ohos_HeidiSQL/
├── build-profile.json5                 # 工程级构建配置（SDK 版本 / 签名）
├── AppScope/                           # 应用级配置（bundleName / 图标）
├── entry/                              # 主模块（整个应用一个 HAP）
│   └── src/main/
│       ├── module.json5                # deviceTypes 含 2in1；INTERNET 权限
│       ├── cpp/                        # NAPI 桥接层 → libdbclient.so
│       │   ├── db_provider.h / .cpp    # 数据库 provider 统一接口
│       │   ├── mysql_provider.cpp      # MySQL/MariaDB 实现（libmariadb）
│       │   ├── sqlite_provider.cpp     # SQLite（桩，待集成）
│       │   ├── postgres_provider.cpp   # PostgreSQL（桩，待集成）
│       │   └── napi_init.cpp           # NAPI 模块注册
│       └── ets/
│           ├── entryability/           # EntryAbility（PC 窗口适配）
│           ├── pages/                  # 20 个 ArkUI 页面
│           ├── viewmodel/              # SQL 构建 / 行编辑缓冲 / 导入导出
│           ├── catalog/                # 数据库树目录服务
│           ├── editor/                 # SQL 语法高亮
│           ├── model/                  # 会话 / HUKS 加密存储 / 偏好
│           └── dbclient/               # 连接注册表
└── native/                             # C 库交叉编译配套
    ├── build/
    │   ├── env.sh                      # OHOS 工具链环境（clang / sysroot / lld）
    │   └── build_libs.sh               # 一键交叉编译 6 个 C 库
    ├── compat/
    │   └── musl_compat.h               # glibc 扩展符号的 musl 兼容桩
    └── prebuilt/arm64-v8a/             # 交叉编译产物（.so + 头文件）

版本全部锁定在脚本里：SQLite 3.46.0、OpenSSL 3.3.1、libmariadb 3.3.3、libpq（PostgreSQL 15.7）、libiconv 1.17、gettext 0.22.5。锁定版本是为了可复现——任何时候换一台机器，./build_libs.sh all 出来的产物字节级可对照。

四、HarmonyOS PC 上的运行实况

以下 4 张截图均在 2026 年 9 月 7 日安装当前签名 HAP 后采集。运行环境为鸿蒙 PC（MateBook Pro 形态）模拟器，屏幕分辨率 3120×2080，应用主窗口 1280×800；底部常驻任务栏与开始菜单可见，一眼可确认是鸿蒙桌面端形态。模拟器通过 10.0.2.2 访问宿主机网络，因此下文连接目标是宿主机上真实运行的 MySQL 8.4.2 实例，所有数据均为真实查询结果。同样的安装与启动流程在 HUAWEI MateBook Pro 真机上完全一致。

1. 会话管理：连接的前置入口

启动后第一屏是会话管理页。左侧为会话列表（名称、主机、上次连接时间），右侧为连接属性面板：类型、主机、端口、用户、密码、字符集、驱动类型等参数一应俱全，底部提供测试连接 / 连接 / 取消操作。密码不落明文，统一经系统 HUKS AES 加密后存储。

2. 连接成功后的工作台

选中会话点击「连接」后进入工作台。顶部是文件 / 查看 / 查询 / 工具 / 帮助菜单栏与工具栏（刷新、新建对象、断开、导出、导入 CSV、用户、设置），左侧数据库树展开出实例下的全部数据库，底部状态栏显示 已连接：10.0.2.2:3306 | MySQL 8.4.2 | 超时：30s——这是真实 TCP 连接建立后由服务端握手包返回的版本号。

3. 数据网格浏览真实数据

展开 test 库的「表」节点并点开 test 表，数据网格加载出真实行数据（共 1 行，列为 id / a），支持列宽拖拽、快速过滤与分页浏览（每页 1000 行）。该视图由 DataGridPage 经 NAPI 调用 libmariadb 的 mysql_store_result 取回，不是预置的演示数据。

4. SQL 编辑器执行查询

切换到 SQL 页签，输入 SELECT id, a FROM test.test; 后按执行按钮，结果面板返回 共 1 条 | 成功 1 失败 0 | 3 ms | 2 列 × 1 行，并渲染出结果网格。编辑器支持语法高亮、格式化、执行历史与失败中止等选项，是日常使用频率最高的入口。

这四张截图串起来就是一条完整的用户路径：新建会话 → 连接 → 浏览数据 → 执行 SQL。链路上任何一个环节不成立，后一环的截图就不可能出现。

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

难点一：按 glibc 假设写的 C 库，要编到 musl 上

鸿蒙 native 工具链基于 musl libc，而 libmariadb / libpq / OpenSSL 这类库默认按 glibc 假设编译，交叉链接时会报出一串 undefined symbol：backtrace、malloc_usable_size、program_invocation_name、__libc_current_sigrtmin 等。逐个改库源码既脏又不可持续——每个库每个版本都要重新打补丁。最终解法是一个 musl_compat.h 兼容桩头，通过 -include 强制注入到所有编译单元，对 glibc 专有符号提供空桩或等价实现，库源码零改动。

难点二：autoconf 与 clang 对目标三元组的认知不一致

clang 侧 target 应写 aarch64-linux-ohos，但 autoconf 系工程的 --host 参数只认识标准三元组，写 -ohos 直接不认，必须传 aarch64-linux-gnu。同一套脚本里两个变量并存（TARGET_TRIPLE 与 TARGET_HOST），混用一次就会在 configure 阶段失败，这个细节踩过之后写进了 env.sh。

难点三：libmariadb 的 OpenSSL 探测在交叉编译下失效

libmariadb 的 CMake 里有 FIND_PACKAGE(OpenSSL)，其内部 TRY_RUN 需要真实运行探测程序——交叉编译时这不可能成功，OPENSSL_FOUND 拿不到值，TLS 支持就被静默裁掉。解法是构建脚本用 sed 往它的 CMakeLists 注入一段 OHOS_CROSS_COMPILE_HACK，跳过探测、直接注入头文件与库路径。同类问题还包括 CMAKE_SYSTEM_NAME 必须显式写 Linux，否则 CMake 在 macOS 上把它检测成 Darwin，交叉编译直接翻车。

难点四：MySQL 8 的默认认证插件在沙箱里走不通

MySQL 8.0+ 默认认证是 caching_sha2_password，libmariadb 对这类认证插件默认动态加载。桌面 Linux 上没问题，但应用沙箱里没有插件搜索路径，运行时找不到插件文件，连接直接报错。解法是编译期把全部客户端认证插件 STATIC 静态链进 libmariadb.so，用不到的（GSSAPI 等）直接 OFF。这个坑的隐蔽之处在于编译期毫无征兆，只有真机连 MySQL 8 时才炸。

难点五：让数据网格像桌面工具，而不是手机列表

数据网格是数据库工具的体验核心。手机上滚动列表就够了，但桌面工具要求：行内编辑、批量事务提交 / 回滚、脏数据守卫（有未提交修改时拦截误切换）、列宽拖拽、快速过滤、无主键表编辑风险告警、BLOB / TEXT 大字段专用编辑器。这些在 ArkUI 下逐个实现，靠 State Management V1 管理编辑缓冲与脏标记，工作量占整个项目近三分之一，但没有捷径。

难点六：ArkTS 严格模式下的规模约束

约 1.6 万行 ArkTS 全程严格模式：禁 any、禁对象字面量类型推断、禁动态属性访问。前期觉得约束多，后期发现它倒逼出清晰的分层（pages / viewmodel / model / dbclient / catalog），跨层引用全部显式类型。对这种规模的移植项目，严格模式实际是护栏而不是负担。

六、关键适配改动

工具链封装（native/build/env.sh）。统一收敛 OHOS ARM64 交叉编译环境：SDK 自带 clang、--sysroot 指向 musl sysroot、链接器 ld.lld，并导出 TARGET_TRIPLE（给 clang）与 TARGET_HOST（给 autoconf）两个变量，所有构建脚本只从这一个文件取环境。

兼容桩注入（native/compat/musl_compat.h）。如难点一所述，以 -include 强制注入，替代逐库改源码。升级库版本时不需要重新维护补丁集。

幂等构建脚本（native/build/build_libs.sh）。按「先依赖后主库」顺序编译 6 个库，源码包已存在则跳过下载、已解压则跳过解压、产物已存在则跳过编译，全流程可重复执行；版本锁定，保证可复现。

统一 provider 接口与组包（entry/src/main/cpp/）。C++ 层定义 DbProvider 抽象接口（连接、断开、Ping、查询、结果集、转义、服务端版本），三个数据库各自实现；CMake 链接 sqlite3 / mariadb / ssl / crypto 与 SDK 的 ace_napi.z / hilog_ndk.z，POST_BUILD 自动把依赖 .so 拷进产物目录，运行时靠 -Wl,-rpath,$ORIGIN 就近加载——HAP 自包含，设备上不需要任何预装库。

PC 形态适配（entry/src/main/ets/entryability/EntryAbility.ets）。主窗口拉起即设为 1280×800，符合桌面工作区习惯；module.json5 的 deviceTypes 显式声明 2in1，PC 上安装即全宽窗口呈现，而非手机全屏比例。

安全存储（entry/src/main/ets/model/SecureSecretStore.ets）。基于 @ohos.security.huks 的 AES 能力对会话密码加解密，密钥由系统 HUKS 管理，应用侧不落明文。

七、编译、安装与启动

1. 交叉编译数据库客户端库

前置：已安装 DevEco Studio（含 HarmonyOS SDK），本机具备 cmake、make、curl、tar、xz、unzip。cmake 优先使用 SDK 自带的 native/build-tools/cmake。

cd native/build
./build_libs.sh all            # 按依赖顺序编译全部 6 个库
# 也可以单独编某一个：
./build_libs.sh openssl
./build_libs.sh libmariadb

产物落在 native/prebuilt/arm64-v8a/（.so + 头文件），NAPI 模块构建时自动链接并随 HAP 打包。

2. 构建 HAP 并签名

用 DevEco Studio 打开工程根目录，先在 File > Project Structure > Signing Configs 点 Fix 生成调试签名，再连设备点 Run；或用命令行：

hvigorw assembleHap

产物为 entry/build/default/outputs/default/entry-default-signed.hap，native 依赖库全部随包。

3. 安装并启动

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

启动后应看到会话管理页，而不是任何探测或加载页面。新建一个 MySQL 会话（填主机、端口、账号），点「测试连接」确认握手成功，再点「连接」进入工作台。

八、当前可用范围与能力边界

按仓库 README.OpenHarmony_CN.md 的 T0 / T1 / T2 三阶段口径，当前状态如下：

T0（能编译、能安装、能启动）——已完成：OHOS ARM64 交叉编译工具链封装完毕；SQLite / OpenSSL / libmariadb 交叉编译产物就绪；NAPI 统一桥接层与 HAP 构建通过；2in1 设备形态适配完成。

T1（核心功能）——MySQL / MariaDB 主线已完成：会话管理、真实连接（native_password 与 caching_sha2_password 认证、可选 TLS）、数据库树导航、数据网格浏览与编辑（批量事务提交 / 回滚）、SQL 编辑器（高亮 / 执行 / 历史）、结构管理（字段 / 索引 / 外键 DDL）、SQL / CSV 导出与 CSV 导入、用户管理与偏好设置。上文截图即为这条主线的真机运行证据。

T2（扩展与后续）：SQLite 与 PostgreSQL 两个后端当前为桩实现——统一 provider 接口、构建脚本、ArkTS 调用层全部备好，libsqlite3.so 已交叉编译并链接，属于「恢复实现」的工作量，不存在架构性堵点；SSH 隧道与 MSSQL / Interbase / Firebird 支持暂不计划，对齐上游 Roadmap 的取舍。

需要如实说明的边界：数据编辑的批量提交依赖目标表具备主键或唯一键，无主键表提供的是带风险告警的受限编辑；连接远程数据库需要 ohos.permission.INTERNET（已在 module.json5 声明）；截图采集自模拟器，但安装、启动、连接的命令序列在真机上逐字相同。

九、总结

HeidiSQL 的鸿蒙 PC 适配走了一条与「运行时移植」不同的路：界面与领域逻辑用 ArkTS / ArkUI 原生重写，数据库协议层交叉编译成熟的 C 客户端库，NAPI 做桥。从结果看，这条路线的主链路——交叉编译、桥接、打包、安装、连接、浏览、编辑、执行 SQL——已经完整走通，四张截图覆盖了从会话管理到 SQL 执行的真实用户路径。

这次移植有三点经验值得沉淀给同类项目。第一，能复用的协议层绝不重写：libmariadb 这类 C 库在 musl 工具链下的坑（三元组、TRY_RUN、认证插件）虽多，但全部可以收敛进一个幂等脚本和一个兼容桩头，一次解决、次次复用。第二，原生重写的成本大头在交互密度而非页面数量：数据网格一个组件的工作量接近全局三分之一，但这正是「桌面工具」与「手机套壳」的分水岭。第三，适配状态要按用户路径如实标注：能启动不等于能连接，界面出现不等于功能闭环——仓库中 T0 / T1 / T2 的划分与本文的边界说明，就是为了把「已验证的」与「待完成的」说清楚。

开源鸿蒙 PC 需要的正是这类日常基础设施软件。HeidiSQL 鸿蒙版的代码已托管在 AtomGit，欢迎加入开源鸿蒙 PC 社区参与共建：无论是 SQLite / PostgreSQL 后端的集成、数据网格的性能打磨，还是新场景的适配反馈（设备型号 + 系统版本），都是很好的贡献起点。