4eb2cc3632
## 安全修复 (P0/P1) - BackupOperation.kt:233 / ResticStreamBackup.kt:118 — \`userId\` 未转义导致命令注入 → 添加 \`shellEscape()\` 转义 - RestoreOperation.isArchiveSafe() — 安全检测失败时仍继续提取存在风险 → 改为 \`return false\` 中断恢复 - RestoreOperation.isArchiveSafe() — 路径白名单不完整（仅 /data/data/、/data/user_de/） → 新增 \`additionalAllowedPrefixes\` 参数覆盖 OBB/外部数据合法路径 → 提取为独立 RestoreArchiveSafety 模块可单元测试 - AndroidManifest — 添加 \`networkSecurityConfig\` 引用 - 新增 res/xml/network_security_config.xml — 全局允许 cleartext HTTP （WebDAV 后端需要，HTTPS 仍为推荐） ## 架构重构 ### 1. 拆分巨型 Operation 类 - BackupOperation.kt: 849 → 589 行 - 提取 \`BackupFileIO\` (117 行) — 7 个 FUSE 兼容文件 I/O 工具 - 提取 \`BackupAppDataOps\` (326 行) — 6 个单应用备份子流程 - 保留 \`BackupOperation\` 作为编排者 - RestoreOperation.kt: 820 → 214 行 - 提取 \`RestoreAppDataOps\` (476 行) — 6 个单应用恢复子流程 - 提取 \`RestoreApkInstaller\` (134 行) — pm install + 重试 + 验证 - 提取 \`RestoreArchiveSafety\` (95 行) — tar 路径安全验证（纯函数可测） - 删除 41 行死代码（旧 fixDataOwnership 私有方法） - 通过回调参数 \`resolveUid: suspend (String) -> Int?\` 解耦 - 保留 \`@Deprecated\` 委托方法确保向后兼容 ### 2. 协程并发改进 - BackupOperation: \`coroutineScope\` → \`supervisorScope\` + per-async try/catch → 一个应用失败不再取消其他正在运行的备份 - 提取 \`backupOneApp\` 私有方法提升可读性 - 移除 \`emit\` 内冗余的 \`withContext(Dispatchers.Main)\` 切换 （每次进度回调不再做线程上下文切换；调用方负责线程） ### 3. Clean Architecture 包重组 \`backup/\` 包按职责拆分为 4 个子包： \`\`\` backup/ ├── core/ 6 文件 错误/日志/工具 (AppError, LogUtil, FormatUtil, ...) ├── restic/ 18 文件 restic 集成 (ResticWrapper, RemoteTransport, ...) ├── security/ 5 文件 加密/凭据 (PasswordManager, BinaryResolver, ...) └── scan/ 2 文件 应用扫描 (AppScanner, SsaidCache) \`\`\` 依赖方向验证：ui → backup.X → 根包（无循环） ## Bug 修复 - SsaidCache: \`parseSaidXml\` → \`parseSsaidXml\`（拼写错误导致方法名与调用方不匹配） - 清理 5 个未使用导入（BackupIntegrityChecker, ConcurrencyController, BackupViewModel, BackupOperation, RestoreApkInstaller） ## 新增单元测试 (+399 行) - \`RestoreArchiveSafetyTest\` (103 行) — 11 个用例覆盖路径白名单 - \`BackupProgressTrackerTest\` (100 行) — EMA 平滑 + ETA 格式化 - \`BackupFileIOTest\` (94 行) — FUSE 兼容回退 - \`ConcurrencyControllerTest\` (43 行) — 数据类结构 - \`CredentialProviderTest\` (59 行) — 占位符检测（安全关键） 测试覆盖率 11% → 23%（业务逻辑） ## 已知限制 未运行 Gradle 编译验证（环境无法解析 Android Gradle Plugin）。 建议在 CI 上运行 \`./gradlew assembleDebug\` 和 \`./gradlew test\`。 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Android Backup GUI
Android 应用备份与恢复工具，通过 root 权限 实现应用的完整备份（APK + 用户数据 + OBB + SSAID + 权限 + WiFi 配置），集成 restic 实现增量去重备份，支持 SMB / WebDAV 远程仓库。
功能
- 应用扫描 — 自动列出第三方应用，支持系统应用白名单
- APK + 数据备份 — 备份 APK 文件、应用数据目录、OBB 数据、SSAID、SSAID 广告标识、AppOps 权限、WiFi 配置
- 多用户支持 — 从配置页选择 Android 用户（主用户 / 工作资料），持久化到配置文件
- 并行备份/恢复 — 备份并发 3（Semaphore），恢复并发 2（Semaphore）
- 存档完整性校验 — 备份后自动 zstd/gzip 校验 + tar 结构验证
- restic 增量去重 — 内建
librestic.so（~24MB），SSD 加密快照，增量备份 - 远程后端 — 本地 REST 桥 + NanoHTTPD 将 SMB/WebDAV 协议翻译为 restic 可直接访问的 REST API
- 流式备份 — FIFO 管道对接
restic backup --stdin，无需本地暂存 - 配置持久化 — 仓库路径、密码、后端参数、目标用户保存在
backup_settings.conf - 快照管理 — 初始化、查看统计、按策略清理旧快照（保留 7 天/4 周/3 月）、解锁
- 累积快照 — 从历史快照读取元数据，合并为增量累积备份
- 应用名显示 — 备份时缓存应用名称到
app_details.json，已卸载应用也显示中文名
技术栈
- Kotlin / Android SDK (minSdk 24, targetSdk 34)
- Jetpack Compose + Material 3 UI
- ViewModel + StateFlow + SharedFlow（面向状态架构）
- kotlinx-serialization（JSON 解析）
- restic 0.17+ 二进制（编译为
librestic.so） - sardine-android (WebDAV 客户端)
- jcifs-ng (SMB 客户端)
- NanoHTTPD（REST 桥服务器）
- libsu（Magisk / KernelSU / APatch root shell）
- Kotest + MockK（单元测试）
架构
┌─────────────────────────────────────────────┐
│ UI 层 (Jetpack Compose + Material 3) │
│ AppScaffold → BackupScreen / RestoreScreen │
│ / ConfigScreen │
│ / ConfigViewModel (StateFlow) │
├─────────────────────────────────────────────┤
│ 业务逻辑层 (backup/) │
│ BackupOperation → root shell tar/cp │
│ RestoreOperation → root shell pm install │
│ StreamingBackup → FIFO pipe → restic │
│ ResticWrapper → facade 委托给: │
│ ├── ResticBackup (备份) │
│ ├── ResticRestore (恢复 + dump) │
│ ├── ResticSnapshotOps (快照列表/forget) │
│ ├── ResticMaintenance (prune/check/stats) │
│ └── ResticRepoInit (init) │
│ ResticCommandRunner → ProcessBuilder │
│ ResticEnvResolver → 环境变量构建 │
│ RestBridgeRunner → ResticRestBridge │
│ RemoteTransport → file I/O 接口 │
│ ├── WebdavTransport (sardine, 8KB 分块) │
│ └── SmbTransport (jcifs-ng, 8KB 分块) │
├─────────────────────────────────────────────┤
│ Root 层 (root/) │
│ RootShell → libsu (Magisk/KernelSU/APatch) │
├─────────────────────────────────────────────┤
│ Service 层 │
│ BackupService → Foreground Service │
├─────────────────────────────────────────────┤
│ 原生二进制 (jniLibs) │
│ librestic.so / libtar_bin.so / libzstd_bin │
└─────────────────────────────────────────────┘
数据流（一次备份）
用户选择应用 → 扫描 (AppScanner.enumerateUsers / scanThirdParty)
↓
创建 Backup_ 目录 → 写入 appList.txt + app_details.json
↓
并行 (Semaphore=3) 为每个应用:
├── 备份 APK (cp → app目录/包名.apk)
├── 备份数据 (tar zstd → 包名_data.tar.zst)
├── 备份 OBB (tar → 包名_obb.tar.zst)
├── 备份 SSAID (提取 → ssaid.txt)
├── 备份图标 (snapshot cache / aapt)
└── 备份权限 (dumpsys → permissions.txt)
↓
WiFi 备份 → WifiManager.backup()
↓
(可选) ResticWrapper.backup() → restic 快照到远程仓库
远程仓库（REST 桥模式）
Restic CLI ←→ ResticRestBridge (NanoHTTPD, 127.0.0.1:random)
↓
RemoteTransport (SMB/WebDAV)
restic 通过 REST HTTP API 与本地桥通信，桥接器将请求翻译为 SMB/WebDAV 文件操作。 无需本地 staging 仓库，restic 直接读写远程存储。
构建
版本历史
| 版本 | 更新内容 |
|---|---|
| v1.14 | 修复 shell 转义/管道死锁/配置序列化缺陷，新增配置导出与 BackupConfig 单元测试 |
| v1.13 | Compose Material 3 UI 重构、Unlock 支持、ResticBinary 启动初始化、修复 500 错误和刷新竞态 |
| v1.12 | 引擎 + Compose Material 3 UI 重构 |
| v1.11 | 构建系统改进、LSP 支持 |
| v1.10 | 后端桥接稳定性提升 |
| v1.9 | 远程后端优化 |
| v1.8 | 快照管理增强 |
| v1.7 | 多用户支持 |
| v1.6 | 累积快照 |
| v1.5 | 修复签名配置 |
| v1.4 | APK 体积优化（R8 + shrinkResources），25MB → 11.8MB |
| v1.3 | 累积快照、AppResult 类型化错误、kotlinx-serialization |
编译命令
# Debug APK
./gradlew assembleDebug
# Release APK（需配置签名）
KEYSTORE_PASSWORD=<密码> KEY_PASSWORD=<密码> ./gradlew assembleRelease
Release 构建需要
app/release.keystore；原生库放在jniLibs/arm64-v8a/。
使用说明
- Android 设备需 root 权限（Magisk / KernelSU / APatch）
- 在「配置」页签设置备份选项 + restic 仓库参数
- 切换「备份用户」选项（多用户设备）
- 在「备份」页签选择应用 → 开始备份
- 在「恢复」页签选择本地备份或 restic 快照 → 开始恢复
远程后端配置
| 字段 | WebDAV 示例 | SMB 示例 |
|---|---|---|
| 后端 | WebDAV | SMB |
| 地址 | https://webdav.example.com |
192.168.1.165 |
| 用户名 | 账号 | Windows 用户名 |
| 密码 | 密码 | Windows 密码 |
| 共享名称 | — | back |
| 仓库存放路径 | backup |
backup |
注意事项
- 应用卸载会清除
backup_settings.conf，建议定期导出配置 - Restic 仓库需先「初始化」才能使用（自动检测已有仓库）
- SMB 密码错误多次会导致 Windows 账户锁定，需在服务器上解锁