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

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

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

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

一、为什么要适配 Angel

Angel 是面向大规模机器学习和图计算的分布式计算平台。它以 Parameter Server 为核心，通过 Master、Worker、PSAgent 和 Parameter Server 的协同完成参数切分、训练调度、状态汇总与模型管理，并能够接入 Hadoop YARN、HDFS 和 Spark on Angel。对于高维稀疏模型、图表示学习等任务，这套架构的价值在于把计算和参数存储分摊到集群，而不是受限于一台开发机的资源。

将 Angel 适配到鸿蒙 PC，真正有价值的部分不是让笔记本独自承担一套分布式训练集群，而是让开发者和运维人员在鸿蒙桌面上获得一个稳定、清晰的控制入口。日常工作中，用户最常查看的是应用状态、训练进度、Worker 与 Parameter Server 拓扑；出现异常时，还需要快速取得日志、线程栈和计数器；任务完成前后，则会涉及提交、终止以及模型保存、加载等操作。

因此，本次适配把目标确定为“鸿蒙 PC 原生控制台”：Angel 的 Java/Scala 分布式执行面继续运行在远端集群，鸿蒙端使用 Qt Widgets 重建操作员控制面，通过一组稳定的 JSON API 与网关通信。这个边界既保留了 Angel 原有的计算能力，也让鸿蒙 PC 端具备符合桌面使用习惯的窗口、表格和操作反馈。

二、先确定边界：迁移控制面，而不是复制整个集群

Angel 上游工程是一个 Maven 多模块项目，其核心依赖 Hadoop、YARN、HDFS、Protobuf RPC 以及 Spark 生态。原项目虽然提供 Web UI，但页面控制器直接依赖 ApplicationMaster、WorkerManager、ParameterServerManager 等运行时对象，页面展示的数据也来自正在运行的集群。这意味着原有 Web 页面并不是可以单独打包的静态前端。

如果把 Master、Worker、Parameter Server 和 Hadoop 运行时一起放进普通 HAP，不但安装包、内存和启动时间会迅速膨胀，后台服务生命周期与应用窗口生命周期也会相互牵制。更重要的是，这种做法会把原本成熟的集群部署方式改造成难以维护的单机变体。

适配后的职责划分如下：

层次	主要职责	所在位置
HarmonyOS 宿主层	Stage UIAbility、窗口创建、XComponent 承载	harmony_pc/entry/
Qt 控制台层	页面布局、表格、表单、状态反馈和桌面窗口行为	qt-console/angel_dashboard.*
客户端通信层	JSON 请求、错误处理、Demo/远端模式切换	qt-console/angel_api_client.*
适配网关层	认证并把 Angel/YARN 状态整理为稳定 API	按 docs/angel-gateway-api.md 部署
Angel 执行层	Master、Worker、PSAgent、Parameter Server、模型与存储	既有远端集群

鸿蒙端不改写分布式算法，也不替代 YARN 调度。它聚焦的是操作者真正需要触达的那一层：看得见任务状态，找得到异常节点，并能发出明确的控制请求。

三、鸿蒙版本的工程结构

适配代码集中在独立目录中，上游 Angel 主体仍保持原有 Java/Scala 结构：

ohos_angel/
├── angel-ps/                         # Angel 参数服务器与执行核心
├── spark-on-angel/                   # Spark 集成
├── docs/                             # 上游部署、算法和架构文档
└── angel-ohos-migration/
    ├── qt-console/
    │   ├── main.cpp                  # Qt 应用入口与鸿蒙窗口模式
    │   ├── angel_dashboard.*         # 九个控制台页面
    │   └── angel_api_client.*        # Demo 数据与远端 API 客户端
    ├── harmony_pc/
    │   ├── entry/src/main/ets/       # Stage UIAbility 与 XComponent 页面
    │   ├── entry/src/main/cpp/       # Qt 原生库构建入口
    │   └── qtforharmony_sdk/         # Qt for HarmonyOS 依赖
    ├── docs/
    │   ├── angel-gateway-api.md      # 网关接口约定
    │   └── qt-harmony-pc-architecture.md
    └── verification/                 # 真机验证记录

运行时链路可以概括为：EntryAbility 创建鸿蒙窗口，ArkTS 页面提供全屏 XComponent，QPA 插件把 Qt Surface 接入窗口，随后由 AngelDashboard 展示控制台。远端模式下，AngelApiClient 使用 Qt Network 访问网关；网关再连接 Angel ApplicationMaster、YARN WebApp 或企业已有的监控服务。

控制台覆盖 Overview、Jobs、Worker Groups、Parameter Servers、Progress、Environment、Executors & Diagnostics、Counters、Model & Config 九个页面。接口则按资源拆分为 /api/overview、/api/jobs、/api/workers、/api/parameter-servers、/api/progress、/api/executors 等路径，任务提交、终止以及模型保存、加载使用 POST 请求。

四、从状态查看到模型操作的真机验证

