DbGate Electron 鸿蒙 PC 适配全记录：从桌面数据库工具到 OpenHarmony HAP

JoJo的数据分析历险记

60人浏览 · 2026-06-15 12:27:02

JoJo的数据分析历险记 · 2026-06-15 12:27:02 发布

DbGate Electron 鸿蒙 PC 适配全记录：从桌面数据库工具到 OpenHarmony HAP

一、写在前面

欢迎加入鸿蒙 PC 开发者社区，共同打造开发者工具生态：鸿蒙 PC 开发者社区：https://harmonypc.csdn.net/

DbGate 原项目开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_dbgate

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

环境搭建文章：https://blog.csdn.net/lbcyllqj/article/details/161286249?sharetype=blogdetail&sharerId=161286249&sharerefer=PC&sharesource=lbcyllqj&spm=1011.2480.3001.8118

这篇文章记录的是 DbGate 桌面端适配 HarmonyOS PC / OpenHarmony Electron 运行环境的完整过程。

DbGate 是一个开源数据库管理工具，原始桌面端基于 Electron 构建，支持 MySQL、PostgreSQL、SQL Server、MongoDB、Redis、ClickHouse、SQLite 等多种数据库。和普通的纯前端 Electron 应用不同，DbGate 的桌面端并不是简单把一个 Web 页面放进窗口里运行，它的主进程里还承载了 Node.js API、数据库驱动、插件加载、配置目录、日志目录、IPC 通信等能力。

所以这次鸿蒙适配的重点不是“页面能打开”这么简单，而是要让下面几件事情同时成立：

HAP 工程能够独立构建、安装和启动；
Electron 主进程能够在鸿蒙环境里正确加载 DbGate；
Svelte 前端资源能够完整打进 HAP；
Node.js API bundle 和插件产物能够在 HAP 资源目录下被找到；
用户配置、日志、工作目录能够写入鸿蒙应用沙箱；
基础数据库连接表单、设置页、侧边栏等核心界面能够在鸿蒙 PC 模拟器里正常操作；
后续能够通过命令行脚本重复构建和自动冒烟测试。

最终适配完成后，DbGate 已经可以在 HarmonyOS PC 模拟器中启动并进入主界面，能够打开新建连接页、切换数据库类型、展开 MySQL 连接表单、进入设置页，并完成几个主要侧边栏页面的跳转验证。

在这里插入图片描述

二、项目技术栈分析

适配之前，先看了一遍 DbGate 的项目结构。这个项目是一个典型的 monorepo，根目录下包含多个 workspace：

packages/
├── api
├── web
├── datalib
├── filterparser
├── rest
├── sqltree
├── tools
└── types

plugins/
└── dbgate-plugin-*

app/
└── src/electron.js

主要技术栈如下：

Electron 38；
Svelte 4；
Rolldown；
Tailwind CSS；
Node.js API bundle；
Electron IPC；
多数据库插件体系；
多种数据库驱动，例如 mysql2、pg、mongodb、ioredis、tedious、@clickhouse/client 等；
Cypress E2E 测试体系。

其中最关键的运行链路是：

Electron 主进程启动；
主进程加载 DbGate API bundle；
主进程创建 BrowserWindow；
BrowserWindow 加载 packages/web/public/index.html；
Svelte 前端通过 Electron IPC 调用主进程 API；
API 根据用户操作加载数据库插件和驱动。

这条链路说明了一个问题：DbGate 的鸿蒙适配不能只迁移 packages/web/public，还必须同步主进程源码、API bundle、插件产物和 Node 运行依赖。

在这里插入图片描述

三、适配思路：保留 Electron 架构，新增鸿蒙 HAP 承载层

这次适配没有重写 DbGate 的业务逻辑，而是保留原来的 Electron 桌面架构，在项目里新增一层 OpenHarmony Electron HAP 工程。

新增的鸿蒙工程目录为：

ohos_hap/
├── AppScope/
├── electron/
├── web_engine/
├── build-profile.json5
└── README.md

真正放置 DbGate 运行资源的位置是：

ohos_hap/web_engine/src/main/resources/resfile/resources/app

这个目录在 HAP 中相当于 Electron runtime 的应用资源目录。适配脚本会把 DbGate 所需的运行资源同步进去，包括：

app/src 主进程源码；
packages/api/dist/bundle.js；
packages/web/public/index.html；
packages/web/public/build/bundle.js；
packages/web/public/build/bundle.css；
packages/web/public/build/tailwind.css；
packages/web/public/build/query-parser-worker.js；
plugins/dist/dbgate-plugin-*；
运行所需的 node_modules；
自动生成的 main.js；
自动生成的 runtime package.json。

