diff --git a/zh-cn/application-dev/file-management/Readme-CN.md b/zh-cn/application-dev/file-management/Readme-CN.md
index ccf665fea3e8c62f374d221a021d0ddb076ee854..8f09386ab05ecda526746e59e139a056c1fcb14a 100644
--- a/zh-cn/application-dev/file-management/Readme-CN.md
+++ b/zh-cn/application-dev/file-management/Readme-CN.md
@@ -10,6 +10,10 @@
- [应用及文件系统空间统计](app-fs-space-statistics.md)
- [向应用沙箱推送文件](send-file-to-app-sandbox.md)
- [应用文件分享](share-app-file.md)
+ - 应用数据备份恢复
+ - [应用数据备份恢复概述](app-file-backup-overview.md)
+ - [应用接入数据备份恢复](app-file-backup-extension.md)
+ - [应用触发数据备份/恢复(仅对系统应用开放)](app-file-backup.md)
- 用户文件
- [用户文件概述](user-file-overview.md)
- 选择与保存用户文件(FilePicker)
diff --git a/zh-cn/application-dev/file-management/app-file-backup-extension.md b/zh-cn/application-dev/file-management/app-file-backup-extension.md
new file mode 100644
index 0000000000000000000000000000000000000000..c95985a0e15a42e767eab45ea488f1e3c691a930
--- /dev/null
+++ b/zh-cn/application-dev/file-management/app-file-backup-extension.md
@@ -0,0 +1,80 @@
+# 应用接入数据备份恢复
+
+应用接入数据备份恢复需要通过BackupExtensionAbility实现。
+
+BackupExtensionAbility,是[Stage模型](../../application-dev/application-models/stage-model-development-overview.md)中扩展组件[ExtensionAbility](../application-models/extensionability-overview.md)的派生类。开发者可以通过修改配置文件定制备份恢复框架的行为,包括是否允许备份恢复,备份哪些文件等。
+
+## 约束与限制
+- 当备份恢复时,所有待备份文件及目录的路径不得超过4095字节,否则将导致未定义行为。
+- 当备份目录时,应用进程必须拥有读取该目录及其所有子目录的权限(DAC中的`r`),否则将导致备份失败。
+- 当备份文件时,应用进程必须拥有搜索该文件所有祖父级目录的权限(DAC中的`x`),否则将导致备份失败。
+
+## 开发步骤
+
+1. 在应用配置文件`module.json5`中注册`extensionAbilities`相关配置
+
+ 新增`"extensionAbilities"`字段,其中注册类型`"type"`设置为`"backup"`,元数据信息["metadata"](../../application-dev/reference/apis/js-apis-bundleManager-metadata.md)新增一个`"name"`为`"ohos. extension. backup"`的条目。
+
+ BackupExtensionAbility配置文件示例:
+
+ ```json
+ {
+ "extensionAbilities": [
+ {
+ "description": "$string:ServiceExtAbility",
+ "icon": "$media:icon",
+ "name": "BackupExtensionAbility",
+ "type": "backup",
+ "visible": true,
+ "metadata": [
+ {
+ "name": "ohos.extension.backup",
+ "resource": "$profile:backup_config"
+ }
+ ],
+ "srcEntrance": "",
+ }
+ ]
+ }
+ ```
+
+2. 新增元数据资源配置文件
+
+ 在元数据资源配置文件中,定义备份恢复时需要传输的文件。元数据资源配置文件名称需要与`module.json5`中 `"metadata.resource"`名称保持一致,其保存位置在Profile文件夹下。
+
+ 元数据资源配置文件示例:
+
+ ```json
+ {
+ "allowToBackupRestore": true,
+ "includes": [
+ "/data/storage/el2/base/files/users/*/*.json"
+ ],
+ "excludes": [
+ "/data/storage/el2/base/files/users/*/hidden.json"
+ ],
+ }
+ ```
+
+### 元数据资源配置文件说明
+
+| 属性名称 | 数据类型 | 必填 | 含义 |
+| -------------------- | ---------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| allowToBackupRestore | 布尔值 | 是 | 是否允许备份恢复,默认为false |
+| includes | 字符串数组 | 否 | 应用沙箱中需要备份的文件和目录。
数组中的每一项均为模式串,可包含SHELL风格通配符(`*`,`?`,`[`)。
当模式串以非/开始时,表示一个相对于根路径的相对路径。
当`includes`已配置时,备份恢复框架会采用开发者配置的模式串,否则将会采用下述代码段内容作为默认值。 |
+| excludes | 字符串数组 | 否 | `includes`中无需备份的例外项。格式同`includes`。
当`excludes`已配置时,备份恢复框架会采用开发者配置的模式串,否则将会采用**空数组**作为默认值。 |
+
+**includes默认值:**
+
+```json
+{
+ "includes": [
+ "data/storage/el2/database/",
+ "data/storage/el2/base/files/",
+ "data/storage/el2/base/preferences/",
+ "data/storage/el2/base/haps/*/database/",
+ "data/storage/el2/base/haps/*/base/files/",
+ "data/storage/el2/base/haps/*/base/preferences/",
+ ]
+}
+```
diff --git a/zh-cn/application-dev/file-management/app-file-backup-overview.md b/zh-cn/application-dev/file-management/app-file-backup-overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..9768041c3bd7e9240cabdafd71c40bc4b7857591
--- /dev/null
+++ b/zh-cn/application-dev/file-management/app-file-backup-overview.md
@@ -0,0 +1,15 @@
+# 应用数据备份恢复概述
+
+用户在使用应用的过程中,会产生对应的应用数据,如配置信息、业务数据等。为了保证用户数据不会因为应用升级、迁移等操作而丢失,应用需要接入数据备份恢复。
+
+在开发前,需要先了解ExtensionAbility组件,建议参考[ExtensionAbility组件概述](../application-models/extensionability-overview.md)。
+
+BackupExtensionAbility是Stage模型中扩展组件ExtensionAbility的派生类,用于提供备份及恢复应用数据的能力。它是一种无界面的扩展组件,随着备份恢复任务的启动而运行,随着备份恢复任务的结束而退出。
+
+不同应用所需实现的场景不同,分为:
+
+- [应用接入数据备份恢复](app-file-backup-extension.md):应用均可以接入数据备份恢复,在接入后,应用可通过修改配置文件定制备份恢复框架的行为,包括是否允许备份恢复、备份哪些数据。
+
+ 应用本身无法触发数据的备份和恢复,仅能进行备份恢复的配置。
+
+- [应用触发数据备份恢复(仅对系统应用开放)](app-file-backup.md):仅系统应用可以触发数据备份恢复,触发后备份恢复框架会确认各个应用是否接入了数据备份恢复。如果应用已接入,备份恢复框架将会根据应用的配置文件备份、恢复数据。
\ No newline at end of file
diff --git a/zh-cn/application-dev/file-management/app-file-backup.md b/zh-cn/application-dev/file-management/app-file-backup.md
new file mode 100644
index 0000000000000000000000000000000000000000..55ee7590b542b12d2d7011f3084d4742f505ecf1
--- /dev/null
+++ b/zh-cn/application-dev/file-management/app-file-backup.md
@@ -0,0 +1,334 @@
+# 应用触发数据备份/恢复(仅对系统应用开放)
+
+备份恢复是为设备上应用数据、公共数据和系统服务提供的完整的数据备份和恢复解决方案。系统应用开发者可以根据需求,按下述指导开发应用,以触发备份/恢复数据。
+
+- [获取能力文件](#获取能力文件):获取当前系统用户内所有应用与备份恢复相关基础信息的能力文件。能力文件在应用备份/恢复数据时不可缺少。
+
+- [应用备份数据](#应用备份数据):根据能力文件提供的应用信息,选择需要备份的应用数据并进行备份。
+
+- [应用恢复数据](#应用恢复数据):根据能力文件提供的应用信息,选择需要恢复的应用数据并进行恢复。
+
+- [应用恢复数据时安装应用](#应用恢复数据时安装应用):应用恢复数据的拓展功能,当用于恢复数据的应用未安装时,建议使用此功能,设备将先安装应用再恢复数据。
+
+## 开发说明
+
+备份恢复API的使用指导请参见[API参考](../reference/apis/js-apis-file-backup.md)。
+
+在使用备份恢复接口之前,需要:
+
+1. [申请相关权限](../security/accesstoken-guidelines.md):`ohos.permission.BACKUP`
+
+2. 导入依赖模块:`@ohos.file.backup`
+
+ ```js
+ import backup from '@ohos.file.backup';
+ ```
+
+## 获取能力文件
+
+获取当前系统用户内所有应用与备份恢复相关基础信息的能力文件。能力文件在应用备份恢复数据时是不可缺少的,开发者可以根据需要获取能力文件。
+
+该文件包含设备类型、设备版本、应用的基础性信息,如应用名称、应用数据大小、应用版本信息、是否支持备份恢复、是否在恢复时安装应用。
+
+调用`backup.getLocalCapabilities()`获取能力文件。
+
+ ```js
+ import fs from '@ohos.file.fs';
+ try {
+ let fileData = await backup.getLocalCapabilities();
+ console.info('getLocalCapabilities success');
+ let fpath = await globalThis.context.filesDir + '/localCapabilities.json';
+ fs.copyFileSync(fileData.fd, fpath);
+ fs.closeSync(fileData.fd);
+ } catch (err) {
+ console.error('getLocalCapabilities failed with err: ' + err);
+ }
+ ```
+
+ **返回的能力文件内容示例:**
+ | 属性名称 | 数据类型 | 必填 | 含义 |
+ | -------------- | -------- | ---- | ---------------------- |
+ | bundleInfos | 数组 | 是 | 应用信息列表 |
+ | allToBackup | 布尔值 | 是 | 是否允许备份恢复 |
+ | extensionName | 字符串 | 是 | 应用的扩展名 |
+ | name | 字符串 | 是 | 应用的包名 |
+ | needToInstall | 布尔值 | 是 | 应用恢复时是否需要安装 |
+ | spaceOccupied | 数值 | 是 | 应用数据占用的空间大小 |
+ | versionCode | 数值 | 是 | 应用的版本号 |
+ | versionName | 字符串 | 是 | 应用的版本名称 |
+ | deviceType | 字符串 | 是 | 设备类型 |
+ | systemFullName | 字符串 | 是 | 设备版本 |
+
+ ```json
+ {
+ "bundleInfos" :[{
+ "allToBackup" : true,
+ "extensionName" : "BackupExtensionAbility",
+ "name" : "com.example.hiworld",
+ "needToInstall" : false,
+ "spaceOccupied" : 0,
+ "versionCode" : 1000000,
+ "versionName" : "1.0.0"
+ }],
+ "deviceType" : "default",
+ "systemFullName" : "OpenHarmony-4.0.0.0"
+ }
+ ```
+
+## 应用备份数据
+
+开发者可以根据能力文件提供的应用信息,选择需要备份的应用数据。
+
+备份过程中,备份恢复服务会将应用的数据打包成文件,打包后的文件会以打开的文件句柄形式,通过创建实例时所注册的回调[onFileReady](../reference/apis/js-apis-file-backup.md#onfileready)接口返回。
+
+开发者可以根据需要将文件内容保存到本地。
+
+**示例**
+
+ ```ts
+ import fs from '@ohos.file.fs';
+ // 创建SessionBackup类的实例用于备份数据
+ let session = new backup.SessionBackup({
+ onFileReady: async (err, file) => {
+ if (err) {
+ console.info('onFileReady err: ' + err);
+ }
+ try {
+ let bundlePath = await globalThis.context.filesDir + '/' + file.bundleName;
+ if (!fs.accessSync(bundlePath)) {
+ fs.mkdirSync(bundlePath);
+ }
+ fs.copyFileSync(file.fd, bundlePath + `/${file.uri}`);
+ fs.closeSync(file.fd);
+ console.info('onFileReady success');
+ } catch (e) {
+ console.error('onFileReady failed with err: ' + e);
+ }
+ },
+ onBundleBegin: (err, bundleName) => {
+ if (err) {
+ console.info('onBundleBegin err: ' + err);
+ } else {
+ console.info('onBundleBegin bundleName: ' + bundleName);
+ }
+ },
+ onBundleEnd: (err, bundleName) => {
+ if (err) {
+ console.info('onBundleEnd err: ' + err);
+ } else {
+ console.info('onBundleEnd bundleName: ' + bundleName);
+ }
+ },
+ onAllBundlesEnd: (err) => {
+ if (err) {
+ console.info('onAllBundlesEnd err: ' + err);
+ } else {
+ console.info('onAllBundlesEnd');
+ }
+ },
+ onBackupServiceDied: () => {
+ console.info('onBackupServiceDied');
+ },
+ });
+ // 此处可根据backup.getLocalCapabilities()提供的能力文件,选择需要备份的应用
+ // 也可直接根据应用包名称进行备份
+ const backupApps = [
+ "com.example.hiworld",
+ ]
+ await session.appendBundles(backupApps);
+ console.info('appendBundles success');
+ ```
+
+## 应用恢复数据
+
+开发者可以根据能力文件提供的应用信息,选择需要恢复的应用数据。
+
+恢复过程中,备份恢复服务会根据开发者调用[getFileHandle](../reference/apis/js-apis-file-backup.md#getfilehandle)的请求内容,将应用待恢复数据的文件句柄,通过创建实例时注册的回调[onFileReady](../reference/apis/js-apis-file-backup.md#onfileready)接口返回。可以根据返回的[uri](../reference/apis/js-apis-file-backup.md#filemeta)将应用对应的待恢复数据写入到文件句柄中。写入完成后开发者调用[publishFile](../reference/apis/js-apis-file-backup.md#publishfile)通知服务写入完成。
+
+待应用所有恢复数据准备就绪后,服务开始恢复应用数据。
+
+**示例**
+
+ ```ts
+ import fs from '@ohos.file.fs';
+ // 创建SessionRestore类的实例用于恢复数据
+ let session = new backup.SessionRestore({
+ onFileReady: async (err, file) => {
+ if (err) {
+ console.info('onFileReady err: ' + err);
+ }
+ try {
+ let bundlePath = await globalThis.context.filesDir + '/' + file.bundleName + '/'+ file.uri;
+ if (!fs.accessSync(bundlePath)) {
+ console.info('onFileReady bundlePath err : ' + bundlePath);
+ }
+ fs.copyFileSync(bundlePath, file.fd);
+ fs.closeSync(file.fd);
+ // 恢复数据传输完成后,会通知服务端文件准备就绪
+ await session.publishFile({
+ bundleName: file.bundleName,
+ uri: file.uri,
+ });
+ console.info('onFileReady success');
+ } catch (e) {
+ console.error('onFileReady failed with err: ' + e);
+ }
+ },
+ onBundleBegin: (err, bundleName) => {
+ if (err) {
+ console.info('onBundleBegin err: ' + err);
+ } else {
+ console.info('onBundleBegin bundleName: ' + bundleName);
+ }
+ },
+ onBundleEnd: (err, bundleName) => {
+ if (err) {
+ console.info('onBundleEnd err: ' + err);
+ } else {
+ console.info('onBundleEnd bundleName: ' + bundleName);
+ }
+ },
+ onAllBundlesEnd: (err) => {
+ if (err) {
+ console.info('onAllBundlesEnd err: ' + err);
+ } else {
+ console.info('onAllBundlesEnd');
+ }
+ },
+ onBackupServiceDied: () => {
+ console.info('onBackupServiceDied');
+ },
+ });
+ const backupApps = [
+ "com.example.hiworld",
+ ]
+ // 能力文件的获取方式可以根据开发者实际场景进行调整。此处仅为请求示例
+ // 开发者也可以根据能力文件内容的结构示例,自行构造能力文件内容
+ let fileData = await backup.getLocalCapabilities();
+ await session.appendBundles(fileData.fd, backupApps);
+ console.info('appendBundles success');
+ // 添加需要恢复的应用成功后,请根据需要恢复的应用名称,调用getFileHandle接口获取待恢复应用数文件的文件句柄
+ // 应用待恢复数据文件数请依据实际备份文件个数为准,此处仅为请求示例
+ await session.getFileHandle({
+ bundleName: restoreApps[0],
+ uri: "manage.json"
+ });
+ await session.getFileHandle({
+ bundleName: restoreApps[0],
+ uri: "1.tar"
+ });
+ console.info('getFileHandle success');
+ ```
+
+## 应用恢复数据时安装应用
+
+开发者在恢复数据时可以选择先安装应用后再进行恢复应用数据。与[应用恢复数据](#应用恢复数据)相比需要修改[能力文件](#获取能力文件)中`bundleInfos`数组内的`needToInstall`字段修改为`true`。
+
+> **说明:**
+> - [应用备份数据](#应用备份数据)不支持备份应用安装包,因此开发者需要自行准备应用安装包。
+> - 开发者在调用[getFileHandle](../reference/apis/js-apis-file-backup.md#getfilehandle)时,传入固定的`FileMeta.uri`=`"/data/storage/el2/restore/bundle.hap"`,用于获取应用安装包的文件句柄。与应用恢复数据时一致,应用安装包的文件句柄,通过创建实例时注册的回调onFileReady接口返回给开发者,返回的`File.uri`=`"/data/storage/el2/restore/bundle.hap"`。
+
+**示例**
+
+ ```ts
+ import fs from '@ohos.file.fs';
+ // 创建SessionRestore类的实例用于恢复数据
+ let session = new backup.SessionRestore({
+ onFileReady: async (err, file) => {
+ if (err) {
+ console.info('onFileReady err: ' + err);
+ }
+ try {
+ let bundlePath;
+ if( file.uri == "/data/storage/el2/restore/bundle.hap" )
+ {
+ // 此处开发者请根据实际场景安装包的存放位置进行调整
+ } else {
+ bundlePath = await globalThis.context.filesDir + '/' + file.bundleName + '/'+ file.uri;
+ }
+ if (!fs.accessSync(bundlePath)) {
+ console.info('onFileReady bundlePath err : ' + bundlePath);
+ }
+ fs.copyFileSync(bundlePath, file.fd);
+ fs.closeSync(file.fd);
+ // 恢复数据传输完成后,会通知服务端文件准备就绪
+ await session.publishFile({
+ bundleName: file.bundleName,
+ uri: file.uri,
+ });
+ console.info('onFileReady success');
+ } catch (e) {
+ console.error('onFileReady failed with err: ' + e);
+ }
+ },
+ onBundleBegin: (err, bundleName) => {
+ if (err) {
+ console.info('onBundleBegin err: ' + err);
+ } else {
+ console.info('onBundleBegin bundleName: ' + bundleName);
+ }
+ },
+ onBundleEnd: (err, bundleName) => {
+ if (err) {
+ console.info('onBundleEnd err: ' + err);
+ } else {
+ console.info('onBundleEnd bundleName: ' + bundleName);
+ }
+ },
+ onAllBundlesEnd: (err) => {
+ if (err) {
+ console.info('onAllBundlesEnd err: ' + err);
+ } else {
+ console.info('onAllBundlesEnd');
+ }
+ },
+ onBackupServiceDied: () => {
+ console.info('onBackupServiceDied');
+ },
+ });
+ const backupApps = [
+ "com.example.hiworld",
+ ]
+ let fpath = await globalThis.context.filesDir + '/localCapabilities.json';
+ let file = fs.openSync(fpath, fileIO.OpenMode.CREATE | fileIO.OpenMode.READ_WRITE);
+ let content = "{\"bundleInfos\" :[{\"allToBackup\" : false,\"extensionName\" : \"\"," +
+ "\"name\" : \"cn.openharmony.inputmethodchoosedialog\",\"needToInstall\" : true,\"spaceOccupied\" : 0," +
+ "\"versionCode\" : 1000000,\"versionName\" : \"1.0.0\"}],\"deviceType\" : \"default\",\"systemFullName\" : \"OpenHarmony-4.0.6.2(Canary1)\"}";
+ fs.writeSync(file.fd, content);
+ fs.fsyncSync(file.fd);
+ await session.appendBundles(file.fd, backupApps);
+ console.info('appendBundles success');
+
+ // 开发者需要请求安装应用的文件句柄
+ await session.getFileHandle({
+ bundleName: restoreApps[0],
+ uri: "/data/storage/el2/restore/bundle.hap"
+ });
+
+ await session.getFileHandle({
+ bundleName: restoreApps[0],
+ uri: "manage.json"
+ });
+ await session.getFileHandle({
+ bundleName: restoreApps[0],
+ uri: "1.tar"
+ });
+ console.info('getFileHandle success');
+ ```
+
+ **恢复数据时安装应用所需的能力文件内容示例:**
+ ```json
+ {
+ "bundleInfos" :[{
+ "allToBackup" : true,
+ "extensionName" : "BackupExtensionAbility",
+ "name" : "com.example.hiworld",
+ "needToInstall" : true,
+ "spaceOccupied" : 0,
+ "versionCode" : 1000000,
+ "versionName" : "1.0.0"
+ }],
+ "deviceType" : "default",
+ "systemFullName" : "OpenHarmony-4.0.0.0"
+ }
+ ```
\ No newline at end of file