MariaDB Server 鸿蒙 PC 适配全记录：从大型 C_C++ 工程交叉编译到 HNP 真机运行

sdp安歌

7人浏览 · 2026-09-13 16:23:44

sdp安歌 · 2026-09-13 16:23:44 发布

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

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

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_mariadb-server

一、为什么要适配 MariaDB Server

MariaDB 是一套成熟的开源关系型数据库，既保留了 MySQL 生态中常用的协议和客户端习惯，也持续发展自己的存储引擎、优化器与运维工具。在开发环境、教学实验、离线数据处理和本地应用调试中，数据库往往不是独立存在的终端产品，而是其他软件能够落地运行的基础设施。将 MariaDB 带到鸿蒙 PC，可以让原生应用在设备本地获得完整的 SQL 数据服务，也为后续移植数据库管理工具、开发框架和依赖关系型存储的桌面软件补齐底层能力。

选择 MariaDB 作为适配对象，还有一层工程上的价值。它不是换一套界面框架就能运行的普通桌面应用，而是包含服务端、客户端、初始化脚本、字符集数据和存储引擎的大型 C/C++ 工程。构建阶段会执行本机代码生成器，目标端又依赖文件映射、线程、网络、动态插件和可写数据目录。这样的项目能够系统检验 HarmonyOS PC 的 Native 工具链、musl 兼容性、HNP 公共命令和 HAP 分发链路是否真正打通。

本次适配以 MariaDB 13.1.0 源码为基础，目标设备为 HarmonyOS PC 2in1，目标架构为 arm64-v8a，应用 BundleName 为 com.mariadb.ohos。最终交付采用“ArkUI 说明页 + 公共 HNP”的组合：HAP 负责应用安装、版本说明和使用引导，HNP 则携带真正运行在设备上的 mariadbd、mariadb、mariadb-install-db、mariadb-admin、mariadb-dump 等原生命令。

二、先确定适配路线：数据库内核与应用页面分层交付

MariaDB 上游默认面向传统 Linux、Unix 和 Windows 环境。把一个 mariadbd 可执行文件复制到设备上，并不能组成可用的数据库：初始化阶段需要系统表 SQL 和错误消息目录，运行阶段需要稳定的 basedir、datadir、端口和插件位置，客户端还要能够完成 TCP 握手与认证。因此，适配从一开始就按四个层次拆分：

层次	MariaDB 的默认前提	鸿蒙侧处理方式
构建期	编译机可运行刚生成的代码生成工具，并可在线获取依赖	先生成主机侧工具，通过 `IMPORT_EXECUTABLES` 供交叉构建复用；依赖改为仓库内自包含源码
编译期	目标系统提供常见 Linux/glibc 接口、OpenSSL、AIO 和 systemd	新增 OHOS 平台配置，使用 OpenHarmony AArch64 工具链和 musl 接口，按目标平台关闭或替代不可用能力
运行期	二进制、插件、SQL 数据和配置位于传统系统目录	将运行资产统一放入 HNP，并通过包装脚本设置 basedir、数据目录、主机和端口
交付期	软件由系统包管理器安装，命令天然位于 PATH	由 HAP 承担签名安装，通过公共 HNP 注册七个终端入口

这套设计刻意让页面与数据库生命周期解耦。ArkUI 页面不伪装成数据库管理器，也不把后台服务绑定到页面是否在前台；用户关闭说明页后，MariaDB 服务仍然可以由系统终端管理。数据库核心保持上游熟悉的命令行方式，鸿蒙侧只在交叉编译、路径和分发边界上做必要适配。

三、项目结构与交付内容

仓库中的鸿蒙适配工作区位于 mariadb-server-ohos-migration/，关键内容如下：

ohos_mariadb-server/
├── README.OpenHarmony_CN.md
└── mariadb-server-ohos-migration/
    ├── cmake/os/OHOS.cmake              # OHOS 平台能力与构建开关
    ├── cmake/pcre.cmake                 # OHOS 下使用仓库内 PCRE2
    ├── cmake/libfmt.cmake               # OHOS 下使用仓库内 fmt 头文件
    ├── libmariadb/                      # 客户端网络与 TLS 兼容处理
    ├── tpool/tpool_generic.cc           # 屏蔽目标端不可用的 Linux 原生 AIO
    ├── ohos/
    │   ├── build_hnp.sh                 # 交叉编译、整理运行时并生成 HNP
    │   ├── package_hap_with_hnp.sh      # 在 HAP 中注入 MariaDB HNP
    │   ├── mariadb.cnf                  # 目标端基础配置
    │   ├── hnp/arm64-v8a/mariadb.hnp
    │   └── entry/src/main/ets/pages/Index.ets
    └── OHOS_BUILD_GUIDE.md

