OHtrix

为 HarmonyOS 桌面形态重新打磨的下载管理器

Electron 体验 · HarmonyOS 适配 · aria2c 移植 · PC / 2in1 / 大屏平板优先

这是什么

OHtrix 是一个面向 HarmonyOS PC、2in1 设备和部分大屏平板的下载管理器。它基于 Motrix 的成熟桌面体验进行移植与再整理，继续使用 Electron + Vue 2 作为应用主体，并以 aria2 作为核心下载引擎。

这不是一个简单的换壳工程。OHtrix 的重点在于把桌面下载器真正放到 HarmonyOS 的运行环境里：窗口需要符合系统桌面形态，下载文件需要落到用户可见的系统目录，aria2c 需要能在 HarmonyOS 上稳定运行，Electron 运行时与系统能力之间也需要适配桥接。

当前项目以实用为先：保留原 Motrix 清爽的任务列表、批量操作、速度统计、BT/Magnet 能力与偏好设置，同时围绕 HarmonyOS 的权限、窗口、HNP、公共目录和进程模型做了定向改造。

为什么需要 OHtrix

传统桌面下载管理器通常默认拥有相对自由的文件系统访问、进程启动能力和窗口控制能力。但在 HarmonyOS 上，这些能力需要重新处理：

问题	OHtrix 的处理
下载引擎如何运行	移植 aria2c 到 HarmonyOS arm64，并通过 HNP 分发
文件应保存在哪里	启动时请求公共 Download 目录权限，默认写入系统下载目录
无边框窗口如何拖拽	隐藏自定义顶栏，保留 HarmonyOS 原生三键，并让左侧栏承担拖拽区域
Electron remote 回调异常	删除文件、确认弹窗等关键路径改为主进程 IPC
上游桌面逻辑如何复用	保留 aria2 JSON-RPC 通信模型，尽量减少渲染层业务重写

核心特性

下载能力

支持 HTTP、HTTPS、FTP、BT、Magnet 等常见下载任务。
支持任务暂停、继续、删除、批量删除、清理记录。
支持 BT 任务信息、下载进度、实时速度与任务详情展示。
保留 aria2 的多连接下载、RPC 控制、session 恢复与配置能力。

HarmonyOS 桌面适配

应用名称、图标、关于面板、版权与仓库链接统一为 OHtrix。
窗口使用 frame=false 的无边框模式。
保留 HarmonyOS 原生右上角窗口三键。
PC / 2in1 场景下可通过左侧导航区域拖拽窗口。
默认下载目录指向 /storage/Users/currentUser/Download。
应用启动时主动请求下载目录权限，降低首次下载失败概率。

工程体验

桌面侧仍使用原 Electron/Vue/Webpack 架构。
HarmonyOS 侧独立放置在 platform/ 下，使用 DevEco Studio / hvigor 构建。
aria2 HarmonyOS 预构建产物与 HNP 包随仓库提供。
保留用于验证 libaria2 / N-API addon 的脚本与 harness。

架构概览

OHtrix 由两个相互独立但最终组合到一起的工程组成：

flowchart LR
  subgraph Desktop["Electron / Vue 2 应用主体"]
    Renderer["Vue Renderer\n任务列表 / 偏好设置 / 关于面板"]
    Main["Electron Main\n窗口 / 配置 / IPC / Engine"]
    Shared["Shared\naria2 JSON-RPC Client"]
  end

  subgraph Harmony["HarmonyOS 适配工程 platform/"]
    Entry["electron HAP\nEntryAbility / HNP 配置"]
    WebEngine["web_engine\nElectron Runtime Adapter"]
    Permission["Permission Adapter\n公共目录权限"]
    HNP["aria2.hnp\naria2c + aria2.conf"]
  end

  Renderer --> Shared
  Main --> Shared
  Main --> HNP
  Entry --> WebEngine
  WebEngine --> Permission
  HNP --> RPC["127.0.0.1 JSON-RPC"]
  Shared --> RPC

运行链路

