MySQL Workbench 鸿蒙 PC 适配全记录：从 GTK_X11 桌面程序到 ArkUI 原生数据库工作台

庆登登登

7人浏览 · 2026-09-13 16:54:59

庆登登登 · 2026-09-13 16:54:59 发布

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

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

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_mysql-workbench

一、为什么适配 MySQL Workbench

MySQL Workbench 是 MySQL 生态中最具代表性的桌面客户端之一。它不只是一个 SQL 输入框，而是把连接配置、Schema 浏览、结果集编辑、服务器管理、权限维护和 EER 数据建模组成了一套完整工作流。对 HarmonyOS PC 而言，适配这类工具的价值在于补齐本地数据库开发环境：开发者可以在同一台设备上完成连接、查询、数据检查和模型分析，而不必为了基本管理操作切换到其他平台。

这个项目同时具有很强的适配代表性。上游 Workbench 是一个以 C++ 为主、依赖 GTK/X11 前端、mforms 控件抽象、GRT 对象运行时、Python 模块和动态插件的大型桌面应用。这些组件默认站在传统 Linux 桌面的文件系统、进程模型和图形栈之上，不能仅靠修改编译参数就直接进入 HAP。适配的关键不是把原界面“搬过来”，而是先在鸿蒙的应用模型中重建一条真正可用的数据库工作流。

二、路线选择：保留数据库能力，重建平台运行面

鸿蒙版采用“Stage 应用 + ArkUI/ArkTS 桌面界面 + C++ N-API 数据库桥”的原生路线。ArkUI 负责窗口、工作区、文件选择和状态管理；C++ 层将 MariaDB Connector/C、OpenSSL 和 libssh2 静态组进 libentry.so，负责 MySQL 认证、TLS、SSH 直连转发、SQL 执行、查询取消以及 .mwb 归档读写。

能力层	上游 Workbench	HarmonyOS PC 当前实现
桌面前端	GTK/Gtkmm、X11	ArkUI/ArkTS Stage 界面
数据库连接	Workbench CDBC/GRT 调用链	C++ N-API + MariaDB Connector/C
TLS 与 SSH	OpenSSL、Workbench SSH 层	静态 OpenSSL + libssh2 direct-tcpip
界面扩展	`mforms`、GRT 模块、Python 插件	当前以 ArkUI 原生功能页为主
模型文件	完整 Workbench XML 对象图	物理表导入 + 保留归档 + Harmony sidecar

这条路线有一个必须说清的边界：frontend/ohos 是独立构建的鸿蒙原生预览，当前没有把上游 GRT、wbpublic、wbprivate、mforms 以及全部模块/插件链接进 HAP。因此，它的准确定位是“面向 HarmonyOS PC 的 MySQL Workbench 核心工作台”，而不是上游桌面版已经整体原样迁移。

三、鸿蒙工程结构与运行链路

与鸿蒙适配直接相关的内容集中在 frontend/ohos/：

frontend/ohos/
├── AppScope/app.json5                         # bundle、版本和应用资源
├── build-profile.json5                       # API 22 产品与构建配置
├── entry/src/main/
│   ├── module.json5                          # EntryAbility、2in1 和系统权限
│   ├── ets/entryability/EntryAbility.ets     # Stage 应用生命周期
│   ├── ets/pages/Index.ets                   # SQL、Administration、Modeling 工作区
│   └── cpp/
│       ├── native.cpp                       # MySQL、查询、文件与模型 N-API
│       ├── ssh_tunnel.cpp                   # SSH direct-tcpip 隧道
│       └── CMakeLists.txt                   # AArch64 原生库组装
├── vendor/                                      # 目标端 MariaDB/OpenSSL/libssh2
├── tools/audit-harmony-hap.sh                   # bundle、ABI 和动态依赖审计
└── docs/                                        # 功能矩阵与真机验证记录

运行时，EntryAbility 首先加载 pages/Index，ArkTS 将连接参数传入 N-API，原生桥完成网络连接和 SQL 执行，再把列名、行数据、影响行数、警告和执行耗时返回 ArkUI。查询是异步的，长时间语句不会直接堵塞桌面主线程；取消操作则通过第二条服务器控制连接发出 KILL。

四、从连接到模型的真机验证

以下 5 张图均在已连接的 HUAWEI MateBook Pro HarmonyOS PC 真机上采集，原始分辨率为 3120×2080。当次运行使用真机安装的 com.mysql.workbench.harmony HAP，通过 HDC 反向端口连接隔离的 MySQL Community Server 8.0.45 验证库；截图中的 Schema、表数据、服务器状态和建模结果均来自本次实际操作。