mariadb.hnp 不只包含服务端二进制。当前包内同时提供客户端、管理和导出工具、数据库初始化脚本、系统表 SQL、帮助表数据、错误消息以及 HNP 链接清单。HNP 安装后注册以下公共命令：

mariadbd
mariadb
mariadb-install-db
mariadb-admin
mariadb-dump
my_print_defaults
resolveip

其中 .real 文件是 OpenHarmony 工具链生成的 aarch64 ELF，短命令则是轻量包装脚本。包装层统一处理 /data/service/hnp/mariadb.org/mariadb_13.1.0 安装位置、MARIADB_DATA_DIR、MARIADB_HOST 和 MARIADB_PORT，避免用户每次输入完整的 HNP 内部路径。

四、从应用安装到事务回滚的真机验证

以下五张截图均来自已连接的 HarmonyOS PC 2in1 真机，设备分辨率为 3120×2080。测试使用当前仓库生成并安装的签名 HAP，终端命令来自随应用安装的公共 HNP；截图中的版本、架构、表数据和事务结果均为设备上实际运行 MariaDB 后取得的输出。

1. 应用页明确交付边界和使用顺序

应用启动后展示 MariaDB 官方标识、版本和四条最常用的终端命令。页面没有放置无法兑现的启动按钮或 SQL 编辑器，而是直接说明初始化、启动和查询入口，让第一次使用 HNP 的读者能够从安装自然过渡到终端操作。

在这里插入图片描述

应用页承担的是可发现性和使用引导，数据库能力则由 HNP 中的原生程序提供。这样的职责划分也便于后续升级：页面资源和数据库原生包可以继续按照同一 HAP 版本交付，不需要把服务端逻辑改写成 ArkTS。

2. 先确认版本、目标系统与处理器架构

真机终端执行 mariadb --version，输出显示实际命令解析到 /data/service/hnp/mariadb.org/mariadb_13.1.0/bin/mariadb.real。随后连接本地服务查询 VERSION()、@@version_compile_os 和 @@version_compile_machine，结果分别为 13.1.0-MariaDB、OHOS 和 aarch64。

在这里插入图片描述

这一验证比页面上的版本文字更关键。页面内容来自应用资源，而终端结果来自真实客户端 ELF；SQL 查询还经过了 TCP 连接、认证、服务端解析和结果返回，说明客户端与服务端链路已经在目标设备上建立。

3. 建库、建表、插入与查询形成数据闭环

测试创建 harmony_demo 数据库，并建立使用 InnoDB 的 products 表。表中包含自增主键、字符串、DECIMAL 价格和整型库存字段，随后插入 HarmonyOS PC 与 MariaDB 13.1 两条数据并立即查询。

在这里插入图片描述

截图中的结果来自刚刚写入的数据文件，并非应用页面中的静态演示文本。这个步骤同时覆盖了系统表初始化、数据库与表创建、InnoDB 表空间、自增列、字符串处理、定点数存储以及客户端表格化输出，是判断数据库能否正常工作的最小闭环。

4. 更新、删除和受影响行数保持一致

在同一张表上继续执行 UPDATE，将第一条记录价格从 6999 调整为 6499、库存从 8 调整为 10；随后删除第二条记录。两次操作的 ROW_COUNT() 均返回 1，最终查询只保留更新后的 HarmonyOS PC 记录。

在这里插入图片描述

把修改语句、受影响行数和最终结果放在同一次验证中，可以直接确认条件匹配、数据页变更与后续读取是一致的，也排除了只展示预先准备结果的可能。

5. 用回滚验证 InnoDB 事务语义

最后开启事务，将商品价格临时改为 1.00。事务内查询可以读到新值，执行 ROLLBACK 后再次查询，价格恢复为 6499.00。

在这里插入图片描述

