InfluxDB Studio 鸿蒙 PC 适配全记录：从 WinForms 管理工具到 Qt 原生数据库工作台

sdp安歌

6353人浏览 · 2026-09-13 16:22:37

sdp安歌 · 2026-09-13 16:22:37 发布

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

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

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

环境搭建文章：https://blog.csdn.net/weixin_52908342/article/details/161343743

一、为什么要适配 InfluxDB Studio

InfluxDB Studio 是一款面向 InfluxDB 1.x 的桌面管理工具。它把连接管理、数据库与 measurement 浏览、InfluxQL 编辑、结果表格、Retention Policy、Continuous Query、用户权限和服务器诊断集中在一个窗口中。对于维护监控、IoT 与时序指标平台的开发者而言，这类工具的价值并不在于“替代命令行”，而在于将对象层级、查询上下文和结果检查放到同一套可视化工作流里。

原项目采用 C#、.NET WinForms、InfluxData.Net 与 ScintillaNET 实现，长期运行环境是 Windows 桌面。HarmonyOS PC 无法直接承载 WinForms 控件、.NET Framework 运行时和原有第三方组件；如果只做一个静态界面，也无法验证数据库工具最关键的网络请求与数据解析链路。因此，本次适配没有修改原始 src/ 工程，而是在仓库的 ohos/ 目录中新增 Qt Widgets 实现：以鸿蒙 Stage 模型管理应用生命周期，以 XComponent 承载 Qt 窗口，以 Qt Network 重新实现 InfluxDB HTTP 客户端。

这次适配希望解决一个更具普遍性的问题：传统桌面数据库管理软件迁入 HarmonyOS PC 时，怎样在保留树形导航、查询编辑和结果表格等桌面交互的同时，让窗口、网络、配置持久化和 Native 库打包都遵循鸿蒙应用模型。完成后的版本面向 2in1 与 tablet，包名为 com.cymaticlabs.influxdbstudio，Native ABI 为 arm64-v8a。

二、先划清适配边界

WinForms 窗体不能机械地转换为 ArkUI 或 Qt 控件，InfluxData.Net 与 ScintillaNET 也不能直接复用。适配时先按用户实际操作链路拆分功能，再决定每一层的替代方案：

层次	原项目实现	鸿蒙侧实现
应用入口	.NET 桌面进程	Stage 模型 `EntryAbility`
窗口宿主	WinForms	ArkTS + XComponent + Qt OpenHarmony QPA
桌面界面	WinForms 控件	Qt 5 Widgets
网络访问	InfluxData.Net	`QNetworkAccessManager`
查询编辑	ScintillaNET	`QPlainTextEdit`
结果展示	WinForms DataGrid	`QTableWidget`
配置保存	.NET Settings	JSON + `QStandardPaths::AppConfigLocation`

当前版本聚焦 InfluxDB 1.x HTTP API，支持 /ping 与 /query、HTTP/HTTPS、Basic Auth、默认数据库、自签名证书忽略、InfluxQL 查询以及常用管理命令。InfluxDB 2.x 只有在开启 1.x 兼容 API 时才能按这一模式接入；Flux、Token、Organization 与 Bucket 的原生管理不在本轮范围内。查询编辑器满足输入与执行需要，但没有声称完整复刻 ScintillaNET 的高级语法高亮和补全体验。

三、鸿蒙版本的整体架构

ArkTS 层只负责 Ability 生命周期和窗口宿主，不在两种语言之间复制数据库业务。Qt 窗口启动后，连接树、查询页、结果页与管理对话框都在同一 Native 进程内协作：

EntryAbility
    └── Index.ets / XComponent
          └── qopenharmony 平台插件
                └── libentry.so
                      ├── MainWindow：菜单、工具栏、资源树与标签页
                      ├── InfluxClient：认证、HTTP 请求与错误处理
                      ├── QueryPage：InfluxQL 编辑和执行
                      └── TablePage：JSON 解析、表格展示与导出

工程目录也刻意与原 .NET 版本隔离：

ohos_InfluxDBStudio/
├── src/                                  # 原始 C# / WinForms 工程
├── README.OpenHarmony_CN.md              # 鸿蒙适配说明
└── ohos/
    ├── AppScope/app.json5                # 包名、版本和应用信息
    ├── build-profile.json5               # SDK、产品与签名配置
    ├── build-ohos.sh                     # 命令行构建入口
    ├── qtforharmony_sdk/                 # Qt for OpenHarmony SDK
    ├── app/
    │   ├── include/                      # Qt 业务头文件
    │   └── src/                          # 主窗口、网络与结果页实现
    └── entry/src/main/
        ├── ets/                          # Ability 与 XComponent 宿主
        └── cpp/                          # CMake、Native 入口与 Qt 链接

InfluxClient 会把连接配置规范化为协议、主机和端口，再统一处理 GET/POST、认证头、SSL 错误和 InfluxDB 返回的业务错误。结果页按 InfluxDB 1.x 的 results → series → columns / values 结构构造表格，并在每条记录前补入 measurement，因而数据库浏览、普通查询和管理命令可以共用同一套显示组件。

