HarmonyOS 应用开发之应用备份恢复与数据安全详解

应用备份恢复与数据安全

一、引言

用户换机、重装系统后，最痛的不是重新下载应用，而是"看过一半的收藏和设置全没了"。HarmonyOS 为应用提供了系统级备份恢复能力：通过声明BackupExtensionAbility与backup_config.json，应用的数据目录可在云备份、换机迁移等场景下被系统安全地打包、传输与还原。multi-short-video 的四个产品模块都实现了备份能力，本文以真实代码为样本，拆解备份扩展能力的声明、实现与数据安全设计，并给出"哪些数据该备份、哪些绝不能备份"的边界判定方法。

二、备份机制与配置声明

HarmonyOS 备份恢复由系统服务驱动：系统在备份时机（换机、云备份、恢复出厂等）唤醒应用注册的备份扩展能力，应用回调onBackup将数据交给系统归档；恢复时回调onRestore将数据重新写入。应用侧只需做两件事：声明扩展能力、提供备份配置。系统负责数据打包、加密传输、跨设备搬运这些重活，应用本身不需要感知备份的完整链路。

先看配置声明。本工程每个产品模块都在module.json5中注册了一个 type 为 backup 的 ExtensionAbility，并关联备份配置文件：

// products/default/src/main/module.json5（pc/tv/wearable 模块结构相同） "extensionAbilities": [ { "name": "MultiShortVideoDefaultBackupAbility", "srcEntry": "./ets/defaultbackupability/MultiShortVideoDefaultBackupAbility.ets", "type": "backup", "exported": false, "metadata": [ { "name": "ohos.extension.backup", "resource": "$profile:backup_config" } ] } ]

关键点：type必须是backup；exported为 false，因为备份扩展只被系统服务调用，不应暴露给其他应用拉起；metadata中name固定为ohos.extension.backup，resource指向resources/base/profile/backup_config.json。该配置文件内容极简：

// products/default/src/main/resources/base/profile/backup_config.json { "allowToBackupRestore": true }

allowToBackupRestore是总开关，置 true 表示应用允许被系统备份与恢复。该文件还支持更细粒度的控制字段：fullBackupOnly限定仅参与整机备份；excludes排除指定目录；includes指定参与备份的目录。字段优先级与继承规则在不同版本略有差异，官方文档是最终依据，实践时建议"先全量、后收紧"：第一版只开总开关跑通链路，再逐步用 excludes 把缓存与日志排除掉。

三、备份扩展能力的实现

四个产品模块的备份 Ability 实现完全一致，以 default 模块为例：

// products/default/src/main/ets/defaultbackupability/MultiShortVideoDefaultBackupAbility.ets import { hilog } from '@kit.PerformanceAnalysisKit'; import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit'; const DOMAIN = 0x0000; export default class DefaultBackupAbility extends BackupExtensionAbility { async onBackup() { hilog.info(DOMAIN, 'testTag', 'onBackup ok'); await Promise.resolve(); } async onRestore(bundleVersion: BundleVersion) { hilog.info(DOMAIN, 'testTag', 'onRestore ok %{public}s', JSON.stringify(bundleVersion)); await Promise.resolve(); } }

类继承自@kit.CoreFileKit的BackupExtensionAbility，实现两个钩子：

• onBackup()：系统准备备份应用数据时回调。若应用有需要预处理的逻辑（如把内存态状态刷入 Preferences、关闭正在写的文件、停止后台任务），在此执行；无特殊逻辑时保持空实现即可，系统会自动归档沙箱内数据。
• onRestore(bundleVersion)：恢复完成后回调，参数携带备份来源的版本信息。可据此做数据迁移：例如备份来自 1.0.0，当前是 1.1.0，则在此处执行一次版本化迁移，保证老数据结构能平滑升级。日志中%{public}s为隐私占位符，%{public}s会脱敏打印、%{s}明文打印，这里使用%{public}s避免把 bundle 内部细节泄露到系统日志。

其余三个产品的实现（MultiShortVideoPcBackupAbility.ets、MultiShortVideoTvBackupAbility.ets、MultiShortVideoWearableBackupAbility.ets）除类名外完全同构，位于各自产品的pcbackupability、tvbackupability、wearablebackupability目录下，体现了"四个入口、同一备份策略"的设计——备份逻辑与 UI 无关，四端复用同一套能力实现，只是各挂一个入口类。

使用备份扩展还要注意三个生命周期约束。其一，备份扩展是后台扩展，没有 UI 上下文，不能在 onBackup/onRestore 中弹窗或跳页面，任何需要用户确认的动作都应提前在前台完成。其二，回调有超时约束，系统不会无限等待，onBackup/onRestore 中的耗时操作（如网络上传、大规模文件整理）应在回调外异步完成，回调内只做必要的落盘与状态收尾，本工程的空实现加await Promise.resolve()正是这种"轻回调"的示范。其三，备份期间应用可能被系统冻结，不要依赖备份回调内的定时器或监听器，回调应当是"一次性、幂等"的——即使被调用两次，也不能产生重复数据或脏数据。

四、备份范围与数据安全设计

备份并非"全盘拷贝"，系统只会归档应用沙箱内允许访问的目录（data/app/el2/100/base/包名 下的 files、preferences 等），数据库、缓存目录等默认可被备份。开发者应主动划定备份边界：