回滚结果说明适配后的 MariaDB 不只是能够接受 SQL 文本，InnoDB 的事务修改、撤销记录和可见性链路也在真机上正常工作。至此，当前版本已经覆盖本地数据库最核心的初始化、启动、连接、建库建表、增删改查和事务回滚流程。

五、适配过程中遇到的关键困难

难点一：交叉编译阶段不能直接执行目标端生成器

MariaDB 构建并不是单纯地把每个源文件交给交叉编译器。语法文件、错误消息和部分生成源码需要先由 comp_err、gen_lex_hash 等工具处理；这些工具如果在目标构建目录中被编译成 OHOS aarch64 ELF，就无法在 macOS 构建机上直接执行。

项目先建立 build-native 主机构建目录，生成 import_executables.cmake，再通过 IMPORT_EXECUTABLES 将本机构建工具导入交叉编译阶段。这样，生成器在开发机上运行，生成结果仍参与目标端编译，最终 HNP 中不会混入宿主机二进制。这个边界处理是大型 CMake 工程交叉编译能否稳定复现的前提。

难点二：依赖下载和目标端 TLS 不能沿用上游默认路径

上游 CMake 会在配置阶段通过 ExternalProject_Add 下载 PCRE2、fmt 等依赖，而 OpenHarmony SDK 随附的构建环境无法稳定完成这条 HTTPS 下载链路。与此同时，OHOS sysroot 不提供传统 Linux 发行版中的 GnuTLS/OpenSSL 开发包，客户端与服务端的 TLS 配置也不能依赖系统库。

适配将 PCRE2 和 fmt 调整为仓库内自包含源码：PCRE2 直接编译为位置无关的静态库，fmt 使用随仓库提供的头文件。TLS 侧复用 bundled wolfSSL 及其 OpenSSL 兼容头文件，使 Connector/C 和服务端共享一致的交叉编译依赖。这样构建不再依赖开发机的临时网络状态，也避免把宿主机库错误链接进目标产物。

难点三：OHOS musl 与 Linux/glibc 的能力边界不同

MariaDB 的 Unix 代码中包含许多“Linux 即可用”的条件判断，但 OpenHarmony 使用 musl，不能简单等同于服务器发行版。项目新增 cmake/os/OHOS.cmake，明确关闭 libwrap、systemd、Valgrind、DTrace、WSREP 和嵌入式服务端等当前目标端不具备或首轮不需要的能力，并强制使用 PIC。对于 glibc 特有的 mmap64，平台配置明确回落到 musl 提供的 mmap；线程池则避免选择依赖 Linux 原生 AIO 的实现。

这种处理不是把所有报错接口统一置空，而是区分核心数据库语义与平台集成能力。SQL 执行、InnoDB、TCP 客户端和管理工具继续保留；systemd、Galera 和 Linux AIO 等平台相关模块则在目标明确的前提下延后，减少首轮产物的依赖面。

难点四：客户端认证阶段的非阻塞发送在真机上会返回 EAGAIN

客户端最初能够创建 socket，却可能在认证握手阶段失败。原因是同步客户端路径仍使用了 send(MSG_DONTWAIT)；在 OHOS 的 socket 行为下，这一调用可能返回 EAGAIN，而上层会把它当作连接失败。

适配针对 __OHOS__ 的同步路径改为阻塞发送，同时保留 MSG_NOSIGNAL 等安全标志。包装脚本默认使用 127.0.0.1:3306 和 TCP 协议，避开应用沙箱之间难以共享的 Unix socket 路径。真机上的版本查询、CRUD 和事务结果表明，这一修改已经覆盖连接、认证和持续查询链路。

难点五：HNP 必须携带完整运行时，并进入 HAP 的打包签名链路

数据库服务端依赖的不只是 mariadbd。如果漏掉系统表 SQL、帮助表、错误消息或初始化脚本，二进制即使可以启动，也无法完成一个全新数据目录的初始化。build_hnp.sh 因此将服务端、客户端、管理工具、配置与 share/ 数据整体整理，再由 hnpcli 生成 mariadb.hnp。

普通 Hvigor 构建主要处理 ArkUI 模块，不能仅凭 module.json5 中的 hnpPackages 声明就假设 HNP 已进入最终产物。项目通过 package_hap_with_hnp.sh 调用 SDK 的 app_packing_tool.jar，以 --hnp-path 将 arm64-v8a/mariadb.hnp 注入 HAP，再对包含 HNP 的产物完成签名。真机终端能够直接解析 mariadb 公共命令，证明 HAP 安装、HNP 解包和链接注册链路已生效。

