From 4b978cc7c18009882e883f28a14b91f66434c3a9 Mon Sep 17 00:00:00 2001 From: sus <54392299+jeffpeng3@users.noreply.github.com> Date: Sun, 25 Aug 2024 11:52:43 +0800 Subject: [PATCH] website: Updated translations (#1959) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 更新翻譯 --- website/docs/.vitepress/locales/zh_TW.ts | 2 +- website/docs/zh_TW/guide/app-profile.md | 31 +-- .../zh_TW/guide/difference-with-magisk.md | 12 +- website/docs/zh_TW/guide/faq.md | 6 +- website/docs/zh_TW/guide/how-to-build.md | 24 +- .../guide/how-to-integrate-for-non-gki.md | 98 +++++--- website/docs/zh_TW/guide/installation.md | 223 +++++++++--------- website/docs/zh_TW/guide/module-webui.md | 17 +- website/docs/zh_TW/guide/module.md | 111 +++++++-- .../docs/zh_TW/guide/rescue-from-bootloop.md | 26 +- .../guide/unofficially-support-devices.md | 6 +- website/docs/zh_TW/guide/what-is-kernelsu.md | 6 +- website/docs/zh_TW/index.md | 6 +- 13 files changed, 340 insertions(+), 228 deletions(-) diff --git a/website/docs/.vitepress/locales/zh_TW.ts b/website/docs/.vitepress/locales/zh_TW.ts index 3a92d45b2cf7..5d6fd9e8f14e 100644 --- a/website/docs/.vitepress/locales/zh_TW.ts +++ b/website/docs/.vitepress/locales/zh_TW.ts @@ -6,7 +6,7 @@ const pkg = require('vitepress/package.json') export default defineConfig({ lang: 'zh-TW', - description: '一個以核心為基礎，適用於 Android GKI 的 Root 解決方案。', + description: '一個基於核心，適用於 Android GKI 的 Root 解決方案。', themeConfig: { nav: nav(), diff --git a/website/docs/zh_TW/guide/app-profile.md b/website/docs/zh_TW/guide/app-profile.md index 659c5660164b..993857702927 100644 --- a/website/docs/zh_TW/guide/app-profile.md +++ b/website/docs/zh_TW/guide/app-profile.md @@ -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）也會透過這個設定決定是否需要卸載。 ::: \ No newline at end of file diff --git a/website/docs/zh_TW/guide/difference-with-magisk.md b/website/docs/zh_TW/guide/difference-with-magisk.md index 6cd291e171de..fdaa5fc9d940 100644 --- a/website/docs/zh_TW/guide/difference-with-magisk.md +++ b/website/docs/zh_TW/guide/difference-with-magisk.md @@ -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 後執行一些腳本。 diff --git a/website/docs/zh_TW/guide/faq.md b/website/docs/zh_TW/guide/faq.md index 8f1c13400c26..57166b68c4ac 100644 --- a/website/docs/zh_TW/guide/faq.md +++ b/website/docs/zh_TW/guide/faq.md @@ -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 嗎？ diff --git a/website/docs/zh_TW/guide/how-to-build.md b/website/docs/zh_TW/guide/how-to-build.md index 034044945df1..89517c84b0d2 100644 --- a/website/docs/zh_TW/guide/how-to-build.md +++ b/website/docs/zh_TW/guide/how-to-build.md @@ -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 ``` -`` 是一個可以唯一確定組建的資訊清單檔案，您可以使用這個資訊清單進行可重新預測的組建。您需要從[標準核心映像 (GKI) 發行組建](https://source.android.com/docs/core/architecture/kernel/gki-release-builds) 下載資訊清單檔案 +`` 是一個可以唯一確定組建的資訊清單，您可以使用這個資訊清單進行可重新預測的組建。您需要從[標準核心映像 (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 的核心映像！ diff --git a/website/docs/zh_TW/guide/how-to-integrate-for-non-gki.md b/website/docs/zh_TW/guide/how-to-integrate-for-non-gki.md index 43b4980e9a66..a6c28485f313 100644 --- a/website/docs/zh_TW/guide/how-to-integrate-for-non-gki.md +++ b/website/docs/zh_TW/guide/how-to-integrate-for-non-gki.md @@ -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 - -``` - -- main 分支(開發版本) - ```sh -curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s main +curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s v0.9.5 ``` -- 選取 tag (例如 v0.5.2) - -```sh -curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s v0.5.2 -``` +:::info 公告 +[KernelSU 1.0 及更新版本不再支援非 GKI 核心](https://github.com/tiann/KernelSU/issues/1705)。最後一個支援的版本為 `v0.9.5`，請確保使用的版本正確。 +::: -然後，您需要檢查您的核心是否啟用 *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 將會如期運作。 diff --git a/website/docs/zh_TW/guide/installation.md b/website/docs/zh_TW/guide/installation.md index c0e0f32d3d6e..1d2e7a3d852f 100644 --- a/website/docs/zh_TW/guide/installation.md +++ b/website/docs/zh_TW/guide/installation.md @@ -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 --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-.img`. +您可以從 [GitHub Release](https://github.com/tiann/KernelSU/releases) 下載 boot.img，請注意，您應該使用正確版本的 boot.img。如果你不知道你該下載哪個檔案，請詳細閱讀文檔中的 [KMI](#kmi) 與[安全性修補程式等級](#security-patch-level)。 -其中 `` 指的是您的官方 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 ``` -## 手動修補 boot.img {#patch-boot-image} +## 使用核心寫入程式安裝 {#install-with-kernel-flasher} + +先決條件：您的裝置必須已經 Root。例如您已經安裝了 Magisk 並取得 Root 存取權，或者您已經安裝了舊版本的 KernelSU 需升級到其他版本的 KernelSU；如果您的裝置並未 Root，請嘗試其他方法。 + +步驟： + +1. 下載 AnyKernel3 的 Zip 檔。如果你不知道你該下載哪個檔案，請詳細閱讀文檔中的 [KMI](#kmi) 與[安全性修補程式等級](#security-patch-level)。 +2. 開啟核心寫入程式提供的 AnyKernel3 Zip 檔案並寫入核心。 -對於某些裝置來說，其 boot.img 格式並不是很常見，比如 `lz4`，`gz` 和未壓縮；最典型的就是 Pixel，它的 boot.img 格式是 `lz4_legacy` 壓縮，ramdisk 可能是 `gz` 也可能是 `lz4_legacy` 壓縮；此時如果您直接刷新 KernelSU 提供的 boot.img，手機可能無法開機；這時，您可以透過手動修補 boot.img 來完成。 +如果您先前並未使用過核心寫入應用程式，可以嘗試下面幾個： -一般有兩種修補方法： +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} -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) +對於某些裝置來說，其 boot.img 格式並不是很常見，不屬於 `lz4`，`gz` 和未壓縮；最典型的就是 Pixel，它的 boot.img 格式是 `lz4_legacy` 壓縮，ramdisk 可能是 `gz` 也可能是 `lz4_legacy` 壓縮；此時如果您直接寫入 KernelSU 提供的 boot.img，手機可能無法開機。這時，您可以透過手動修補 boot.img 來完成。 -其中，Android-Image-Kitchen 適用於在電腦上作業，magiskboot 需要手機協作。 +永遠建議使用 `magiskboot` 來修補映像，一般有兩種修補方法： -### 準備 {#patch-preparation} +1. [magiskboot](https://github.com/topjohnwu/Magisk/releases) +2. [magiskboot_build](https://github.com/ookiineko/magiskboot_build/releases/tag/last-ci) -1. 取得您手機的原廠 boot.img；您可以聯絡您的裝置製造商，您也可能需要[payload-dumper-go](https://github.com/ssut/payload-dumper-go) -2. 下載 KernelSU 提供的與您的裝置 KMI 一致地 AnyKernel3 Zip 檔案 (可參閱 *使用自訂 Recovery 安裝*)。 -3. 解壓縮 AnyKernel3 Zip 檔案，取得其中的 `Image` 檔案，此檔案為 KernelSU 的核心檔案。 +其中，官方的 `magiskboot` 僅能在 Android 上使用，若您想在電腦上完成，可以嘗試第二個選項。 -### 使用 Android-Image-Kitchen {#using-android-image-kitchen} +### 準備 {#preparation} -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 刷新即可 (刷新方法請參閱上一章節)。 +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 的核心。 -### 使用 magiskboot {#using magiskboot} +### 在 Android 上使用 magiskboot {#using-magiskboot-on-Android-devices} -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 提供的核心。 diff --git a/website/docs/zh_TW/guide/module-webui.md b/website/docs/zh_TW/guide/module-webui.md index 5dbdaf7826f2..671faad7a153 100644 --- a/website/docs/zh_TW/guide/module-webui.md +++ b/website/docs/zh_TW/guide/module-webui.md @@ -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/) 進行打包。它無須設定，使用非常方便。不過，如果你是前端高手或有自己的喜好，那就選擇你喜歡的吧！ diff --git a/website/docs/zh_TW/guide/module.md b/website/docs/zh_TW/guide/module.md index 717c862890ec..dac0fec6c3ee 100644 --- a/website/docs/zh_TW/guide/module.md +++ b/website/docs/zh_TW/guide/module.md @@ -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