数据

是否应备份

说明

用户设置（Preferences 首选项）	是	播放位置、页签索引、主题偏好
收藏/点赞本地缓存	是	换机后用户体验连续
视频缓存文件	否	体积大、可从网络重建
账号 Token/密钥	否	高敏数据，应走账号同步而非本地备份
日志、临时文件	否	无价值且增大备份体积

对不应备份的目录，可在backup_config.json中用excludes排除。数据安全上要遵循三条红线：

• 权限最小化：本工程仅声明一个受限权限ohos.permission.DETECT_GESTURE（见 default 模块 module.json5 的 requestPermissions），备份链路本身不需要任何额外权限——这也是判断"备份配置是否合规"的简单标准：备份不应该成为申请权限的理由。
• 敏感数据不落盘：账号凭据应存于系统账密管理能力（@kit.BasicServicesKit的 Asset Store），而不是 Preferences——后者会被备份机制打包，扩大泄露面。Asset Store 中的数据独立加密存储，系统备份时也不会随普通数据目录搬运。
• 日志脱敏：onRestore 打印版本信息使用%{public}s而非%{s}，避免把 bundle 内部数据带入系统日志；业务侧打印用户相关数据时也应统一脱敏。

备份包的加密由系统负责，开发者不需要也不应该自行加密整个数据目录——过度自研加密反而会破坏备份的可恢复性。正确的做法是"分级安全"：普通偏好数据裸存、可备份；敏感凭据进 Asset Store、不备份。

五、卸载重装与账号数据隔离

备份恢复与"卸载重装"是两条不同的数据通路：

• 备份恢复：换机/云备份场景，系统级搬运整个数据目录，应用无感，用户无需登录即可找回本地数据。
• 卸载重装：默认清空沙箱数据；本工程module.json5中deliveryWithInstall: false表示应用随设备预置或单独安装，installationFree: false表示不支持免安装运行——免安装场景下沙箱数据不保留，必须依赖备份或账号云端同步。

因此推荐的数据架构是"三层分离"：设备本地数据（播放位置、界面偏好）走备份恢复；用户资产数据（收藏、作品）走账号同步到服务端；不可再生数据（视频缓存）不备份也不入账号。对多设备应用而言，同一账号在手机与平板的观看进度理论上应通过云端账号体系对齐，本地备份只负责兜底单设备的连续性——本工程用内存 mock 数据演示交互，工程化落地时应把WorksDataModel、CommentDataModel这类模型与账号服务绑定，而不是塞进本地备份包。原因有二：一是账号资产跨端共享天然应由云端承载，本地备份无法解决"另一台设备"的同步；二是备份包一旦包含用户内容，就升级为个人信息处理场景，隐私合规成本陡增。

六、备份恢复的验证与排障

备份能力接入后必须实测，不能只看配置。验证路径分两步：

• 安装后验证注册：安装应用后查看系统日志或使用hdc shell bm dump --extension-type backup确认备份扩展已被系统识别，若看不到对应 Ability，说明 module.json5 的 metadata 声明或 backup_config.json 路径有误。
• 触发真实备份/恢复：通过系统"云备份"或换机助手触发一次备份，卸载重装（或在新设备安装）后执行恢复，验证onBackup与onRestore日志按预期打印、Preferences 中的播放位置与页签索引确实还原。恢复后首次启动建议在onRestore中打印bundleVersion，人工核对来源版本与迁移分支是否命中。

排障时最常遇到的三类问题：

现象

可能原因

处置

备份扩展未被调用	metadata 的 resource 指向错误	检查$profile:backup_config与文件是否同名
恢复后数据缺失	数据位于 excludes 排除目录	核对 backup_config 的排除规则
恢复后崩溃	备份版本数据结构与当前版本不兼容	在 onRestore 中按 BundleVersion 做迁移

这三个问题的共同点是把"备份"当成一次性配置，缺少版本视角：数据结构一旦演进，就必须同步维护恢复侧的迁移逻辑，否则备份反而成为升级的隐患。

七、总结与最佳实践

备份恢复是把"换机零丢失"变成产品卖点的系统能力，成本极低但收益明显。本工程四个产品模块通过"一个 backup 扩展 + 一个配置开关"即完成了能力接入，值得所有应用参考。最佳实践归纳为：

• 显式声明：在 module.json5 注册type: backup扩展并在 metadata 中关联$profile:backup_config，allowToBackupRestore置 true。
• 默认空实现：无预处理逻辑时 onBackup/onRestore 保持空实现，系统自动完成归档；不要在里面做耗时业务，备份回调有超时约束。
• 版本化迁移：利用 onRestore 的BundleVersion参数做数据结构迁移，兼容老版本备份包；升级数据模型时同步维护迁移逻辑。
• 划清备份边界：用 excludes 排除缓存与日志；Token 等敏感数据走 Asset/账号体系，绝不进入备份包。
• 卸载策略区分：明确"备份恢复"与"卸载重装"两条通路，账号数据与本地数据严格隔离，避免把云端资产误入本地备份引发隐私风险。

备份能力接入很简单，但"备份什么、不备份什么"才是真正的设计题。把数据分级模型想清楚，备份恢复就能成为多设备体验的加分项，而不是隐私合规的隐患。