1. 连接 MySQL 8 并执行 SQL

连接面板支持主机、端口、用户、默认 Schema、TLS 和 SSH 配置。密码、SSH 密码与私钥口令只保留在当前会话，不随连接 Profile 持久化。本次真机执行 SELECT VERSION() 和 CURRENT_USER()，结果网格返回 MySQL 8.0.45 以及实际认证账号。

在这里插入图片描述

2. 浏览 Schema 并保留真实数据语义

Navigator 刷新 mwb_device_test 后，可以展开基础表、视图、存储过程和函数。选中 people 表后，客户端按 100 行分页读取数据，并识别主键 id。截图中同时包含中文字符、SQL NULL 和 3 字节 BLOB，这三类数据用于检查 UTF-8、空值与二进制列在展示和后续写回时不被混淆。

在这里插入图片描述

3. 从管理工作区读取服务器状态

Administration 不是静态信息页。点击 Refresh Status 后，应用执行 SHOW GLOBAL STATUS，当次返回 494 行状态变量，包括客户端中止计数、binlog cache 使用情况和收发字节数。同一工作区还提供 Server Variables、Client Connections、Users and Privileges、数据导出与恢复入口。

在这里插入图片描述

4. 对在线 Schema 执行反向工程

Modeling 工作区会遍历当前 Schema 中的基础表，读取 SHOW CREATE TABLE、索引和外键元数据，再生成可编辑的模型。截图中 departments、employees、no_primary_key 和 people 都是从当次在线数据库反向生成，画布上的外键连线对应 employees.department_id 到 departments.id 的真实约束。

在这里插入图片描述

5. 在模型中检查 DDL、索引和外键

在 Catalog Tree 中选中 employees 后，右侧 Table Editor 会加载服务器返回的 CREATE TABLE 定义，并把主键、普通索引和外键拆分到对应编辑区。当前版本还可基于模型生成 DDL、比较在线 Schema，并对只包含 CREATE TABLE 或受限 ALTER TABLE ... ADD/MODIFY 的同步语句进行显式审阅与应用；破坏性语句不会被直接执行。

在这里插入图片描述

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

难点一：真正的平台边界不只是 GTK 窗口

上游界面依赖 GTK/Gtkmm，模型画布还牵涉 Cairo、OpenGL、GLX 和 X11；与界面紧密合作的后端又依赖 mforms、GRT、Python 和插件装载路径。如果只替换顶层窗口，底层的类型、资源和运行时假设仍会向鸿蒙侧泄漏。当前方案先用 ArkUI 建立独立平台面，把数据库通信与模型处理收口到 N-API 边界，为后续逐步迁移可复用层留出稳定接口。

难点二：MySQL 8 认证插件必须跟随 HAP 交付

MySQL 8 常用 caching_sha2_password、sha256_password 等客户端认证插件。桌面 Linux 通常可以从安装目录动态加载，而 HAP 沙箱中不宜依赖一个额外的可写插件目录。适配工程因此对 MariaDB Connector/C 增加 OpenHarmony 补丁，将所需认证插件与 Connector、OpenSSL 静态链接到 libentry.so。HAP 审计脚本还会检查 AArch64 ABI 和动态依赖，防止出现“能编译，真机却找不到插件”的交付缺口。

难点三：NULL、文本和 BLOB 不能共用一套显示逻辑

结果网格中的 NULL 是数据库语义，不是字符串；[BLOB 3 bytes] 是二进制列的展示标记，也不能在编辑后原样写回。适配过程中曾发现 MySQL 字段的 BINARY_FLAG 会让普通元数据被误判为 BLOB，后续将判定收紧为“二进制字符集 + 明确二进制字段类型”，并在内部保留 NULL/BLOB 标记，避免网格文本污染真实数据。

难点四：网络安全选项必须在沙箱内形成闭环

TLS 的 CA/CRT/CER 文件要通过系统选择器导入并复制到应用私有证书目录，再交给原生层建立 TLS 连接。SSH 隧道不仅要支持密码和私钥，还要在默认严格模式下校验 OpenSSH known_hosts；缺失或不匹配的主机密钥应在数据库认证前就拒绝连接。这些设计已经进入实现，但完整的 TLS/SSH 正反用例仍需继续扩大真机回归。

难点五：`.mwb` 不是一个可以随意重写的 JSON 文件

