鸿蒙中应用数据备份与恢复-BackupExtensionAbility

本文同步发表于我的，微信搜索程语新视界即可关注，每个工作日都有文章更新BackupExtensionAbility 是 HarmonyOS Stage 模型中的派生类，专门用于处理应用数据的备份与恢复。可通过配置文件定制备份恢复行为，包括是否允许备份、备份哪些文件等。

梦想不只是梦与想

537人浏览 · 2026-02-06 06:45:00

梦想不只是梦与想 · 2026-02-06 06:45:00 发布

本文同步发表于我的微信公众号，微信搜索程语新视界即可关注，每个工作日都有文章更新

BackupExtensionAbility 是 HarmonyOS Stage 模型中 ExtensionAbility 的派生类，专门用于处理应用数据的备份与恢复。可通过配置文件定制备份恢复行为，包括是否允许备份、备份哪些文件等。

主要特点：

基于 Stage 模型扩展组件
支持通过配置文件灵活定义备份内容
提供多个生命周期回调接口，支持自定义处理逻辑

数据备份

系统触发时机
- 由系统主动发起，通常在以下场景自动启动：
- 设备空闲状态（如夜间充电时）
- 系统升级/迁移前（如 OTA 升级）
- 应用卸载后重装（恢复用户数据）
- 开发者无法主动触发，仅能通过实现 BackupExtensionAbility接入备份框架。
执行条件
- 需在 backup_config.json中配置 "allowToBackupRestore": true。
- 备份过程在后台无界面运行，任务结束后自动退出。

二、核心接口

接口名	描述
`onBackup(): void`	数据备份准备阶段回调（迁移备份数据前）
`onBackupEx(backupInfo: string): string \| Promise<string>`	支持传递备份信息并返回结果
`onRestore(bundleVersion: BundleVersion): void`	数据恢复阶段回调（备份数据迁移完成后）
`onRestoreEx(bundleVersion: BundleVersion, restoreInfo: string): string \| Promise<string>`	支持传递恢复信息并返回结果
`onRelease(scenario: number): Promise<void>`	备份或恢复完成时的回调（API 20+ 支持）

推荐使用 onBackupEx 和 onRestoreEx，支持更灵活的信息传递与结果返回。

三、限制

路径长度：所有待备份文件及目录路径不得超过 4095 字节。
权限要求：
- 备份目录：需拥有读取该目录及其子目录的权限（DAC 中的 r）
- 备份文件：需拥有搜索该文件所有祖父级目录的权限（DAC 中的 x）
路径格式：不支持相对路径（../）和软链接。
el3/el4 路径：不支持备份 el3、el4 路径。

四、开发步骤

步骤1：注册 BackupExtensionAbility

在 module.json5 文件中注册 extensionAbilities：

{
  "extensionAbilities": [
    {
      "description": "$string:ServiceExtAbility",
      "icon": "$media:icon",
      "name": "BackupExtensionAbility",
      "type": "backup",
      "exported": false,
      "metadata": [
        {
          "name": "ohos.extension.backup",
          "resource": "$profile:backup_config"
        }
      ],
      "srcEntry": "./ets/BackupExtension/BackupExtension.ets"
    }
  ]
}

步骤2：创建元数据资源配置文件

在 resources/base/profile/ 目录下创建 backup_config.json：

{
  "allowToBackupRestore": true,
  
  // 包含路径：支持通配符和模式匹配
  "includes": [
    // 用户数据
    "/data/storage/el2/base/files/user_data/",
    "/data/storage/el2/base/files/settings/",
    
    // 数据库文件
    "/data/storage/el2/database/main.db",
    "/data/storage/el2/database/cache.db",
    
    // 配置文件
    "/data/storage/el2/base/preferences/",
    
    // 通配符模式
    "/data/storage/el2/base/files/logs/*.log",
    "/data/storage/el2/base/files/cache/*_temp.*",
    
    // 多级目录匹配
    "/data/storage/el2/base/files/**/config.json",
    
    // 排除某些子目录的文件
    "/data/storage/el2/base/files/images/!thumbnails/"
  ],
  
  // 排除路径：优先级高于includes
  "excludes": [
    // 临时文件
    "/data/storage/el2/base/files/user_data/temp/",
    
    // 缓存文件（可重新生成）
    "/data/storage/el2/base/files/cache/",
    
    // 大文件或不重要文件
    "/data/storage/el2/base/files/logs/debug.log",
    "/data/storage/el2/base/files/images/*.tmp",
    
    // 隐私敏感数据（即使加密也不备份）
    "/data/storage/el2/base/files/private/token.key"
  ],
  
  // 恢复模式配置
  "fullBackupOnly": false,
  
  // 依赖应用配置（谨慎使用）
  "restoreDeps": "com.example.dependent_app",
  
  // 扩展信息
  "extraInfo": {
    "backupVersion": "2.0",
    "encryptionEnabled": true,
    "compressionLevel": "high",
    "maxBackupSize": "1GB",
    "excludePatterns": [
      "*.tmp",
      "cache/*",
      "temp/*"
    ],
    "metadata": {
      "appCategory": "productivity",
      "dataPriority": "high",
      "autoBackupInterval": "weekly"
    }
  },
  
  // 版本兼容性配置
  "compatibility": {
    "minAppVersion": "2.0.0",
    "maxAppVersion": "4.0.0",
    "supportedAPIVersions": [8, 9, 10]
  },
  
  // 备份策略
  "backupStrategy": {
    "incrementalBackup": true,
    "encryptBackup": true,
    "compressBackup": true,
    "verifyBackupIntegrity": true,
    "backupSchedule": {
      "autoBackup": true,
      "frequency": "weekly",
      "requireCharging": true,
      "requireWiFi": true
    }
  }
}