在这里插入图片描述

四、第一步：新增资源同步脚本

为了让 DbGate 的桌面产物进入鸿蒙 HAP，需要新增一个资源同步脚本：

scripts/build-ohos-package.js

这个脚本主要做几件事：

检查并构建 DbGate workspace 产物；
检查并构建 API bundle；
检查并构建 Web 前端产物；
检查并同步插件产物；
清空鸿蒙资源输出目录；
复制主进程、Web、API、插件和依赖；
写入鸿蒙环境下的 main.js 启动入口；
写入 runtime package.json。

根目录 package.json 增加了几个命令：

{
  "build:ohos": "node scripts/build-ohos-package.js",
  "ohos:sync": "OHOS_DBGATE_OUT=ohos_hap/web_engine/src/main/resources/resfile/resources/app node scripts/build-ohos-package.js",
  "ohos:build": "node scripts/build-ohos-hap.js",
  "ohos:smoke": "node scripts/smoke-ohos-emulator.js"
}

平时同步资源可以执行：

fnm exec --using v16.20.2 corepack yarn ohos:sync

如果想强制重新构建 DbGate 产物，可以执行：

OHOS_DBGATE_FORCE_REBUILD=1 fnm exec --using v16.20.2 corepack yarn ohos:sync

五、第二步：生成鸿蒙 Electron 启动入口

DbGate 原来的 Electron 入口是：

app/src/electron.js

但是在 HAP 里不能直接沿用桌面端的目录假设。因此同步脚本会在资源目录下生成一个新的启动入口：

ohos_hap/web_engine/src/main/resources/resfile/resources/app/main.js

生成后的核心逻辑类似这样：

'use strict';

const path = require('path');

process.env.DBGATE_OPENHARMONY = '1';
process.env.BUILTWEBMODE = '1';
process.env.DBGATE_DISABLE_GPU = process.env.DBGATE_DISABLE_GPU || '1';
process.env.WORKSPACE_DIR =
  process.env.WORKSPACE_DIR || path.join(require('electron').app.getPath('userData'), '.dbgate');

global.API_PACKAGE = path.join(__dirname, 'packages/api/dist/bundle.js');

require('./src/electron.js');

这段入口代码做了几件很重要的事情：

用 DBGATE_OPENHARMONY=1 标记当前运行在鸿蒙环境；
用 BUILTWEBMODE=1 让 DbGate 按构建后的 Web 资源路径运行；
默认禁用 GPU，降低鸿蒙 Electron runtime 下的渲染兼容风险；
把 DbGate 工作目录放到鸿蒙应用沙箱的 userData/.dbgate 下；
明确指定 API bundle 的路径；
最后继续复用原来的 app/src/electron.js。

这样做的好处是：主工程的 Electron 逻辑可以被最大程度复用，鸿蒙差异只通过环境变量和少量平台判断收口。

在这里插入图片描述

六、第三步：修改 Electron 主进程以适配鸿蒙运行环境

DbGate 的主进程文件是：

app/src/electron.js

这里主要增加了鸿蒙平台识别：

const isOpenHarmony = process.env.DBGATE_OPENHARMONY == '1';

然后围绕这个标记处理几类桌面端和鸿蒙端的差异。

6.1 禁用自动更新

桌面端 DbGate 使用 electron-updater 处理自动更新，但 HAP 应用的分发和更新机制不应该继续走桌面端 updater。因此鸿蒙环境下使用一个空实现：

const noopAutoUpdater = {
  autoDownload: false,
  allowPrerelease: false,
  channel: null,
  logger: null,
  isUpdaterActive: () => false,
  checkForUpdates: () => null,
  downloadUpdate: () => null,
  quitAndInstall: () => null,
  on: () => null,
};

const autoUpdater = isOpenHarmony ? noopAutoUpdater : require('electron-updater').autoUpdater;

这样可以避免应用启动后访问桌面端更新逻辑，也避免在鸿蒙环境中引入不必要的 updater 行为。

6.2 禁用硬件加速

鸿蒙 PC 模拟器里，Electron GPU 相关能力容易受到运行时和模拟器图形栈影响。为了先保证基础可用性，鸿蒙环境下默认禁用硬件加速：

if (isOpenHarmony || process.env.DBGATE_DISABLE_GPU == '1') {
  app.disableHardwareAcceleration();
}

这不是性能最优方案，但对首版适配来说更稳。

6.3 使用鸿蒙应用沙箱目录

原桌面端通常会把工作目录放在用户 home 下的 .dbgate。鸿蒙 HAP 环境中，应用应优先写入自己的沙箱目录。因此适配后使用：