Workbench 模型是包含 XML、附件和其他条目的 ZIP 归档。当前鸿蒙版能导入物理 MySQL 表、列、索引与外键，导出时保留原始 XML、附件、归档注释和未知条目，并把鸿蒙侧可编辑模型写入 harmony/model.json。这保证了未识别数据不被破坏，但也意味着当前还不能将它描述为完整的 Workbench XML 对象回写。

六、编译、签名与真机启动

当前工程面向 HarmonyOS PC 2in1、arm64-v8a，compileSdkVersion、compatibleSdkVersion 和 targetSdkVersion 均为 6.0.2(22)。开发机需要 DevEco Studio 6.0.2 SDK、Native SDK、DevEco JBR、ohpm、Hvigor、CMake、Ninja 和 HDC。这一版鸿蒙前端使用 ArkUI/ArkTS，不依赖 Qt 或 Electron，因此不需要额外引用两者的环境搭建流程。

首先准备 OHOS AArch64 的静态依赖。MariaDB Connector/C 需应用仓库内的 OpenHarmony 补丁，并将 MySQL 8 认证插件设为静态；OpenSSL 和 libssh2 也需按目标 ABI 构建。最终 CMake 会检查以下核心产物：

vendor/build/mariadb-ohos/libmariadb/libmariadbclient.a
vendor/build/openssl-ohos/libssl.a
vendor/build/openssl-ohos/libcrypto.a
vendor/build/libssh2-ohos/src/libssh2.a

构建 HAP：

cd frontend/ohos
ohpm install --all
env JAVA_HOME=/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home \
  DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
  PATH=/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home/bin:$PATH \
  /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  --mode project -p product=default assembleApp --no-daemon

未签名产物默认位于：

frontend/ohos/entry/build/default/outputs/default/entry-default-unsigned.hap

组包后应先运行项目审计，检查 bundle name、2in1 声明、AArch64 原生库、N-API 运行时依赖以及 MariaDB/OpenSSL/libssh2 是否按预期静态组包：

cd frontend/ohos
bash tools/audit-harmony-hap.sh \
  entry/build/default/outputs/default/entry-default-unsigned.hap
bash tools/check-mwb-fixtures.sh

公开仓库不应包含证书、私钥、Profile 或签名密码。使用 DevEco Studio 为 com.mysql.workbench.harmony 配置与目标设备匹配的开发者签名后，再安装并启动：

hdc install -r entry-default-signed.hap
hdc shell aa start \
  -a EntryAbility -b com.mysql.workbench.harmony -m entry

设备启动后，应实际连接可达的 MySQL 服务，通过 SQL 结果、服务器日志和真机截图共同验收；单独的签名校验或 HAP 安装成功不等于数据库功能已经通过。

七、当前能力与明确边界

当前实现已覆盖 MySQL TCP 连接与断开、MySQL 8 认证、可选 TLS/SSH、单条与多结果集 SQL、查询取消、Schema/表/视图/例程/触发器浏览、结果排序和导出、主键表数据编辑、状态/变量/会话/账户管理、Schema 备份，以及基础模型反向工程、DDL 生成与差异比较。本文 5 张截图只选择连接查询、真实表数据、服务器状态和模型链路，因为它们能直接证明界面、原生桥和 MySQL 服务器之间已经形成实际数据往返。

仍需保留以下边界：

完整 EER 画布语义、全量 Workbench XML 对象回写和高级建模交互尚未对齐上游。
GRT、mforms、wbpublic、wbprivate、Python 模块和 Workbench 插件体系尚未整体进入鸿蒙产物。
MySQL 5.7/8.4 兼容矩阵、TLS 正反向证书、SSH 密码/私钥/host-key mismatch、大结果集、取消、导入导出、备份恢复和权限变更仍需完成更完整的真机回归。
当前功能矩阵中“已实现”表示源码路径已存在，不能等同于对应功能域已经完成全量真机验收。

八、总结

MySQL Workbench 的 HarmonyOS PC 适配说明，大型桌面开发工具的迁移不能用“窗口能打开”来判定成功。数据库客户端的真正主线是：在目标设备上完成认证，执行真实 SQL，正确往返文本、NULL 和二进制数据，再把元数据、管理信息和模型结果稳定地送回桌面工作区。

当前版本已经在真机上跑通 MySQL 8.0.45 连接、SQL 查询、Schema 和表数据浏览、服务器状态读取，以及基础表和外键的反向建模。更重要的是，这次适配已经把 GTK/X11 桌面假设、数据库通信、安全密钥、HAP 沙箱和 .mwb 归档之间的边界理清。后续可以沿着这些边界继续扩展 GRT/插件覆盖和严格真机验收，而不必推翻已经建立的鸿蒙原生运行链路。