以下五张截图均在连接的鸿蒙 PC 真机上重新安装并启动签名 HAP 后获取。测试设备为 HUAWEI MateBook Pro（HAD-W32），系统版本为 HarmonyOS 6.1.0.117(SP78C00E100R13P3)，截图分辨率为 3120×2080。

本轮验证使用应用内的 Demo data 模式，目的是在没有临时搭建 Angel/YARN 集群的条件下，真实检查 HAP 启动、Qt 渲染、页面切换和按钮操作。截图中的窗口与操作结果均来自真机实时运行；其中集群业务数据为可交互的演示数据，不将其表述为线上集群返回结果。远端模式使用相同页面和信号链路，只是数据源切换为适配网关。

1. Overview 先给出一眼能读懂的集群摘要

应用启动后直接进入 Overview。页面将运行状态、Worker 数量、Parameter Server 数量、内存占用和训练进度放在首屏，当前演示任务处于 RUNNING，GraphSAGE 训练进度为 72%。

这里没有照搬原 Web UI 的导航和模板，而是重新组织为宽屏桌面布局。操作者打开应用后无需先判断该进入哪个子页面，就能确认任务是否存活、资源规模是否符合预期以及迭代是否持续推进。

2. 在同一页面完成任务提交和状态回读

Jobs 页面保留任务名、部署模式、输入路径和输出路径四项关键参数。真机点击“Submit job”后，页面底部出现 Job submitted in demo mode 回执，任务表新增一条状态为 SUBMITTED 的记录。

远端模式下，这个动作会向 /api/jobs 发送结构化 JSON，而不是由客户端拼接并执行一条不可审计的 Shell 命令。YARN、LOCAL、KUBERNETES 等部署模式作为明确字段传递，后续也便于网关统一做权限校验、参数检查与操作日志记录。

3. Parameter Server 拓扑单独呈现

Parameter Server 是 Angel 与普通批处理平台差异最明显的组成部分。对应页面按节点列出状态、主机、矩阵数量和内存占用，真机上可看到 ps-0、ps-1 两个节点及其当前资源摘要。

把这部分从总览中拆出来，是为了让定位问题时保留足够的节点粒度。例如训练进度停滞时，操作者可以先看 PS 是否仍为 RUNNING，再结合矩阵数量、内存与后续线程栈判断问题发生在参数分片、网络同步还是 Worker 一侧。

4. Executors 与线程栈形成故障定位入口

Executors & Diagnostics 页面同时展示执行器角色、宿主机、核心数和内存。点击右上角“Thread dump”后，下方文本区真实刷新，显示 Worker 的 RPC、Task、Heartbeat 线程状态，以及 Parameter Server 的 Matrix Partition I/O 和 Snapshot Writer 状态。

诊断信息采用纯文本承载，避免把线程栈强行拆成大量表格字段。远端模式下，日志和线程栈分别访问 /api/logs 与 /api/threads；网关可以在这一层处理鉴权、脱敏、超时和数据裁剪，HAP 无需直接暴露集群内部管理端口。

5. 模型操作保留明确的路径与回执

Model & Config 页面只留下模型路径、保存和加载三个核心交互。真机点击“Load model”后，顶部状态区与窗口底部同时给出 Model load plan accepted: hdfs:///model/graph-sage 回执，说明按钮事件、客户端逻辑和界面反馈链路已经贯通。

模型实体仍位于远端 HDFS/Parameter Server 数据面，鸿蒙端发送的是控制请求，不会把分布式模型复制进应用沙箱。这样的语义比简单显示“成功”更准确：客户端确认请求已被接受，真正的加载进度和最终状态仍应由集群侧持续回报。

五、适配过程中最棘手的几个问题

难点一：原项目类型容易让自动迁移方向跑偏

从仓库特征看，Angel 首先是一个 Java/Scala Maven 项目，常规检测很容易把它归类为没有桌面 UI 的服务端工程。但继续追踪源码后会发现，它确实拥有完整的运维 Web 界面，只是这些页面与 ApplicationMaster 和 YARN 上下文紧密耦合。适配时必须先区分“没有界面”和“界面不能脱离集群独立运行”，两者对应的方案完全不同。

最终没有给 Java 服务端机械套一层 WebView，而是把原页面表达的运维能力整理为独立 Qt 控制台。这一步决定了后续工作是围绕用户任务组织页面，而不是围绕上游控制器逐个复制路由。

难点二：控制面与执行面的边界必须足够清楚

Angel 的 Master、Worker 和 Parameter Server 之间依赖内部 RPC、集群调度和共享存储，任何一个组件的“本地化”都会牵动其余部分。适配若只追求表面功能数量，很容易出现按钮很多、实际没有可靠执行语义的问题。

本项目将鸿蒙端限定为控制面，将网关定义为唯一的远端入口，并在接口文档中明确 GET/POST 方法、字段和响应结构。客户端负责发起请求和展示结果，网关负责认证与状态转换，集群继续负责真正的调度、计算和存储。这样每一层失败时都有清晰的错误归属。

难点三：Qt 窗口需要真正进入 HarmonyOS Stage 生命周期