四、在真机上走通核心工作流

以下五张截图均由当前仓库生成的签名 HAP 在 HarmonyOS PC 真机上实际运行后，通过 snapshot_display 直接获取。验证设备为 HUAWEI MateBook Pro（HAD-W32），系统版本为 6.1.0.117，截图分辨率为 3120×2080。测试过程重新启动应用，并连接局域网内提供 InfluxDB 1.x 响应格式的验证服务；界面渲染、网络请求、JSON 解析、标签切换和表格填充均在真机应用内完成。

1. 连接配置必须先通过真实网络验证

连接管理器保存名称、主机、端口、默认数据库、用户名、密码及 HTTPS 选项。点击“测试连接”时，应用实际请求服务端 /ping；只有 Qt Network 收到成功响应后才显示“连接成功”。这一步同时验证了鸿蒙网络权限、Qt 网络库打包、局域网路由和配置持久化，而不是仅检查输入框是否为空。

在这里插入图片描述

连接配置以 JSON 写入应用配置目录。主机允许填写纯地址，也兼容带 http:// 或 https:// 的输入；客户端在发起请求前会去除重复协议和路径，避免拼出错误 URL。当前密码字段随连接配置保存在应用私有目录并用于认证，因此生产环境应配合最小权限账号和设备访问控制，不能把真实凭据写进仓库或文章示例。

2. 资源树要反映服务端的真实对象层级

连接成功后，展开连接节点会执行 SHOW DATABASES；继续展开数据库节点会执行 SHOW MEASUREMENTS。截图中 demo、_internal 两个数据库以及 cpu、memory 两个 measurement 均来自服务端响应，Qt 端把结果转换为带类型与上下文的数据树节点。

在这里插入图片描述

树节点不仅用于展示。数据库节点保存连接 ID 与数据库名，measurement 节点继续保存 measurement 名称；后续新建查询、刷新资源、查看 Series、Tag Keys、Field Keys 和删除对象时，都从当前选中节点取得操作范围。这样能够避免管理工具中常见的“界面选中了 A，命令却发往 B”的上下文错位。

3. 查询编辑器保留数据库上下文

选中 demo 后新建查询，页面会明确显示当前数据库。验证中输入 SELECT * FROM cpu LIMIT 100，既可以点击页面右上角的“执行查询”，也可以使用 Ctrl+Enter。编辑区与结果区采用纵向分割布局，适合在桌面大屏上反复修改语句并观察结果。

在这里插入图片描述

执行时，客户端把数据库名、查询语句和 epoch=ms 编码为查询参数。HTTP 传输错误、非法 JSON、根级错误以及 results 中的业务错误会统一进入结果页，不会把失败响应误当作空表格。对创建、删除、授权等修改类语句，应用使用表单编码的 POST 请求，避免把所有管理操作都混成只读查询。

4. 返回结果要转成可核对、可导出的表格

服务端返回响应后，结果页按列名和行值填充表格。截图中可以看到 measurement、时间、usage_user、usage_system、host 与 region，共 3 行记录；页面状态同步显示“查询结果 · 3 行”。CSV 与 JSON 导出按钮直接使用当前解析结果，便于把排查数据交给脚本或其他分析工具继续处理。

在这里插入图片描述

表格启用了整行选择、交替行色与排序，并保持只读，避免用户误以为直接修改单元格就会回写数据库。CSV 导出会处理逗号、双引号与换行转义；JSON 导出保留服务端原始响应结构，兼顾人工查看与程序复用。

5. 数据查询之外，还要覆盖服务器管理

InfluxDB Studio 的定位不是单一查询器。服务器菜单提供用户查看与创建、密码修改、数据库权限与管理员权限授予/撤销、运行中查询、Kill Query、Diagnostics、Stats 和通用 InfluxQL 命令入口。截图通过 SHOW USERS 返回两个用户及其管理员状态，说明服务器级命令同样复用了真实网络请求和结果表格链路。

在这里插入图片描述

数据库侧还提供创建/删除数据库、删除 measurement 与 series、查看 Series、Tag Keys、Tag Values、Field Keys，以及 Retention Policy、Continuous Query 和 Backfill 操作。危险操作在发送命令前会要求确认；需要名称、时长、Replication 或时间范围的命令通过对话框收集参数，再生成带标识符引用的 InfluxQL。

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

难点一：WinForms 组件体系不能直接落到鸿蒙窗口

原程序的窗体、DataGrid、ScintillaNET 编辑器和事件模型都依赖 Windows/.NET 环境。真正困难的不是把按钮改成 Qt 的 QPushButton，而是重新建立菜单、资源树、标签页、查询页和管理对话框之间的状态关系。适配中把连接 ID、数据库名和 measurement 名作为节点数据保存，所有动作都从当前选择推导上下文，减少了 UI 重写后业务状态散落的问题。

难点二：Qt 窗口必须正确进入 HarmonyOS 生命周期