步骤3：实现 BackupExtensionAbility 子类

创建 BackupExtension.ets 文件，继承并重写相关方法：

import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = `FileBackupExtensionAbility`;

export default class BackupExtension extends BackupExtensionAbility {
  async onBackup() {
    hilog.info(0x0000, TAG, `onBackup ok`);
  }

  async onRestore(bundleVersion: BundleVersion) {
    hilog.info(0x0000, TAG, `onRestore end`);
  }
}

五、进阶：使用 onRelease 清理临时文件（API 20+）

如果需要在备份或恢复完成后执行清理操作，可重写 onRelease 方法：

import { BackupExtensionAbility } from '@kit.CoreFileKit';
import { fileIo } from '@kit.CoreFileKit';

const SCENARIO_BACKUP = 1;
const SCENARIO_RESTORE = 2;
let filePath = '/data/storage/el2/base/.temp/';

class BackupExt extends BackupExtensionAbility {
  async onRelease(scenario: number): Promise<void> {
    try {
      if (scenario === SCENARIO_BACKUP || scenario === SCENARIO_RESTORE) {
        console.info(`onRelease begin`);
        await fileIo.rmdir(filePath);
        console.info(`onRelease end, rmdir succeed`);
      }
    } catch (error) {
      console.error(`onRelease failed with error. Code: ${error.code}, message: ${error.message}`);
    }
  }
}

注意：onRelease 有 5 秒超时机制，超时后应用进程将被强制退出。

六、元数据配置文件

属性	类型	必填	说明
`allowToBackupRestore`	布尔值	是	是否允许备份恢复，默认 `false`
`includes`	字符串数组	否	需要备份的文件和目录列表
`excludes`	字符串数组	否	无需备份的例外项（需在 includes 子集中）
`fullBackupOnly`	布尔值	否	是否使用临时目录恢复，默认 `false`
`restoreDeps`	字符串	否	依赖应用名称（不推荐使用）
`extraInfo`	JSON 字符串	否	额外信息传递

关于 `fullBackupOnly`：

false：恢复数据以 / 为根目录解压，覆盖同名文件。
true：数据解压到临时目录，需在 onRestore/onRestoreEx 中手动处理恢复逻辑。

includes 支持路径：

{
  "includes": [
    // EL1 安全级别路径（较低安全级别）
    "data/storage/el1/database/",           // EL1数据库目录
    "data/storage/el1/base/files/",         // EL1基础文件目录
    "data/storage/el1/base/preferences/",   // EL1偏好设置目录
    "data/storage/el1/base/haps/*/files/",  // 多hap包文件目录
    "data/storage/el1/base/haps/*/preferences/", // 多hap包偏好设置
    
    // EL2 安全级别路径（标准应用数据）
    "data/storage/el2/database/",           // 主数据库目录
    "data/storage/el2/base/files/",         // 主文件存储目录
    "data/storage/el2/base/preferences/",   // 主偏好设置目录
    "data/storage/el2/base/haps/*/files/",  // 多hap包文件目录
    "data/storage/el2/base/haps/*/preferences/", // 多hap包偏好设置
    "data/storage/el2/distributedfiles/",   // 分布式文件目录
    
    // EL5 安全级别路径（高安全级别）
    "data/storage/el5/database/",           // 高安全数据库
    "data/storage/el5/base/files/",         // 高安全文件
    "data/storage/el5/base/preferences/",   // 高安全偏好设置
    "data/storage/el5/base/haps/*/files/",  // 高安全多hap包文件
    "data/storage/el5/base/haps/*/preferences/" // 高安全多hap包偏好设置
  ]
}

七、示例说明

假设应用备份路径为：
/data/storage/el2/base/files/A/

若 fullBackupOnly = false：
恢复时数据直接解压到原路径。
若 fullBackupOnly = true：
数据解压到临时目录：
临时路径/restore/data/storage/el2/base/files/A/
需在 onRestoreEx 中手动迁移到目标路径。