HarmonyOS 启动 entry HAP。
web_engine 承载 Electron/Chromium 运行环境。
Electron 主进程加载 OHtrix 的 dist/electron/main.js。
主进程解析 HarmonyOS 下的 aria2c / aria2.conf / session 路径。
aria2c 启动本地 JSON-RPC 服务。
渲染进程通过 @shared/aria2 连接 RPC，继续使用上游 Motrix 的任务管理模型。

aria2c HarmonyOS 移植

aria2c 是 OHtrix 最重要的底座。原版 Motrix 在桌面平台上直接携带对应系统的 aria2c 可执行文件，而 HarmonyOS 对二进制执行、应用沙箱、公共目录权限和动态库加载都有不同限制，因此 OHtrix 对 aria2c 做了专门移植与工程化封装。

独立移植仓库：

HanversionOvO/aria2-harmonyos

移植目标

目标	说明
运行架构	HarmonyOS / OpenHarmony arm64
核心引擎	aria2c / libaria2
通信方式	JSON-RPC over HTTP/WebSocket
分发方式	HNP 包 + 预构建二进制
下载目录	HarmonyOS 公共 Download 目录
备选方案	N-API addon 内嵌 libaria2 并启动 RPC

本仓库中的落地点

路径	作用
`platform/prebuilt/aria2-ohos-arm64/aria2c`	HarmonyOS arm64 版 aria2c
`platform/prebuilt/aria2.hnp`	可随应用分发的 aria2 HNP 包
`platform/electron/hnp/arm64-v8a/aria2.hnp`	entry HAP 引用的 HNP 资源
`platform/prebuilt/aria2-ohos-arm64/aria2_engine.node`	N-API addon 预构建产物
`platform/scripts/build-aria2-ohos.sh`	aria2 / OpenSSL / addon 构建脚本
`platform/scripts/aria2_engine.cc`	基于 libaria2 的进程内 RPC 引擎实现
`platform/scripts/harness/`	设备侧加载 addon 与 RPC 探测示例
`src/main/core/Engine.js`	Electron 主进程中的 aria2 生命周期管理
`src/main/utils/index.js`	HarmonyOS 下 aria2c、aria2.conf、Download 路径解析

关键适配点

1. 交叉编译

platform/scripts/build-aria2-ohos.sh 负责使用 HarmonyOS / OpenHarmony arm64 工具链构建 aria2。脚本同时处理 OpenSSL、aria2、RPC probe、N-API addon 等阶段，确保 HTTPS 下载、WebSocket RPC 与基础命令行行为可用。

2. OpenSSL 选择

脚本中固定使用 OpenSSL 1.1.x 系列，是为了避开 OpenSSL 3 legacy provider 在设备侧部署时可能带来的额外复杂度。对下载器而言，稳定可用的 TLS 能力比追新版本更重要。

3. HNP 分发

HarmonyOS 侧不沿用桌面系统的 extra/<platform>/engine/aria2c 路径，而是通过 HNP 包提供 aria2c。运行时主进程会解析系统安装后的 HNP 路径，并读取其中的 aria2.conf。

4. JSON-RPC 保持

OHtrix 没有重写下载业务层。aria2c 仍然暴露本地 JSON-RPC，主进程和渲染进程继续通过 @shared/aria2 调用 aria2.addUri、aria2.tellActive、aria2.pause 等接口。这样可以最大限度复用 Motrix 的任务流。

5. 公共目录权限

HarmonyOS 对公共目录访问有权限边界。OHtrix 启动时请求下载目录权限，并将默认目录设置到系统 Download 目录。这样用户下载完成后可以直接在系统文件管理中看到文件，也避免 aria2 因无权写入目标路径而失败。

6. N-API addon 预案

如果某些环境限制外部可执行文件启动，项目保留 aria2_engine.node 方案。它通过 N-API 加载 libaria2，在应用进程内启动 aria2 RPC 服务，上层仍然通过同一套 JSON-RPC 客户端通信。

目录导览

