Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 174 additions & 0 deletions docs/kill-app-options.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
# Killing app options

`Settings -> Backup settings -> Killing app options` decides what happens to an app right before
its data is read (backup) or written (restore). The very same list is shown under
`Settings -> Restore settings`, and both pages read and write the same preference, so a single
choice applies to backups and restores alike.

* Preference key: `kill_app_option` in DataStore (`KeyKillAppOption`), holding the name of
`com.xayah.core.model.KillAppOption`.
* Read once per task in `AbstractBackupService.onProcessing()` / `AbstractRestoreService.onProcessing()`,
then applied per package with `AbstractPackagesService.killApp()`.
* When option III is active, the suspension is lifted again by `releaseApp()` once the package has
been processed.
* Stopping and suspending a package is a **best-effort helper** of the task: a failure in any of those
steps – including the user trying to open the app in the meantime – only writes a log line, it never
aborts the task and never fails the package. See
[Opening the app while it is being backed up](#opening-the-app-while-it-is-being-backed-up).

| Option | Enum | Mechanism | Runs as |
| --- | --- | --- | --- |
| Disabled | `DISABLED` | Nothing | – |
| Option One | `OPTION_I` | Root shell retry loop (`killall` / `am force-stop` / `am kill`) | root shell |
| Option II (default) | `OPTION_II` | One `IActivityManager.forceStopPackageAsUser()` call | root service (Binder) |
| Advanced pause | `OPTION_III` | `am force-stop` followed by `pm suspend` | root shell |

## Disabled

Only a log line is written (`Won't kill <package>.`). The app keeps running while its data is
copied, which is the fastest option and the only one that leaves the app untouched.

## Option One

Implemented in `BaseUtil.killPackage()`. A new root shell (libsu) is opened, the global mount
namespace is entered (`nsenter --mount=/proc/1/ns/mnt sh`), and this loop is executed:

```sh
until [[ $(dumpsys activity processes | grep "packageList" | cut -d '{' -f2 | cut -d '}' -f1 \
| egrep -w "$packageName" | sed -n '1p') = "" ]]; do
killall -9 "$packageName" &>/dev/null
am force-stop --user "$userId" "$packageName" &>/dev/null
am kill "$packageName" &>/dev/null
done
```

* `dumpsys activity processes` lists the running processes of the package; the loop keeps going
until the package no longer appears in it.
* `killall -9` sends `SIGKILL` to every process whose name matches the package name.
* `am force-stop` asks ActivityManager to stop the package, `am kill` kills its background processes.
* The whole job is given 3 seconds (`timeout = 3`); when it expires, the command is closed and the
backup continues anyway.
* Because it is a shell loop, the package can be started again by a broadcast or a job in the middle
of the loop, which is why it has to be retried. This is the option that most often leaves the app
running while its data is copied.

## Option II (default)

Implemented in `AbstractPackagesService.killApp()` together with
`RemoteRootService.forceStopPackageAsUser()`:

```kotlin
mRootService.forceStopPackageAsUser(pkg.packageEntity.packageName, pkg.packageEntity.userId)
```

* The call crosses Binder into the root process (`:root`, running as uid 0) and ends up in the
hidden `ActivityManager.forceStopPackageAsUser(packageName, userId)`.
* It is a single call: ActivityManager force-stops every process of the package, marks the package
as stopped and cancels its alarms/jobs, so nothing restarts it until the user launches it again.
* No shell, no retry loop, no 3 second budget – this is why it is the default.

## Option III — Advanced pause

Both mechanisms above only *stop* the app. An app with a foreground service, an `AlarmManager`
alarm, a `JobScheduler` job or a push channel can come back while its files are being archived.
Option III additionally **suspends** the package, which the platform honours for every start
request, and the launcher shows the icon greyed out.

Implemented in `SuspendUtil.suspendPackage()` + `BaseUtil.suspendPackage()` (and the matching
`resumePackage()` / `resumeAll()`):

```sh
am force-stop --user "$userId" "$packageName"
pm suspend --user "$userId" "$packageName"
```

```sh
pm unsuspend --user "$userId" "$packageName"
```

* `pm suspend` requires `android.permission.SUSPEND_APPS`, which is only granted to root/shell, so
the command is executed through the root shell (`libsu`).
* While suspended, the package cannot be started by the launcher, by broadcasts, by services, by
jobs or by other apps; its icon is greyed out and its notifications are suppressed. Reading its
files keeps working, which is exactly what a backup needs.
* The suspension is lifted by `releaseApp()` in a `finally` block right after that app has been
processed, so it lasts for the duration of **one app**, not the whole task.
* Every suspended package is written to `files/suspended_packages.txt` before the command is issued.
At the beginning of a task `releaseApps()` calls `pm unsuspend` for every entry of that file, so a
task that was killed, crashed or interrupted by a reboot cannot leave an app suspended forever.
* **System apps are never suspended.** For a package with `PackageEntity.isSystemApp == true` the
option falls back to a plain force-stop (`forceStopPackageAsUser`), because suspending
`com.android.systemui`, the launcher or another core package can take the device down.
The app never suspends itself either.

### Verifying the state by hand

```sh
adb shell dumpsys package <package> | grep -i suspended # suspended=true means paused
adb shell pm unsuspend --user 0 <package> # lift it manually
```

`pm suspend` exists since Android 7.0 (API 24), which matches the app's `minSdk`.

## Opening the app while it is being backed up

Two things have to hold **at the same time**: the app cannot be opened while it is being backed up,
and the attempt to open it does not change the outcome of the backup. Three layers take care of that.

### 1. It does not open, because the package is suspended

After `pm suspend`, the platform refuses every start request – `am start` answers
`Activity not started`, a tap on the launcher does nothing and the icon is greyed out. This was
verified against a control group on an emulator (android-33 x86_64):

| State | Result of one `am start` | Does the app record a launch |
| --- | --- | --- |
| Not suspended | `pid: 20094`, process created | yes |
| Suspended | `pid: (none)`, no process | no |

### 2. The attempt does not fail the backup: `tar` exit code 1 is accepted

Before the suspension lands – or right after the system lifted it on its own – the app may already
be running. Reading its data then hits "a file changed while it was being read", and `tar` exits
with code **1** (`file changed as we read it`). The archive is still perfectly readable, but
`ShellResult.isSuccess` used to accept only 0, so the package was reported as failed.

`PackagesBackupUtil.isAcceptableTarResult()` changes the verdict to:

| Exit code | Meaning | Outcome |
| --- | --- | --- |
| 0 | Finished normally | pass |
| 1 | Some files changed or vanished while being read | **pass**, `testArchive()` is the verdict |
| 2 | Fatal error | fail |
| anything else / no result / timeout | Command broke | fail |

In other words, whether the archive can be decompressed and listed is what decides, not whether
somebody touched the files.

### 3. Started in between: `reinforcePause()` pauses it again

`killApp()` runs once per package, but reading the data takes several passes (APK, user data,
device-protected data, app data). To close the window where the APK pass is done and the app is
already up again by the time the data is read, the pause is re-applied in between:

```
backup(APK) -> reinforcePause() -> backup(USER) -> backup(USER_DE) -> reinforcePause() -> backup(DATA) -> ...
```

A restore has the same window: installing the APK may start the app, so `reinforcePause()` is called
again before `PACKAGE_DATA` is written. It only does something for option III and for non-system
packages, and running it repeatedly is safe (`pm suspend` on an already suspended package is a no-op).

### 4. No failure along the way can drag the task down

`killApp()` / `releaseApp()` / `releaseApps()` / `SuspendUtil` / `BaseUtil.suspendPackage()` are all
wrapped in `runCatching` and only log the failure:

```
Failed to pause <package>: ...
Failed to re-apply the pause of <package>: ...
```

`SuspendUtil` itself runs on `Dispatchers.IO + NonCancellable`, so a cancelled task still lifts every
suspension it applied and never leaves an app greyed out.

156 changes: 156 additions & 0 deletions docs/kill-app-options.zh-CN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
# 杀死应用选项(实现说明)

`设置 -> 备份设置 -> 杀死应用选项` 决定每个应用在读取数据(备份)或写入数据(恢复)之前被如何处理。
同样的选项也会出现在 `设置 -> 恢复设置` 中,两个页面读写的是同一个偏好项,因此选择一次即对备份与恢复同时生效。

* 偏好项:DataStore 中的 `kill_app_option`(`KeyKillAppOption`),值为
`com.xayah.core.model.KillAppOption` 的枚举名。
* 每个任务开始时读取一次:`AbstractBackupService.onProcessing()` /
`AbstractRestoreService.onProcessing()`,随后按应用逐个调用 `AbstractPackagesService.killApp()`。
* 选中「高级暂停」时,应用处理结束后由 `releaseApp()` 解除挂起。
* 停止/挂起应用都只是任务里的**尽力而为的辅助步骤**:任何一步失败(包括用户在此期间尝试打开应用)
只写日志,不会中止任务,也不会把该应用判定为备份失败。详见
[备份过程中尝试打开被备份的应用](#备份过程中尝试打开被备份的应用)。

| 选项 | 枚举 | 实现方式 | 执行身份 |
| --- | --- | --- | --- |
| 禁用 | `DISABLED` | 不做任何处理 | – |
| 方案I | `OPTION_I` | root shell 循环重试(`killall` / `am force-stop` / `am kill`) | root shell |
| 方案II(默认) | `OPTION_II` | 调用一次 `IActivityManager.forceStopPackageAsUser()` | root 服务(Binder)|
| 高级暂停 | `OPTION_III` | 先 `am force-stop`,再 `pm suspend` | root shell |

## 禁用

只写一行日志(`Won't kill <包名>.`),应用在数据复制期间保持运行。速度最快,也是唯一完全不干扰应用的选项。

## 方案I

实现在 `BaseUtil.killPackage()`。先通过 libsu 新开一个 root shell,切入全局挂载命名空间
(`nsenter --mount=/proc/1/ns/mnt sh`),再执行下面的循环:

```sh
until [[ $(dumpsys activity processes | grep "packageList" | cut -d '{' -f2 | cut -d '}' -f1 \
| egrep -w "$packageName" | sed -n '1p') = "" ]]; do
killall -9 "$packageName" &>/dev/null
am force-stop --user "$userId" "$packageName" &>/dev/null
am kill "$packageName" &>/dev/null
done
```

* 用 `dumpsys activity processes` 判断该包是否还在进程列表中,只要还在就一直循环。
* `killall -9` 向所有同名的进程发送 `SIGKILL`。
* `am force-stop` 请求 ActivityManager 停止该包,`am kill` 杀掉其后台进程。
* 整体给 3 秒(`timeout = 3`),超时后关闭命令、照常继续备份。
* 因为只是一个 shell 循环,循环过程中应用仍可能被广播或任务重新拉起,所以才需要反复重试。
这也是最容易出现「备份时应用仍在运行」的选项。

## 方案II(默认)

实现在 `AbstractPackagesService.killApp()` 与 `RemoteRootService.forceStopPackageAsUser()`:

```kotlin
mRootService.forceStopPackageAsUser(pkg.packageEntity.packageName, pkg.packageEntity.userId)
```

* 经由 Binder 进入 root 进程(`:root`,uid 0),最终调用隐藏 API
`ActivityManager.forceStopPackageAsUser(packageName, userId)`。
* 只有一次调用:ActivityManager 停止该包的全部进程、把包标记为 stopped,并取消其闹钟与任务,
在用户主动点开之前不会被重新拉起。
* 不需要 shell、没有重试循环、也没有 3 秒限制,因此是默认值。

## 高级暂停(方案III)

前两个方案只是「停掉」应用。带有前台服务、`AlarmManager` 闹钟、`JobScheduler` 任务或推送通道的应用,
完全可以在文件被打包的过程中重新起来。方案III 在此基础上把包**挂起(suspend)**,
系统会拦截所有启动请求,同时桌面图标变灰。

实现在 `SuspendUtil.suspendPackage()` + `BaseUtil.suspendPackage()`(以及配套的
`resumePackage()` / `resumeAll()`):

```sh
am force-stop --user "$userId" "$packageName"
pm suspend --user "$userId" "$packageName"
```

```sh
pm unsuspend --user "$userId" "$packageName"
```

* `pm suspend` 需要 `android.permission.SUSPEND_APPS`,该权限只授予 root/shell,因此命令通过 root shell 执行。
* 挂起期间:桌面、广播、服务、任务栏、其他应用都无法拉起它;图标变灰、通知被抑制;
但读取其文件不受影响,这正是备份需要的效果。
* 解除挂起放在 `finally` 里的 `releaseApp()`,即该应用处理完立即解除——作用范围是**单个应用**,
而不是整个任务。
* 挂起前会先把 `uid:包名` 写入 `files/suspended_packages.txt`;任务开始时 `releaseApps()` 会对文件中
的每一项执行 `pm unsuspend`。因此即使任务被强杀、崩溃或中途重启,也不会让某个应用永远处于挂起状态。
* **系统应用绝不挂起。** `PackageEntity.isSystemApp == true` 的包会退化为直接强制停止
(`forceStopPackageAsUser`)——挂起 `com.android.systemui`、桌面或其它核心包可能直接让设备不可用。
应用本身也不会挂起自己。

### 手动验证状态

```sh
adb shell dumpsys package <包名> | grep -i suspended # suspended=true 表示处于挂起
adb shell pm unsuspend --user 0 <包名> # 手动解除
```

`pm suspend` 自 Android 7.0(API 24)起提供,与本应用的 `minSdk` 一致。

## 备份过程中尝试打开被备份的应用

目标语义是两条**同时**成立:备份期间被备份的应用打不开;而用户「尝试打开」这个动作本身
**不影响备份结果**。实现上分三层保障。

### 1. 打不开由挂起保证

`pm suspend` 之后,任何启动请求都会被系统拒绝——`am start` 返回
`Activity not started`,桌面点击无反应,图标变灰。这一点在模拟器(android-33 x86_64)上做过对照验证:

| 场景 | 一次 `am start` 的结果 | 应用是否写入启动记录 |
| --- | --- | --- |
| 未挂起 | `pid: 20094`,进程拉起 | 写入 |
| 已挂起 | `pid: (none)`,进程未创建 | 不写入 |

### 2. 「尝试打开」不导致失败:`tar` 退出码 1 视为可接受

挂起之前,或者挂起被系统自动解除的瞬间,应用可能已经在运行。这时读它的数据会出现
「读的时候文件变了」,`tar` 会以退出码 **1** 结束(`file changed as we read it`)。
归档本身仍然完整可读,但在旧逻辑里 `ShellResult.isSuccess` 只认 0,于是整包被判失败。

`PackagesBackupUtil.isAcceptableTarResult()` 把判定改为:

| 退出码 | 含义 | 处理 |
| --- | --- | --- |
| 0 | 正常结束 | 通过 |
| 1 | 有文件在读取过程中变化/消失 | **通过**,以 `testArchive()` 的解压校验为准 |
| 2 | 致命错误 | 失败 |
| 其它 / 缺少结果 / 超时 | 命令异常 | 失败 |

也就是说,真正决定成败的是 `testArchive()` 能否正常解压并列出归档内容,而不是「有没有人动过文件」。

### 3. 处理中途被拉起:`reinforcePause()` 重新挂起

`killApp()` 只在每个应用开始时执行一次,而读数据分成 APK、用户数据(DE)、应用数据等多趟。
为了不留下「APK 读完了、数据开始读的时候应用已经起来了」这个窗口,读完前两趟之后会再挂起一次:

```
backup(APK) -> reinforcePause() -> backup(USER) -> backup(USER_DE) -> reinforcePause() -> backup(DATA) -> ...
```

恢复同理:安装完 APK 之后系统可能把应用拉起来,因此在写 `PACKAGE_DATA` 之前也调一次
`reinforcePause()`。只有在「高级暂停」且非系统应用时才会真正执行,重复执行是安全的
(`pm suspend` 对已挂起的包再次执行不会报错)。

### 4. 任何一步出错都不拖垮任务

`killApp()` / `releaseApp()` / `releaseApps()` / `SuspendUtil` / `BaseUtil.suspendPackage()`
全部用 `runCatching` 包住,失败只写一条日志:

```
Failed to pause <包名>: ...
Failed to re-apply the pause of <包名>: ...
```

`SuspendUtil` 内部跑在 `Dispatchers.IO + NonCancellable` 上,所以即使任务被取消,
该解除的挂起仍然会被解除,不会把应用留在灰掉的状态。

5 changes: 5 additions & 0 deletions source/app/src/main/res/values-zh-rCN/strings.xml
Original file line number Diff line number Diff line change
Expand Up @@ -339,9 +339,14 @@
<string name="no_root_directory">请勿选择根目录</string>
<string name="option_i">方案I</string>
<string name="option_ii">方案II</string>
<string name="option_iii">高级暂停</string>
<string name="disabled">禁用</string>
<string name="kill_app_options">杀死应用选项</string>
<string name="kill_app_options_desc">备份应用前行为</string>
<string name="kill_app_option_disabled_desc">不做任何处理,应用在数据复制期间保持运行。</string>
<string name="kill_app_option_i_desc">在 root shell 中循环执行 killall -9、am force-stop 与 am kill,直到该应用从 dumpsys activity processes 中消失;3 秒后仍未消失则放弃。</string>
<string name="kill_app_option_ii_desc">由 root 服务通过 Binder 调用一次 IActivityManager.forceStopPackageAsUser(),该应用的全部进程会被一次性停止。</string>
<string name="kill_app_option_iii_desc">先强行停止应用,再用 pm suspend 挂起:桌面、广播、服务与任务都无法再拉起它,图标随之变灰;该应用处理完成后立刻解除挂起。系统应用只会被强行停止。</string>
<string name="language">语言</string>
<string name="download">下载</string>
<string name="changelog">更新日志</string>
Expand Down
5 changes: 5 additions & 0 deletions source/app/src/main/res/values-zh-rHK/strings.xml
Original file line number Diff line number Diff line change
Expand Up @@ -337,9 +337,14 @@
<string name="no_root_directory">請勿選擇根目錄</string>
<string name="option_i">方案I</string>
<string name="option_ii">方案II</string>
<string name="option_iii">進階暫停</string>
<string name="disabled">禁用</string>
<string name="kill_app_options">殺死應用選項</string>
<string name="kill_app_options_desc">備份應用前行爲</string>
<string name="kill_app_option_disabled_desc">不做任何處理,應用在資料複製期間保持執行。</string>
<string name="kill_app_option_i_desc">在 root shell 中循環執行 killall -9、am force-stop 與 am kill,直到該應用從 dumpsys activity processes 中消失;3 秒後仍未消失則放棄。</string>
<string name="kill_app_option_ii_desc">由 root 服務透過 Binder 呼叫一次 IActivityManager.forceStopPackageAsUser(),該應用的全部行程會被一次性停止。</string>
<string name="kill_app_option_iii_desc">先強制停止應用,再用 pm suspend 暫停:桌面、廣播、服務與任務都無法再啟動它,圖示隨之變灰;該應用處理完成後立刻解除暫停。系統應用只會被強制停止。</string>
<string name="language">語言</string>
<string name="download">下載</string>
<string name="changelog">更新日志</string>
Expand Down
Loading