鸿蒙 PC:晶析云(ohos_GSAS-II)晶体材料分析工作台移植全记录
跑不动的 Python 科研软件,怎么在鸿蒙上变成一个真正有用的应用
一、写在前面
开源地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_GSAS-II
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
本文导读
- 要解决的问题:GSAS-II 是几十万行 Python + wxPython 的晶体学软件,鸿蒙上既跑不了 Python 也带不动它的 GUI。硬带运行时只会得到一个又大又慢又难验证的东西。
- 你会读到的技术细节:"本地工作区 + 远端分析服务"双模式的推演过程、六个
/v1/projects接口的标准化设计、HTTPS + 短时令牌验证通过才落盘的安全链路、系统文件选择器注册自定义 MIME(“晶体数据”)。- 本文的实测数据:11 项真机验证、HAP 444 KB;文章也如实记录了仓库缺省
build-profile.json5的构建问题。- 适合谁读:做科研/行业软件、需要在"不能上云"和"跑不动"之间找第三条路的开发者。
这篇文章记录的是把 GSAS-II 这套晶体学分析软件,移植成鸿蒙 PC 工作台的过程。最终落地的应用叫 晶析云,包名 com.crystalcloud.analysis。
其他移植项目分别是本地工具(剪贴板)、本地计算(有限元)、云客户端(沙箱)。这个项目是第四种形态,也是最难取舍的一种:原项目是一个几十万行的 Python 桌面程序,鸿蒙上既跑不了 Python,也带不动它的 GUI。
所以这次移植的核心命题是:
一个跑不动的 Python 科研软件,怎么在鸿蒙上变成一个「有用的」应用?
先给结论:
移植完成,采用了「本地工作区 + 远端分析服务」的双模式:本地可导入晶体数据并管理项目,重计算交给按标准接口对接的分析服务。
验证环境是真实设备:
| 项 | 值 |
|---|---|
| 设备型号 | HUAWEI MateBook Pro S(MOR-M1) |
| 系统版本 | HarmonyOS 7.0.0.111(SP15C00E101R9P2) |
| API 版本 | 26 |
| 设备形态 | 2in1 |
| 构建工具 | DevEco Studio 内置 hvigor 6.26.4 |
| SDK | HarmonyOS SDK 26.0.0.105 |
二、项目背景
GSAS-II(https://github.com/AdvancedPhotonSource/GSAS-II)是先进光子源(APS)团队维护的开源晶体学分析套件,广泛用于粉末衍射、单晶衍射、中子衍射的结构精修。
它的技术形态决定了移植难度:
- 语言:几乎全是 Python,依赖 NumPy/SciPy、matplotlib、wxPython;
- GUI:wxPython 桌面窗口,大量交互式绘图;
- 算法:Rietveld 精修、Le Bail 拟合、峰型分析、相鉴定——典型的数值密集型;
- 输入:CIF(晶体结构)、XY(粉末衍射图谱)、RAW(仪器原始数据)、GPX(GSAS-II 项目文件)。
对鸿蒙来说,这四条里有三条直接判死:
| 组成部分 | 鸿蒙上能用吗 |
|---|---|
| wxPython GUI | ❌ 完全没有对应物 |
| Python 解释器 + SciPy | ⚠️ 理论上可打成 HNP,但几百 MB,启动慢 |
| Rietveld 精修算法 | ⚠️ 纯 Python,就算带进解释器也慢 |
| 数据文件格式 | ✅ CIF/XY/RAW/GPX 都是文本,可以解析 |
所以移植的工程判断只有一条路:
界面和项目状态留在鸿蒙本地,数值计算通过标准化的 HTTP 接口外置。
这就是这套应用「本地工作区 + 分析服务」双模式的由来。
三、总体变化概览
ohos/
├── entry/src/main/
│ ├── module.json5 仅申请 INTERNET 权限
│ └── ets/
│ ├── pages/Index.ets 全部界面(2277 行)
│ ├── service/
│ │ └── CrystalAnalysisService.ets 分析服务客户端(797 行)
│ ├── model/CrystalModels.ets 数据模型(195 行)
│ ├── store/
│ │ ├── ProjectStore.ets 项目摘要 → Preferences(68 行)
│ │ └── CredentialStore.ets 服务地址/令牌 → AssetStoreKit(97 行)
│ └── entryability/EntryAbility.ets
└── backend/ Python 参考服务(可独立部署)
技术栈映射:
| GSAS-II 原方案 | 晶析云(鸿蒙) |
|---|---|
| wxPython 桌面 GUI | ArkUI 原生工作台 |
| Python 直接调算法 | POST /v1/projects/{id}/refinement 触发远端精修 |
本地 .gpx 项目文件 | Preferences 存项目摘要 |
| 文件路径参数 | 系统文件选择器(按需授权) |
| 环境变量/配置文件存凭据 | AssetStoreKit 安全存储 |
依赖面极小:只申请 ohos.permission.INTERNET,零第三方包。6 个 ArkTS 文件、3476 行。
架构文档里把边界写得很清楚:
ArkTS 页面只处理交互、项目状态和结果展示,数值计算由
CrystalAnalysisService统一承接。这样可以在不把 Python 解释器和桌面 GUI 带进 HAP 的前提下复用现有算法。
四、原始项目直接跑鸿蒙会遇到什么问题
4.1 Python 运行时是个无底洞
把 CPython + NumPy + SciPy 打成 HNP 是可行的,但代价是:
- 包体从几百 KB 涨到几百 MB;
- 冷启动要拉起解释器,几秒钟;
- Rietveld 精修在纯 Python 下本来就慢,移动端 CPU 更慢。
更要命的是——这只是「能跑」,不是「好用」。科研计算的价值在于精度和结果可复现,把算法搬到一个更难验证的环境里,收益是负的。
4.2 wxPython 界面完全无法移植
GSAS-II 的界面不是简单表单,而是大量交互式绘图(衍射图谱、拟合曲线、峰型标记)。wxPython 这套在鸿蒙上没有任何对应物,必须按鸿蒙的方式重新移植一套。
4.3 科研数据不能默认上传
CIF/XY/RAW 这些是未发表的实验数据,很多还涉及仪器原始格式。一个科研工具如果默认把数据传到云上,是不会有人用的。
4.4 但「纯本地」又没法用
完全本地化意味着要在鸿蒙上重新实现整个 GSAS-II 的算法——那已经不是一个移植项目,而是重造一个科研软件,工程量不可接受。
所以必须在「本地」和「云端」之间找一条中间线,这就是第五章要讲的核心设计。
五、鸿蒙适配核心路径
5.1 第一步:划清「本地做什么」的边界
最终的设计是两层:
| 层 | 在哪 | 做什么 |
|---|---|---|
| 交互层 | 本地 | 项目空间、数据导入、摘要展示、Rwp 趋势、精修进度 |
| 计算层 | 远端 | CIF 解析、峰型拟合、Rietveld 精修 |
关键约束写进了导入对话框里:

仅保存项目摘要,不会自动上传
也就是说:导入数据本身不触发任何网络请求。用户可以先把一堆衍射数据导入、建项目、看摘要,全程离线;等到真正要做精修时,才需要连分析服务。
这个设计把「数据主权」交还给了用户,是这次移植里最重要的一个产品决策。
5.2 第二步:两种工作模式并存
顶栏一直显示当前模式,未连接时是 本地工作区:

右上角一行小字很关键:本地工作区 · 未连接分析服务。这句话在任何页面都能看到,用户永远不会搞不清楚「我现在算的是本地还是云端」。
「计算服务」这一项进去就是连接配置:

对话框只有两个字段,但约束很硬:
- 服务地址:占位符是
https://analysis.example.com - 短时访问令牌:令牌不会回显
- 底部提示:仅支持 HTTPS。令牌验证成功之后才会写入系统安全存储。
这三条拼起来是一个完整的安全设计:
- 强制 HTTPS,杜绝明文传输;
- 令牌只读不回显,界面上拿不到;
- 验证通过才落盘——避免用户输错一个地址,把令牌泄给错误的服务器。
5.3 第三步:凭据与项目数据分开存
CredentialStore 和 ProjectStore 是两个独立文件,职责清晰:
CredentialStore(97 行)→ AssetStoreKit,存服务地址和访问令牌;ProjectStore(68 行)→ Preferences,存项目摘要。
架构文档里还专门写了一句:
正式认证流程仍应由甲方登录组件签发短时令牌,不要把真实令牌写进源码或普通 Preferences。
这句话既是给合作方的约束,也是这类科研应用上架时必须交代清楚的合规点。
5.4 第四步:把服务接口标准化
移植能不能被别人复用,取决于接口定义得够不够清楚。ARCHITECTURE.md 里直接给了一张接口表:
| 接口 | 用途 |
|---|---|
POST /v1/projects | 上传 CIF/XY/RAW/GPX 创建项目(JSON + Base64,解码后 ≤ 20 MB) |
GET /v1/projects | 获取当前用户的项目摘要 |
GET /v1/projects/{id}/summary | 获取 Rwp、相位数、精修进度 |
GET /v1/projects/{id}/trend | 获取拟合趋势与绘图数据 |
POST /v1/projects/{id}/refinement | 启动一次精修任务 |
DELETE /v1/projects/{id} | 删除项目及应用上传的原始文件 |
这六个接口基本覆盖了一个晶体分析工作流的全生命周期。移动端只收版本化 JSON,不传二进制中间结果——这样服务端换实现(比如以后用 C++ 另写一版算法)客户端不用改。
仓库里还带了 backend/ 目录,是一个 Python 参考服务,用 GSASIIscriptable.G2Project 读 GPX 摘要,没有装 GSAS-II 也能起健康检查和项目索引接口。
5.5 第五步:文件选择走系统选择器
导入数据时不去扫目录,而是调系统文件选择器:

这里有两个细节值得说:
- 安全访问提示:顶部横幅写着「应用仅可访问您选定的文件或文件夹,无法访问文件夹其他内容。」这是鸿蒙的分区存储模型,应用拿不到整个文件系统;
- 格式过滤:底部「文件格式」显示的是 晶体数据——说明应用注册了自定义 MIME 类型,而不是让用户在一堆图片里找
.cif。
设置页里也对应写着「文件选择 / 系统选择器按需授权」——权限模型是对用户透明的。
六、问题困难解决
6.1 困难一:怎么让「跑不动」的项目变得有用
这是这次移植最大的设计题。
三条路都试过推演:
| 方案 | 包体 | 可用性 | 结论 |
|---|---|---|---|
| Python HNP 全本地 | 数百 MB | 精修慢,界面还得移植一遍 | ❌ |
| 纯云客户端 | 很小 | 数据必须上传,科研场景不接受 | ❌ |
| 本地工作区 + 远端计算 | 很小 | 离线可管理,联网才精修 | ✅ |
选第三条的关键理由是:科研数据的所有权和计算的归属可以分开。数据可以留在本地,重计算才出去。
6.2 困难二:界面工作量大,但只有一个页面文件
Index.ets 有 2277 行,全部界面都在这一个文件里。这在前端工程里算「巨文件」了,但对这个项目是有道理的——
- 三个主页面(工作台、项目空间、分析摘要)共享大量状态(当前项目、Rwp、精修进度);
- 拆成多个文件就要引入状态管理或 props 层层传递;
- 单个文件反而让「当前项目」这个核心状态只有一份。
这是个典型的取舍:可读性 vs 状态简单性。作者选了后者。
6.3 困难三:科研指标怎么在卡片里表达
工作台首页的四张卡片不是随便设计的:

进行中的项目 0 本月数据集 0 最佳 Rwp — 已完成项目 0
其中 Rwp 是 Rietveld 精修的核心质量指标(加权剖面残差,越小越好)。把一个专业指标放进首页卡片,说明这个界面是给懂行的人看的,不是给演示用的。
同理,「项目空间」页面里显示的是「0 个相位 / 尚未精修」:

「相位(phase)」和「精修(refinement)」都是晶体学的标准术语。界面没有为了「通俗」把它们改成「成分」「优化」——这个判断是对的,目标用户就是科研人员。
6.4 困难四:空态不能糊弄
三个页面在没数据时都没有伪造内容:
| 页面 | 空态文案 |
|---|---|
| 工作台 | 暂无分析项目 / 导入 CIF、XY、RAW 或 GPX 开始 |
| 最近数据 | 导入文件后,最近数据会显示在这里 |
| 导入对话框 | 最近使用 / 暂无最近导入的文件 |
而且工作台的绿卡片上明确标着 0% 已完成 和 —(而不是 0)表示「无数据」。— 和 0 的区分在科研场景里很重要:一个是「还没测」,一个是「测出来是零」。
七、构建与运行方式
7.1 环境
- DevEco Studio(内置 hvigor + SDK)
- HarmonyOS SDK API 26(本机 26.0.0.105)
- 无需 Python、无需 native 工具链
7.2 构建
cd ohos
ohpm install
hvigorw assembleHap --mode module -p product=default -p buildMode=debug
注:仓库原本只提供
build-profile.template.json5和entry/build-profile.template,克隆后需要先生成build-profile.json5才能构建。移植验证时补上了这两份配置(签名留空,便于任何人用自己的证书)。
产物:
entry-default-unsigned.hap 444 KB
纯 ArkTS,构建约 3 秒。
7.3 签名与安装
scripts/sign_hap.sh(环境变量方式)或 DevEco 自动签名。调试 profile 绑定设备 UDID,换设备需重新自动签名,否则报 9568423 device is unauthorized。
hdc shell aa start -b com.crystalcloud.analysis -a EntryAbility
7.4 部署分析服务(可选)
如果要跑真实精修,需要部署 backend/ 里的参考服务:
CRYSTALCLOUD_TOKEN=local-dev-token \
PYTHONPATH=. python -m ohos.backend.server
然后在应用里「设置与连接 → 计算服务」填入 HTTPS 地址和令牌。
八、适配成果
8.1 工作台

左侧是「工作区」和「系统」两组导航,右侧是四张指标卡 + 当前项目卡 + 最近数据。底部常驻 本地工作区 状态。
8.2 项目空间

一屏里同时给出「全部项目列表」和「当前选择」两个视角:左边看全集,右边看当前项目的相位数和精修状态。右上角「共 0 个项目 · 已完成 0」是全局计数。
8.3 设置与连接

六个入口分成两组:
- 工作区:计算服务(本地/远端切换)、文件选择、消息提示
- 关于应用:隐私与数据、开源与致谢、版本信息(
1.0.0 · OpenHarmony)
这个结构对一个科研工具来说是够用的——没有堆砌设置项,把「数据来源」和「合规信息」放在了最显眼的位置。
8.4 工程量
| 指标 | 数值 |
|---|---|
| ArkTS 源文件 | 6 个 |
| 代码行数 | 3476 行 |
| 主界面 | Index.ets 2277 行 |
| 服务客户端 | CrystalAnalysisService.ets 797 行 |
| 第三方依赖 | 0 |
| 权限数量 | 1(INTERNET) |
| HAP 体积 | 444 KB |
8.5 同类移植项目横向对比
| ClipNest | 澜析工程 | 沙箱控制台 | 晶析云 | |
|---|---|---|---|---|
| 类型 | 本地工具 | 本地计算 | 云客户端 | 混合模式 |
| ArkTS 行数 | 4782 | 3417 | 5862 | 3476 |
| 随包原生产物 | 0 | 17 MB | 0 | 0 |
| HAP 体积 | 752 KB | 19 MB | 892 KB | 444 KB |
| 核心难点 | 权限与自写入回环 | 进程模型 | 双端点 API 封装 | 本地/远端边界 |
九、功能验证结果
9.1 已在真机验证
| 功能 | 结果 | 验证方式 |
|---|---|---|
| 构建与安装 | ✅ | 444 KB HAP 产出,hdc install 成功 |
| 应用启动 | ✅ | 进程稳定运行,窗口正常渲染 |
| 工作台首页 | ✅ | 四张指标卡、当前项目卡、最近数据均正确 |
| 项目空间 | ✅ | 列表 + 当前选择双栏,空态正确 |
| 分析摘要入口 | ✅ | 按钮存在并可进入 |
| 设置与连接 | ✅ | 六个入口全部渲染,版本信息 1.0.0 · OpenHarmony 正确 |
| 模式标识 | ✅ | 顶栏与底栏均显示「本地工作区 · 未连接分析服务」 |
| 计算服务配置 | ✅ | HTTPS 地址 + 短时令牌对话框正常,提示「仅支持 HTTPS」 |
| 导入数据对话框 | ✅ | 四种格式说明、最近使用空态、安全提示均正确 |
| 系统文件选择器 | ✅ | 正常拉起,显示「晶体数据」格式过滤与分区存储提示 |
| 权限配置 | ✅ | 仅声明 INTERNET,未触发额外授权弹窗 |
9.2 未验证(需要部署分析服务)
| 功能 | 说明 |
|---|---|
| 连接分析服务 | 需要一个真实的 HTTPS 端点 + 有效令牌,本次未部署 |
| 项目创建与上传 | 依赖服务端 POST /v1/projects |
| Rwp 与精修趋势 | 依赖服务端 /summary 与 /trend 接口 |
| 启动精修任务 | 依赖 /refinement 接口 |
| 实际导入晶体文件 | 设备上没有 .cif/.xy/.raw/.gpx 样本,未走完导入 |
| 凭据写入 AssetStoreKit | 需要一次成功连接才能验证落盘路径 |
9.3 已知限制
| 限制 | 说明 |
|---|---|
| 精修计算不在本地 | 必须部署分析服务,或对接甲方已有服务 |
| 需要自备 HTTPS 端点 | 应用强制 HTTPS,本地调试需自签证书 |
| 仓库缺省构建配置 | 原仓库只有 template,需先生成 build-profile.json5 |
| 调试 profile 绑 UDID | 换设备需重新自动签名 |
十、上架复盘:审核不通过怎么办
移植跑通只是第一关。上架审核看的是另一套东西:用户会不会把这款应用误认为上游官方版,或者误认为换皮抄袭。名称、图标、截图、描述、权限、实际行为,只要有一项对不上,就可能被驳回。
10.1 名称和图标:开源许可不等于品牌许可
这是最容易踩的坑。很多人觉得“这是开源软件,保留原名和原图标很正常”,但 MIT/Apache/GPL 给的是版权许可,不是商标许可。审核看到“应用名和上游一样、图标是上游 Logo 换色、截图里还有上游品牌”,就会按“冒用/抄袭”处理。典型的三连击是:应用名直接沿用上游、图标只把颜色换一下、截图里还带着上游 Logo——即使代码全部重写,也会被判定为冒用。
我们的处理原则:
- 应用名改成独立品牌,包名不带上游商标;
- 图标重画,不复用、不改色、不截取上游 Logo;
- 截图、启动图、关于页不出现上游 Logo,只保留文字致谢;
- 关于页写明“基于 GSAS-II 移植,非官方发行”,并保留上游 LICENSE/NOTICE;
- 如果被质疑,提交《品牌与素材来源说明》:改名前后对照、图标设计稿、上游许可证、代码差异、真机录屏。
10.2 被判定“抄袭/雷同”时,交什么证据
只回“这是开源软件”通常没用。按这个顺序给材料:
- 上游仓库地址和 LICENSE 原文;
- 本仓库与上游的差异清单(UI 重写、平台层、构建脚本);
- 品牌变更记录(旧名→新名、旧图标→新图标);
- 功能差异说明(哪些是鸿蒙特有、哪些上游没有);
- 真机录屏,证明不是套壳。
如果确实沿用了上游 UI,先改再申诉;审核一般不看“开源所以可以一样”的解释。
10.3 这个项目的高频驳回点
- 数据去哪:科研数据敏感,隐私政策要写清“只上传到用户自己配置的服务”,默认空态,不预置假项目。
- 审核机没有后端:准备一个可用的测试服务或内置演示模式,否则会被判“功能不可用”。
- 品牌:晶析云是独立品牌,关于页写“基于 GSAS-II,非官方”,不出现上游 Logo。
10.4 驳回后的处理顺序
先分类,再动手。审核意见通常落在六类:名称/图标/品牌、隐私与权限、功能与描述不符、技术(签名/包名/架构/体积/崩溃)、内容合规、资质(软著/授权书/备案)。
- 一次只改一类,别在同一个版本里混改;
- 回复时逐条对应:版本号 + 审核意见 + 改了什么 + 怎么验证;
- 测试账号/令牌在复审前重置,写进审核备注;
- 截图必须来自当前版本真机,不能用设计稿;
- 换正式证书后重新打包,不要用调试签名送审;
- 被拒后先回一条“已收到,逐条说明”,再提新包,避免被判定骚扰;
- 上架材料提前备齐:软著/授权书、隐私政策公网 URL、测试账号、真机截图、开源许可证与 NOTICE。
回复可以按这个模板:
您好,针对第 X 条“……”:我们已在版本 A.B.C 中修改:1)……;2)……。验证路径:……。相关材料见附件/链接。
一句话:上架不是“把包传上去”,而是把“这不是官方版、也不是换皮”这件事,用名称、图标、截图、代码和材料同时证明一遍。
十一、结语
这次移植最特别的地方是:它不是「把功能搬过来」,而是「重新划分计算边界」。
四点体会:
-
不是所有项目都能整体移植,学会切分更重要。GSAS-II 的 Python + wxPython 组合在鸿蒙上无解,硬带运行时只会得到一个又大又慢又难验证的东西。把「交互」和「计算」切开,各自放到最合适的地方,才是可行解。
-
科研工具的第一原则是数据主权。导入对话框那句「仅保存项目摘要,不会自动上传」,比任何功能都重要。用户可以离线建项目、看摘要,联网时才动用云端算力。
-
接口标准化决定移植能不能被复用。
ARCHITECTURE.md里那六个/v1/projects接口,让服务端可以随时换实现而客户端不动。这是把一次性移植变成长期工程的关键。 -
专业术语不要为了「通俗」而替换。Rwp、相位、精修——目标用户就是科研人员,改成「质量分」「成分」「优化」反而让人怀疑专业性。
444 KB 的包体,装着一个完整的晶体分析工作台。它自己不做数值计算,但它把「用户怎么用一个跑不动的科研软件」这个问题回答清楚了。
一句话:不是所有移植都要"整体搬"——把计算边界切开,往往才是正解。
相关链接
- 适配仓库:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_GSAS-II
- 上游项目 GSAS-II:https://github.com/AdvancedPhotonSource/GSAS-II
- OpenHarmony PC 开发者社区:https://atomgit.com/OpenHarmonyPCDeveloper
更多推荐



所有评论(0)