OHtrix
├─ src/
│  ├─ main/                      Electron 主进程
│  │  ├─ core/Engine.js           aria2 引擎启动、session、参数组装
│  │  ├─ core/ConfigManager.js    默认下载目录与配置迁移
│  │  └─ ui/WindowManager.js      HarmonyOS 无边框窗口处理
│  ├─ renderer/                  Vue 2 渲染进程
│  │  ├─ components/Task/         任务列表、删除、批量操作
│  │  ├─ components/About/        OHtrix 关于面板
│  │  └─ api/Api.js               aria2 RPC 业务封装
│  └─ shared/aria2/              主进程/渲染进程共享 RPC 客户端
├─ platform/
│  ├─ electron/                  HarmonyOS entry HAP
│  ├─ web_engine/                Electron Runtime 适配层
│  ├─ prebuilt/                  aria2c、aria2.hnp、addon 预构建
│  └─ scripts/                   aria2 HarmonyOS 构建与验证脚本
├─ screenshots/                  README 展示截图
├─ static/                       应用图标与静态资源
└─ .electron-vue/                Webpack 构建系统

构建说明

1. 构建 Electron 资源

根目录是 Electron/Vue 侧工程。首次构建前安装依赖：

yarn

生成主进程与渲染进程产物：

yarn run pack

输出目录：

dist/electron

2. 同步到 HarmonyOS 工程

将 dist/electron 同步到 HarmonyOS 工程内的 app 资源目录：

platform/web_engine/src/main/resources/resfile/resources/app/dist/electron

该目录是 HarmonyOS 运行时加载 Electron 应用主体的位置。

3. 构建 HarmonyOS HAP

使用 DevEco Studio 打开：

platform/

然后同步 ohpm 依赖并构建 entry 模块。HarmonyOS 工程使用 hvigor / ohpm，与根目录的 yarn / Webpack 是两套构建体系。

4. 运行目标

当前推荐在以下设备形态上验证：

HarmonyOS PC
HarmonyOS 2in1 设备
带键鼠或大屏形态的 HarmonyOS 平板

当前状态

模块	状态
应用品牌 OHtrix	已完成
无边框窗口 + 原生三键	已完成
左侧栏拖拽窗口	已完成
默认下载目录迁移到 Download	已完成
启动时请求下载目录权限	已完成
aria2c HarmonyOS arm64 预构建	已完成
aria2 HNP 集成	已完成
删除文件 remote callback 问题	已改为主进程 IPC
手机形态适配	非当前目标

清理策略

仓库默认不保留本机依赖、IDE 配置与构建缓存。以下内容应由开发环境重新生成：

node_modules/
platform/**/oh_modules/
platform/.hvigor/
platform/*/build/
dist/
.idea/

致谢

OHtrix 站在这些项目和工作之上：

Motrix：清晰、优雅且成熟的下载管理器体验。
aria2：强大的多协议下载引擎。
HanversionOvO/aria2-harmonyos：aria2c 在 HarmonyOS / OpenHarmony 上的移植基础。

许可证

本项目沿用上游开源许可。详见 LICENSE。

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.electron-vue		.electron-vue
build		build
extra		extra
platform		platform
screenshots		screenshots
src		src
static		static
.babelrc		.babelrc
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README-EN.md		README-EN.md
README.md		README.md
app-update.yml		app-update.yml
electron-builder.json		electron-builder.json
jsconfig.json		jsconfig.json
package.json		package.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

OHtrix

为 HarmonyOS 桌面形态重新打磨的下载管理器

这是什么

为什么需要 OHtrix

核心特性

下载能力

HarmonyOS 桌面适配

工程体验

架构概览

运行链路

aria2c HarmonyOS 移植

移植目标

本仓库中的落地点

关键适配点

1. 交叉编译

2. OpenSSL 选择

3. HNP 分发

4. JSON-RPC 保持

5. 公共目录权限

6. N-API addon 预案

目录导览

构建说明

1. 构建 Electron 资源

2. 同步到 HarmonyOS 工程

3. 构建 HarmonyOS HAP

4. 运行目标

当前状态

清理策略

致谢

许可证

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages