android/SukiSU-Ultra
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

website: Updated translations (#1959)

Browse Source 
更新翻譯
This commit is contained in:
sus
2024-08-25 11:52:43 +08:00
committed by GitHub
parent 8169a16f56
commit 4b978cc7c1
13 changed files with 341 additions and 229 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
website/docs/zh_TW/guide/app-profile.md
View File

@@ -2,7 +2,8 @@
App Profile 是 KernelSU 提供的一種針對各種應用程式自訂其使用配置的機制。
對於授予了root 權限（也即可以使用 `su`）的應用程式來說，App Profile 也可以稱為Root Profile，它可以自訂 `su` 的 `uid`, `gid` , `groups` , ` capabilities` 以及 `SELinux context` 規則，從而限制 root 使用者的權限；例如可以針對防火牆應用程式僅授予網路權限，而不授予檔案存取權限，針對凍結類別應用程式僅授予 shell 權限而不是直接給 root ；透過最小化權限原則**把權力關進籠子裡**。
對於授予了 root 權限（即可以使用 `su`）的應用程式來說，App Profile 也可以稱為 Root Profile，它可以自訂 `su` 的 `uid`、`gid`、`groups`、` capabilities` 以及 `SELinux context` 規則，從而限制 root 使用者的權限。
例如可以針對防火牆應用程式僅授予網路權限，而不授予檔案存取權限，針對凍結類別應用程式僅授予 shell 權限而不是直接給 root ；透過最小化權限原則**把權力關進籠子裡**。
對於沒有被授予 root 權限的普通應用，App Profile 可以控制核心以及模組系統對此應用的行為；例如是否需要針對此應用程式卸載模組造成的修改等。核心和模組系統可以透過此配置決定是否要做一些類似「隱藏痕跡」類別的操作。
@@ -16,8 +17,8 @@ UID 為 0 的使用者稱為 root 使用者，GID 為 0 的群組稱為 root 群
對於 Android 系統來說，每個應用程式都是一個單獨的使用者（不考慮 share uid 的情況），擁有一個唯一的 UID。例如 `0` 是 root 使用者，`1000` 是 `system`，`2000` 是 ADB shell，10000-19999 的是一般使用者。
:::info
此處的 UID 跟 Android 系統的多使用者，或者說工作資料（Work Profile），不是概念。工作資料實際上是對 UID 進行分片實現的，例如 10000-19999 是主使用者，110000-119999 是工作資料；他們中的任何一個普通應用都擁有自己獨有的 UID。
:::info 補充
此處的 UID 跟 Android 系統的多使用者，或者說工作資料（Work Profile），是不同概念。工作資料實際上是對 UID 進行分片實現的，例如 10000-19999 是主使用者，110000-119999 是工作資料；他們中的任何一個普通應用都擁有自己獨有的 UID。
:::
每一個應用程式可以有若干個群組，GID 使其主要的群組，通常與 UID 一致；其他的群組稱為補充群組(groups)。某些權限是透過群組控制的，例如網路訪問，藍牙等。
@@ -29,7 +30,7 @@ oriole:/ $ id
uid=2000(shell) gid=2000(shell) groups=2000(shell),1004(input),1007(log),1011(adb),1015(sdcard_rw),1028(sdcard_r),1078(ext_data_ww) (ext_obb_rw),3001(net_bt_admin),3002(net_bt),3003(inet),3006(net_bw_stats),3009(readproc),3011(uhid),3012(readreadtracefs:s05:
```
其中，UID 為`2000`，GID 也即主要組ID 也為`2000`；除此之外它還在許多補充組裡面，例如`inet` 組代表可以創建`AF_INET` 和`AF_INET6` 的socket（存取網路），`sdcard_rw` 代表可以讀寫sdcard 等。
其中，UID 為`2000`，GID 也即主要組 ID 也為 `2000`；除此之外它還在許多補充組裡面，例如 `inet` 組代表可以創建 `AF_INET` 和 `AF_INET6` 的 socket（存取網路），`sdcard_rw` 代表可以讀寫 sdcard 等。
KernelSU 的 Root Profile 可以自訂執行 `su` 後 root 程式的 UID, GID 和 groups。例如，你可以設定某個 root 應用程式的Root Profile 其UID 為`2000`，這表示此應用程式在使用`su` 的時候，它的實際權限是ADB Shell 等級；你可以去掉groups 中的`inet` ，這樣這個`su` 就無法存取網路。
@@ -43,7 +44,7 @@ App Profile 只是控制 root 應用程式使用 `su` 後的權限，它並非
Capabilities 是 Linux 的一種分權機制。
傳統的 UNIX 系統為了執行權限檢查，將流程分為兩類：特權程式（其有效使用者 ID 為 0，稱為超級使用者或 root）和非特權程式（其有效 UID 為非零）。特權程式會繞過所有核心權限檢查，而非特權程式則根據其憑證（通常是有效UID、有效GID和補充群組清單）進行完整的權限檢查。
傳統的 UNIX 系統為了執行權限檢查，將流程分為兩類：特權程式（其等效使用者 ID 為 0，稱為超級使用者或 root）和非特權程式（其等效 UID 為非零）。特權程式會繞過所有核心權限檢查，而非特權程式則根據其憑證（通常是等校 UID、等效 GID 和補充群組清單）進行完整的權限檢查。
從 Linux 2.2開始，Linux 將傳統上與超級使用者關聯的特權分解為獨立的單元，稱為 Capabilities（有的也翻譯為「權能」），它們可以獨立啟用和停用。
@@ -52,7 +53,7 @@ Capabilities 是 Linux 的一種分權機制。
KernelSU 的 Root Profile 可以自訂執行 `su` 後 root 程式的 Capabilities，從而實現只授予「部分 root 權限」。與上面介紹的UID, GID 不同，某些 root 應用就是需要 `su` 後 UID 是 `0`，此時我們可以透過限制這個 UID 為 `0` 的 root 使用者的 Capabilities，就可以限制它能夠執行的操作。
:::tip 強烈建議
Linux 系統關於 Capability 的[官方文件](https://man7.org/linux/man-pages/man7/capabilities.7.html)，解釋了每一項Capability 所代表的能力，寫的非常詳細，如果你想要自訂Capabilities，請務必先閱讀此文件。
Linux 的 Capability [官方文件](https://man7.org/linux/man-pages/man7/capabilities.7.html)詳細解釋了每一項 Capability 所代表的能力，如果你想要自訂Capabilities，請務必先閱讀此文件。
:::
### SELinux {#selinux}
@@ -76,7 +77,7 @@ SELinux 的完整概念比較複雜，我們這裡不打算講解它的具體運
KernelSU 的 Root Profile 可以自訂執行 `su` 後 root 程式的 SELinux context，並且可以針對這個 context 設定特定的存取控制規則，從而更精細地控制 root 權限。
通常情況下，應用程式執行 `su` 後，會將進程切換到一個**不受任何限制** 的SELinux 域，例如`u:r:su:s0`，透過 Root Profile，我們可以將它切換到一個自訂的網域，例如 `u:r:app1:s0`，然後為這個網域制定一系列規則：
通常情況下，應用程式執行 `su` 後，會將進程切換到一個**不受任何限制** 的 SELinux 域，例如`u:r:su:s0`，透過 Root Profile，我們可以將它切換到一個自訂的作用域，例如 `u:r:app1:s0`，然後為這個作用域制定一系列規則：
```sh
type app1
@@ -85,34 +86,34 @@ typeattribute app1 mlstrustedsubject
allow app1 * * *
```
注意：此處的 `allow app1 * * *` 僅僅作為演示方便而使用，實際過程中不應使用這個規則，因為它跟 permissive 區別不大。
注意：此處的 `allow app1 * * *` 僅僅作為示範方便而使用，實際過程中不應使用這個規則，因為它跟寬容模式區別不大。
### 逃逸 {#escalation}
如果 Root Profile 的配置不合理，那麼可能會發生逃逸的情況：Root Profile 的限制會意外失效。
例如，如果你為ADB shell 使用者設定允許root 權限（這是相當常見的情況）；然後你給某個普通應用程式允許root 權限，但是配置它的root profile 中的UID 為2000（ADB shell 使用者的UID）；那麼此時，這個App 可以透過執行兩次 `su` 來獲得完整的root 權限：
例如，如果你為ADB shell 使用者設定允許root 權限（這是相當常見的情況）；然後你給某個普通應用程式允許 root 權限，但是配置它的 root profile 中的 UID 為 2000（ADB shell 使用者的UID）；那麼此時，這個 App 可以透過執行兩次 `su` 來獲得完整的root 權限：
1. 第一次執行 `su`，由於 App Profile 強制生效，會正常切換到 UID 為 `2000(adb shell)` 而非 `0(root)`。
2. 第二次執行 `su`，由於此時它 UID 是 `2000`，而你給 `2000(adb shell)` 配置了允許 root，它會獲得完整的 root 權限！
1. 第一次執行 `su`，由於 App Profile 強制生效，會正常切換到 UID 為 `2000` (adb shell) 而非 `0` (root)。
2. 第二次執行 `su`，由於此時它 UID 是 `2000`，而你給 `2000` (adb shell) 配置了允許 root，它會獲得完整的 root 權限！
:::warning 注意
這是完全符合預期的行為，並非 BUG！因此我們建議：
如果你的確需要給 adb 授予 root 權限（例如你是開發者），那麼不建議你在配置 Root Profile 的時候將 UID 改成 `2000`，用 `1000(system)` 會更好。
如果你的確需要給 adb 授予 root 權限（例如你是開發者），那麼不建議你在配置 Root Profile 的時候將 UID 改成 `2000`，用 `1000` (system) 會更好。
:::
## Non Root Profile {#non-root-profile}
### 卸載模組 {#umount-modules}
KernelSU 提供了一種 systemless 的方式來修改系統分區，這是透過掛載 overlayfs 來實現的。但有些情況下，App 可能會對這種行為比較敏感；因此，我們可以透過設定「卸載模組」來卸載掛載在這些應用程式上的模組。
KernelSU 提供了一種無須直接修改系統分區的方式 (systemless) 來修改系統分區，這是透過掛載 overlayfs 來實現的。但有些情況下，App 可能會對這種行為比較敏感；因此，我們可以透過設定「卸載模組」來卸載掛載在這些應用程式上的模組。
另外，KernelSU 管理器的設定介面還提供了一個「預設卸載模組」的開關，這個開關預設是**開啟**的，這表示**如果不對應用程式做額外的設定**，預設情況下 KernelSU 或某些模組會對此應用程式執行卸載操作。當然，如果你不喜歡這個設定或這個設定會影響某些 App，你可以有以下選擇：
1. 保持「預設卸載模組」的開關，然後針對不需要「卸載模組」的應用程式進行單獨的設置，在 App Profile 中關閉「卸載模組」；（相當於「白名單」）。
2. 關閉「預設卸載模組」的開關，然後針對需要「卸載模組」的應用程式進行單獨的設置，在 App Profile 中開啟「卸載模組」；（相當於「黑名單」）。
:::info
KernelSU 在 5.10 及以上內核上，內核無須任何修改就可以卸載模組；但在 5.10 以下的設備上，這個開關僅僅是一個“設定”，KernelSU 本身不會做任何動作，如果你希望在 5.10 以前的內核可以卸載模組，你需要將 `path_unmount` 函數向後移植到 `fs/namespace.c`，您可以在[如何為非 GKI 核心整合 KernelSU](/zh_TW/guide/how-to-integrate-for-non-gki.html)的末尾獲取更多資訊。一些模組（如 ZygiskNext）也會透過這個設定決定是否需要卸載。
:::info 提示
KernelSU 在 5.10 及以上內核上，內核無須任何修改就可以卸載模組；但在 5.10 以下的設備上，這個開關僅僅是一個"設定"，KernelSU 本身不會做任何動作，如果你希望在 5.10 以前的內核可以卸載模組，你需要將 `path_unmount` 函數向後移植到 `fs/namespace.c`，您可以在[如何為非 GKI 核心整合 KernelSU](how-to-integrate-for-non-gki.md#how-to-backport-path_unpount)獲取更多資訊。一些模組（如 ZygiskNext）也會透過這個設定決定是否需要卸載。
:::

12
website/docs/zh_TW/guide/difference-with-magisk.md
View File

@@ -1,4 +1,4 @@
# KernelSU 與 Magisk 的差異 {#title}
# KernelSU 與 Magisk 的差異 {#difference-with-magisk}
儘管 KernelSU 模組和 Magisk 模組之間有許多相似之處，但由於它們完全不同的實作機制，不可避免地存在一些差異；如果您想讓您的模組同時在 Magisk 和 KernelSU 上運作，那麼您必須瞭解這些差異。
@@ -6,7 +6,7 @@
- 模組檔案格式：都以 Zip 的格式組織模組，並且模組的格式幾乎相同
- 模組安裝目錄：都位於 `/data/adb/modules`
- Systemless：都支援通過模組以無系統修改的方式來更改 `/system`
- 無系統修改：都支援透過模組以無系統修改的方式來更改 `/system`
- `post-fs-data.sh`：執行階段和語義完全相同
- `service.sh`：執行階段和語義完全相同
- `system.prop`：完全相同
@@ -19,10 +19,10 @@
以下是一些不同之處：
1. KernelSU 的模組不支援在 Recovery 中安裝。
1. KernelSU 的模組無法在 Recovery 中安裝。
2. KernelSU 的模組沒有內建的 Zygisk 支援 (但您可以透過 [ZygiskNext](https://github.com/Dr-TSNG/ZygiskNext) 來使用 Zygisk 模組)。
3. KernelSU 模組取代或刪除檔案與 Magisk 完全不同。KernelSU 不支援 `.replace` 方法，相反，您需要透過 `mknod filename c 0 0` 建立相同名稱的資料夾以刪除對應檔案。
4. BusyBox 的目錄不同；KernelSU 內建的 BusyBox 在 `/data/adb/ksu/bin/busybox` 而 Magisk 在 `/data/adb/magisk/busybox`；**注意此為 KernelSU 內部行為，未來可能會變更！**
5. KernelSU 不支援 `.replace` 檔案；但 KernelSU 支援 `REPLACE` 和 `REMOVE` 變數以移除或取代檔案 (資料夾)。
4. BusyBox 的目錄不同。KernelSU 內建的 BusyBox 在 `/data/adb/ksu/bin/busybox`，而 Magisk 在 `/data/adb/magisk/busybox`。**注意此為 KernelSU 內部行為，未來可能會變更！**
5. KernelSU 不支援 `.replace` 檔案；但 KernelSU 支援 `REPLACE` 和 `REMOVE` 變數以移除或取代檔案與資料夾。
6. KernelSU 新增了 `boot-completed` 階段以在啟動完成時執行一些腳本。
7. KernelSU 新增了 `post-mount` 階段，以便在掛載 overlayfs 後執行一些腳本
7. KernelSU 新增了 `post-mount` 階段，以便在掛載 overlayfs 後執行一些腳本。

6
website/docs/zh_TW/guide/faq.md
View File

@@ -26,7 +26,7 @@ KernelSU 沒有內建 Zygisk 支援，但是您可以用 [ZygiskNext](https://gi
KernelSU 的模組系統與 Magisk 的 magic mount 存在衝突，如果在 KernelSU 中啟用了任何模組，那麼整個 Magisk 將無法正常運作。
但是如果您只使用 KernelSU 的 `su`，那么它會和 Magisk 一同運作：KernelSU 修改 `kernel` 、 Magisk 修改 `ramdisk`，它們可以搭配使用。
但是如果您只使用 KernelSU 的 `su`，那么它會和 Magisk 一同運作：KernelSU 修改 `kernel`、Magisk 修改 `ramdisk`，它們可以搭配使用。
## KernelSU 会取代 Magisk 嗎？
@@ -49,11 +49,11 @@ KernelSU 的模組系統與 Magisk 的 magic mount 存在衝突，如果在 Kern
## 如何為舊版核心整合 KernelSU？
請參閱[指南](how-to-integrate-for-non-gki)
請參閱[指南](how-to-integrate-for-non-gki.md)
## 為何我的 Android 版本為 13，但核心版本卻是 "android12-5.10"？
核心版本與 Android 版本無關，如果您要刷新 KernelSU，請一律使用**核心版本**而非 Android 版本，如果你為 "android12-5.10" 的裝置刷新 Android 13 的核心，等候您的將會是開機迴圈。
核心版本與 Android 版本無關，如果您要使用 KernelSU，請一律使用**核心版本**而非 Android 版本，如果你為 "android12-5.10" 的裝置寫入 Android 13 的核心，等候您的將會是開機迴圈。
## 我是 GKI1.0，能用 KernelSU 嗎？

24
website/docs/zh_TW/guide/how-to-build.md
View File

@@ -5,7 +5,7 @@
1. [建置核心](https://source.android.com/docs/setup/build/building-kernels)
2. [標準核心映像 (GKI) 發行組建](https://source.android.com/docs/core/architecture/kernel/gki-release-builds)
::: warning
::: warning 警告
此文件適用於 GKI 裝置，如果您是舊版核心，請參閱[如何為非 GKI 裝置整合 KernelSU](how-to-integrate-for-non-gki)
:::
@@ -20,7 +20,7 @@ repo init -m manifest.xml
repo sync
```
`<kernel_manifest.xml>` 是一個可以唯一確定組建的資訊清單檔案，您可以使用這個資訊清單進行可重新預測的組建。您需要從[標準核心映像 (GKI) 發行組建](https://source.android.com/docs/core/architecture/kernel/gki-release-builds) 下載資訊清單檔案
`<kernel_manifest.xml>` 是一個可以唯一確定組建的資訊清單，您可以使用這個資訊清單進行可重新預測的組建。您需要從[標準核心映像 (GKI) 發行組建](https://source.android.com/docs/core/architecture/kernel/gki-release-builds)下載資訊清單。
### 建置 {#build}
@@ -34,14 +34,14 @@ LTO=thin BUILD_CONFIG=common/build.config.gki.aarch64 build/build.sh
不要忘記新增 `LTO=thin`，否則，如果您的電腦記憶體小於 24GB，建置可能會失敗。
從 Android 13 開始，核心由 `bazel` 建置：
從 Android 13 開始，核心使用 `bazel` 建置：
```sh
tools/bazel build --config=fast //common:kernel_aarch64_dist
```
:::info
對於某些 Android 14 內核，要使 Wi-Fi/藍牙正常工作，可能需要刪除所有受 GKI 保護的匯出：
:::info 你可能需要知道...
對於某些 Android 14 核心，要使 Wi-Fi/藍牙正常工作，可能需要刪除所有受 GKI 保護的匯出：
```sh
rm common/android/abi_gki_protected_exports_*
@@ -52,22 +52,20 @@ rm common/android/abi_gki_protected_exports_*
如果您可以成功建置核心，那麼建置 KernelSU 就會非常輕鬆，依自己的需求在核心原始碼根目錄中執行以下任一命令：
- 最新 tag (穩定版本)
::: code-group
```sh
```sh[最新 tag (穩定版本)]
curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -
```
- main 分支 (開發版本)
```sh
```sh[main 分支 (開發版本)]
curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s main
```
- 選取 tag (例如 v0.5.2)
```sh
```sh[選取 tag (例如 v0.5.2)]
curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s v0.5.2
```
:::
然後重新建置核心，您將會得到一個帶有 KernelSU 的核心映像！

98
website/docs/zh_TW/guide/how-to-integrate-for-non-gki.md
View File

@@ -1,4 +1,4 @@
# 如何為非 GKI 核心整合 KernelSU {#introduction}
# 如何為非 GKI 核心整合 KernelSU {#how-to-integrate-kernelsu-for-non-gki-kernels}
KernelSU 可以被整合到非 GKI 核心中，現在它最低支援到核心 4.14 版本；理論上也可以支援更低的版本。
@@ -11,31 +11,21 @@ KernelSU 可以被整合到非 GKI 核心中，現在它最低支援到核心 4.
1. 藉助 `kprobe` 自動整合
2. 手動修改核心原始碼
## 使用 kprobe 整合 {#using-kprobes}
## 使用 kprobe 整合 {#integrate-with-kprobe}
KernelSU 使用 kprobe 機制來處理核心的相關 hook，如果 *kprobe* 可以在您建置的核心中正常運作，那麼建議使用這個方法進行整合。
首先，把 KernelSU 新增至您的核心來源樹狀結構，再核心的根目錄執行以下命令：
- 最新 tag (稳定版本)
```sh
curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -
curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s v0.9.5
```
- main 分支(開發版本)
:::info 公告
[KernelSU 1.0 及更新版本不再支援非 GKI 核心](https://github.com/tiann/KernelSU/issues/1705)。最後一個支援的版本為 `v0.9.5`，請確保使用的版本正確。
:::
```sh
curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s main
```
- 選取 tag (例如 v0.5.2)
```sh
curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s v0.5.2
```
然後，您需要檢查您的核心是否啟用 *kprobe* 相關組態，如果未啟用，則需要新增以下組態：
然後，您需要檢查您的核心是否啟用 *kprobe*，如果未啟用，則需要新增以下設定：
```
CONFIG_KPROBES=y
@@ -45,33 +35,40 @@ CONFIG_KPROBE_EVENTS=y
最後，重新建置您的核心即可。
如果您發現 KPROBES 仍未生效，很有可能是因為它的相依性 `CONFIG_MODULES` 並未被啟用 (如果還是未生效請輸入 `make menuconfig` 搜尋 KPROBES 的其他相依性並啟用)
如果您發現 KPROBES 仍未生效，很有可能是因為它依賴的 `CONFIG_MODULES` 並未被啟用，如果還是未生效請輸入 `make menuconfig` 搜尋 KPROBES 的其他相依性並啟用。
如果您在整合 KernelSU 之後手機無法啟動，那麼很可能您的核心中 **kprobe 無法正常運作**，您需要修正這個錯誤，或者使用第二種方法。
:::tip 如何檢查 kprobe 是否損毀？
將 `KernelSU/kernel/ksu.c` 中的 `ksu_enable_sucompat()` 和 `ksu_enable_ksud()` 取消註解，如果正常開機，即 kprobe 已損毀；或者您可以手動嘗試使用 kprobe 功能，如果不正常，手機會直接重新啟動。
將 `KernelSU/kernel/ksu.c` 中的 `ksu_enable_sucompat()` 和 `ksu_enable_ksud()` 註解掉，如果正常開機，即 kprobe 已損毀；或者您可以手動嘗試使用 kprobe 功能，如果不正常，手機會直接重新啟動。
:::
:::info 如何為非 GKI 核心啟用卸載模組功能
如果你的內核版本小於 5.10，你應該將 `path_umount` 向後移植至 `fs/namespace.c`。 卸載模組功能依賴於這個函數。 如果你沒有向後移植 `path_umount`，卸載模組功能將無法工作。 你可以在底下查看更多關於 `path_unmount` 的資料。
如果你的內核版本小於 5.10，你應該將 `path_umount` 向後移植至 `fs/namespace.c`。卸載模組功能依賴於這個函數。如果你沒有向後移植 `path_umount`，卸載模組功能將無法工作。你可以在[這裡查看更多關於 `path_unmount` 的資料](#how-to-backport-path_unpount)。
:::
## 手動修改核心原始碼 {#modify-kernel-source-code}
## 手動修改核心原始碼 {#manually-modify-the-kernel-source}
如果 kprobe 無法正常運作 (可能是上游的錯誤或核心版本過低)，那您可以嘗試這種方法：
如果 kprobe 無法正常運作 (在4.8之前可能是上游或核心的錯誤)，那您可以嘗試這種方法：
首先，將 KernelSU 新增至您的原始碼樹狀結構，再核心的根目錄執行以下命令：
首先，將 KernelSU 新增至您的原始碼樹狀結構，在核心的根目錄執行以下命令：
```sh
curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -
curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s v0.9.5
```
請記住，在某些裝置上，您的 `defconfig` 可能位於 `arch/arm64/configs` 中，或在其他情況下位於 `arch/arm64/configs/vendor/你的defconfig` 中。無論您使用哪個 `defconfig`，請確保使用 `CONFIG_KSU=y` 啟用KernelSU，或使用 `n` 停用它。例如，如果您選擇啟用它，則 `defconfig` 應包含以下字串：
```conf
# KernelSU
CONFIG_KSU=y
```
然後，手動修改核心原始碼，您可以參閱下方的 patch：
```diff
::: code-group
```diff[exec.c]
diff --git a/fs/exec.c b/fs/exec.c
index ac59664eaecf..bdd585e1d2cc 100644
--- a/fs/exec.c
@@ -97,7 +94,7 @@ index ac59664eaecf..bdd585e1d2cc 100644
return __do_execve_file(fd, filename, argv, envp, flags, NULL);
}
```
```diff
```diff[open.c]
diff --git a/fs/open.c b/fs/open.c
index 05036d819197..965b84d486b8 100644
--- a/fs/open.c
@@ -128,7 +125,7 @@ index 05036d819197..965b84d486b8 100644
if (mode & ~S_IRWXO) /* where's F_OK, X_OK, W_OK, R_OK? */
return -EINVAL;
```
```diff
```diff[read_write.c]
diff --git a/fs/read_write.c b/fs/read_write.c
index 650fc7e0f3a6..55be193913b6 100644
--- a/fs/read_write.c
@@ -151,7 +148,7 @@ index 650fc7e0f3a6..55be193913b6 100644
return -EBADF;
if (!(file->f_mode & FMODE_CAN_READ))
```
```diff
```diff[stat.c]
diff --git a/fs/stat.c b/fs/stat.c
index 376543199b5a..82adcef03ecc 100644
--- a/fs/stat.c
@@ -175,6 +172,8 @@ index 376543199b5a..82adcef03ecc 100644
return -EINVAL;
```
:::
主要修改四個項目：
1. do_faccessat，通常位於 `fs/open.c`
@@ -236,9 +235,11 @@ index 2ff887661237..e758d7db7663 100644
return -EINVAL;
```
### 安全模式 {#safe-mode}
若要啟用 KernelSU 內建的安全模式，您還需要修改 `drivers/input/input.c` 中的 `input_handle_event` 方法：
:::tip
:::tip 小建議
強烈建議啟用此功能，如果遇到開機迴圈，這將會非常有用！
:::
@@ -266,9 +267,45 @@ index 45306f9ef247..815091ebfca4 100755
add_input_randomness(type, code, value);
```
:::info 不小心進入安全模式？
如果您使用手動整合且不停用 `CONFIG_KPROBES`，那麼您將可能會在啟動後透過按下音量來減少按鈕來觸發安全模式！因此，如果使用手動集成，您需要停用 `CONFIG_KPROBES` ！
:::
### 無法在終端中執行 `pm` ? {#failed-to-execute-pm-in-terminal}
你應該修改 `fs/devpts/inode.c`，參考:
```diff
diff --git a/fs/devpts/inode.c b/fs/devpts/inode.c
index 32f6f1c68..d69d8eca2 100644
--- a/fs/devpts/inode.c
+++ b/fs/devpts/inode.c
@@ -602,6 +602,8 @@ struct dentry *devpts_pty_new(struct pts_fs_info *fsi, int index, void *priv)
return dentry;
}
+#ifdef CONFIG_KSU
+extern int ksu_handle_devpts(struct inode*);
+#endif
+
/**
* devpts_get_priv -- get private data for a slave
* @pts_inode: inode of the slave
@@ -610,6 +612,7 @@ struct dentry *devpts_pty_new(struct pts_fs_info *fsi, int index, void *priv)
*/
void *devpts_get_priv(struct dentry *dentry)
{
+ #ifdef CONFIG_KSU
+ ksu_handle_devpts(dentry->d_inode);
+ #endif
if (dentry->d_sb->s_magic != DEVPTS_SUPER_MAGIC)
return NULL;
return dentry->d_fsdata;
```
### 如何向後移植 path_umount {#how-to-backport-path_unpount}
你可以透過向後移植 `path_umount` 來讓卸載模組功能在小於 5.10 的非 GKI 核心上運作. 你可以參考這個修改:
你可以透過向後移植 `path_umount` 來讓卸載模組功能在低於 5.10 的非 GKI 核心上運作。你可以參考這個修改:
```diff
--- a/fs/namespace.c
@@ -315,5 +352,4 @@ index 45306f9ef247..815091ebfca4 100755
* This is important for filesystems which use unnamed block devices.
```
最後，再次建置您的核心，KernelSU 將會如期運作。

225
website/docs/zh_TW/guide/installation.md
View File

@@ -1,25 +1,25 @@
# 安裝 {#title}
## 檢查您的裝置是否受支援 {#check-if-supported}
## 檢查您的裝置是否受支援 {#check-if-your-device-is-supported}
從 [GitHub Releases](https://github.com/tiann/KernelSU/releases) 下載 KernelSU 管理器應用程式，然後將應用程式安裝至裝置並開啟：
從 [GitHub Releases](https://github.com/tiann/KernelSU/releases) 下載 KernelSU 管理器，然後安裝至裝置並開啟：
- 如果應用程式顯示「不支援」，則表示您的裝置不支援 KernelSU，您需要自行編譯核心才能繼續使用，，KernelSU 官方也永遠不會為您提供一個可以刷新的 Boot 映像。
- 如果應用程式顯示「未安裝」，那麼 KernelSU 支援您的裝置；可以進行下一步作業。
- 如果顯示「不支援」，則表示您的裝置不支援 KernelSU，您需要自行編譯核心才能繼續使用，KernelSU 官方也永遠不會提供一個您可以寫入的 Boot 映像。
- 如果顯示「未安裝」，那麼 KernelSU 支援您的裝置。
:::info
::: info 提示
對於顯示「不支援」的裝置，這裡有一個[非官方支援裝置清單](unofficially-support-devices.md)，您可以使用這個清單裡的核心自行編譯。
:::
## 備份您的原廠 boot.img {#backup-boot-image}
## 備份您的原廠 boot.img {#backup-stock-boot-img}
在進行刷新作業前，您必須預先備份您的原廠 boot.img。如果您在後續刷新作業中出現了任何問題，您都可以透過使用 Fastboot 刷新回到原廠 Boot 以還原系統。
在寫入核心映像前，您必須預先備份您的原廠 boot.img。如果您在後續寫入中出現了任何問題，您都可以透過使用 Fastboot 寫回原廠 Boot 以還原系統。
::: warning
刷新作業可能會造成資料遺失，請確保做好這一步再繼續進行下一步作業！！必要時您還可以備份您手機的所有資料。
::: warning 警告
寫入核心映像可能會造成資料遺失，請確保做好這一步再繼續進行下一步作業！！必要時您還可以備份您手機的所有資料。
:::
## 必要知識 {#acknowage}
## 必要知識 {#necessary-knowledge}
### ADB 和 Fastboot {#adb-and-fastboot}
@@ -27,9 +27,9 @@
### KMI
KMI 全稱 Kernel Module Interface，相同 KMI 的核心版本是**相容的** 這也是 GKI 中「標準」的涵義所在；反之，如果 KMI 不同，那麼這些核心之間無法彼此相容，刷新與您裝置 KMI 不同的核心映像可能會導致開機迴圈。
KMI 全稱 Kernel Module Interface，相同 KMI 的核心版本是**相容的**，這也是 GKI 中「標準」的涵義所在。反之，如果 KMI 不同，那麼這些核心之間無法彼此相容，寫入與您裝置 KMI 不同的核心映像可能會導致無法開機。
具體來講，對 GKI 的裝置，其核心版本格式應該如下：
具體來講，對於 GKI 的裝置，其核心版本格式應該如下：
```txt
KernelRelease :=
@@ -37,21 +37,27 @@ Version.PatchLevel.SubLevel-AndroidRelease-KmiGeneration-suffix
w .x .y -zzz -k -something
```
其中，`w.x-zzz-k` 為 KMI 版本。例如，一部裝置核心版本為 `5.10.101-android12-9-g30979850fc20`，那麼它的 KMI 為 `5.10-android12-9`；理論上刷新其他這個 KMI 的核心也能正常開機。
其中，`w.x-zzz-k` 為 KMI 版本。例如，一部裝置核心版本為 `5.10.101-android12-9-g30979850fc20`，那麼它的 KMI 為 `5.10-android12-9`，理論上寫入其他這個 KMI 的核心也能正常開機。
::: tip
::: tip 補充
請注意，核心版本中的 SubLevel 並非 KMI 的一部分！也就是說 `5.10.101-android12-9-g30979850fc20` 與 `5.10.137-android12-9-g30979850fc20` 的 KMI 相同！
:::
### 安全性修補程式等級 {#security-patch-level}
較新的 Android 裝置可能具有防回滾機制，不允許寫入具有較舊安全性修補程式等級的啟動映像。例如，如果您的裝置核心為 `5.10.101-android12-9-g30979850fc20`，則其安全修補程式等級為 `2023-11`；即使寫入了 KMI 對應的核心，如果安全修補程式等級早於 `2023-11`（例如 `2023-06`），也可能會導致無法開機。
因此，最好使用具有最新安全性修補程式等級的核心來維護與 KMI 的對應關係。
### 核心版本與 Android 版本 {#kernel-version-vs-android-version}
請注意：**核心版本與 Android 版本並不一定相同！**
如果您發現您的核心版本是 `android12-5.10.101`，然而您 Android 系統的版本為 Android 13 或者其他；請不要覺得奇怪，因為 Android 系統的版本與 Linux 核心的版本號碼並非一致；Linux 核心的版本號碼一般與**裝置出廠時隨附的 Android 系統的版本一致**，如果後續 Android 系統更新，核心版本一般不會發生變化。如果您需要刷新，**請以核心版本為準！！**
如果您發現您的核心版本是 `android12-5.10.101`，然而您 Android 系統的版本為 Android 13 或更高，請不要覺得奇怪，因為 Android 系統的版本與 Linux 核心的版本號碼並非一致。Linux 核心的版本號碼一般與**裝置出廠時隨附的 Android 系統的版本一致**，如果後續 Android 系統更新，核心版本一般不會發生變化。如果您需要寫入，**請以核心版本為準！！**
## 安裝簡介 {#introduction}
自 `0.9.0` 版本以後，在 GKI 裝置中，KernelSU 支援兩種運行模式：
自 `0.9.0` 版本以後，在 GKI 裝置上，KernelSU 支援兩種運作模式：
1. `GKI`：使用**通用核心鏡像**（GKI）取代掉裝置原有的核心。
2. `LKM`：使用**可載入核心模組**（LKM）的方式載入到裝置核心中，不會替換掉裝置原有的核心。
@@ -60,55 +66,56 @@ w .x .y -zzz -k -something
### GKI 模式 {#gki-mode}
GKI 模式會替換掉裝置原有的內核，使用 KernelSU 提供的通用內核鏡像。 GKI 模式的優點是：
GKI 模式會替換掉裝置原有的核心，使用 KernelSU 提供的通用核心鏡像。 GKI 模式的優點是：
1. 通用型強，適用於大多數裝置；例如三星開啟了 KNOX 的裝置，LKM 模式無法運作。還有一些冷門的魔改裝置，也只能使用 GKI 模式；
2. 不依賴官方韌體即可使用；不需要等待官方韌體更新，只要 KMI 一致，就可以使用；
1. 通用型高，適用於大多數裝置；例如開啟了 KNOX 的三星裝置、或是 LKM 模式無法運作的裝置。還有一些冷門的魔改裝置，也只能使用 GKI 模式。
2. 不依賴官方韌體即可使用；不需要等待官方韌體更新，只要 KMI 一致，就可以使用。
### LKM 模式 {#lkm-mode}
LKM 模式不會替換掉裝置原有的內核，而是使用可載入內核模組的方式載入到裝置內核中。 LKM 模式的優點是：
LKM 模式不會替換掉裝置原有的核心，而是使用可載入核心模組的方式載入到裝置核心中。 LKM 模式的優點是：
1. 不會取代裝置原有的核心；如果你對裝置原有的核心有特殊需求，或是你希望在使用第三方核心的同時使用 KernelSU，可以使用 LKM 模式；
2. 升級和 OTA 較為方便；升級 KernelSU 時，可以直接在管理器內部安裝，無需再手動刷寫；系統 OTA 後，可以直接安裝到第二個槽位，也無需再手動刷寫；
3. 適用於一些特殊場景；例如使用臨時 ROOT 權限也可以載入 LKM，由於不需要替換 boot 分區，因此不會觸發 avb，不會使裝置意外變磚；
4. LKM 可以被暫時卸載；如果你暫時想取消 root，可以卸載 LKM，這個過程不需要刷寫分區，甚至也不用重啟裝置；如果你想再次 root，只需要重啟裝置即可；
1. 不會取代裝置原有的核心：如果你對裝置原有的核心有特殊需求，或是你希望在使用第三方核心的同時使用 KernelSU，可以使用 LKM 模式。
2. 升級和 OTA 較為方便：升級 KernelSU 時，可以直接在管理器內部安裝，無需再手動寫入；系統 OTA 後，可以直接安裝到第二個槽位，也無需再手動寫入。
3. 適用於一些特殊場景：例如使用臨時 root 權限也可以載入 LKM，由於不需要替換 boot 分區，因此不會觸發 avb，不會使裝置意外變磚。
4. LKM 可以被暫時卸載：如果你暫時想取消 root，可以卸載 LKM，這個過程不需要寫入分區，甚至也不用重啟裝置。如果你想重新取得 root，只需要重啟裝置即可。
:::tip 兩種模式共存
打開管理器後，你可以在首頁看到裝置目前運行的模式；注意 GKI 模式的優先級高於 LKM ，如你你既使用 GKI 內核替換掉了原有的內核，又使用 LKM 的方式修補了 GKI 內核，那麼 LKM 會被忽略，裝置將永遠以 GKI 的模式運作。
打開管理器後，你可以在首頁看到裝置目前運行的模式。注意 GKI 模式的優先級高於 LKM ，如你既使用 GKI 核心替換掉了原有的核心，又使用 LKM 的方式修補了 GKI 核心，那麼 LKM 會被忽略，裝置將永遠以 GKI 的模式運作。
:::
### 選哪個？ {#which-one}
如果你的裝置是手機，我們建議您優先考慮 LKM 模式；如果你的裝置是模擬器、WSA 或 Waydroid 等，我們建議您優先考慮 GKI 模式。
如果你的裝置是手機，我們建議您優先考慮 LKM 模式。
如果你的裝置是模擬器、WSA 或 Waydroid 等，我們建議您優先考慮 GKI 模式。
## LKM 安裝 {#lkm-installation}
### 取得官方韌體 {#get-the-official-firmware}
使用 LKM 的模式，需要取得官方韌體，然後在官方韌體的基礎上修補；如果你使用的是第三方內核，可以把第三方內核的 boot.img 作為官方韌體。
使用 LKM 的模式，需要取得官方韌體，然後在官方韌體的基礎上修補；如果你使用的是第三方核心，可以把第三方核心的 boot.img 作為官方韌體。
取得官方韌體的方法有很多，如果你的裝置支援 `fastboot boot`，那麼我們最推薦以及最簡單的方法是使用 `fastboot boot` 臨時啟動 KernelSU 提供的 GKI 內核，然後安裝管理器，最後在管理器中直接安裝；這種方法不需要你手動下載官方韌體，也不需要你手動提取 boot。
取得官方韌體的方法有很多，如果你的裝置支援 `fastboot boot`，那麼我們最推薦以及最簡單的方法是使用 `fastboot boot` 臨時啟動 KernelSU 提供的 GKI 核心，並參考[使用管理器](#use-the-manager)安裝。
如果你的裝置不支援 `fastboot boot`，那麼你可能需要手動去下載官方韌體包，然後從中提取 boot。
與 GKI 模式不同，LKM 模式會修改 `ramdisk`，因此在出廠 Android 13 的裝置上，它需要修補的是 `init_boot` 分區而非 `boot` 分區；而 GKI 模式則永遠是操作 `boot` 分區。
與 GKI 模式不同，LKM 模式會修改 `ramdisk`，因此在出廠 Android 13 的裝置上，通常它需要修補的是 `init_boot` 分區而非 `boot` 分區；而 GKI 模式則永遠是修改 `boot` 分區。
### 使用管理器 {#use-the-manager}
開啟管理器，點選右上角的安裝圖標，會出現若干個選項：
1. 選擇並修補一個文件：如果你手機目前沒有 root 權限，你可以選擇這個選項，然後選擇你的官方韌體，管理器會自動修補它；你只需要刷入這個修補後的文件，即可永久取得 root 權限；
2. 直接安裝：如果你手機已經 root，你可以選擇這個選項，管理器會自動獲取你的裝置資訊，然後自動修補官方韌體，然後刷入；你可以考慮使用`fastboot boot` KernelSU 的 GKI 內核來取得臨時 root 安裝管理器，然後再使用這個選項；這種方式也是 KernelSU 升級最主要的方式；
3. 安裝到另一個分割區：如果你的裝置支援 A/B 分割區，你可以選擇這個選項，管理器會自動修補官方韌體，然後安裝到另一個分割區；這種方式適用於 OTA 後的裝置，你可以在 OTA 後直接安裝到另一個分割區，然後重新啟動裝置即可；
1. 選擇並修補一個文件：如果你手機目前沒有 root 權限，你可以選擇這個選項，然後選擇你的官方韌體，管理器會自動修補它。你只需要寫入這個修補後的文件，即可永久取得 root 權限。
2. 直接安裝：如果你手機已經 root，你可以選擇這個選項，管理器會自動獲取你的裝置資訊，然後自動修補官方韌體，然後寫入。你可以考慮使用 `fastboot boot` KernelSU 的 GKI 核心來取得臨時 root 安裝管理器，然後再使用這個選項。**這種方式也是 KernelSU 升級最主要的方式**。
3. 安裝到另一個分割區：如果你的裝置支援 A/B 分區，你可以選擇這個選項，管理器會自動修補官方韌體，然後安裝到另一個分區。這種方式適用於 OTA 後的裝置，你可以在 OTA 後直接安裝到另一個分割區，然後重新啟動裝置即可。
### 使用命令列
### 使用命令列{#use-the-command-line}
如果你不想使用管理器，你也可以使用命令列來安裝 LKM；KernelSU 提供的 `ksud` 工具可以幫助你快速修補官方韌體，然後刷入。
如果你不想使用管理器，你也可以使用命令列來安裝 LKM。KernelSU 提供的 `ksud` 可以幫助你快速修補官方韌體，然後寫入。
這個工具支援 macOS、Linux 和 Windows，你可以在 [GitHub Release](https://github.com/tiann/KernelSU/releases) 下載對應的版本。
使用方法：`ksud boot-patch` 具體的使用方法你可以查看命令列幫助。
使用方法：`ksud boot-patch`。 你可以查看命令列的提示了解具體的使用方法。
```sh
husky:/ # ksud boot-patch -h
@@ -129,126 +136,130 @@ Options:
-h, --help Print help
```
需要說明的幾個選項：
1. `--magiskboot` 選項可以指定 magiskboot 的路徑，如果不指定，ksud 會在環境變數中尋找；如果你不知道如何取得 magiskboot，可以參考[這裡](#patch-boot-image)；
2. `--kmi` 選項可以指定 `KMI` 版本，如果你的裝置核心名字沒有遵循 KMI 規範，你可以透過這個選項來指定；
1. `--magiskboot` 選項可以指定 magiskboot 的路徑，如果不指定，ksud 會在環境變數中尋找。如果你不知道如何取得 magiskboot，可以參考[這裡](#patch-boot-image)。
2. `--kmi` 選項可以指定 `KMI` 版本，如果你的裝置核心名字沒有遵循 KMI 規範，你可以透過這個選項來指定。
最常見的使用方法為：
```sh
ksud boot-patch -b <boot.img> --kmi android13-5.10
```
## GKI 安裝
## GKI 安裝{#gki-mode-installation}
GKI 的安裝方式有以下幾種，各自適用於不同的場景，請依需求選擇：
1. 使用自訂 Recovery (如 TWRP) 安裝
2. 使用核心刷新應用程式 (例如 Franco Kernel Manager) 安裝
3. 使用 KernelSU 提供的 boot.img 透過 Fastboot 安裝
1. 使用 KernelSU 提供的 boot.img 透過 Fastboot 安裝
2. 使用核心寫入程式 (例如 KernelFlasher) 安裝
3. 使用自訂 Recovery (例如 TWRP) 安裝
4. 手動修補 boot.img 並安裝
## 使用自訂 Recovery 安裝 {#install-by-recovery}
先決條件：您的裝置必須有自訂的 Recovery，例如 TWRP；如果沒有或者只有官方 Recovery，請使用其他方法。
步驟：
1. 在 KernelSU 的 [Release 頁面](https://github.com/tiann/KernelSU/releases) 下載與您手機版本相符的以 AnyKernel3 開頭的 Zip 套件；例如，手機核心版本為 `android12-5.10.66`，那麼您應該下載 `AnyKernel3-android12-5.10.66_yyyy-MM.zip` 這個檔案 (其中 `yyyy` 為年份，`MM` 為月份)。
2. 重新開機手機至 TWRP。
3. 使用 Adb 將 AnyKernel3-*.zip 放置到手機 /sdcard 然後在 TWRP 圖形使用者介面選擇並安裝；或者您也可以直接 `adb sideload AnyKernel-*.zip` 安裝。
PS. 這種方法適用於任何狀況下的安裝 (不限於初次安裝或後續更新)，只要您用 TWRP 就可以進行作業。
## 使用核心刷新應用程式安裝 {#install-by-kernel-flasher}
先決條件：您的裝置必須已經 Root。例如您已經安裝了 Magisk 並取得 Root 存取權，或者您已經安裝了舊版本的 KernelSU 需升級到其他版本的 KernelSU；如果您的裝置並未 Root，請嘗試其他方法。
步驟：
1. 下載 AnyKernel3 的 Zip 檔案；請參閱 *使用自訂 Recovery 安裝* 章節的内容。
2. 開啟核心刷新應用程式提供的 AnyKernel3 Zip 檔案進行刷新。
如果您先前並未使用過核心刷新應用程式，可以嘗試下面幾個方法：
1. [Kernel Flasher](https://github.com/capntrips/KernelFlasher/releases)
2. [Franco Kernel Manager](https://play.google.com/store/apps/details?id=com.franco.kernel)
3. [Ex Kernel Manager](https://play.google.com/store/apps/details?id=flar2.exkernelmanager)
PS. 這種方法在更新 KernelSU 時比較方便，無需電腦即可完成 (注意備份！)。
## 使用 KernelSU 提供的 boot.img 安裝 {#install-with-boot-img-provided-by-kernelsu}
這種方法無需您有 TWRP，也無需您的手機有 Root 權限；適用於您初次安裝 KernelSU。
如果你的裝置的 `boot.img` 使用常見的壓縮格式，你可以直接寫入 KernelSU 提供的 GKI 核心映像，這種方法無需 TWRP，也無需您的手機有 Root 權限；適用於您初次安裝 KernelSU。
### 找到合適的 boot.img {#find-proper-boot-img}
KernelSU 為 GKI 裝置提供了標準 boot.img，您需要將 boot.img 刷新至裝置的 Boot 分割區。
KernelSU 為 GKI 裝置提供了標準 boot.img，您需要將 boot.img 寫入至裝置的 Boot 分區。
您可以從 [GitHub Release](https://github.com/tiann/KernelSU/releases) 下載 boot.img，請注意，您應該使用正確版本的 boot.img。例如，如果您的裝置顯示核心是 `android12-5.10.101`，需要下載 `android-5.10.101_yyyy-MM.boot-<format>.img`.
您可以從 [GitHub Release](https://github.com/tiann/KernelSU/releases) 下載 boot.img，請注意，您應該使用正確版本的 boot.img。如果你不知道你該下載哪個檔案，請詳細閱讀文檔中的 [KMI](#kmi) 與[安全性修補程式等級](#security-patch-level)。
其中 `<format>` 指的是您的官方 boot.img 的核心壓縮格式，請檢查您原有 boot.img 的核心壓縮格式，您應該使用正確的格式，例如 `lz4`、`gz`；如果使用不正確的壓縮格式，刷新 Boot 後可能無法開機。
通常，在相同的 KMI 和安全性修補程式等級下，會存在三種不同格式的啟動檔案。除了核心壓縮格式之外，它們都是相同的。請檢查您原來的 boot.img 的核心壓縮格式。您應該使用正確的格式，例如 `lz4` 、 `gz`，如果你使用了不正確的壓縮格式，你可能會在寫入後無法開機。
::: info
1. 您可以透過 magiskboot 以取得您的原始 Boot 的壓縮格式；當然，您也可以詢問與您相同型號的其他更有經驗的使用者。另外，核心的壓縮格式通常部會出現變更，如果您使用的某個壓縮格式成功開機，後續可以優先嘗試這個格式。
::: info 關於 boot.img 的壓縮格式
1. 您可以透過 magiskboot 以取得您的原始 Boot 的壓縮格式。當然，您也可以詢問與您相同型號的其他更有經驗的使用者。另外，核心的壓縮格式通常不會出現變更，如果您使用的某個壓縮格式成功開機，後續可以優先嘗試這個格式。
2. 小米裝置通常 `gz` 或者 **不壓縮**。
3. Pixel 裝置有些特殊，請遵循下方的指示。
:::
### 將 boot.img 刷新至裝置 {#flash-boot-img-to-device}
### 將 boot.img 寫入至裝置 {#flash-boot-img-to-device}
使用 `adb` 連接您的裝置，然後執行 `adb reboot bootloader` 進入 fastboot 模式，然後使用此命令刷新 KernelSU：
使用 `adb` 連接您的裝置，然後執行 `adb reboot bootloader` 進入 fastboot 模式，然後使用此命令寫入 KernelSU：
```sh
fastboot flash boot boot.img
```
::: info
如果您的裝置支援 `fastboot boot`，可以先使用 `fastboot boot boot.img` 來先嘗試使用 boot.img 開機進入系統，如果出現意外，重新啟動即可開機。
::: info 提示
如果您的裝置支援 `fastboot boot`，可以先使用 `fastboot boot boot.img` 來嘗試使用 boot.img 開機進入系統，如果出現意外，重新啟動即可開機。
:::
### 重新開機 {#reboot}
刷新完成後，您應該重新啟動您的裝置：
寫入完成後，您應該重新啟動您的裝置：
```sh
fastboot reboot
```
## 使用核心寫入程式安裝 {#install-with-kernel-flasher}
先決條件：您的裝置必須已經 Root。例如您已經安裝了 Magisk 並取得 Root 存取權，或者您已經安裝了舊版本的 KernelSU 需升級到其他版本的 KernelSU；如果您的裝置並未 Root，請嘗試其他方法。
步驟：
1. 下載 AnyKernel3 的 Zip 檔。如果你不知道你該下載哪個檔案，請詳細閱讀文檔中的 [KMI](#kmi) 與[安全性修補程式等級](#security-patch-level)。
2. 開啟核心寫入程式提供的 AnyKernel3 Zip 檔案並寫入核心。
如果您先前並未使用過核心寫入應用程式，可以嘗試下面幾個：
1. [Kernel Flasher](https://github.com/capntrips/KernelFlasher/releases)
2. [Franco Kernel Manager](https://play.google.com/store/apps/details?id=com.franco.kernel)
3. [Ex Kernel Manager](https://play.google.com/store/apps/details?id=flar2.exkernelmanager)
P.S. 這種方法在更新 KernelSU 時比較方便，無需電腦即可完成 (注意備份！)。
## 手動修補 boot.img {#patch-boot-image}
對於某些裝置來說，其 boot.img 格式並不是很常見，比如 `lz4`，`gz` 和未壓縮；最典型的就是 Pixel，它的 boot.img 格式是 `lz4_legacy` 壓縮，ramdisk 可能是 `gz` 也可能是 `lz4_legacy` 壓縮；此時如果您直接刷新 KernelSU 提供的 boot.img，手機可能無法開機；這時，您可以透過手動修補 boot.img 來完成。
對於某些裝置來說，其 boot.img 格式並不是很常見，不屬於 `lz4`，`gz` 和未壓縮；最典型的就是 Pixel，它的 boot.img 格式是 `lz4_legacy` 壓縮，ramdisk 可能是 `gz` 也可能是 `lz4_legacy` 壓縮；此時如果您直接寫入 KernelSU 提供的 boot.img，手機可能無法開機。這時，您可以透過手動修補 boot.img 來完成。
一般有兩種修補方法：
永遠建議使用 `magiskboot` 來修補映像，一般有兩種修補方法：
1. [Android-Image-Kitchen](https://forum.xda-developers.com/t/tool-android-image-kitchen-unpack-repack-kernel-ramdisk-win-android-linux-mac.2073775/)
2. [magiskboot](https://github.com/topjohnwu/Magisk/releases)
1. [magiskboot](https://github.com/topjohnwu/Magisk/releases)
2. [magiskboot_build](https://github.com/ookiineko/magiskboot_build/releases/tag/last-ci)
其中，Android-Image-Kitchen 適用於在電腦上作業，magiskboot 需要手機協作。
其中，官方的 `magiskboot` 僅能在 Android 上使用，若您想在電腦上完成，可以嘗試第二個選項。
### 準備 {#patch-preparation}
### 準備 {#preparation}
1. 取得您手機的原廠 boot.img；您可以聯絡您的裝置製造商，您也可能需要[payload-dumper-go](https://github.com/ssut/payload-dumper-go)
2. 下載 KernelSU 提供的與您的裝置 KMI 一致地 AnyKernel3 Zip 檔案 (可參閱 *使用自訂 Recovery 安裝*)。
3. 解壓縮 AnyKernel3 Zip 檔案，取得其中的 `Image` 檔案，此檔案為 KernelSU 的核心檔案。
1. 取得您手機的原廠 boot.img，您可以從您的裝置製造商取得，您也可能需要 [payload-dumper-go](https://github.com/ssut/payload-dumper-go)。
2. 下載 KernelSU 提供的與您的裝置 KMI 一致的 AnyKernel3 Zip 檔 (可參閱[使用自訂 Recovery 安裝](#install-with-custom-recovery))。
3. 解壓縮 AnyKernel3 Zip 檔，取得其中的 `Image` 檔，此檔案為具有 KernelSU 的核心。
### 使用 Android-Image-Kitchen {#using-android-image-kitchen}
### 在 Android 上使用 magiskboot {#using-magiskboot-on-Android-devices}
1. 下載 Android-Image-Kitchen 至您的電腦。
2. 將手機原廠 boot.img 放置於 Android-Image-Kitchen 根目錄。
3. 在 Android-Image-Kitchen 根目錄執行 `./unpackimg.sh boot.img`；此命令會將 boot.img 解除封裝，您會得到一些檔案。
4. 將 `split_img` 目錄中的 `boot.img-kernel` 取代為您從 AnyKernel3 解壓縮出來的 `Image` (注意名稱變更為 boot.img-kernel)。
5. 在 Android-Image-Kitchecn 根目錄執行 `./repackimg.sh`；此時您會得到一個 `image-new.img` 檔案；使用此 boot.img 透過 fastboot 刷新即可 (刷新方法請參閱上一章節)。
### 使用 magiskboot {#using magiskboot}
1. 在 Magisk 的 [Release 頁面](https://github.com/topjohnwu/Magisk/releases) 下載最新的 Magisk 安裝套件。
2. 將 `Magisk-*(version).apk` 重新命名為 `Magisk-*.zip` 然後解壓縮。
3. 將解壓縮後的 `Magisk-*/lib/arm64-v8a/libmagiskboot.so` 檔案，使用 Adb 推入至手機：`adb push Magisk-*/lib/arm64-v8a/libmagiskboot.so /data/local/tmp/magiskboot`
1. 在 Magisk 的 [Release 頁面](https://github.com/topjohnwu/Magisk/releases) 下載最新的 Magisk。
2. 將 `Magisk-*(version).apk` 重新命名為 `Magisk-*.zip` 並解壓縮。
3. 使用 Adb 將 magiskboot 推入至手機：`adb push Magisk-*/lib/arm64-v8a/libmagiskboot.so /data/local/tmp/magiskboot`。
4. 使用 Adb 將原廠 boot.img 和 AnyKernel3 中的 Image 推入至手機。
5. adb shell 進入 /data/local/tmp/ 目錄，然後賦予先前推入檔案的可執行權限 `chmod +x magiskboot`
5. adb shell 進入 /data/local/tmp/ 目錄，然後賦予先前推入的檔案可執行權限 `chmod +x magiskboot`。
6. adb shell 進入 /data/local/tmp/ 目錄，執行 `./magiskboot unpack boot.img` 此時會將 `boot.img` 解除封裝，得到一個名為 `kernel` 的檔案，這個檔案是您的原廠核心。
7. 使用 `Image` 取代 `kernel`: `mv -f Image kernel`
8. 執行 `./magiskboot repack boot.img` 重新封裝 img，此時您會得到一個 `new-boot.img` 檔案，透過 Fastboot 將這個檔案刷新至裝置即可。
8. 執行 `./magiskboot repack boot.img` 重新封裝映像，此時您會得到一個 `new-boot.img` 檔案，透過 Fastboot 將這個檔案寫入至裝置即可。
### 在 Windows/macOS/Linux PC 上使用 magiskboot {#using-magiskboot-on-PC}
1. 在 [magiskboot_build](https://github.com/ookiineko/magiskboot_build/releases/tag/last-ci) 下載對應的 magiskboot。
2. (僅linux)賦予檔案可執行權限 `chmod +x magiskboot`。
3. 執行 `./magiskboot unpack boot.img` 此時會將 `boot.img` 解除封裝，得到一個名為 `kernel` 的檔案，這個檔案是您的原廠核心。
4. 使用 `Image` 取代 `kernel`: `mv -f Image kernel`
5. 執行 `./magiskboot repack boot.img` 重新封裝映像，此時您會得到一個 `new-boot.img` 檔案，透過 Fastboot 將這個檔案寫入至裝置即可。
## 使用自訂 Recovery 安裝 {#install-with-custom-recovery}
先決條件：您的裝置必須有自訂的 Recovery，例如 TWRP。如果沒有或者只有官方 Recovery，請使用其他方法。
步驟：
1. 在 KernelSU 的 [Release 頁面](https://github.com/tiann/KernelSU/releases) 下載與您手機版本相符的以 AnyKernel3 開頭的 Zip 檔；例如，手機核心版本為 `android12-5.10.66`，那麼您應該下載 `AnyKernel3-android12-5.10.66_yyyy-MM.zip` 這個檔案 (其中 `yyyy` 為年份，`MM` 為月份)。
2. 重新開機手機至 TWRP。
3. 使用 Adb 將 AnyKernel3-*.zip 放置到手機 `/sdcard` 然後在 TWRP 圖形使用者介面選擇並安裝；或者您也可以直接 `adb sideload AnyKernel-*.zip` 安裝。
PS. 這種方法適用於任何狀況下的安裝 (不限於初次安裝或後續更新)，只要您用 TWRP 就可以進行作業。
## GKI的其他替代方法 {#other-methods}
其實所有這些安裝方法的主旨只有一個，那就是**將原廠核心取代為 KernelSU 提供的核心**；只要能實現這個目的，就可以安裝；比如以下是其他可行的方法：
其實所有這些安裝方法的主旨只有一個，那就是**將原廠核心取代為 KernelSU 提供的核心**。只要能實現這個目的，就可以安裝，比如以下是其他可行的方法：
1. 首先安裝 Magisk，透過 Magisk 取得 Root 權限後使用核心寫入程式寫入 KernelSU 的 AnyKernel Zip。
2. 使用某些 PC 上的寫入工具組寫入 KernelSU 提供的核心。
但是，如果不起作用，請嘗試 Magiskboot 方法。
1. 首先安裝 Magisk，透過 Magisk 取得 Root 權限後使用核心刷新程式刷新 KernelSU 的 AnyKernel Zip。
2. 使用某些 PC 上的刷新工具組刷新 KernelSU 提供的核心。

17
website/docs/zh_TW/guide/module-webui.md
View File

@@ -2,11 +2,11 @@
KernelSU 的模組除了執行啟動腳本和修改系統檔案之外，還支援顯示 UI 介面和與使用者互動。
該模組可以透過任何 Web 技術編寫HTML + CSS + JavaScript頁面。 KernelSU的管理器將透過 WebView 顯示這些頁面。它還提供了一些用於與系統互動的JavaScript API，例如執行shell命令。
該模組可以透過任何 Web 技術編寫 HTML + CSS + JavaScript 頁面。 KernelSU的管理器將透過 WebView 顯示這些頁面。它還提供了一些用於與系統互動的 JavaScript API，例如執行 shell 命令。
## WebUI 根目錄 {#webroot-directory}
Web資源應放置在模組根目錄的`webroot`子目錄中，並且其中**必須**有一個名為`index.html`的文件，該檔案是模組頁面入口。
Web資源應放置在模組根目錄的 `webroot` 子目錄中，並且其中**必須**有一個名為 `index.html` 的文件，該檔案是模組頁面入口。
包含Web介面的最簡單的模組結構如下：
@@ -18,7 +18,7 @@ Web資源應放置在模組根目錄的`webroot`子目錄中，並且其中**必
`-- index.html
```
:::warning
:::warning 提醒
安裝模組時，KernelSU 將自動設定`webroot`的權限和 SELinux context。如果您不知道自己在做什麼，請不要自行設定該目錄的權限！
:::
@@ -28,7 +28,7 @@ Web資源應放置在模組根目錄的`webroot`子目錄中，並且其中**必
如果只是一個顯示頁面，那和一般網頁沒有什麼不同。更重要的是，KernelSU 提供了一系列的系統 API，讓您可以實現模組獨特的功能。
KernelSU 提供了一個 JavaScript 庫並[在 npm 上發布](https://www.npmjs.com/package/kernelsu)，您可以在網頁的 JavaScript 程式碼中使用它。
KernelSU [在 npm 上發布](https://www.npmjs.com/package/kernelsu)了一個 JavaScript 庫，您可以在網頁的 JavaScript 程式碼中使用它。
例如，您可以執行 shell 命令來取得特定配置或修改屬性：
@@ -42,8 +42,9 @@ const { errno, stdout } = exec("getprop ro.product.model");
[API 文檔](https://www.npmjs.com/package/kernelsu)
如果您發現現有的API無法滿足您的需求或使用不方便，歡迎您在[這裡](https://github.com/tiann/KernelSU/issues)給我們建議！
## 一些技巧
如果您發現現有的 API 無法滿足您的需求或使用不方便，歡迎您在[這裡](https://github.com/tiann/KernelSU/issues)給我們建議！
1. 您可以正常使用`localStorage`來儲存一些數據，但卸載管理器後，這些數據將會遺失。如果需要持久保存，可以自行將資料寫入某個目錄。
2. 對於簡單的頁面，我建議您使用[parceljs](https://parceljs.org/)進行打包。它無須設定，使用非常方便。不過，如果你是前端高手或有自己的喜好，那就選擇你喜歡的吧！
## 一些技巧 {#some-tips}
1. 您可以正常使用 `localStorage` 來儲存一些數據，但解除安裝管理器後，這些數據將會遺失。如果需要持久保存，可以自行將資料寫入某個目錄。
2. 對於簡單的頁面，我建議您使用 [parceljs](https://parceljs.org/) 進行打包。它無須設定，使用非常方便。不過，如果你是前端高手或有自己的喜好，那就選擇你喜歡的吧！

111
website/docs/zh_TW/guide/module.md
View File

@@ -1,8 +1,8 @@
# 模組指南 {#introduction}
# 模組指南 {#module-guide}
KernelSU 提供了一個模組機制，它可以在保持系統分割區完整性的同時達到修改系統分割區的效果；這種機制一般被稱為 systemless。
KernelSU 提供了一個模組機制，它可以在保持系統分割區完整性的同時達到修改系統分割區的效果；這種機制一般被稱為 systemless (無系統修改)。
KernelSU 的模組運作機制與 Magisk 幾乎相同，如果您熟悉 Magisk 模組的開發，那麼開發 KernelSU 的模組大同小異，您可以跳過下列有關模組的介紹，只需要瞭解 [KernelSU 模組與 Magisk 模組的異同](difference-with-magisk.md)。
KernelSU 的模組運作機制與 Magisk 幾乎相同，如果您熟悉 Magisk 模組的開發，那麼開發 KernelSU 的模組大同小異，您可以跳過下列有關模組的介紹，只需要瞭解 [KernelSU 模組與 Magisk 模組的差異](difference-with-magisk.md)。
## WebUI
@@ -11,20 +11,20 @@ KernelSU 的模組支援顯示互動介面，請參閱 [WebUI 文檔](module-web
## Busybox
KernelSU 提供了一個完備的 BusyBox 二進位檔案 (包括完整的 SELinux 支援)。可執行檔位於 `/data/adb/ksu/bin/busybox`。
KernelSU 的 BusyBox 支援同時執行時可切換的 "ASH Standalone Shell Mode"。
這種讀了模式意味著在執行 BusyBox 的 ash shell 時，每個命令都會直接使用 BusyBox 中內建的應用程式，而不論 PATH 的設定為何。
例如，`ls`、`rm`、`chmod` 等命令將不會使用 PATH 中設定的命令 (在 Android 的狀況下，預設狀況下分別為 `/system/bin/ls`、`/system/bin/rm` 和 `/system/bin/chmod`)，而是直接呼叫 BusyBox 內建的應用程式。
KernelSU 的 BusyBox 支援執行時可切換的 "ASH 獨立模式"。
ASH 獨立模式在執行 BusyBox 時，每個命令都會直接使用 BusyBox 中內建的應用程式，而不論 `PATH` 的設定為何。
例如，`ls`、`rm`、`chmod` 等命令將不會使用 `PATH` 中設定的命令 (在 Android 的狀況下，預設狀況下分別為 `/system/bin/ls`、`/system/bin/rm` 和 `/system/bin/chmod`)，而是直接呼叫 BusyBox 內建的應用程式。
這確保了腳本始終在可預測的環境中執行，並始終具有完整的命令套件，不論它執行在哪個 Android 版本上。
要強制下一個命令不使用 BusyBox，您必須使用完整路徑呼叫可執行檔。
在 KernelSU 上下文中執行的每個 shell 腳本都將在 BusyBox 的 ash shell 中以獨立模式執行。對於第三方開發人員相關的內容，包括所有開機腳本和模組安裝腳本。
每個基於 KernelSU 上下文的腳本都將在 BusyBox 的獨立模式執行。對於第三方開發人員而言，這包括所有開機腳本和模組安裝腳本。
對於想要在 KernelSU 之外使用這個「獨立模式」功能的使用者，有兩種啟用方法：
1. 將環境變數 `ASH_STANDALONE` 設為 `1`。例如：`ASH_STANDALONE=1 /data/adb/ksu/bin/busybox sh <script>`
2. 使用命令列選項切換：`/data/adb/ksu/bin/busybox sh -o standalone <script>`
為了確保所有後續的 `sh` shell 都在獨立模式下執行，第一種是首選方法 (這也是 KernelSU 和 KernelSU 管理員內部使用的方法)，因為環境變數會被繼承到子處理程序中。
為了確保所有後續的 `sh` shell 都在獨立模式下執行，第一種是首選方法 (這也是 KernelSU 和 KernelSU 管理器內部使用的方法)，因為環境變數會被繼承到子執行緒中。
::: tip 與 Magisk 的差異
KernelSU 的 BusyBox 現在是直接使用 Magisk 專案編譯的二進位檔案，**感謝 Magisk！**
@@ -86,12 +86,12 @@ KernelSU 模組是一個放置於 `/data/adb/modules` 且滿足下列結構的
```
::: tip 與 Magisk 的差異
KernelSU 沒有內建的針對 Zygisk 的支援，因此模組中沒有與 Zygisk 相關的內容，但您可以透過 [ZygiskNext](https://github.com/Dr-TSNG/ZygiskNext) 以支援 Zygisk 模組，此時 Zygisk 模組的內容與 Magisk 所支援的 Zygisk 完全相同。
KernelSU 沒有內建的針對 Zygisk 的支援，因此模組中沒有與 Zygisk 相關的內容，但您可以透過安裝 [ZygiskNext](https://github.com/Dr-TSNG/ZygiskNext) 以支援 Zygisk 模組，此時 Zygisk 模組的內容與 Magisk 所支援的 Zygisk 完全相同。
:::
### module.prop
module.prop 是一個模組的組態檔案，在 KernelSU 中如果模組中不包含這個檔案，那麼它將不被認為是一個模組；這個檔案的格式如下：
module.prop 是一個模組的設定檔，在 KernelSU 中如果模組中不包含這個檔案，那麼它將不被認為是一個模組；這個檔案的格式如下：
```txt
id=<string>
@@ -102,7 +102,7 @@ author=<string>
description=<string>
```
- id 必須與這個規則運算式相符：`^[a-zA-Z][a-zA-Z0-9._-]+$` 例如：✓ `a_module`，✓ `a.module`，✓ `module-101`，✗ `a module`，✗ `1_module`，✗ `-a-module`。這是您的模組的唯一識別碼，發表後將無法變更。
- id 必須與這個正則表達式相符：`^[a-zA-Z][a-zA-Z0-9._-]+$` 例如：✓ `a_module`，✓ `a.module`，✓ `module-101`，✗ `a module`，✗ `1_module`，✗ `-a-module`。這是您的模組的唯一識別碼，發表後將無法變更。
- versionCode 必須是一個整數，用於比較版本。
- 其他未在上方提到的內容可以是任何單行字串。
- 請確保使用 `UNIX (LF)` 分行符號類型，而非 `Windows (CR + LF)` 或 `Macintosh (CR)`。
@@ -110,6 +110,8 @@ description=<string>
### Shell 腳本 {#shell-scripts}
請閱讀 [開機腳本](#boot-scripts) 章節，以瞭解 `post-fs-data.sh` 和 `service.sh` 之間的差別。對於大多數模組開發人員來說，如果您只需要執行一個開機腳本，`service.sh` 應該已經足夠了。
如果您需要在啟動完成後執行腳本，請使用 `boot-completed.sh`。
如果你想在掛載 overlayfs 後做一些事情，請使用 `post-mount.sh`。
在您的模組中的所有腳本中，請使用 `MODDIR=${0%/*}` 以取得您的模組基本目錄路徑；請不要在腳本中以硬式編碼的方式加入您的模組路徑。
@@ -119,7 +121,7 @@ description=<string>
### `system` 目錄 {#system-directories}
這個目錄的內容會在系統啟動後，以 `overlayfs` 的方式覆疊在系統的 `/system` 分割區之上，這表示：
這個目錄的內容會在系統啟動後，以 `overlayfs` 的方式覆疊在系統的 `/system` 分區之上，這表示：
1. 系統中對應目錄的相同名稱的檔案會被此目錄中的檔案覆寫。
2. 系統中對應目錄的相同名稱的檔案會與此目錄的檔案合併。
@@ -152,10 +154,10 @@ REPLACE="
::: tip 與 Magisk 的差異
KernelSU 的 systemless 機制透過核心的 overlayfs 實作，而 Magisk 目前則是透過 magic mount (bind mount)，兩者的實作方式有很大的差別，但最終的目標是一致的：不修改實際的 `/system` 分割區但修改 `/system` 檔案。
KernelSU 的 systemless 機制透過核心的 overlayfs 實作，而 Magisk 目前則是透過 magic mount (bind mount)，兩者的實作方式有很大的差別，但最終的目標是一致的：不修改實際的 `/system` 分區但修改 `/system` 檔案。
:::
如果您對 overlayfs 感興趣，建議閱讀 Linux Kernel 關於 [overlayfs 的文件](https://docs.kernel.org/filesystems/overlayfs.html)
如果您對 overlayfs 感興趣，建議閱讀 Linux Kernel 關於 [overlayfs 的文檔](https://docs.kernel.org/filesystems/overlayfs.html)
### system.prop
@@ -163,7 +165,7 @@ KernelSU 的 systemless 機制透過核心的 overlayfs 實作，而 Magisk 目
### sepolicy.rule
如果您的模組需要一些額外 SELinux 原則修補程式，請將這些原則新增至這個檔案中。這個檔案的每一行都將被視為一個原則陳述。
如果您的模組需要一些額外 sepolicy 修補，請將這些原則新增至這個檔案中。這個檔案的每一行都將被視為一個原則陳述。
## 模組安裝程式 {#module-installer}
@@ -179,15 +181,15 @@ module.zip
│
```
:::warning
:::warning 警告
KernelSU 模組不支援在 Recovery 中安裝！！
:::
### 自訂安裝程序 {#customizing-installation}
### 自訂安裝過程 {#customizing-installation}
如果您想要控制模組的安裝程序，可以在模組的目錄下建立一個名為 `customize.sh` 的檔案，這個檔案將會在模組被解壓縮後**匯入**至目前的 shell 中，如果您的模組需要依據裝置的 API 版本或裝置架構執行一些額外的作業，這個腳本將非常有用。
如果您想要控制模組的安裝過程，可以在模組的目錄下建立一個名為 `customize.sh` 的檔案，這個檔案將會在模組被解壓縮後經由 **source** 調用，如果您的模組需要依據裝置的 API 版本或裝置架構執行一些額外的作業，這個腳本將非常有用。
如果您想完全控制腳本的安裝程序，您可以在 `customize.sh` 中宣告 `SKIPUNZIP=1` 以跳過所有的預設安裝步驟；此時，您需要自行處理所有的安裝程序 (例如解壓縮模組、設定權限等)
如果您想完全控制腳本的安裝過程，您可以在 `customize.sh` 中宣告 `SKIPUNZIP=1` 以跳過所有的預設安裝步驟。此時，您需要自行處理所有的安裝過程(例如解壓縮模組、設定權限等)。
`customize.sh` 腳本以「獨立模式」執行在 KernelSU 的 BusyBox `ash` shell 中。您可以使用下列變數和函式：
@@ -205,7 +207,7 @@ KernelSU 模組不支援在 Recovery 中安裝！！
- `IS64BIT` (bool): 是否為 64 位元裝置
- `API` (int): 目前裝置的 Android API 版本 (例如 Android 6.0 上為 `23`)
::: warning
::: warning 警告
`MAGISK_VER_CODE` 在 KernelSU 永遠為 `25200`，`MAGISK_VER` 則為 `v25.2`，請不要透過這兩個變數來判斷是否為 KernelSU！
:::
@@ -243,7 +245,7 @@ set_perm_recursive <directory> <owner> <group> <dirpermission> <filepermission>
- 這個階段是 **阻塞** 的。在執行完成之前或 10 秒鐘之後，開機程序會被暫停。
- 腳本在任何模組被掛接之前執行。這使模組開發人員可以在模組被掛接之前動態調整他們的模組。
- 這個階段發生在 Zygote 啟動之前，這意味著 Android 中的一切。
- 使用 `setprop` 會導致開機程序死鎖！請使用 `resetprop -n <prop_name> <prop_value>` 替代。
- **警告**: 使用 `setprop` 會導致開機程序死鎖！請使用 `resetprop -n <prop_name> <prop_value>` 替代。
- **僅在必要時在此模式中執行腳本**。
- late_start 服務模式
@@ -261,6 +263,69 @@ set_perm_recursive <directory> <owner> <group> <dirpermission> <filepermission>
- 模組腳本
- 放置於模組自己的資料夾中。
- 僅有在模組啟用時才會執行。
- `post-fs-data.sh` 以 post-fs-data 模式運行，`post-mount.sh` 以 post-mount 模式運行，而`service.sh` 則以 late_start 服務模式運行，`boot-completed`在 Android 系統啟動完畢後以服務模式運作。
- `post-fs-data.sh` 以 post-fs-data 模式運行，`post-mount.sh` 在 overlayfs 掛載後運行，而 `service.sh` 則以 late_start 服務模式運行，`boot-completed` 在 Android 系統啟動完畢後以服務模式運作。
所有啟動腳本都將在 KernelSU 的 BusyBox ash shell 中執行，並啟用**獨立模式**。
所有啟動腳本都將在 KernelSU 的 BusyBox ash shell 中執行，並啟用**獨立模式**。
### 開機腳本解釋 {#boot-scripts-process-explanation}
以下是Android的相關啟動流程（部分省略），其中包括KernelSU的運行（帶前導星號），可以幫助您更好地理解這些模組腳本的用途：
```txt
0. Bootloader (nothing on screen)
load patched boot.img
load kernel:
- GKI mode: GKI kernel with KernelSU integrated
- LKM mode: stock kernel
...
1. kernel exec init (oem logo on screen):
- GKI mode: stock init
- LKM mode: exec ksuinit, insmod kernelsu.ko, exec stock init
mount /dev, /dev/pts, /proc, /sys, etc.
property-init -> read default props
read init.rc
...
early-init -> init -> late_init
early-fs
start vold
fs
mount /vendor, /system, /persist, etc.
post-fs-data
*safe mode check
*execute general scripts in post-fs-data.d/
*load sepolicy.rule
*mount tmpfs
*execute module scripts post-fs-data.sh
**(Zygisk)./bin/zygisk-ptrace64 monitor
*(pre)load system.prop (same as resetprop -n)
*remount modules /system
*execute general scripts in post-mount.d/
*execute module scripts post-mount.sh
zygote-start
load_all_props_action
*execute resetprop (actual set props for resetprop with -n option)
... -> boot
class_start core
start-service logd, console, vold, etc.
class_start main
start-service adb, netd (iptables), zygote, etc.
2. kernel2user init (rom animation on screen, start by service bootanim)
*execute general scripts in service.d/
*execute module scripts service.sh
*set props for resetprop without -p option
**(Zygisk) hook zygote (start zygiskd)
**(Zygisk) mount zygisksu/module.prop
start system apps (autostart)
...
boot complete (broadcast ACTION_BOOT_COMPLETED event)
*execute general scripts in boot-completed.d/
*execute module scripts boot-completed.sh
3. User operable (lock screen)
input password to decrypt /data/data
*actual set props for resetprop with -p option
start user apps (autostart)
```
如果您對 Android 的 Init 語言感興趣，建議閱讀它的 [文檔](https://android.googlesource.com/platform/system/core/+/master/init/README.md).

26
website/docs/zh_TW/guide/rescue-from-bootloop.md
View File

@@ -1,24 +1,24 @@
# 搶救開機迴圈 {#intruduction}
在刷新裝置時，我們很可能會遇到裝置「變磚」的狀況，從理論上講，如果您只是使用 Fastboot 刷新 Boot 分割區或者安裝不合適的模組導致裝置無法開機，那麼這都可以透過合適的作業還原您的手機；這個文件提供一些緊急方法可以讓您在「變磚」中還原。
在寫入裝置時，我們很可能會遇到裝置「變磚」的狀況，從理論上講，如果您只是使用 Fastboot 寫入 Boot 分區或者安裝不合適的模組導致裝置無法開機，那麼這都可以透過合適的作業還原您的手機；這個文件提供一些緊急方法可以讓您在「變磚」中還原。
## 刷新 Boot 時變磚 {#brick-by-flashing-boot-partition}
## 寫入 Boot 時變磚 {#brick-by-flashing-boot-partition}
在 KernelSU 中，刷新 boot 時變磚有下列原因：
在 KernelSU 中，寫入 boot 時變磚有下列原因：
1. 你刷新了錯誤格式的 Boot 映像。比如您的手機 Boot 格式為 `gz`，但您刷新 `lz4` 格式的映像，那麼此時手機將無法開機。
1. 你寫入了錯誤格式的 Boot 映像。比如您的手機 Boot 格式為 `gz`，但您寫入 `lz4` 格式的映像，那麼此時手機將無法開機。
2. 您的手機需要關閉 AVB 驗證才可正常開機 (這通常需要抹除手機上的所有資料)。
3. 您的核心存在某些錯誤或您的核心並不適合這部手機刷新。
3. 您的核心存在某些錯誤或您的核心並不適合這部手機寫入。
無論哪種狀況，您都可以透過**刷新原廠 Boot**還原；因此，在安裝教學最開始，我們已經強烈建議大家，在刷新之前備份自己的原廠 Boot！如果您沒有備份，那麼您可以透過其他與您相同裝置的使用者或官方韌體擷取 Boot。
無論哪種狀況，您都可以透過**寫入原廠 Boot** 還原；因此，在安裝教學最開始，我們已經強烈建議大家，在寫入之前備份自己的原廠 Boot！如果您沒有備份，那麼您可以透過其他與您相同裝置的使用者或官方韌體擷取 Boot。
## 刷新模組變磚 {#brick-by-modules}
## 安裝模組變磚 {#brick-by-modules}
刷新模組變磚可能是大家遇到的更常見的狀況，但是這裡要嚴正警示大家：**不要刷新未知來源的模組！！**。因為模組擁有 Root 權限，它能完全對您的裝置造成無法復原的損壞！
安裝模組變磚可能是大家遇到的更常見的狀況，但是這裡要嚴正警示大家：**不要安裝未知來源的模組！！**。因為模組擁有 Root 權限，它能完全對您的裝置造成無法復原的損壞！
### 一般模組 {#normal-modules}
如果大家刷新了某些開放原始碼的或者被證明是安全的模組使手機無法開機，那麼這種狀況在 KernelSU 中非常容易還原，也無需擔心。KernelSU 內建了下列兩種機制以搶救您的裝置：
如果大家安裝了某些開放原始碼的或者被證明是安全的模組使手機無法開機，那麼這種狀況在 KernelSU 中非常容易還原，也無需擔心。KernelSU 內建了下列兩種機制以搶救您的裝置：
1. AB 更新
2. 透過按下「音量 -」搶救
@@ -29,14 +29,14 @@ KernelSU 的模組借鑒了 Android 系統 OTA 更新時的 AB 更新機制，
因此，最簡單最常用的搶救方法就是：**強制重新開機一次**。如果您在刷新某個模組之後系統無法開機，您可以長按電源按鈕超過 10 秒，系統會自動重新開機；模組會回復為更新前的狀態，先前更新的模組也將會被自動停用。
#### 透過按下「音量 -」搶救 {#volume-down}
#### 透過按下「音量 -」搶救 {#rescue-by-pressing-volume-down}
如果 AB 更新仍然無法解決，您可以嘗試使用**安全模式**。進入安全模式之後，所有的模組將會被停用。
進入安全模式的方法有兩種：
1. 某些系統內建的安全模式；有些系統是長按「音量 -」，有些系統 (例如 MIUI) 可以在 Recovery 中啟用安全模式。進入系統的安全模式後，KernelSU 也會進入安全模式，並自動停用模組。
2. KernelSU 內建的安全模式；作業方法：開機第一個畫面後，**連續按下「音量 -」按鈕超過三次**。注意是按下-抬起、按下-抬起、按下-抬起，並非一直按下。
1. 某些系統內建的安全模式：有些系統是長按「音量 -」，有些系統 (例如 MIUI) 可以在 Recovery 中啟用安全模式。進入系統的安全模式後，KernelSU 也會進入安全模式，並自動停用模組。
2. KernelSU 內建的安全模式：開機第一個畫面後，**連續按下「音量 -」按鈕超過三次**。注意是按下-抬起、按下-抬起、按下-抬起，並非一直按下。
進入安全模式後，KernelSU 管理員的模組頁面的所有模組將會被停用，但您可以執行「解除安裝」作業，將可能存在問題的模組解除安裝。
@@ -46,5 +46,5 @@ KernelSU 的模組借鑒了 Android 系統 OTA 更新時的 AB 更新機制，
如果以上方法無法搶救您的裝置，那麼很可能您安裝的模組存在惡意作業或透過其他方式損壞了您的裝置，在這種狀況下，只有兩個建議：
1. 抹除資料並刷新官方系統。
1. 抹除資料並恢復為官方系統。
2. 諮詢售後服務。

6
website/docs/zh_TW/guide/unofficially-support-devices.md
View File

@@ -1,11 +1,11 @@
# 非官方支援裝置
::: warning
::: warning 警告
本文件列出由其他開發人員維護的支援 KernelSU 的非 GKI 裝置核心
:::
::: warning
本文件仅便於尋找裝置對應原始碼，這並非意味著這些原始碼**被** KernelSU 開發人員**審查**，您應自行承擔風險。
::: warning 警告
本文件僅便於尋找裝置對應原始碼，這並非意味著這些原始碼被 KernelSU 開發人員**審查**，您應自行承擔風險。
:::
<script setup>

6
website/docs/zh_TW/guide/what-is-kernelsu.md
View File

@@ -1,12 +1,12 @@
# 什麼是 KernelSU？ {#introduction}
# 什麼是 KernelSU？ {#what-is-kernelsu}
KernelSU 是 Android GKI 裝置的 Root 解決方案，它以核心模式運作，並直接在核心空間中為使用者空間應用程式授予 Root 權限。
## 功能 {#features}
KernelSU 的主要功能是它是**以核心為基礎的**。 KernelSU 在核心空間中執行，所以它可以向我們提供從未有過的核心介面。例如，我們可以在核心模式中為任何處理程序新增硬體中斷點；我們可以在任何處理程序的實體記憶體中存取，而無人知曉；我們可以在核心空間攔截任何系統呼叫；等等。
KernelSU 的主要功能是它是**基於核心的**。 KernelSU 在核心空間中執行，所以它可以向我們提供從未有過的核心介面。例如，我們可以在核心模式中為任何處理程序新增硬體中斷點；我們可以在任何處理程序的實體記憶體中存取，而無人知曉；我們可以在核心空間攔截任何系統呼叫；等等。
KernelSU 還提供了一個以 overlayfs 為基礎的模組系統，允許您將自訂外掛程式載入到系統中。它還提供了一種修改 `/system` 分割區中檔案的機制。
KernelSU 還提供了一個以 overlayfs 為基礎的模組系統，允許您將自訂模組載入到系統中。它還提供了一種修改 `/system` 分區中檔案的機制。
## 如何使用 {#how-to-use}

6
website/docs/zh_TW/index.md
View File

@@ -1,10 +1,10 @@
---
layout: home
title: Android 上以核心為基礎的 Root 解決方案
title: 基於核心的 Android Root 解決方案
hero:
name: KernelSU
text: Android 上以核心為基礎的 root 解決方案
text: 基於核心的 Android root 解決方案
tagline: ""
image:
src: /logo.png
@@ -21,7 +21,7 @@ features:
- title: 以核心為基礎
details: KernelSU 以 Linux 核心模式運作，對使用者空間有更強的掌控。
- title: 白名單存取控制
details: 僅有被授予 Root 權限的應用程式才可存取 `su`，而其他應用程式完全無法知悉。
details: 僅有被授予 Root 權限的應用程式才可存取 su，而其他應用程式完全無法知悉。
- title: 可定制的 Root 權限
details: KernelSU 能夠對 su 的使用者ID（uid）、群組ID（gid）、群組、權限，以及 SELinux 規則進行客製化管理，以此加強 root 權限的安全性。
- title: 模組支援