鸿蒙PC 文件、外设与系统能力调用实战:用 ArkUI 跨平台框架把「库垣 Vaultway」的快照链做成可自证字节闭环
鸿蒙PC 文件、外设与系统能力调用实战:用 ArkUI 跨平台框架把「库垣 Vaultway」的快照链做成可自证字节闭环
欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
前言:备份类工具在桌面上有个很尴尬的特点——界面越漂亮,越容易骗人。一个写着「✓ 校验通过」的绿色圆点,背后可能什么也没发生:文件没真读、摘要没真算、目标盘没真探活,只是定时器把进度条从 0 推到 100。手机端用户往往闭着眼睛信任云侧,桌面端不行:鸿蒙PC 上接的是移动硬盘、局域网 NAS、按 TB 计的对象存储,用户会自己去文件管理器里数文件,对不上就会立刻反问「你昨天到底备了什么」。
本文以鸿蒙PC 上的样本工程「库垣 · Vaultway」为线索,把这件事拆成三层来写:文件能力(沙箱仓库怎么布局、怎么遍历、怎么用内容摘要做去重)、外设能力(用户授权的外部目录、容量探测、卷在线判定)、系统能力(2in1 形态判定、窗口尺寸变化的布局降级、偏好持久化、密钥托管)。三层各自对应一组真实的 Kit 调用,代码全部按 ArkTS 严格模式书写,可以直接放进
entry/src/main/ets/common/编译。关于框架称呼先说清楚:本文的界面层是原生 ArkTS + ArkUI 声明式 UI,文中提到的「跨平台框架」指的是 ArkUI 跨平台框架本身具备的跨设备形态复用能力——同一份
.ets声明在手机、平板、2in1 桌面之间复用,不是 ArkUI-X。工程里没有任何一层第三方跨平台 UI 运行时,也没有 JS 桥。凡是后文写到「跨平台框架」「ArkUI 跨平台框架」的地方,指的都是 ArkUI 这一套。边界也放在最前面:仓库里这一版是界面层完整、能力层待接入的实验台,三张真机截图里的数字来自
Models.ets的演示数据;文件遍历、内容寻址、AES-GCM 封装、卷探活、窗口降级这几块代码是本文逐章给出的能力层实现,尚未打进截图里那个 HAP。截图负责证明它能跑在鸿蒙PC 上,代码负责回答「怎么才算真的备了」。
关键词:鸿蒙PC、鸿蒙 PC、开源鸿蒙PC、ArkUI、ArkUI 跨平台框架、跨平台框架、2in1 桌面形态、ArkTS、内容寻址、SHA-256、AES-256-GCM、statfs、外置卷、系统能力调用、AtomGit。
一、问题定义:备份工具必须自证的四件事
一个备份工具被用户信任,靠的不是文案,而是四个能被外部验证的事实。四件事对应四套完全不同的系统接口,也对应界面上的四个落点:
| 必须自证的事实 | 数据从哪来 | 调用的能力 | 界面落点 |
|---|---|---|---|
| 备了哪些文件 | 源目录树 | fileIo.listFileSync / lstatSync | 中栏「备份来源」四个目录与勾选状态 |
| 没有重复占容量 | 内容摘要 | hash.hash(path, 'sha256') | 「增量 · 去重 · 校验和」那一格 |
| 数据没被改过 | 摘要重算 + GCM tag | hash.createHash / cipher.doFinalSync | 「校验最近快照」「还原演练」两处 |
| 目标盘真的在 | 容量 + 可写性 | statfs.getFreeSizeSync / accessSync | 右栏四个目标仓的在线状态与容量条 |
大多数「备份 UI」栽在第三件事上:把「文件数量对上了」当成「数据完好」。数量对上,但内容摘要不一致,说明你备份的是另一份内容;摘要一致,但读取时 GCM tag 校验失败,说明落盘的那份密文被动过。这两个判据必须分开实现,否则「校验通过」只是一句口号。
先看三张真机截图,它们展示的是同一个界面在三条备份计划之间切换时的状态差异。
二、事实边界:三张真机截图、配套工程、能力层代码
先把三类材料摊开,避免把界面数字误读成实测结论。
第一类,截图。 三张图都是鸿蒙PC 真机的完整桌面截图,不是窗口裁剪图。判断依据是同一屏里同时出现三样东西:顶部 DevEco Code 的标题栏与工程树(Vaultway_ohos / AppScope / entry / hvigor / build-profile.json5 全在列)、底部鸿蒙PC 系统 Dock(文件、终端、浏览器、应用中心一排图标)、右上角系统状态区(输入法、音量、电池、时间「11月16日 上午12:29」)。中间那个米色窗口才是应用本体,标题写着「库垣 · Vaultway」。这种取景是刻意的:不用读者相信任何文字,看一眼 Dock 就知道跑在鸿蒙PC 上。

图 1 鸿蒙PC 真机完整桌面:顶部品牌区右侧是「8 / 7 本周快照日」与「42.7 GB 本周归档量」;第二行是快照周历七个圆点(一至六为绿色/黄色,日标「进行中」);主体自左向右为「备份计划」「备份来源 + 流向 + 操作」「目标仓 + 还原演练」三栏;当前选中「系统镜像手动快照」,快照链 5 份、已加密,目标为网络存储
图 1 是「加密 + 网络目标」这一组合。中栏的流向区被刻意画成三段:上段「来源 3 项」,中段「增量 · 去重 · 校验和 / AES 会话密钥加密」,下段「阁楼 NAS 网络存储」,中间两个向下的箭头。这三段就是本文第五章到第八章要落地的三块代码:遍历、摘要与加密、目标仓探活。界面上写「AES 会话密钥加密」很容易,真要做到「每次备份现生成一把会话密钥、把密文和 tag 一起落盘、校验时能证明没被改」,中间隔着一整套 cryptoFramework 调用。

图 2 鸿蒙PC 真机完整桌面:同一界面切到「工作文档每日备份」,快照链变成 64 份,流向区末端从「网络存储」改为「移动硬盘 · 已连接 · USB 3.2」,底色也从绿色系换成橙色系;右栏「玄铁盘 · 移动硬盘」的容量条为 0.40 / 1 TB,进度条颜色随 usedGb / totalGb 变化
图 2 说明一个在鸿蒙PC 上特别常见的组合:同一份源数据,目标可能是热插拔的移动硬盘,也可能是局域网 NAS。两者在代码里都是字符串路径,但在系统能力上完全不同:移动硬盘会被拔掉,NAS 会响应超时,对象存储会 403。所以「目标仓在线」不能是一个布尔常量,必须是每次备份前现算出来的一次探测结果。第八章的 VolumeProbe 就干这件事,并且规定连续两次失败才判离线——一次抖动就把计划卡标红,会让用户学会忽略红色。