六、构建、安装与运行

MariaDB Server 不是 Electron 或 Qt 项目，因此构建使用 CMake、Ninja、OpenHarmony Native SDK、HNP 工具和 Hvigor。开发机需要安装 DevEco Studio，并准备 CMake、Ninja、Bison、Java 与可用的 HarmonyOS 应用签名。

首先生成交叉构建需要的主机侧工具：

cd mariadb-server-ohos-migration
cmake -S . -B build-native -G Ninja
cmake --build build-native --target import_executables

然后构建 MariaDB 原生产物并打包 HNP：

./ohos/build_hnp.sh

生成的 Native Package 位于：

mariadb-server-ohos-migration/ohos/hnp/arm64-v8a/mariadb.hnp

构建 ArkUI HAP 并注入 HNP：

cd ohos
ohpm install --all
env -u HOS_SDK_HOME \
  DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
  /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  assembleHap --mode module -p product=default
cd ..
./ohos/package_hap_with_hnp.sh

连接鸿蒙 PC 后安装签名产物并启动说明页：

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

在设备的系统终端中完成首次初始化和服务启动：

MARIADB_DATA_DIR=./mariadb-data mariadb-install-db
MARIADB_DATA_DIR=./mariadb-data mariadbd >./mariadbd.log 2>&1 &
mariadb-admin ping
mariadb -e "SELECT VERSION();"

如需更改监听地址或端口，可以在启动服务和客户端时设置相同的环境变量：

MARIADB_HOST=127.0.0.1 MARIADB_PORT=3307 \
  MARIADB_DATA_DIR=./mariadb-data mariadbd &
MARIADB_HOST=127.0.0.1 MARIADB_PORT=3307 mariadb

七、当前能力与适配边界

当前版本已经在 HarmonyOS PC 真机验证以下能力：

HAP 签名安装、ArkUI 页面启动与公共 HNP 解包；
mariadb、mariadbd、mariadb-install-db、mariadb-admin、mariadb-dump 等命令注册；
全新数据目录初始化和系统表创建；
MariaDB 服务启动、TCP 监听、客户端认证和管理命令探活；
OHOS aarch64 客户端与服务端版本查询；
InnoDB 数据库和表创建；
自增主键、字符串、DECIMAL 与整型字段的写入和读取；
条件更新、条件删除与受影响行数检查；
START TRANSACTION、事务内修改和 ROLLBACK 回滚；
数据库导出工具随 HNP 一同交付。

当前定位是面向鸿蒙 PC 本地开发、数据验证与实验使用的原生命令行数据库环境，不是图形化数据库管理器。页面暂不提供服务启停、SQL 编辑器、对象树和连接管理；Galera/WSREP、systemd 集成、嵌入式服务端、Linux 原生 AIO、完整插件生态与长期压力测试也不在首轮验证范围内。InnoDB 与基础 SQL 的功能结果已经通过真机验证，但这不等同于完成生产数据库所要求的高并发、异常断电恢复、备份恢复演练和长期稳定性认证。

八、总结

MariaDB Server 的鸿蒙 PC 适配，难点并不集中在某一个编译错误，而在构建期工具、目标端 ABI、第三方依赖、运行资产和系统分发格式之间的连续约束。只解决交叉编译，得不到可初始化的数据库；只打包二进制，终端找不到稳定入口；只展示应用页面，又无法证明数据库内核真的工作。

本项目通过主机生成器与目标构建分离，解决了交叉编译期间执行目标程序的问题；通过 OHOS 平台配置和自包含依赖，处理了 musl、AIO、TLS 与构建网络差异；再用 HNP 将服务端、客户端、SQL 数据和包装脚本作为一个运行整体交付。最终，真机上的版本与架构识别、建库建表、增删改查和事务回滚证明，当前成果已经从“能够生成 aarch64 文件”走到了“能够在 HarmonyOS PC 上处理真实数据”。

这套方法也适用于其他没有桌面界面、但拥有复杂原生构建系统的基础软件：先划清宿主机工具与目标端程序的边界，再保证依赖和运行资产闭环，最后用设备上的真实业务操作验收，而不是把编译成功当作适配完成。