diff --git a/website/docs/.vitepress/locales/zh_TW.ts b/website/docs/.vitepress/locales/zh_TW.ts index 62cdc3e2d507..3a92d45b2cf7 100644 --- a/website/docs/.vitepress/locales/zh_TW.ts +++ b/website/docs/.vitepress/locales/zh_TW.ts @@ -45,11 +45,14 @@ function sidebarGuide() { text: 'Guide', items: [ { text: '什麼是 KernelSU？', link: '/zh_TW/guide/what-is-kernelsu' }, + { text: 'KernelSU 與 Magisk 的差異', link: '/zh_TW/guide/difference-with-magisk' }, { text: '安裝', link: '/zh_TW/guide/installation' }, { text: '如何建置？', link: '/zh_TW/guide/how-to-build' }, { text: '如何為非 GKI 核心整合 KernelSU', link: '/zh_TW/guide/how-to-integrate-for-non-gki'}, { text: '非官方支援裝置', link: '/zh_TW/guide/unofficially-support-devices.md' }, { text: '模組指南', link: '/zh_TW/guide/module.md' }, + { text: '模組 WebUI', link: '/zh_TW/guide/module-webui.md' }, + { text: 'App Profile', link: '/zh_TW/guide/app-profile.md' }, { text: '搶救開機迴圈', link: '/zh_TW/guide/rescue-from-bootloop.md' }, { text: '常見問題', link: '/zh_TW/guide/faq' }, { text: '隱藏功能', link: '/zh_TW/guide/hidden-features' }, diff --git a/website/docs/public/templates/adaway.root b/website/docs/public/templates/adaway.root index fe2ed8d94b32..746fa32245a8 100644 --- a/website/docs/public/templates/adaway.root +++ b/website/docs/public/templates/adaway.root @@ -16,6 +16,10 @@ "context":"u:r:su:s0", "namespace":"INHERITED", "locales": { + "zh_TW": { + "name": "Adaway Root", + "description": "僅允許 Adaway 修改 hosts 和執行 Web 伺服器的必要權限" + }, "bn": { "name": "অ্যাডঅ্যাওয়ে রুট", "description": "অ্যাডঅ্যাওয়ে সিস্টেমের হোস্ট ফাইল পরিবর্তন এবং ওয়েবসার্ভার চালু করতে কমপক্ষে যা অনুমতি লাগে।" diff --git a/website/docs/public/templates/adb b/website/docs/public/templates/adb index 86258534398f..8507e1c27017 100644 --- a/website/docs/public/templates/adb +++ b/website/docs/public/templates/adb @@ -13,6 +13,10 @@ "name": "Adb 模版", "description": "大多数使用 ADB 权限应用所需要的最小权限" }, + "zh_TW": { + "name": "Adb", + "description": "大多數使用 ADB 權限應用程式所需要的最低權限" + }, "tr": { "name": "Adb", "description": "ADB ayrıcalığını kullanan çoğu uygulama için gereken minimum kurallar." diff --git a/website/docs/public/templates/cemiuiler.readproc b/website/docs/public/templates/cemiuiler.readproc index d8a936c6627f..9d6fe01c6e91 100644 --- a/website/docs/public/templates/cemiuiler.readproc +++ b/website/docs/public/templates/cemiuiler.readproc @@ -19,6 +19,10 @@ "name": "西米露Cemiuiler", "description": "授予Cemiuiler能正常工作——重启作用域应用的最小限度权限。" }, + "zh_TW": { + "name": "Cemiuiler", + "description": "授予Cemiuiler能正常運作－重啟作用域應用程式的最低權限" + }, "tr": { "name": "Cemiuiler", "description": "Cemiuiler uygulamasına düzgün çalışması için minimum izinleri verin." diff --git a/website/docs/public/templates/incompetent.root b/website/docs/public/templates/incompetent.root index 1947e03db472..7016c284efd1 100644 --- a/website/docs/public/templates/incompetent.root +++ b/website/docs/public/templates/incompetent.root @@ -13,6 +13,10 @@ "name": "无能的 Root", "description": "无任何权能的 root 用户。" }, + "zh_TW": { + "name": "無能的 Root", + "description": "無任何權限的 root" + }, "tr": { "name": "Yetersiz root", "description": "Herhangi bir özelliği olmayan yetersiz bir root kullanıcısı." diff --git a/website/docs/public/templates/kernelmanager.root b/website/docs/public/templates/kernelmanager.root index 492ee0fd8d1e..92e914faea2b 100644 --- a/website/docs/public/templates/kernelmanager.root +++ b/website/docs/public/templates/kernelmanager.root @@ -21,6 +21,10 @@ "context":"u:r:su:s0", "namespace":"INHERITED", "locales": { + "zh_TW": { + "name": "核心管理器", + "description": "常用於 FKM 和 SmartPack 等核心管理器" + }, "in": { "name": "Kernel Manager", "description": "Umumnya digunakan pada Kernel manager seperti FKM dan SmartPack." diff --git a/website/docs/public/templates/rootexploler.root b/website/docs/public/templates/rootexploler.root index e3e84a7746d9..f09fc9ee1be2 100644 --- a/website/docs/public/templates/rootexploler.root +++ b/website/docs/public/templates/rootexploler.root @@ -16,6 +16,10 @@ "context":"u:r:su:s0", "namespace":"INHERITED", "locales": { + "zh_TW": { + "name": "Root Explorer", + "description": "具有根目錄讀寫權限的檔案管理器" + }, "in": { "name": "Root Explorer", "description": "File manager dengan kemampuan Root." diff --git a/website/docs/public/templates/shizuku.root b/website/docs/public/templates/shizuku.root index 160053d62337..a7ecf877ec5a 100644 --- a/website/docs/public/templates/shizuku.root +++ b/website/docs/public/templates/shizuku.root @@ -14,6 +14,10 @@ "context":"u:r:su:s0", "namespace":"INHERITED", "locales": { + "zh_TW": { + "name": "Shizuku", + "description": "只有啟動 Shizuku 服務所需的權限" + }, "bn": { "name": "শিজুকু সার্ভিস", "description": "শিজুকু চালানোর জন্য শুধু যে অনুমতি গুলি লাগে।" diff --git a/website/docs/public/templates/system b/website/docs/public/templates/system index 1910cb222a38..562a4ed62ee5 100644 --- a/website/docs/public/templates/system +++ b/website/docs/public/templates/system @@ -13,6 +13,10 @@ "name": "Android 系统", "description": "Android 系统运行的权限级别，但没有任何权能。" }, + "zh_TW": { + "name": "Android 系統", + "description": "Android 系統運作的權限級別，但沒有任何權能" + }, "tr": { "name": "Sistem", "description": "Android sisteminin herhangi bir yetenek olmadan çalıştığı izin düzeyi." diff --git a/website/docs/zh_TW/guide/app-profile.md b/website/docs/zh_TW/guide/app-profile.md new file mode 100644 index 000000000000..acb51b58ff55 --- /dev/null +++ b/website/docs/zh_TW/guide/app-profile.md @@ -0,0 +1,118 @@ +# App Profile + +App Profile 是 KernelSU 提供的一種針對各種應用程式自訂其使用配置的機制。 + +對於授予了root 權限（也即可以使用 `su`）的應用程式來說，App Profile 也可以稱為Root Profile，它可以自訂 `su` 的 `uid`, `gid` , `groups` , ` capabilities` 以及 `SELinux context` 規則，從而限制 root 使用者的權限；例如可以針對防火牆應用程式僅授予網路權限，而不授予檔案存取權限，針對凍結類別應用程式僅授予 shell 權限而不是直接給 root ；透過最小化權限原則**把權力關進籠子裡**。 + +對於沒有被授予 root 權限的普通應用，App Profile 可以控制核心以及模組系統對此應用的行為；例如是否需要針對此應用程式卸載模組造成的修改等。核心和模組系統可以透過此配置決定是否要做一些類似「隱藏痕跡」類別的操作。 + +## Root Profile + +### UID、GID 和 groups + +Linux 系統中有使用者和群組兩個概念。每個使用者都有一個使用者 ID(UID)，一個使用者可以屬於多個群組，每個群組也有群組 ID(GID)。此 ID 用於識別系統的使用者並確定使用者可以存取哪些系統資源。 + +UID 為 0 的使用者稱為 root 使用者，GID 為 0 的群組稱為 root 群組；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。 +::: + +每一個應用程式可以有若干個群組，GID 使其主要的群組，通常與 UID 一致；其他的群組稱為補充群組(groups)。某些權限是透過群組控制的，例如網路訪問，藍牙等。 + +例如，如果我們在 ADB shell 中執行 `id` 指令，會得到以下輸出： + +```sh +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 等。 + +KernelSU 的 Root Profile 可以自訂執行 `su` 後 root 程式的 UID, GID 和 groups。例如，你可以設定某個 root 應用程式的Root Profile 其UID 為`2000`，這表示此應用程式在使用`su` 的時候，它的實際權限是ADB Shell 等級；你可以去掉groups 中的`inet` ，這樣這個`su` 就無法存取網路。 + +:::tip 注意 +App Profile 只是控制 root 應用程式使用 `su` 後的權限，它並非控制應用程式本身的權限！如果應用程式本身申請了網路存取權限，那麼它即使不使用 `su` 也可以存取網路；為 `su` 去掉 `inet` 群組只是讓 `su` 無法存取網路。 +::: + +與應用程式透過 `su` 主動切換使用者或群組不同，Root Profile 是在核心中強制實施的，不依賴 root 應用程式的自覺行為，`su` 權限的授予完全取決於使用者而非開發者。 + +### Capabilities + +Capabilities 是 Linux 的一種分權機制。 + +傳統的 UNIX 系統為了執行權限檢查，將流程分為兩類：特權程式（其有效使用者 ID 為 0，稱為超級使用者或 root）和非特權程式（其有效 UID 為非零）。特權程式會繞過所有核心權限檢查，而非特權程式則根據其憑證（通常是有效UID、有效GID和補充群組清單）進行完整的權限檢查。 + +從 Linux 2.2開始，Linux 將傳統上與超級使用者關聯的特權分解為獨立的單元，稱為 Capabilities（有的也翻譯為「權能」），它們可以獨立啟用和停用。 + +每一個 Capability 代表一個或一類權限。例如 `CAP_DAC_READ_SEARCH` 就代表是否有能力繞過檔案讀取權限檢查和目錄讀取和執行權限檢查。如果一個有效 UID 為 `0` 的使用者（root 使用者）沒有 `CAP_DAC_READ_SEARCH` 或更高 Capalities，這表示即使它是 root 也不能​​隨意讀取檔案。 + +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，請務必先閱讀此文件。 +::: + +### SELinux + +SELinux 是一種強大的強制權限存取控制（MAC）機制。它按照**預設拒絕**的原則運作：任何未經明確允許的行為都會被拒絕。 + +SELinux 可依兩種全域模式運作： + +1. 寬容模式：權限拒絕事件會被記錄下來，但不會被強制執行。 +2. 強制模式：權限拒絕事件會被記錄下來**並且**強制執行。 + +:::warning 警告 +現代的 Android 系統極度依賴 SELinux 來保障整個系統的安全性，我們強烈建議您不要使用任何以「寬容模式」運作的自訂系統，因為那樣與裸奔沒什麼區別。 +::: + +SELinux 的完整概念比較複雜，我們這裡不打算講解它的具體運作方式，建議你先透過以下資料來了解其運作原理： + +1. [wikipedia](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) +2. [Redhat: what-is-selinux](https://www.redhat.com/en/topics/linux/what-is-selinux) +3. [ArchLinux: SELinux](https://wiki.archlinux.org/title/SELinux) + +KernelSU 的 Root Profile 可以自訂執行 `su` 後 root 程式的 SELinux context，並且可以針對這個 context 設定特定的存取控制規則，從而更精細地控制 root 權限。 + +通常情況下，應用程式執行 `su` 後，會將進程切換到一個**不受任何限制** 的SELinux 域，例如`u:r:su:s0`，透過 Root Profile，我們可以將它切換到一個自訂的網域，例如 `u:r:app1:s0`，然後為這個網域制定一系列規則： + +```sh +type app1 +enforce app1 +typeattribute app1 mlstrustedsubject +allow app1 * * * +``` + +注意：此處的 `allow app1 * * *` 僅僅作為演示方便而使用，實際過程中不應使用這個規則，因為它跟 permissive 區別不大。 + +### 逃逸 + +如果 Root Profile 的配置不合理，那麼可能會發生逃逸的情況：Root Profile 的限制會意外失效。 + +例如，如果你為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 權限！ + +:::warning 注意 +這是完全符合預期的行為，並非 BUG！因此我們建議： + +如果你的確需要給 adb 授予 root 權限（例如你是開發者），那麼不建議你在配置 Root Profile 的時候將 UID 改成 `2000`，用 `1000(system)` 會更好。 +::: + +## Non Root Profile + +### 卸載模組 + +KernelSU 提供了一種 systemless 的方式來修改系統分區，這是透過掛載 overlayfs 來實現的。但有些情況下，App 可能會對這種行為比較敏感；因此，我們可以透過設定「卸載模組」來卸載掛載在這些應用程式上的模組。 + +另外，KernelSU 管理器的設定介面還提供了一個「預設卸載模組」的開關，這個開關預設是**開啟**的，這表示**如果不對應用程式做額外的設定**，預設情況下 KernelSU 或某些模組會對此應用程式執行卸載操作。當然，如果你不喜歡這個設定或這個設定會影響某些 App，你可以有以下選擇： + +1. 保持「預設卸載模組」的開關，然後針對不需要「卸載模組」的應用程式進行單獨的設置，在 App Profile 中關閉「卸載模組」；（相當於「白名單」）。 +2. 關閉「預設卸載模組」的開關，然後針對需要「卸載模組」的應用程式進行單獨的設置，在 App Profile 中開啟「卸載模組」；（相當於「黑名單」）。 + +:::info +KernelSU 在 5.10 及以上內核上，內核會執行“卸載模組”的操作；但在 5.10 以下的設備上，這個開關僅僅是一個“設定”，KernelSU 本身不會做任何動作，一些模組（如 Zygisksu 會透過這個模組決定是否需要卸載） +::: \ 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 f0d05447dfd5..6cd291e171de 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 的差異 {#title} 儘管 KernelSU 模組和 Magisk 模組之間有許多相似之處，但由於它們完全不同的實作機制，不可避免地存在一些差異；如果您想讓您的模組同時在 Magisk 和 KernelSU 上運作，那麼您必須瞭解這些差異。 @@ -6,9 +6,9 @@ - 模組檔案格式：都以 Zip 的格式組織模組，並且模組的格式幾乎相同 - 模組安裝目錄：都位於 `/data/adb/modules` -- Systemless：都支援透過模組的形式以 systemless 修改 /system -- `post-fs-data.sh`：執行時間和語義完全相同 -- `service.sh`：執行時間和語義完全相同 +- Systemless：都支援通過模組以無系統修改的方式來更改 `/system` +- `post-fs-data.sh`：執行階段和語義完全相同 +- `service.sh`：執行階段和語義完全相同 - `system.prop`：完全相同 - `sepolicy.rule`：完全相同 - BusyBox：指令碼在 BusyBox 中以「獨立模式」執行 @@ -24,3 +24,5 @@ 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` 變數以移除或取代檔案 (資料夾)。 +6. KernelSU 新增了 `boot-completed` 階段以在啟動完成時執行一些腳本。 +7. KernelSU 新增了 `post-mount` 階段，以便在掛載 overlayfs 後執行一些腳本 diff --git a/website/docs/zh_TW/guide/faq.md b/website/docs/zh_TW/guide/faq.md index 006262f5d011..8f1c13400c26 100644 --- a/website/docs/zh_TW/guide/faq.md +++ b/website/docs/zh_TW/guide/faq.md @@ -55,13 +55,26 @@ KernelSU 的模組系統與 Magisk 的 magic mount 存在衝突，如果在 Kern 核心版本與 Android 版本無關，如果您要刷新 KernelSU，請一律使用**核心版本**而非 Android 版本，如果你為 "android12-5.10" 的裝置刷新 Android 13 的核心，等候您的將會是開機迴圈。 +## 我是 GKI1.0，能用 KernelSU 嗎？ + +GKI1 與 GKI2 完全不同，所以您需要自行編譯核心。 + ## KernelSU 支援 --mount-master/全域掛接命名空間嗎？ -目前沒有 (未來可能會支援)，但實際上有很多種方法手動進入全域命名空間，無需 Su 內建支援，比如： +目前沒有 (未來可能會支援)，但實際上有很多種方法手動進入全域命名空間，無需 `su` 內建支援，比如： 1. `nsenter -t 1 -m sh` 可以取得一個全域 mount namespace 的 shell. 2. 在您要執行的命令前新增 `nsenter --mount=/proc/1/ns/mnt` 即可使此命令在全域 mount namespace 下執行。KernelSU 本身也使用了 [這種方法](https://github.com/tiann/KernelSU/blob/77056a710073d7a5f7ee38f9e77c9fd0b3256576/manager/app/src/main/java/me/weishu/kernelsu/ui/util/KsuCli.kt#L115) -## 我是 GKI1.0，能用 KernelSU 嗎？ +## KernelSU 可以修改 Hosts 嗎？ 我要怎麼使用 AdAway？ +當然。但是 KernelSU 沒有內建的 Hosts 支持，您可以安裝 [systemless-hosts](https://github.com/symbuzzer/systemless-hosts-KernelSU-module) 來做到這一點。 -GKI1 與 GKI2 完全不同，所以您需要自行編譯核心。 +## 為什麼會有 1TB 的龐大檔案？ + +1 TB 大小的 `modules.img` 是一個磁碟映像文件，不用擔心它的大小，它是一種特殊類型的文件，稱為稀疏檔案，它的實際大小只有你使用的模組的大小，並且在你刪除模組後會動態縮小；實際上並沒有佔用1TB的磁碟空間（實際上你的手機可能並沒有那麼多空間）。 + +如果你確實對檔案的大小不滿意，可以使用 `resize2fs -M` 指令將其調整為實際大小；但此時模組可能無法正常運作，我們不會這種情況提供任何支援。 + +## 為什麼我的設備顯示錯誤的儲存空間大小？ + +某些裝置使用非正規方法來計算裝置的儲存大小，可能會導致系統應用程式的儲存空間計算不準確，特別是在處理 1 TB 的稀疏檔案時。雖然這個問題似乎是三星設備特有的，僅影響三星應用程式和服務，但必須注意的是，差異主要在於總儲存大小，可用空間運算仍然準確。 \ No newline at end of file diff --git a/website/docs/zh_TW/guide/hidden-features.md b/website/docs/zh_TW/guide/hidden-features.md index c07762db612a..1a12947cb5eb 100644 --- a/website/docs/zh_TW/guide/hidden-features.md +++ b/website/docs/zh_TW/guide/hidden-features.md @@ -1,7 +1,7 @@ # 隱藏功能 -## ksurc +## .ksurc 預設狀況下，`/system/bin/sh` 會載入 `/system/etc/mkshrc`。 -可以透過建立 `/data/adb/ksu/.ksurc` 檔案來讓 Su 載入此檔案而非 `/system/etc/mkshrc`。 \ No newline at end of file +可以透過建立 `/data/adb/ksu/.ksurc` 檔案來讓 `su` 載入此檔案而非 `/system/etc/mkshrc`。 \ No newline at end of file diff --git a/website/docs/zh_TW/guide/how-to-build.md b/website/docs/zh_TW/guide/how-to-build.md index 0f95bf7ff0c5..dff349549ea4 100644 --- a/website/docs/zh_TW/guide/how-to-build.md +++ b/website/docs/zh_TW/guide/how-to-build.md @@ -40,6 +40,14 @@ LTO=thin BUILD_CONFIG=common/build.config.gki.aarch64 build/build.sh tools/bazel build --config=fast //common:kernel_aarch64_dist ``` +:::info +對於某些 Android 14 內核，要使 Wi-Fi/藍牙正常工作，可能需要刪除所有受 GKI 保護的匯出： + +```sh +rm common/android/abi_gki_protected_exports_* +``` +::: + ## 使用 KernelSU 建置核心 如果您可以成功建置核心，那麼建置 KernelSU 就會非常輕鬆，依自己的需求在核心原始碼根目錄中執行以下任一命令： diff --git a/website/docs/zh_TW/guide/module-webui.md b/website/docs/zh_TW/guide/module-webui.md new file mode 100644 index 000000000000..02e424adb0fc --- /dev/null +++ b/website/docs/zh_TW/guide/module-webui.md @@ -0,0 +1,49 @@ +# 模組 WebUI + +KernelSU 的模組除了執行啟動腳本和修改系統檔案之外，還支援顯示 UI 介面和與使用者互動。 + +該模組可以透過任何 Web 技術編寫HTML + CSS + JavaScript頁面。 KernelSU的管理器將透過 WebView 顯示這些頁面。它還提供了一些用於與系統互動的JavaScript API，例如執行shell命令。 + +## WebUI 根目錄 + +Web資源應放置在模組根目錄的`webroot`子目錄中，並且其中**必須**有一個名為`index.html`的文件，該檔案是模組頁面入口。 + +包含Web介面的最簡單的模組結構如下： + +```txt +❯ tree . +. +|-- module.prop +`-- webroot + `-- index.html +``` + +:::warning +安裝模組時，KernelSU 將自動設定`webroot`的權限和 SELinux context。如果您不知道自己在做什麼，請不要自行設定該目錄的權限！ +::: + +如果您的頁面包含 CSS 和 JavaScript，您也需要將其放入此目錄中。 + +## JavaScript API + +如果只是一個顯示頁面，那和一般網頁沒有什麼不同。更重要的是，KernelSU 提供了一系列的系統 API，讓您可以實現模組獨特的功能。 + +KernelSU 提供了一個 JavaScript 庫並[在 npm 上發布](https://www.npmjs.com/package/kernelsu)，您可以在網頁的 JavaScript 程式碼中使用它。 + +例如，您可以執行 shell 命令來取得特定配置或修改屬性： + +```JavaScript +import { exec } from 'kernelsu'; + +const { errno, stdout } = exec("getprop ro.product.model"); +``` + +再例如，你可以讓網頁全螢幕顯示，或是顯示一個 Toast。 + +[API 文檔](https://www.npmjs.com/package/kernelsu) + +如果您發現現有的API無法滿足您的需求或使用不方便，歡迎您在[這裡](https://github.com/tiann/KernelSU/issues)給我們建議！ +## 一些技巧 + +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 9658bd45e774..717c862890ec 100644 --- a/website/docs/zh_TW/guide/module.md +++ b/website/docs/zh_TW/guide/module.md @@ -4,16 +4,20 @@ KernelSU 提供了一個模組機制，它可以在保持系統分割區完整 KernelSU 的模組運作機制與 Magisk 幾乎相同，如果您熟悉 Magisk 模組的開發，那麼開發 KernelSU 的模組大同小異，您可以跳過下列有關模組的介紹，只需要瞭解 [KernelSU 模組與 Magisk 模組的異同](difference-with-magisk.md)。 +## WebUI + +KernelSU 的模組支援顯示互動介面，請參閱 [WebUI 文檔](module-webui.md). + ## 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 內建的應用程式。 -這確保了指令碼始終在可預測的環境中執行，並始終具有完整的命令套件，不論它執行在哪個 Android 版本上。 +這確保了腳本始終在可預測的環境中執行，並始終具有完整的命令套件，不論它執行在哪個 Android 版本上。 要強制下一個命令不使用 BusyBox，您必須使用完整路徑呼叫可執行檔。 -在 KernelSU 上下文中執行的每個 shell 指令碼都將在 BusyBox 的 ash shell 中以獨立模式執行。對於第三方開發人員相關的內容，包括所有開機指令碼和模組安裝指令碼。 +在 KernelSU 上下文中執行的每個 shell 腳本都將在 BusyBox 的 ash shell 中以獨立模式執行。對於第三方開發人員相關的內容，包括所有開機腳本和模組安裝腳本。 對於想要在 KernelSU 之外使用這個「獨立模式」功能的使用者，有兩種啟用方法： @@ -24,7 +28,7 @@ KernelSU 的 BusyBox 支援同時執行時可切換的 "ASH Standalone Shell Mod ::: tip 與 Magisk 的差異 KernelSU 的 BusyBox 現在是直接使用 Magisk 專案編譯的二進位檔案，**感謝 Magisk！** -因此，您完全不必擔心 BusyBox 指令碼與在 Magisk 和 KernelSU 之間的相容性問題，因為它們完全相同！ +因此，您完全不必擔心 BusyBox 腳本與在 Magisk 和 KernelSU 之間的相容性問題，因為它們完全相同！ ::: ## KernelSU 模組 {#kernelsu-modules} @@ -57,9 +61,9 @@ KernelSU 模組是一個放置於 `/data/adb/modules` 且滿足下列結構的 │ │ │ │ *** 選用檔案 *** │ │ -│ ├── post-fs-data.sh <--- 這個指令碼將會在 post-fs-data 中執行 -│ ├── service.sh <--- 這個指令碼將會在 late_start 服務中執行 -| ├── uninstall.sh <--- 這個指令碼將會在 KernelSU 移除模組時執行 +│ ├── post-fs-data.sh <--- 這個腳本將會在 post-fs-data 中執行 +│ ├── service.sh <--- 這個腳本將會在 late_start 服務中執行 +| ├── uninstall.sh <--- 這個腳本將會在 KernelSU 移除模組時執行 │ ├── system.prop <--- 這個檔案中指定的屬性將會在系統啟動時透過 resetprop 變更 │ ├── sepolicy.rule <--- 這個檔案中的 SELinux 原則將會在系統開機時載入 │ │ @@ -103,14 +107,14 @@ description= - 其他未在上方提到的內容可以是任何單行字串。 - 請確保使用 `UNIX (LF)` 分行符號類型，而非 `Windows (CR + LF)` 或 `Macintosh (CR)`。 -### Shell 指令碼 {#shell-scripts} +### Shell 腳本 {#shell-scripts} -請閱讀 [開機指令碼](#boot-scripts) 章節，以瞭解 `post-fs-data.sh` 和 `service.sh` 之間的差別。對於大多數模組開發人員來說，如果您只需要執行一個開機指令碼，`service.sh` 應該已經足夠了。 +請閱讀 [開機腳本](#boot-scripts) 章節，以瞭解 `post-fs-data.sh` 和 `service.sh` 之間的差別。對於大多數模組開發人員來說，如果您只需要執行一個開機腳本，`service.sh` 應該已經足夠了。 -在您的模組中的所有指令碼中，請使用 `MODDIR=${0%/*}` 以取得您的模組基本目錄路徑；請不要在指令碼中以硬式編碼的方式加入您的模組路徑。 +在您的模組中的所有腳本中，請使用 `MODDIR=${0%/*}` 以取得您的模組基本目錄路徑；請不要在腳本中以硬式編碼的方式加入您的模組路徑。 :::tip 與 Magisk 的差異 -您可以透過環境變數 `KSU` 來判斷指令碼是執行在 KernelSU 還是 Magisk 中，如果執行在 KernelSU，這個值會被設為 `true`。 +您可以透過環境變數 `KSU` 來判斷腳本是執行在 KernelSU 還是 Magisk 中，如果執行在 KernelSU，這個值會被設為 `true`。 ::: ### `system` 目錄 {#system-directories} @@ -181,15 +185,15 @@ KernelSU 模組不支援在 Recovery 中安裝！！ ### 自訂安裝程序 {#customizing-installation} -如果您想要控制模組的安裝程序，可以在模組的目錄下建立一個名為 `customize.sh` 的檔案，這個檔案將會在模組被解壓縮後**匯入**至目前的 shell 中，如果您的模組需要依據裝置的 API 版本或裝置架構執行一些額外的作業，這個指令碼將非常有用。 +如果您想要控制模組的安裝程序，可以在模組的目錄下建立一個名為 `customize.sh` 的檔案，這個檔案將會在模組被解壓縮後**匯入**至目前的 shell 中，如果您的模組需要依據裝置的 API 版本或裝置架構執行一些額外的作業，這個腳本將非常有用。 -如果您想完全控制指令碼的安裝程序，您可以在 `customize.sh` 中宣告 `SKIPUNZIP=1` 以跳過所有的預設安裝步驟；此時，您需要自行處理所有的安裝程序 (例如解壓縮模組、設定權限等) +如果您想完全控制腳本的安裝程序，您可以在 `customize.sh` 中宣告 `SKIPUNZIP=1` 以跳過所有的預設安裝步驟；此時，您需要自行處理所有的安裝程序 (例如解壓縮模組、設定權限等) -`customize.sh` 指令碼以「獨立模式」執行在 KernelSU 的 BusyBox `ash` shell 中。您可以使用下列變數和函式： +`customize.sh` 腳本以「獨立模式」執行在 KernelSU 的 BusyBox `ash` shell 中。您可以使用下列變數和函式： #### 變數 {#variables} -- `KSU` (bool): 標示此指令碼執行於 KernelSU 環境中，此變數的值將永遠為 `true`，您可以透過它與 Magisk 進行區分。 +- `KSU` (bool): 標示此腳本執行於 KernelSU 環境中，此變數的值將永遠為 `true`，您可以透過它與 Magisk 進行區分。 - `KSU_VER` (string): KernelSU 目前的版本名稱 (例如 `v0.4.0`) - `KSU_VER_CODE` (int): KernelSU 使用者空間目前的版本代碼 (例如 `10672`) - `KSU_KERNEL_VER_CODE` (int): KernelSU 核心空間目前的版本代碼 (例如 `10672`) @@ -231,32 +235,32 @@ set_perm_recursive set_perm dir owner group dirpermission context ``` -## 開機指令碼 {#boot-scripts} +## 開機腳本 {#boot-scripts} -在 KernelSU 中，依據指令碼執行模式的不同分為兩種：post-fs-data 模式和 late_start 服務模式。 +在 KernelSU 中，依據腳本執行模式的不同分為兩種：post-fs-data 模式和 late_start 服務模式。 - post-fs-data 模式 - - 這個階段是「封鎖」的。在執行完成之前或 10 秒鐘之後，開機程序會被暫停。 - - 指令碼在任何模組被掛接之前執行。這使模組開發人員可以在模組被掛接之前動態調整他們的模組。 + - 這個階段是 **阻塞** 的。在執行完成之前或 10 秒鐘之後，開機程序會被暫停。 + - 腳本在任何模組被掛接之前執行。這使模組開發人員可以在模組被掛接之前動態調整他們的模組。 - 這個階段發生在 Zygote 啟動之前，這意味著 Android 中的一切。 - - 使用 setprop 會導致開機程序死鎖！請使用 `resetprop -n ` 替代。 - - **僅在必要時在此模式中執行指令碼**。 + - 使用 `setprop` 會導致開機程序死鎖！請使用 `resetprop -n ` 替代。 + - **僅在必要時在此模式中執行腳本**。 - late_start 服務模式 - - 這個階段是「非封鎖」的。您的指令碼會與其餘的啟動程序**平行**執行。 - - **大多数脚本都建议在这种模式下运行**。 + - 這個階段是 **非阻塞** 的。您的腳本會與其餘的啟動程序**平行**執行。 + - **大多數腳本建議在這種模式下執行**。 -在 KernelSU 中，開機指令碼依據存放位置的不同還分為兩種：一般指令碼和模組指令碼。 +在 KernelSU 中，開機腳本依據存放位置的不同還分為兩種：一般腳本和模組腳本。 -- 一般指令碼 +- 一般腳本 - 放置於 `/data/adb/post-fs-data.d` 或 `/data/adb/service.d` 中。 - - 僅有指令碼被設為可執行 (`chmod +x script.sh`) 時才會被執行。 - - 在 `post-fs-data.d` 中的指令碼以 post-fs-data 模式執行，在 `service.d` 中的指令碼以 late_start 服務模式執行。 - - 模組**不應**在安裝程序中新增一般指令碼。 + - 僅有腳本被設為可執行 (`chmod +x script.sh`) 時才會被執行。 + - 在 `post-fs-data.d` 中的腳本以 post-fs-data 模式執行，在 `service.d` 中的腳本以 late_start 服務模式執行。 + - 模組**不應**在安裝程序中新增一般腳本。 -- 模組指令碼 +- 模組腳本 - 放置於模組自己的資料夾中。 - 僅有在模組啟用時才會執行。 - - `post-fs-data.sh` 以 post-fs-data 模式執行，而 `service.sh` 則以 late_start 服務模式執行。 + - `post-fs-data.sh` 以 post-fs-data 模式運行，`post-mount.sh` 以 post-mount 模式運行，而`service.sh` 則以 late_start 服務模式運行，`boot-completed`在 Android 系統啟動完畢後以服務模式運作。 -所有启动脚本都将在 KernelSU 的 BusyBox ash shell 中运行，并启用“独立模式”。 +所有啟動腳本都將在 KernelSU 的 BusyBox ash shell 中執行，並啟用**獨立模式**。 \ No newline at end of file diff --git a/website/docs/zh_TW/guide/what-is-kernelsu.md b/website/docs/zh_TW/guide/what-is-kernelsu.md index 4d1bce758425..14e0aa38a2f7 100644 --- a/website/docs/zh_TW/guide/what-is-kernelsu.md +++ b/website/docs/zh_TW/guide/what-is-kernelsu.md @@ -6,7 +6,7 @@ KernelSU 是 Android GKI 裝置的 Root 解決方案，它以核心模式運作 KernelSU 的主要功能是它是**以核心為基礎的**。 KernelSU 在核心空間中執行，所以它可以向我們提供從未有過的核心介面。例如，我們可以在核心模式中為任何處理程序新增硬體中斷點；我們可以在任何處理程序的實體記憶體中存取，而無人知曉；我們可以在核心空間攔截任何系統呼叫；等等。 -KernelSU 還提供了一個以 overlayfs 為基礎的模組系統，允許您將自訂外掛程式載入到系統中。它還提供了一種修改 /system 分割區中檔案的機制。 +KernelSU 還提供了一個以 overlayfs 為基礎的模組系統，允許您將自訂外掛程式載入到系統中。它還提供了一種修改 `/system` 分割區中檔案的機制。 ## 如何使用 {#how-to-use} diff --git a/website/docs/zh_TW/index.md b/website/docs/zh_TW/index.md index 65861eb028ba..8125b4acf157 100644 --- a/website/docs/zh_TW/index.md +++ b/website/docs/zh_TW/index.md @@ -22,8 +22,8 @@ features: details: KernelSU 以 Linux 核心模式運作，對使用者空間有更強的掌控。 - title: 白名單存取控制 details: 僅有被授予 Root 權限的應用程式才可存取 `su`，而其他應用程式完全無法知悉。 + - title: 可定制的 Root 權限 + details: KernelSU 能夠對 su 的使用者ID（uid）、群組ID（gid）、群組、權限，以及 SELinux 規則進行客製化管理，以此加強 root 權限的安全性。 - title: 模組支援 details: KernelSU 支援透過 overlayfs 修改 /system，它甚至可以使 /system 可寫入。 - - title: 開放原始碼 - details: KernelSU 是 GPL-3 授權下的開放原始碼專案。