const datadir =
  process.env.WORKSPACE_DIR ||
  path.join(isOpenHarmony ? app.getPath('userData') : os.homedir(), '.dbgate');

同时 packages/api/src/utility/directories.js 中创建目录时改成递归创建：

fs.mkdirSync(dir, { recursive: true });

这样首次启动时，即使父目录不存在，也能正常创建 .dbgate、logs、files 等目录。

6.4 使用原生菜单和常规标题栏

鸿蒙 PC 环境下，窗口标题栏、菜单和桌面端有差异。适配时将鸿蒙环境默认视为使用原生菜单，避免隐藏标题栏等桌面端定制窗口行为带来的兼容问题。

在这里插入图片描述

七、第四步：构建 HAP

资源同步完成后，还需要通过 OpenHarmony 工程构建出 HAP。这里新增了：

scripts/build-ohos-hap.js

这个脚本负责：

调用 build-ohos-package.js 同步 DbGate 资源；
执行 ohpm install 安装鸿蒙工程依赖；
准备 Hvigor / pnpm 本地缓存；
补齐本地 oh_modules 链接；
查找 DevEco Studio SDK；
查找合适的 Node 环境；
调用 Hvigor 构建 HAP。

命令如下：

YARN_IGNORE_ENGINES=1 fnm exec --using v16.20.2 corepack yarn ohos:build

构建完成后，HAP 输出位置为：

ohos_hap/electron/build/default/outputs/default/electron-default-unsigned.hap

本次构建出的 HAP 大约 462 MB。包体积偏大是预期内的，因为 DbGate 需要携带 Electron runtime、API bundle、多数据库插件和部分 Node 运行依赖。

在这里插入图片描述

八、适配过程中遇到的主要问题

8.1 问题一：应用能启动，但一直卡在三个点加载页

这是本次适配中最典型的问题。

现象是：HAP 能安装，应用也能启动，窗口中出现 DbGate 的初始加载页，但一直停在三个点 loading 状态，无法进入主界面。

一开始容易怀疑是 Electron IPC、API bundle 或数据库插件加载失败。但进一步检查 HAP 资源后发现，真正原因是：

HAP 中只有 packages/web/public/index.html，
但没有 packages/web/public/build/bundle.js 和相关 CSS。

DbGate 的 index.html 会加载：

build/bundle.js
build/bundle.css
build/tailwind.css
build/query-parser-worker.js

如果这些资源没有打入 HAP，Svelte 应用根本不会 mount，页面自然就会停在加载状态。

修复方式是在 scripts/build-ohos-package.js 中明确检查并同步这些 Web 构建产物：

packages/web/public/build/bundle.js
packages/web/public/build/bundle.css
packages/web/public/build/tailwind.css
packages/web/public/build/query-parser-worker.js

修复后重新执行：

yarn ohos:sync
yarn ohos:build

再次安装启动，DbGate 就可以进入主界面了。

8.2 问题二：DbGate 项目 Node 版本和 Web 构建工具 Node 版本不一致

DbGate 的部分构建流程适合 Node 16 环境，但当前 Web 构建使用的 Rolldown 对 Node 版本有更高要求。实际构建时遇到过类似问题：

node:util does not provide an export named styleText

这类错误本质上是构建工具使用了新版本 Node 才有的 API。

解决方式是在 build-ohos-package.js 中增加现代 Node 查找逻辑。脚本会优先查找：

OHOS_WEB_BUILD_NODE_HOME
OHOS_HVIGOR_NODE_HOME
NODE_HOME
本机 fnm 下的 Node 24、22、20、18

当需要执行 build:web 时，优先用较新的 Node 来跑：

runYarnScriptWithModernNode('build:web');

这样 DbGate 其他流程仍然可以在 Node 16 下执行，而 Web 构建可以自动切换到更合适的 Node。

在这里插入图片描述

8.3 问题三：数据库驱动依赖很多，native 依赖需要分阶段处理

DbGate 支持的数据库很多，对应依赖也比较复杂。像下面这些依赖相对适合作为首版能力验证：

mysql2
pg
mongodb
ioredis
tedious
@clickhouse/client
cassandra-driver

但也有一些依赖涉及 native 二进制、系统 SDK 或平台特定能力，例如：

better-sqlite3
@duckdb/node-api
oracledb
node-firebird
msnodesqlv8
mongodb-client-encryption

这些 native 驱动不能简单复制进 HAP 就认为可用，需要在 OpenHarmony arm64 环境下单独验证、编译或替换。因此首版适配的策略是：

先保证 Electron 壳、Svelte 前端、API bundle、插件加载和网络数据库驱动可运行；native 风险驱动放到后续专项适配。