传统 Qt 程序通常从 main() 创建 QApplication，但鸿蒙应用由 Ability 启动。项目通过 XComponent 加载 plugins_platforms_qopenharmony，由 QPA 插件启动 libentry.so，再创建 Qt 主窗口。ArkTS 层保持轻量可以减少生命周期重复，但要求 HAP 同时正确打包入口库、平台插件和 Qt Core/Gui/Widgets/Network/OhExtras 依赖；遗漏任一环节都可能表现为应用能启动却没有窗口。

难点三：网络成功不等于业务成功

InfluxDB 既可能用非 2xx 状态表示失败，也可能在正常 JSON 的根对象或单个 results 中返回 error。如果只判断 QNetworkReply::NoError，界面会把业务失败当成成功。当前实现依次检查传输状态、JSON 解析状态、根级错误和结果级错误，并把同一错误路径交给页面显示。Basic Auth、HTTPS 与自签名证书处理也集中在客户端，避免每个功能自行拼请求。

难点四：异步请求期间页面可能已经被关闭

资源树和表格页都依赖异步网络回调。用户在请求返回前关闭标签页时，直接保存裸指针会造成悬空访问。表格打开流程使用 QPointer<TablePage> 守护页面对象，回调首先确认页面仍然存在；资源树请求也把加载状态显式放入节点，完成后再替换内容。对桌面管理工具而言，这类细节比首页能否显示更影响连续使用的稳定性。

难点五：Qt for OpenHarmony 的构建与 HAP 打包要同时成立

Native 侧由 CMake 查找 Qt 5 的 Core、Gui、Network、OhExtras 和 Widgets，并链接 qopenharmony 平台集成插件；Hvigor 再把 arm64-v8a 产物、ArkTS 代码和资源组装为 HAP。项目脚本会先检查 qtforharmony_sdk/lib/cmake/Qt5/Qt5Config.cmake 和 hvigorw 是否存在，提前暴露 SDK 路径错误。签名配置属于构建机私有信息，应由开发者在本地维护，不能直接复制公开仓库中的路径或凭据。

六、构建、安装与启动

建议先按照文首的 Qt 环境搭建文章准备 DevEco Studio、OpenHarmony SDK 和 Qt for OpenHarmony，再用 DevEco Studio 打开仓库中的 ohos/。当前产品配置的 target/compatible SDK 为 5.0.5(17)，Native 编译器为 BiSheng，ABI 为 arm64-v8a。

命令行构建可直接使用工程脚本：

cd ohos
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
export HVIGOR=/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw
bash build-ohos.sh

签名 HAP 默认生成在：

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

安装与启动命令如下：

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

本次真机验证使用的签名 HAP 约 23.3 MB。安装后依次完成应用启动、连接测试、数据库与 measurement 展开、查询编辑、结果展示和用户权限查看，五张截图均来自同一台真实设备的当前画面。

七、当前能力与边界

当前版本已经覆盖 InfluxDB 1.x 日常管理的主要闭环：

新增、编辑、删除、测试和断开多个 InfluxDB 连接；
连接配置 JSON 持久化、导入与导出；
HTTP/HTTPS、Basic Auth 与可选的自签名证书忽略；
数据库与 measurement 资源树加载和刷新；
InfluxQL 编辑、Ctrl+Enter 执行、结果表格、CSV/JSON 导出；
数据库、measurement、series、tag key/value 与 field key 管理；
Retention Policy、Continuous Query 与 Backfill；
用户、密码、数据库权限与管理员权限管理；
运行中查询、Kill Query、Diagnostics、Stats 与通用 InfluxQL 命令。

当前没有适配原 WinForms 界面的直接运行、ScintillaNET 完整编辑体验、独立 point 写入编辑器、Kapacitor 专用界面、Flux 查询，以及 InfluxDB 2.x 原生 Token/Organization/Bucket 管理。鸿蒙版本更准确的定位是“InfluxDB 1.x 的 Qt/HarmonyOS PC 管理工作台”，而不是对 Windows 版本每一个控件和扩展能力的逐项复制。

真机截图中的服务用于验证 InfluxDB 1.x 协议链路，数据为测试数据。接入生产 InfluxDB 前，仍应使用目标服务器的实际版本、认证方式、TLS 证书与最小权限账号再次验证；涉及删除、授权和 Kill Query 的操作尤其需要先在测试库中确认。

八、总结

InfluxDB Studio 的适配说明，传统桌面数据库工具迁入 HarmonyOS PC 的关键不是重画一个相似窗口，而是把窗口生命周期、资源上下文、异步网络、错误模型、数据解析和 Native 打包重新连成一条可靠链路。Qt Widgets 保留了树形导航、标签页和大表格的桌面效率，Qt Network 取代原 .NET 客户端，ArkTS 与 XComponent 则让这套 Native 界面符合鸿蒙应用启动模型。

从真机结果看，连接测试、资源发现、InfluxQL 编辑、表格展示与服务器用户查询已经形成连续工作流。后续如果继续扩展，优先级应放在生产环境兼容验证、查询编辑体验、批量数据浏览和 InfluxDB 2.x 原生 API，而不是简单增加更多菜单项。只有持续在真实服务、真实权限和真实数据量下验证，数据库管理工具的适配才算从“能够运行”走向“能够使用”。