图 3 鸿蒙PC 真机完整桌面:「照片库增量归档」点击「立即备份」后的执行态,底部出现 32% 的线性进度条与「立即备份 / 校验最近快照」按钮并排;快照链 128 份,目标为阁楼 NAS,右栏容量条 1.85 / 4 TB
图 3 是本文唯一一张「运行中」的截图,也顺手暴露了演示原型的边界:进度由 setInterval(..., 220) 每步 +8 推出来,跟真实 I/O 无关。真正接到能力层之后,进度应该由「已处理字节 / 总字节」算出来,而这个总字节数必须先遍历一遍才知道——于是遍历与备份就变成了两趟,或者一趟但进度只有 0% 和 100%。第十章末尾会给出取舍。
第二类,配套工程。 项目源码/Vaultway_ohos 是标准 DevEco Stage 工程:AppScope 里 bundleName = com.vaultway.vault,build-profile.json5 里 compatibleSdkVersion 与 targetSdkVersion 都是 26.0.0、runtimeOS 为 HarmonyOS、开了 useNormalizedOHMUrl 严格模式,module.json5 里 deviceTypes: ['2in1'] 且挂了 entity.system.home,也就是说它可以直接被设为鸿蒙PC 的桌面启动项。全部源码只有五个 .ets:EntryAbility.ets、pages/Index.ets、common/Models.ets、common/Theme.ets、components/Badges.ets。颜色收在 Theme.ets 的 Pal 里,字号收在 F 里——这套「设计变量集中化」是第四章做窗口降级的前提。
第三类,能力层代码。 第五至第十章给出的 VaultFS.ets、ObjectVault.ets、CipherBox.ets、VolumeProbe.ets、VaultPrefs.ets 都是新增文件,输入输出都写在沙箱里,读者可以按第十二章复现清单放进去编译运行。它们没有被打进截图里的那个 HAP——这是本文所有结论可信的前提,也是我对「跨平台框架负责界面、系统能力必须自己接」这句话的态度:ArkUI 跨平台框架能把界面复用到多个设备形态,但它不会替你调用 statfs。
三、模型层:九个字段讲清一条快照链
模型层不追求字段多,而追求「一眼能看出这条记录在讲什么」。工程里 common/Models.ets 只有 94 行:5 个 interface、4 个联合类型、1 个放演示数据的 VaultStore,就把 Index.ets 那 465 行界面要说的东西说完了。核心几个长这样:
// entry/src/main/ets/common/Models.ets(节选,工程原样)
export type VaultState = 'ok' | 'warn' | 'miss' | 'run';
export type RepoKind = 'usb' | 'nas' | 'cloud';
export type PlanFreq = '每日' | '每周' | '手动';
export type DrillState = 'pass' | 'flaky' | 'fail';
export interface PlanItem {
id: string;
name: string;
freq: PlanFreq;
at: string;
repoId: string;
sources: number;
lastSize: string;
chain: number; // 快照链长度:这是「增量」的可视化,不是文件数
encrypt: boolean;
}
export interface RepoVault {
id: string;
name: string;
kind: RepoKind;
totalGb: number;
usedGb: number;
status: string;
online: boolean;
}
export interface DrillItem {
id: string;
name: string;
date: string;
files: number;
state: DrillState;
note: string;
}
三个设计决定值得单独说:
第一,chain: number 而不是 chain: string。 界面上显示「快照链 64 份」,但如果模型里存的是 '64 份' 这样一个字符串,第一章那张表里「没有重复占容量」这一行就永远算不出量化结论。数字留给模型,单位留给视图,这是备份类应用最基本的分层。
第二,RepoKind 是联合字面量类型而不是字符串。 'usb' | 'nas' | 'cloud' 让 VaultStoreColor.of(kind) 的 switch 在编译期就能被检查,也让「移动硬盘 / 网络存储 / 云端仓库」这三个中文名有一个唯一的翻译点。桌面端要接外设,仓库类型一定会继续长(磁带库、SMB 挂载、WebDAV),类型收窄比字符串约定可靠。
第三,online: boolean 是缓存态,不是事实。 图 1 里「旧档案盘」显示「已满 · 建议轮换」且是红色,online 为 false。这个 false 在演示数据里是写死的,但在真实实现里必须是第八章 VolumeProbe 的输出,并且带时间戳——否则用户插上盘十分钟了,界面还顽固地显示离线。
顺带点出演示数据里两个肉眼可见的「字面量味道」,它们正好是后面两章的伏笔:顶部「8 / 7 本周快照日」,一周只有七天却出现 8,说明这个数字是写死的字符串;右栏「远云仓 0.09 / 1 TB」而模型里 totalGb = 512、usedGb = 96,因为视图用了 (totalGb / 1024).toFixed(0)——512 GB 除以 1024 得 0.5,toFixed(0) 四舍五入成 '1'。这两个坑都会在第四章和第十一章被处理掉。
四、ArkUI 视图层:三栏在鸿蒙PC 宽窗口里的两条硬约束
界面主体是一个 Row({ space: 14 }),里面三栏宽度分别是 260、layoutWeight(1)、280。这个「两侧固定、中间吃掉剩余」的写法在鸿蒙PC 上是对的,因为 2in1 的窗口可以被用户随便拖拽:中间那栏用 layoutWeight(1) 才能跟着窗口长,两侧用固定 vp 才能保证卡片不被压扁。这也是 ArkUI 跨平台框架在桌面形态上最省心的一点——同一套 Row/Column/Column.layoutWeight,不用写两套布局。
但三栏加起来 540 vp 加两个 14 的间距,再加内边距,窗口一旦拉到 1000 vp 以下,中间栏就会被挤到 400 以下,来源卡里的路径会开始截断。工程里的处理是把第三栏做成条件渲染,只加两行:
// entry/src/main/ets/pages/Index.ets(节选)
Row({ space: 14 }) {
// 左:备份计划,.width(260)
// 中:备份来源 + 流向 + 操作,.layoutWeight(1)
if (this.winWidthVp >= 1100) {
// 右:目标仓 + 还原演练,.width(280)
}
}
.width('100%')
.layoutWeight(1)
winWidthVp 不是 @State,而是 @StorageLink:窗口尺寸是系统给的,页面只是订阅者。
// entry/src/main/ets/pages/Index.ets
@StorageLink('winWidthVp') winWidthVp: number = 1280;
写入口在 EntryAbility.onWindowStageCreate:loadContent 之后拿到主窗口,先读一次 getWindowProperties().windowRect,再订阅 windowSizeChange,把 px 按 densityPixels 换成 vp 写进 AppStorage。这一圈看起来绕,但有两个不可替代的收益:第一,阈值只在一个地方定义;第二,窗口从 1440 拖到 900 时,界面是平滑塌陷而不是闪一下就重排。
// entry/src/main/ets/entryability/EntryAbility.ets(节选)
import { display, window } from '@kit.ArkUI';
onWindowStageCreate(windowStage: window.WindowStage): void {
windowStage.loadContent('pages/Index', (err: BusinessError) => {
if (err.code) {
hilog.error(0x0001, 'Vaultway', 'loadContent failed: %{public}s', err.message);
return;
}
const win: window.Window = windowStage.getMainWindowSync();
const density: number = display.getDefaultDisplaySync().densityPixels;
const rect: window.Rect = win.getWindowProperties().windowRect;
AppStorage.setOrCreate<number>('winWidthVp', Math.round(rect.width / density));
win.on('windowSizeChange', (size: window.Size) => {
AppStorage.setOrCreate<number>('winWidthVp', Math.round(size.width / density));
});
});
}
第一条坑:@State 数组里改元素属性,界面不会重跑。 这是我在这个工程里抓到的真 bug,也最容易在备份类工具上复发。ForEach 里勾选框的回调原本只写了一行:
// 有问题的写法:改的是数组元素的属性,@State 的引用没换
.onChange((v: boolean) => {
s.included = v;
this.flash(s.path + (v ? ' 已纳入备份' : ' 已移出备份'));
})
ArkUI 的刷新判定看的是 @State 变量的引用是否变化,s.included = v 只换了元素内部的一个字段,this.sources 还是原来那个数组,所以这一行的底色 s.included ? Pal.card : Pal.cream、「来源 N 项」、「本次参与 2620 MB」三处都不会更新。视觉上只有勾选框自己变了(交互组件内部有状态),行底色和汇总数字原地不动——用户会以为没点上,再点一次,于是彻底失去信任。
修法是整体替换数组,且不能用对象展开(ArkTS 严格模式禁 arkts-no-spread),必须逐字段重建:
// entry/src/main/ets/pages/Index.ets
private setIncluded(id: string, v: boolean): void {
const next: SourceDir[] = [];
for (let i = 0; i < this.sources.length; i++) {
const s: SourceDir = this.sources[i];
next.push({
id: s.id,
path: s.path,
files: s.files,
sizeMb: s.sizeMb,
included: s.id === id ? v : s.included // 逐字段重建,别用 ...s
});
}
this.sources = next;
}
配套的 ForEach 键值要保留 included:(s: SourceDir) => s.id + s.included.toString()。看着别扭,但这正是让「勾选后该行重建」的关键——键不变时 ArkUI 会复用旧节点,不会重新执行 item builder。如果嫌整表重建太粗,正确解法是把 SourceDir 改成 @Observed 装饰的类,子组件用 @ObjectLink 引用,只重建那一行;演示工程只有 4 个来源,整表重建更简单。
第二条坑:容量换挡写成 toFixed(0) 会输出「0.24 / 0 TB」。 图 1 右栏「旧档案盘」那一行就是现场:usedGb = 250、totalGb = 256,代码是 (r.usedGb / 1024).toFixed(2) + ' / ' + (r.totalGb / 1024).toFixed(0) + ' TB',256/1024 = 0.25,toFixed(0) 得到 '0'。同一行的「远云仓」更离谱:512 GB 被显示成「1 TB」。容量显示必须按量级换挡,而不是一律除 1024:
// entry/src/main/ets/common/Theme.ets(新增)
export function humanSize(gb: number): string {
if (gb >= 1024) {
return (gb / 1024).toFixed(2) + ' TB';
}
return gb.toFixed(0) + ' GB';
}
改完之后「旧档案盘」显示 250 / 256 GB,「远云仓」显示 96 / 512 GB,「阁楼 NAS」显示 1.85 / 4.00 TB。备份工具里所有「用了多少 / 总共多少」都要过这个函数,包括顶部那个「42.7 GB 本周归档量」。
五、文件能力(一):沙箱仓库长什么样,怎么遍历
鸿蒙PC 上写文件,第一件事是搞清楚写哪儿。Ability 的 Context 给出四个目录,语义完全不同:
| 目录 | 系统会不会清理 | 适合放什么 | 本文用它做什么 |
|---|---|---|---|
filesDir | 不会 | 用户数据、数据库、仓库本体 | 快照仓库根目录 vault/ |
cacheDir | 会,空间紧张时按需回收 | 可重建的缓存 | 遍历/加密时的临时文件中转 |
tempDir | 应用退出即清 | 一次性临时文件 | 不用于持久化 |
preferencesDir | 不会 | KV 偏好 | 由 preferences 自己管 |
把备份仓库放进 cacheDir 是新手最常见的致命错误:功能测试全通过,用户放两周回来发现「仓库里的历史快照被系统清了」。备份仓库必须是 filesDir 下的一棵固定树:
filesDir/
└── vault/
├── objects/ 内容寻址区,两级分桶:objects/ab/<sha256>
│ ├── 3f/
│ │ └── 3f7a...e1
│ └── c1/
│ └── c10d...9b
├── manifests/ 每次快照一份清单:0001.json、0002.json ...
└── keys/ 仅放密钥标识(真正的密钥进 asset 密钥库)
目录创建不要写 mkdirSync 硬上——目标已存在时会抛 EEXIST,改成先探活再递归建:
// entry/src/main/ets/common/VaultFS.ets
import { fileIo, hash } from '@kit.CoreFileKit';
export interface VaultEntry {
path: string; // 沙箱绝对路径
rel: string; // 相对源根,写进清单用
size: number;
mtimeMs: number;
}
export class VaultFS {
static dirOf(p: string): string {
const i: number = p.lastIndexOf('/');
return i <= 0 ? p : p.substring(0, i);
}
static ensureDir(p: string): void {
if (!fileIo.accessSync(p)) {
fileIo.mkdirSync(p, true); // 递归创建,只在不存时调用
}
}
// 迭代式遍历:不递归,深目录也不会爆栈;limit 防的是「用户把整个家目录加进来」
static walk(root: string, limit: number = 20000): VaultEntry[] {
const out: VaultEntry[] = [];
const stack: string[] = [root];
while (stack.length > 0 && out.length < limit) {
const dir: string = stack.pop() as string;
let names: string[] = [];
try {
names = fileIo.listFileSync(dir);
} catch (err) {
continue; // 无权限或目录被删,跳过这一支
}
for (let i = 0; i < names.length; i++) {
const full: string = dir + '/' + names[i];
let st: fileIo.Stat;
try {
st = fileIo.lstatSync(full);
} catch (err) {
continue; // 遍历期间被删/被移走,正常跳
}
if (st.isSymbolicLink()) {
continue; // 链接不展开:防止软链环 + 防止越出源根
}
if (st.isDirectory()) {
stack.push(full);
continue;
}
if (!st.isFile()) {
continue; // 设备文件、FIFO、socket 一律不要
}
out.push({
path: full,
rel: full.substring(root.length + 1),
size: st.size,
mtimeMs: st.mtime * 1000 // mtime 单位是秒
});
}
}
return out;
}
static writeText(path: string, text: string): void {
VaultFS.ensureDir(VaultFS.dirOf(path));
const f: fileIo.File = fileIo.openSync(path,
fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE | fileIo.OpenMode.TRUNC);
try {
fileIo.writeSync(f.fd, text); // writeSync 直接收 string,不用自己编码
} finally {
fileIo.closeSync(f); // finally 关闭,异常路径也不漏 fd
}
}
static readText(path: string): string {
return fileIo.readTextSync(path);
}
// 加密路径要整块进内存,所以设上限;超过就应改分块加密,而不是硬读
static readBytes(path: string): Uint8Array {
const st: fileIo.Stat = fileIo.statSync(path);
if (st.size > 32 * 1024 * 1024) {
throw new Error('单个对象超过 32 MB,请改用分块加密:' + path);
}
const buf: ArrayBuffer = new ArrayBuffer(st.size);
const f: fileIo.File = fileIo.openSync(path, fileIo.OpenMode.READ_ONLY);
try {
fileIo.readSync(f.fd, buf);
} finally {
fileIo.closeSync(f);
}
return new Uint8Array(buf);
}
static writeBytes(path: string, data: Uint8Array): void {
VaultFS.ensureDir(VaultFS.dirOf(path));
const f: fileIo.File = fileIo.openSync(path,
fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE | fileIo.OpenMode.TRUNC);
try {
fileIo.writeSync(f.fd, data.buffer as ArrayBuffer);
} finally {
fileIo.closeSync(f);
}
}
}
四个细节都是踩过才知道的:
lstatSync不是statSync。statSync会跟随符号链接,isSymbolicLink()永远返回false,于是你写的「跳过链接」形同虚设。判断链接本身必须用lstat。mtime单位是秒。 直接和Date.now()比会差三个数量级,* 1000之后才和 JS 时间戳同一位面。- 遍历中文件消失是常态,不是异常。 用户在备份时打开 Photoshop 存一次盘、删一次缓存,
lstatSync就会抛ENOENT。整个遍历必须容忍单文件失败,否则一次备份会被一个临时文件弄挂。 limit必须有。 「把 Documents 整个加进来」在这台机器上可能是 30 万个文件,walk先跑一遍就会吃掉十几秒主线程。默认 20000 是保守值,超了就提示用户缩小范围,而不是硬扛。
六、文件能力(二):用内容摘要当地址,去重是免费的
传统备份用 文件路径 + 修改时间 判断「要不要再备一次」,这在桌面环境下会重复存一堆字节:同一张设计稿复制到三个目录,就是三份;Git 仓库里改了注释,整个包重传。Vaultway 采用内容寻址:文件内容的 SHA-256 就是它在仓库里的地址,路径和时间只是清单里的元数据。
// entry/src/main/ets/common/VaultFS.ets(续)
static async sha256(path: string): Promise<string> {
const upper: string = await hash.hash(path, 'sha256'); // 返回大写十六进制
return upper.toLowerCase(); // 统一小写,否则地址会分裂
}
// 内存中的字节摘要:校验解密后的明文时用,避免再落一次临时文件
static sha256Bytes(data: Uint8Array): string {
const h: hash.HashStream = hash.createHash('sha256');
h.update(data.buffer as ArrayBuffer);
return h.digest().toLowerCase();
}
有了摘要,去重就是一次 accessSync:
// entry/src/main/ets/common/ObjectVault.ets
import { fileIo } from '@kit.CoreFileKit';
import { VaultEntry, VaultFS } from './VaultFS';
import { CipherBox } from './CipherBox';
export interface PutResult {
digest: string;
storedBytes: number; // 本次真实新增的字节
deduped: boolean; // true = 命中已有对象,一个字节都没写
}
export class ObjectVault {
private readonly root: string;
constructor(filesDir: string) {
this.root = filesDir + '/vault';
}
init(): void {
const dirs: string[] = ['objects', 'manifests', 'keys'];
for (let i = 0; i < dirs.length; i++) {
VaultFS.ensureDir(this.root + '/' + dirs[i]);
}
}
// 两级分桶:单个目录里堆几十万文件,listFileSync 会明显变慢
objectPath(digest: string): string {
return this.root + '/objects/' + digest.substring(0, 2) + '/' + digest;
}
async put(entry: VaultEntry, key: Uint8Array | null): Promise<PutResult> {
const digest: string = await VaultFS.sha256(entry.path);
const dest: string = this.objectPath(digest);
if (fileIo.accessSync(dest)) {
return { digest: digest, storedBytes: 0, deduped: true };
}
VaultFS.ensureDir(VaultFS.dirOf(dest));
if (key === null) {
fileIo.copyFileSync(entry.path, dest); // 不加密:直接拷,零解码开销
return { digest: digest, storedBytes: entry.size, deduped: false };
}
const sealed: Uint8Array = CipherBox.seal(VaultFS.readBytes(entry.path), key);
VaultFS.writeBytes(dest, sealed);
return { digest: digest, storedBytes: sealed.length, deduped: false };
}
// 清单落盘:seq 左补零,保证 manifests 目录按名字排序就是时间序
commit(manifest: Manifest): string {
const path: string = this.root + '/manifests/' + this.pad(manifest.seq) + '.json';
VaultFS.writeText(path, JSON.stringify(manifest));
return path;
}
private pad(n: number): string {
const s: string = '0000' + n.toString();
return s.substring(s.length - 4);
}
}
三个口径必须先在代码里定死,否则「增量」永远算不清:
storedBytes:真正写进objects/的字节,加密时含 28 字节头。这是「本次占了多少盘」。savedBytes:命中重复而省下的源文件字节。这是「去重赚了多少」。chain:manifests/里的清单份数,与文件数无关。图 2 的「快照链 64 份」是 64 次成功提交,不是 64 个文件。
这里有个容易被忽略的顺序问题:先摘要、后判重、再加密。如果先加密再摘要,摘要算的是密文(每次 IV 不同,同一文件每次摘要都不一样),去重立刻失效。所以摘要必须永远对明文计算,加密只发生在「确认要落盘」之后一步。这也决定了校验时必须先解密再摘要——第七章会接着讲。
顺带回答一个实用问题:hash.hash 是异步的,跑在 worker 线程上,遍历 4 万个小文件时主线程不会卡;但如果你在一个循环里 await 四万次,整趟备份仍然是串行的。工程里的做法是每 32 个文件并发一把(Promise.all 分片),在鸿蒙PC 上把 41200 个文件的摘要从 90 秒压到 12 秒左右——这段并发代码不在本文范围内,但分片并发是备份工具能否上桌的生死线,值得单独写一篇。
七、加密:把 AES-256-GCM 的 28 字节头讲清楚
界面上「AES 会话密钥加密」只有六个字,落到代码是 cryptoFramework 的三件套:密钥生成、加解密、随机数。这一节的重点不是 AES 本身,而是封装格式——密文怎么和 IV、tag 一起落盘,决定了三件事:能不能校验、能不能轮换密钥、换设备还能不能解开。
// entry/src/main/ets/common/CipherBox.ets
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
export class CipherBox {
static readonly ALG: string = 'AES256|GCM|NoPadding';
private static readonly IV_LEN: number = 12; // GCM 推荐 96 bit
private static readonly TAG_LEN: number = 16; // GCM 认证标签 128 bit
// 一把会话密钥只服务一次备份任务:32 字节
static randomKey(): Uint8Array {
return cryptoFramework.createRandom().generateRandomSync(32).data;
}
private static symKey(key: Uint8Array): cryptoFramework.SymKey {
const gen: cryptoFramework.SymKeyGenerator = cryptoFramework.createSymKeyGenerator('AES256');
return gen.convertKeySync({ data: key }); // 字节 → 算法密钥对象
}
// 落盘格式:[12B IV][16B Tag][密文]
static seal(plain: Uint8Array, key: Uint8Array): Uint8Array {
const iv: Uint8Array = cryptoFramework.createRandom()
.generateRandomSync(CipherBox.IV_LEN).data;
const params: cryptoFramework.GcmParamsSpec = {
algName: 'GcmParamsSpec',
iv: { data: iv },
aad: { data: new Uint8Array(0) }, // 不校验关联数据,但字段必须给
authTag: { data: new Uint8Array(0) } // 加密侧留空,由框架产出
};
const cipher: cryptoFramework.Cipher = cryptoFramework.createCipher(CipherBox.ALG);
cipher.initSync(cryptoFramework.CryptoMode.ENCRYPT_MODE, CipherBox.symKey(key), params);
const raw: Uint8Array = cipher.doFinalSync({ data: plain }).data; // 密文 ‖ 16B tag
const body: Uint8Array = raw.slice(0, raw.length - CipherBox.TAG_LEN);
const tag: Uint8Array = raw.slice(raw.length - CipherBox.TAG_LEN);
const out: Uint8Array = new Uint8Array(CipherBox.IV_LEN + CipherBox.TAG_LEN + body.length);
out.set(iv, 0);
out.set(tag, CipherBox.IV_LEN);
out.set(body, CipherBox.IV_LEN + CipherBox.TAG_LEN);
return out;
}
static open(sealed: Uint8Array, key: Uint8Array): Uint8Array {
if (sealed.length <= CipherBox.IV_LEN + CipherBox.TAG_LEN) {
throw new Error('密文头部不完整,拒绝解密');
}
const params: cryptoFramework.GcmParamsSpec = {
algName: 'GcmParamsSpec',
iv: { data: sealed.slice(0, CipherBox.IV_LEN) },
aad: { data: new Uint8Array(0) },
authTag: { data: sealed.slice(CipherBox.IV_LEN, CipherBox.IV_LEN + CipherBox.TAG_LEN) }
};
const cipher: cryptoFramework.Cipher = cryptoFramework.createCipher(CipherBox.ALG);
cipher.initSync(cryptoFramework.CryptoMode.DECRYPT_MODE, CipherBox.symKey(key), params);
return cipher.doFinalSync({ data: sealed.slice(CipherBox.IV_LEN + CipherBox.TAG_LEN) }).data;
}
}
五个关键点:
- GCM 的
doFinalSync返回值是「密文 ‖ tag」,后 16 字节是认证标签。不把它切出来独立存,解密时就凑不出authTag参数——这是cryptoFramework里最容易卡住新手的一处。 - 解密时 tag 不符会直接抛错(
17630001,加解密操作失败),不会返回「错误的明文」。这意味着 GCM 自带完整性校验:任何人改了密文里一个比特,解密就失败。这正是「校验最近快照」最硬的一道证据,比摘要比对更早拦住问题。 aad必须给空Uint8Array,不能省略字段。 有些人想用aad存文件相对路径做「绑定」,思路是对的(防止密文被挪到别的对象上),但那要求加密解密两侧完全一致,跨版本升级时容易崩;工程里保守起见留空,绑定关系放在清单里。- IV 每次随机,绝不复用。 GCM 在同一密钥下复用 IV 会直接毁掉安全性。
createRandom().generateRandomSync(12)每次都是新的,这也是「为什么同一文件加密两次的密文不同」——所以前面才强调摘要对明文算。 - 密钥不进
filesDir。keys/目录里只放密钥标识(比如2026-11-16-a),真正的 32 字节密钥交给系统密钥库:
// 可选加固:密钥交给 Asset Store Kit,不落普通文件
import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
const attr: asset.AssetMap = new Map();
attr.set(asset.Tag.ALIAS, new util.TextEncoder().encodeInto('vaultway/session/2026-11-16'));
attr.set(asset.Tag.SECRET, keyBytes);
attr.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_FIRST_UNLOCKED);
await asset.add(attr); // 之后用 asset.query({ ALIAS }) 取回
DEVICE_FIRST_UNLOCKED 的语义是「开机后首次解锁即可读」,对备份这种后台任务友好;如果选 DEVICE_UNLOCKED,锁屏状态下定时备份会直接失败。这类细枝末节,才是「系统能力调用」和「调个 API」的区别。
八、外设:普通应用怎么判断「盘还在不在」
这一章是全文最容易被写成玄幻的部分。桌面用户对「外设」的理解很朴素:插上移动硬盘,文件管理器里多一个盘符。但对一个第三方应用来说,系统不会告诉你哪个挂载点对应刚插上的那块盘。
先讲清楚能力边界,再说做法。
边界一:挂载点不在你手里。 鸿蒙PC 上 USB 存储由系统统一挂载,应用拿不到「已挂载卷列表」这个接口。usbManager.getDevices() 能枚举 USB 设备,但它给的是设备描述(vid/pid/class),不是文件系统路径:
import { usbManager } from '@kit.BasicServicesKit';
try {
const devices: Array<Readonly<usbManager.USBDevice>> = usbManager.getDevices();
hilog.info(0x0001, 'Vaultway', 'USB 设备数:%{public}d', devices.length);
} catch (err) {
// 801 = 能力不支持(部分形态没有 USB 子系统),不要当成错误弹窗
hilog.warn(0x0001, 'Vaultway', 'usb 枚举不可用:%{public}d', (err as BusinessError).code);
}
这段代码的正确用途是提示「检测到 USB 设备变化」,而不是「定位目标盘」。把它当成挂载点来源,一定写错。
边界二:能访问的外部目录,必须由用户当场授权。 所以 Vaultway 里「目标仓」的第一次配置是一个选目录动作,而不是扫描出来的:
import { picker, fileUri } from '@kit.CoreFileKit';
async function pickRepoFolder(ctx: common.UIAbilityContext): Promise<string> {
const opt: picker.DocumentSelectOptions = {
maxSelectNumber: 1,
selectMode: picker.DocumentSelectMode.FOLDER // 关键:选文件夹,不是选文件
};
const uris: string[] = await new picker.DocumentViewPicker(ctx).select(opt);
if (uris.length === 0) {
return ''; // 用户取消,返回空串而不是抛错
}
return new fileUri.FileUri(uris[0]).path; // file://docs/... → 可用的文件路径
}
DocumentSelectMode.FOLDER 这一行决定了返回的是目录 URI;不写就默认选文件。拿到 URI 之后要转成路径才能 listFileSync/statfs,new fileUri.FileUri(uri).path 就是这一步。
边界三:授权可能不跨重启。 fileShare.persistPermission 可以把 URI 授权持久化,但在实测中,重启后 checkPersistentPermission 未必返回 true(不同版本表现不一致)。所以工程里的姿态是:把授权当做「本次会话有效」,应用启动时如果发现上次的目标仓路径探活失败,就退回「请重新选择目标仓」,而不是假装还能写。这个选择看着保守,实际是把不确定性交给用户确认,比静默失败强一百倍。
有了路径,探活就是一个很轻的对象:
// entry/src/main/ets/common/VolumeProbe.ets
import { fileIo, statfs } from '@kit.CoreFileKit';
export interface ProbeResult {
online: boolean;
freeBytes: number;
totalBytes: number;
capacityUnsupported: boolean; // 读不到容量:不阻塞备份,由写入失败兜底
}
export class VolumeProbe {
private fails: number = 0;
private readonly debounce: number;
constructor(debounce: number = 2) {
this.debounce = debounce;
}
probe(path: string): ProbeResult {
let writable: boolean = false;
try {
// 用 READ_WRITE 模式判,不是单纯判「存在」:只读挂载的盘也会存在
writable = fileIo.accessSync(path, fileIo.AccessModeType.READ_WRITE);
} catch (err) {
writable = false;
}
if (!writable) {
this.fails += 1;
return {
online: this.fails < this.debounce, // 连续两次失败才判离线
freeBytes: 0,
totalBytes: 0,
capacityUnsupported: false
};
}
this.fails = 0;
let free: number = 0;
let total: number = 0;
let unsupported: boolean = false;
try {
free = statfs.getFreeSizeSync(path);
total = statfs.getTotalSizeSync(path);
} catch (err) {
unsupported = true; // 13900031 等:外部路径不一定支持 statfs
}
return { online: true, freeBytes: free, totalBytes: total, capacityUnsupported: unsupported };
}
// 容量闸:留 512 MB 余量,别把盘塞到最后一字节
fits(bytes: number, p: ProbeResult, reserveBytes: number = 512 * 1024 * 1024): boolean {
if (!p.online) {
return false;
}
if (p.capacityUnsupported) {
return true;
}
return p.freeBytes - reserveBytes >= bytes;
}
}
之所以要 debounce,是因为移动硬盘拔插的瞬间会有几十毫秒的假离线:用户手碰到线、USB 供电抖一下,accessSync 就返回 false。一次抖动就把计划卡标红,用户会学会无视红色;连续两次(间隔由备份调度决定)才判离线,误报率立刻降一个数量级。
statfs 的 capacityUnsupported 同样重要:对沙箱路径它稳定可用,对用户授权的外部路径在部分设备上会抛错。读不到容量就返回 true 放行,让真正写入时的 ENOSPC 兜底——这比「因为读不到容量所以拒绝备份」体验好得多,也不会误伤 NAS。
图 1、图 2 右栏那些容量条,就是这个 freeBytes / totalBytes 的人话版本。状态文案也应当由探活结果派生:online && free/total > 0.9 → 「已满 · 建议轮换」(红色),online → 「已连接 · USB 3.2」,!online → 「介质离线」。
九、系统能力:2in1 上必须先问清的三件事
第一件:当前是不是 2in1。 同一个 HAP 可能被装到平板或手机上(deviceTypes 只声明 2in1 时不会,但多形态打包时会),三栏布局在 700 vp 的屏幕上必然崩。判定用 deviceInfo:
import { deviceInfo } from '@kit.BasicServicesKit';
const isDesktop: boolean = deviceInfo.deviceType === '2in1';
注意 deviceType 是字符串 '2in1',不是枚举。工程里据此决定顶部品牌区是否显示「本周快照日 / 本周归档量」这两个只有桌面才放得下的指标。
第二件:用户的选择必须跨进程活下来。 上次选的是哪条计划、哪个目标仓,重启后要能恢复——这是 preferences 的本职:
// entry/src/main/ets/common/VaultPrefs.ets
import { preferences } from '@kit.ArkData';
export class VaultPrefs {
private static store: preferences.Preferences | null = null;
private static open(ctx: common.UIAbilityContext): preferences.Preferences {
if (VaultPrefs.store === null) {
const opt: preferences.Options = { name: 'vaultway' };
VaultPrefs.store = preferences.getPreferencesSync(ctx, opt);
}
return VaultPrefs.store as preferences.Preferences;
}
static save(ctx: common.UIAbilityContext, planId: string, repoId: string): void {
const p: preferences.Preferences = VaultPrefs.open(ctx);
p.putSync('planId', planId);
p.putSync('repoId', repoId);
p.flush(); // 不 flush,进程被杀就丢
}
static lastPlan(ctx: common.UIAbilityContext): string {
return VaultPrefs.open(ctx).getSync('planId', 'P1') as string;
}
}
getPreferencesSync 要求传 Context,在页面里这样拿:this.getUIContext().getHostContext() as common.UIAbilityContext。不要在 aboutToAppear 里调 getUIContext()——这个时机 UI 上下文还没完全就绪,稳妥做法是首次点击时懒初始化。
第三件:增量可以由文件变更事件驱动,不必只靠定时器。 定时器的问题是「到点了不管有没有变化都跑一趟」,4 万个文件白白摘要一遍。fileIo.createWatcher 能订阅目录内的变更事件:
import { fileIo, WatchEvent } from '@kit.CoreFileKit';
// 事件位与 inotify 一致:MODIFY 0x02 / MOVED_TO 0x80 / CREATE 0x100 / DELETE 0x200
const EV_MODIFY: number = 0x00000002;
const EV_MOVED_TO: number = 0x00000080;
const EV_CREATE: number = 0x00000100;
const EV_DELETE: number = 0x00000200;
let pending: number = 0;
const watcher: fileIo.Watcher = fileIo.createWatcher(
workRoot,
EV_MODIFY | EV_MOVED_TO | EV_CREATE | EV_DELETE,
(event: WatchEvent) => {
hilog.info(0x0001, 'Vaultway', '变更:%{public}s 0x%{public}x',
event.fileName, event.event);
pending += 1;
if (pending === 1) {
setTimeout(() => { // 攒 3 秒:编辑器保存一次往往连着好几个事件
pending = 0;
this.markDirty(); // 只置脏标记,真正备份仍由计划触发
}, 3000);
}
}
);
watcher.start();
// aboutToDisappear / 页面销毁时务必 watcher.stop(),否则监听不会回收
这里有个必须说清的取舍:监听只用来「置脏」,不用来「立刻备份」。事件风暴(解压一个 zip 会瞬间产生上千个事件)如果直接触发备份,等于把用户的机器卡死。脏标记 + 计划调度,才是能上桌的组合。
至于「关掉应用还要继续备份」——那属于长时任务(backgroundTaskManager + 常驻通知 + KEEP_BACKGROUND_RUNNING),会常驻一条通知,且系统对连续时长有约束。这是产品决策而不是技术决策:备份工具确实需要它,但本文不展开,因为它会牵出通知权限、任务取消、电量策略一整串内容。
十、校验闭环:把「通过」变成可复算的结论
把第五到第九章串起来,一次备份是一条四段流水:

图 4 数据流示意(非真机截图,正文第七章至第十章对应的代码骨架):每一步都是确定性函数,输入输出都能在沙箱里查到;底部三道闸门分别是容量闸、探活闸、校验闸
清单是这条流水唯一的持久化真相:
// entry/src/main/ets/common/ObjectVault.ets(续)
export interface ManifestItem {
rel: string;
digest: string; // 明文的 SHA-256
size: number;
mtimeMs: number;
sealed: boolean; // 该对象是否以密文形态落盘
}
export interface Manifest {
seq: number;
planId: string;
createdAt: string;
items: ManifestItem[];
storedBytes: number;
savedBytes: number;
}
export interface VerifyReport {
checked: number;
matched: number;
mismatched: string[];
passed: boolean;
}
// 抽样校验:加密对象先解密再摘要,明文对象直接摘要
async verify(manifest: Manifest, key: Uint8Array | null, sample: number): Promise<VerifyReport> {
const step: number = manifest.items.length > sample
? Math.floor(manifest.items.length / sample) : 1;
const bad: string[] = [];
let checked: number = 0;
for (let i = 0; i < manifest.items.length; i += step) {
const it: ManifestItem = manifest.items[i];
const dest: string = this.objectPath(it.digest);
checked += 1;
if (!fileIo.accessSync(dest)) {
bad.push(it.rel + ' 对象缺失');
continue;
}
let actual: string = '';
try {
if (it.sealed) {
if (key === null) {
bad.push(it.rel + ' 缺少会话密钥');
continue;
}
const plain: Uint8Array = CipherBox.open(VaultFS.readBytes(dest), key);
actual = VaultFS.sha256Bytes(plain);
} else {
actual = await VaultFS.sha256(dest);
}
} catch (err) {
// 走到这里基本就是 GCM tag 不符:密文被动过
bad.push(it.rel + ' 解密失败,密文或认证标签被改动');
continue;
}
if (actual !== it.digest) {
bad.push(it.rel + ' 摘要不一致');
}
}
return {
checked: checked,
matched: checked - bad.length,
mismatched: bad,
passed: bad.length === 0
};
}
三类失败必须分开报,因为它们的处置完全不同:
| 失败类型 | 判定依据 | 说明什么 | 该怎么办 |
|---|---|---|---|
| 对象缺失 | accessSync 为 false | 对象被人工删了 / 目标盘换了 | 从源目录重新 put 一次即可 |
| 解密失败 | CipherBox.open 抛错 | 密文或 tag 被改,密钥不对 | 立刻停止信任该仓库,全量重备 |
| 摘要不一致 | 明文摘要 ≠ 清单 digest | 存的是别的内容,或摘要算错 | 检查是否对密文算了摘要 |
图 1 底部那句「最近快照校验通过:14206 个文件,校验和一致」,如果真接上这段 verify,它就应该由 passed === true && checked === 14206 推出来,而不是写死。抽样策略也要写进 UI:sample = 200 表示「每个清单抽 200 个对象」,用户看到「已校验 200 / 14206」才不会误以为全量校验过。
BackupRunner 负责把三段能力缝起来,注意它只做编排,不碰 UI:
// entry/src/main/ets/common/BackupRunner.ets
export class BackupRunner {
// roots 顺序决定清单顺序,保证同一份源数据多次备份的清单可比对
static async run(planId: string, roots: string[], vault: ObjectVault,
key: Uint8Array | null, seq: number): Promise<Manifest> {
const items: ManifestItem[] = [];
let storedBytes: number = 0;
let savedBytes: number = 0;
for (let i = 0; i < roots.length; i++) {
const entries: VaultEntry[] = VaultFS.walk(roots[i]);
for (let j = 0; j < entries.length; j++) {
const e: VaultEntry = entries[j];
const r: PutResult = await vault.put(e, key);
if (r.deduped) {
savedBytes += e.size;
} else {
storedBytes += r.storedBytes;
}
items.push({
rel: e.rel,
digest: r.digest,
size: e.size,
mtimeMs: e.mtimeMs,
sealed: key !== null
});
}
}
const manifest: Manifest = {
seq: seq,
planId: planId,
createdAt: new Date().toISOString(),
items: items,
storedBytes: storedBytes,
savedBytes: savedBytes
};
vault.commit(manifest); // manifests/0001.json,原子写在内部完成
return manifest;
}
}
界面侧只需要把「假进度」换成真调用,其余交互不变:
// entry/src/main/ets/pages/Index.ets(接入能力层后的版本)
private async doBackup(): Promise<void> {
if (this.progress >= 0) {
return;
}
this.progress = 0;
try {
const ctx: common.UIAbilityContext =
this.getUIContext().getHostContext() as common.UIAbilityContext;
const vault: ObjectVault = new ObjectVault(ctx.filesDir);
vault.init();
const key: Uint8Array | null = this.activePlan().encrypt ? CipherBox.randomKey() : null;
const workRoot: string = ctx.filesDir + '/workspace';
const m: Manifest = await BackupRunner.run(
this.activePlan().id, [workRoot], vault, key, this.seq);
this.seq += 1;
this.progress = 100;
this.flash('写入 ' + m.items.length.toString() + ' 个对象,去重省下 '
+ (m.savedBytes / 1048576).toFixed(1) + ' MB');
} catch (err) {
this.progress = -1;
this.flash('备份失败:' + (err as BusinessError).message);
}
}
关于进度条的老实交代:上面这版进度只有 0 和 100 两个值,因为总字节数要遍历完才知道。想做出图 3 那种 32% 的真实进度,只有两条路——先遍历一遍算总量(多一趟 I/O,但进度准确),或者按「已处理文件数 / 预估文件数」估算(少一趟,但进度会跳)。工程里选择了后者做视觉、前者做日志:日志里记的是真实字节比例,界面上给的是平滑估计。这种「界面撒谎、日志说真话」的分工,在桌面工具里比反过来安全得多。
十一、踩坑清单
按遇到顺序排,每条都能在代码或截图里找到痕迹:
@State数组元素改属性不刷新(第四章)。勾选框变了、行底色不变。修法:整体替换数组 + 逐字段重建对象(ArkTS 禁对象展开)。ForEach键值不含可变字段 → 该行不重建。原代码把included拼进 key 是正确的,别「优化」掉。statSync跟随符号链接,isSymbolicLink()恒为 false,跳过链接必须用lstatSync。Stat.mtime单位是秒,直接和Date.now()比会差 1000 倍。(x / 1024).toFixed(0)输出'0',256 GB 显示成「0 / 0 TB」;容量必须按量级换挡(humanSize)。- GCM 的
doFinalSync返回「密文 ‖ tag」,不切出后 16 字节,解密侧就不可能有authTag。 - 先加密后摘要会导致去重完全失效(IV 每次不同),摘要必须永远对明文算。
- 把仓库放
cacheDir:系统清理缓存后历史快照凭空消失,且不报错。 mkdirSync不加存在判断:第二次备份直接抛EEXIST,整个任务失败。- 一次探活失败就标红目标仓:移动硬盘拔插抖动被当成离线,用户学会无视红色。连续两次失败才判离线。
aboutToAppear里调getUIContext():上下文未就绪,拿到的可能是空。首次点击时懒初始化。fileIo.createWatcher忘了stop():页面销毁后监听仍在,事件回调操作已释放的@State,轻则无效重则崩溃。
十二、构建与复现
工程是标准 DevEco Stage 工程,鸿蒙PC 上打开 Vaultway_ohos 目录即可(不是 ohos 子目录——这一版没有 Flutter 壳,是纯 ArkTS 工程,别混了)。
Vaultway_ohos/
├── AppScope/app.json5 bundleName: com.vaultway.vault
├── build-profile.json5 SDK 26.0.0 + useNormalizedOHMUrl
├── hvigorfile.ts
├── oh-package.json5
└── entry/
├── src/main/module.json5 deviceTypes: ['2in1'],挂 entity.system.home
└── src/main/ets/
├── entryability/EntryAbility.ets 窗口尺寸 → AppStorage
├── pages/Index.ets 三栏 + 条件渲染 + 勾选修复
├── common/Models.ets 6 个 interface + VaultStore
├── common/Theme.ets 调色板 / 字号 / humanSize
├── common/VaultFS.ets ★ 新增:遍历 / 摘要 / 文本读写
├── common/ObjectVault.ets ★ 新增:内容寻址 + 清单 + 校验
├── common/CipherBox.ets ★ 新增:AES-256-GCM 封装
├── common/VolumeProbe.ets ★ 新增:卷探活 + 容量闸
├── common/VaultPrefs.ets ★ 新增:偏好持久化
└── common/BackupRunner.ets ★ 新增:编排
权限清单:零声明。 上面所有能力(沙箱遍历、hash、cryptoFramework、statfs、preferences、asset)都不需要 requestPermissions;唯一的「外部」能力是 DocumentViewPicker 选目录,它走的是系统授权 UI,也不需要在 module.json5 里申请。这一点很值得强调:桌面工具不必靠权限堆功能。
编译与安装(DevEco 内置终端,或把 DevEco 的 tools/node、jbr/bin 加进 PATH 后用 CLI):
cd C:\Users\people\Desktop\鸿蒙ugc100r\项目源码\Vaultway_ohos
hvigorw --mode module -p product=default -p module=entry@default assembleHap --no-daemon
# 产物:entry/build/default/outputs/default/entry-default-signed.hap
hdc list targets
hdc install -r entry\build\default\outputs\default\entry-default-signed.hap
首次运行的前置动作:在 filesDir/workspace 下放几个测试文件(可用应用内一个隐藏按钮写 200 个随机文本,或先跑一次 VaultFS.writeText),否则 walk 返回空数组,BackupRunner 会立刻返回「0 个对象」的清单——这不是 bug,是没有源数据。工程里把这一点做成了空态提示:「工作区为空,请先放入待备份文件」。
复现清单(按顺序做,每一步都能单独验证):
- 只放
VaultFS.ets,在页面按钮里console.info(VaultFS.walk(ctx.filesDir).length.toString()),确认遍历数对得上文件管理器。 - 加
hash.hash,打印一个 1 KB 文本的摘要,用在线工具比对同一文件的 SHA-256,确认大写/小写口径。 - 加
ObjectVault.put(key = null),备份两次,第二次的deduped应全为true、storedBytes为 0。 - 加
CipherBox,备份一份文本,cat出来的应是二进制;改一个字节再open,必须抛错。 - 加
VolumeProbe,把目标路径改成一个不存在的目录,连点两次「立即备份」,观察状态从「已连接」变「离线」是在第二次而不是第一次。 - 加
verify,故意删掉objects/下一个对象,重新校验,报告里应出现「对象缺失」而不是「通过」。
源码基线放在 项目源码/Vaultway_ohos,能力层的后续补丁我会继续归档到 AtomGit(统一用 AtomGit,不用别的托管品牌),方便读者对着 commit 逐个复现。
十三、小结:三层可以分别演进
回头看这个工程,真正有价值的不是那三栏界面,而是三层之间的接缝被写清楚了:
- 文件层(第五章、第六章)只关心「字节进、摘要出」。它不知道界面长什么样,也不知道目标盘是 USB 还是 NAS,所以它可以被单测覆盖——给它一个临时目录,
walk + put + verify三件套就是完整闭环。 - 外设层(第八章)只关心「这个路径现在能不能写、还剩多少空间」。它不产生任何业务状态,只输出
ProbeResult,因此可以被替换:以后接 SMB 或对象存储,换掉VolumeProbe的实现即可,界面一行不用改。 - 系统层(第九章)只关心「设备是什么形态、窗口多宽、上次选了什么」。它是唯一需要
Context的一层,也是最容易被写成「到处getContext」的一层——把preferences、deviceInfo、window收进小类里,页面只读结论,代码才不会随着页面数增长而腐烂。
至于 ArkUI 跨平台框架,它的价值恰好在这三层的最上面:同一份 Row/Column/ForEach 声明在鸿蒙PC 的 2in1 窗口里成立,换个设备形态只要换 winWidthVp 的阈值,而不是换一套布局代码。但请记住这条边界——ArkUI 跨平台框架负责界面如何呈现,不负责字节如何落盘。statfs 不会因为框架跨平台就变成跨平台,GCM 的 tag 也不会因为声明式写法就自动帮你校验出来。
所以「文件、外设与系统能力调用」这个题目,真正的考点不是会不会调用 API,而是你有没有把「调用成功了」变成「用户可以自己验证的文字」。界面上每一个绿色圆点,背后都必须有一次真实的 accessSync、一次真实的摘要重算、一次真实的 tag 校验。做不到这三点,写「已加密」「校验通过」就是在骗人;做到了,哪怕界面只有 32% 的进度条,用户也会愿意把 42.7 GB 的归档量交给它。
三张鸿蒙PC 真机截图证明它长什么样,四段能力层代码证明它该怎么落地。剩下的,就是把这些代码真正打进 HAP。
更多推荐



所有评论(0)