Qt Widgets 不能只交叉编译出一个 ARM64 二进制就算完成适配。应用还需要由 Stage UIAbility 创建窗口，通过 XComponent 和 QPA 建立绘制表面，再调用 Qt for HarmonyOS 的启动入口。打包时还要一并带上 Qt Core、Gui、Widgets、Network、OhExtras、QOpenHarmony 平台插件及所需图像插件。

任何一环缺失，都可能表现为 HAP 可以安装但启动白屏，或者进程存在却没有可见窗口。当前工程把 ArkTS 宿主控制在最小职责范围，界面统一交给 Qt 管理，既避免两套 UI 状态相互竞争，也方便后续继续复用 Qt 桌面组件。

难点四：桌面端不是把移动页面简单放大

鸿蒙 PC 的屏幕分辨率、观看距离和窗口形态与手机不同。初版界面即便逻辑完整，如果字体、标签、表格行高和点击区域偏小，实际操作仍会吃力。适配中对默认字体、页签宽度、表格行高、表单控件和进度条进行了统一调整，并让窗口在 PC 上默认最大化。

同时通过 QOhWidgetHelper 声明全屏、分屏和悬浮窗口能力，让 Qt 主窗口能够遵循鸿蒙 PC 的窗口管理方式，而不是始终占据一个固定尺寸的画布。

难点五：离线演示与远端数据不能维护两套界面

开发阶段并非随时都有可用的 Angel 集群，但没有集群又很难验证提交、终止、线程栈和模型操作等交互。项目在 AngelApiClient 内提供 Demo data 模式，数据通过与远端请求相同的 Qt signal/slot 更新页面。切换到远端模式后，页面本身不变，只替换数据来源。

这种设计解决了真机离线验收问题，也避免演示版本与生产版本逐渐分叉。文章中的截图可以如实说明数据来源，而远端联调时仍复用同一套 UI 状态处理和错误提示。

六、构建、安装与运行

本项目使用 Qt 5.15.12 和 DevEco Studio SDK 6.0.2 工具链，目标架构为 arm64-v8a。Qt for HarmonyOS 环境准备可参考文首的环境搭建文章。

先进入鸿蒙 Stage 工程并构建签名 HAP：

cd angel-ohos-migration/harmony_pc

DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
HOS_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk/default \
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
assembleHap --mode module -p product=default

产物位于：

angel-ohos-migration/harmony_pc/entry/build/default/outputs/default/entry-default-signed.hap

连接鸿蒙 PC 后，先确认设备，再安装并启动：

hdc list targets

hdc install -r \
  angel-ohos-migration/harmony_pc/entry/build/default/outputs/default/entry-default-signed.hap

hdc shell aa start \
  -a EntryAbility \
  -b com.tencent.angel.harmony

应用默认启用 Demo data，可直接验证页面和操作流程。联调真实集群时，先按 angel-ohos-migration/docs/angel-gateway-api.md 实现并部署网关，再取消 Demo data 勾选，填写网关地址后点击“Connect / refresh”。生产环境还应在网关侧补充 TLS、身份认证、权限控制、审计日志和请求限流。

七、当前能力与边界

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

• 签名 HAP 安装、Stage UIAbility 启动和 Qt Widgets 正常渲染；
• Overview、Jobs、Worker Groups、Parameter Servers、Progress、Environment、Executors、Counters、Model 等页面切换；
• Demo 模式任务提交、任务终止、日志、线程栈、模型保存与加载操作；
• Qt Network 远端请求路径及错误反馈；
• 最大化布局，以及全屏、分屏、悬浮窗口模式声明；
• ARM64 原生库、QOpenHarmony 平台插件和相关 Qt 模块随 HAP 打包。

当前边界也需要明确：HAP 不包含 Angel 的 Java/Scala 分布式执行引擎，不在本地启动 Hadoop YARN、HDFS 或 Spark on Angel；真实集群的在线监控与控制依赖按接口约定部署的网关；此次截图验证的是可交互 Demo 数据链路，并不等同于完成某个线上集群的压力与稳定性测试。

后续若进入生产部署，重点应放在网关鉴权、集群版本兼容、长时间断线重连、大规模节点分页、敏感日志脱敏以及控制操作的二次确认，而不是继续把服务端组件塞入 HAP。

八、总结

Angel 的鸿蒙 PC 适配不是一次简单的界面翻译。真正决定结果的，是先承认分布式平台的运行边界，再把最适合出现在桌面端的能力提炼出来。当前方案保留 Angel 成熟的集群执行面，用 Qt Widgets 提供高信息密度的鸿蒙 PC 控制台，并以独立网关隔离设备端与集群内部结构。

从真机上的状态总览、任务提交、Parameter Server 拓扑、线程诊断到模型加载，核心操作已经形成连续的控制流程。它既不是只能展示几张静态卡片的外壳，也没有夸大为“在本地运行完整 Angel 集群”。对于同类依赖复杂服务端生态的开发工具，这种“远端执行面 + 鸿蒙原生控制面”的路线同样具有可复用性。