同步脚本中也保留了开关：

OHOS_DBGATE_INCLUDE_NATIVE_DRIVERS=1 yarn ohos:sync

只有需要专门验证 native 驱动时才开启。

8.4 问题四：HAP 日志噪音很多，要区分系统日志和应用问题

在鸿蒙模拟器中查看 hilog 时，会看到不少系统层面的 PARAM、accessibility、window、SCB 等日志。这些日志不一定代表 DbGate 崩溃。

实际排查时更关注这些关键词：

dbgate
org.dbgate.ohos
fatal
crash
uncaught
exception
SIGSEGV
abort

本次自动冒烟测试结束后，日志中可以看到 DbGate 正常启动和 MySQL 插件加载：

Loading module dbgate-plugin-mysql ...

也能看到首次运行时 settings.json 不存在：

Error loading settings.json: ENOENT ...

这个属于首次启动没有用户配置文件的正常现象，不是崩溃。

九、模拟器验证：不用手动点，写一个自动冒烟脚本

适配到“能启动”不等于真的能用。为了避免每次都手动在模拟器里点击验证，这次新增了一个自动冒烟脚本：

scripts/smoke-ohos-emulator.js

根目录命令：

yarn ohos:smoke

脚本使用 hdc 和鸿蒙系统自带的 uitest 能力完成自动化操作：

安装 HAP；
启动应用；
截图；
dump 当前窗口布局；
等待 DbGate 主界面出现；
点击新建连接；
打开数据库类型下拉框；
选择 MySQL；
检查 MySQL 表单字段；
滚动到底部；
点击 Test 按钮；
检查页面仍然稳定；
打开 Settings；
点击 Saved files；
点击 Query history；
点击 DbGate Cloud；
回到 Connections。

实际执行命令：

YARN_IGNORE_ENGINES=1 fnm exec --using v16.20.2 corepack yarn ohos:smoke

执行结果：

OpenHarmony smoke test passed.

本次通过的检查项包括：

launch
new-connection-form
driver-dropdown
mysql-form
mysql-form-actions
test-button-stability
settings
saved-files
query-history
cloud
connections-sidebar

测试结果会保存在：

ohos_hap/smoke-results/<timestamp>/

十、当前完成度和功能边界

目前已经完成的能力：

DbGate HAP 工程接入；
命令行资源同步；
命令行 HAP 构建；
Electron 主进程鸿蒙平台识别；
鸿蒙环境禁用桌面自动更新；
鸿蒙环境默认禁用 GPU；
用户数据目录迁移到应用沙箱；
API bundle 打包和加载；
Svelte Web 产物完整打包；
插件产物同步；
MySQL 插件加载验证；
HarmonyOS PC 模拟器启动验证；
新建连接页面验证；
数据库类型下拉框验证；
MySQL 连接表单验证；
Settings 页面验证；
Saved files、Query history、Cloud、Connections 侧边栏验证；
自动冒烟脚本。

首版功能边界：

目标是让用户在 HarmonyOS PC 上完成基础数据库管理流程；
网络型数据库驱动优先验证；
SQLite、DuckDB、Oracle、Firebird、SQL Server native driver 等 native 依赖需要后续单独适配；
模拟器里的 WebView 输入框文本注入不够稳定，因此自动化里只验证了点击 Test 后页面稳定，没有完成真实账号密码连接数据库的全链路自动输入测试。

在这里插入图片描述

十一、总结

DbGate 的鸿蒙 PC 适配可以概括为一句话：

保留原有 Electron + Svelte + Node API + 插件体系，在外层增加 OpenHarmony Electron HAP 承载，并把桌面端运行假设逐步改成鸿蒙应用沙箱下可成立的运行假设。

这次适配中最关键的不是某一处代码修改，而是把完整运行链路打通：

DbGate 源码
  -> workspace 构建
  -> API bundle
  -> Svelte public/build
  -> plugins/dist
  -> resources/app
  -> OpenHarmony Electron runtime
  -> HAP
  -> HarmonyOS PC 模拟器
  -> 自动冒烟测试

其中最容易被忽略的问题是 Web 资源不完整。应用能启动不代表前端已经真正加载成功，像 index.html 引用了哪些 JS、CSS、worker，都必须明确进入 HAP 资源目录。

整体来看，DbGate 这类复杂 Electron 桌面工具迁移到鸿蒙 PC 并不是简单搬一个前端页面，而是一次完整的运行时工程迁移。只要主进程入口、资源路径、Node 依赖、插件产物和应用沙箱这几条线处理清楚，传统 Electron 桌面软件在 HarmonyOS PC 上达到基础可用是完全可行的。