KernelSU：基于 Android 内核的 Root 方案 —— 特性、兼容性与内核集成实践（基于葡语版 README）
【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU
本文以 KernelSU 仓库中的葡萄牙语（巴西）版项目文档 docs/README_PT-BR.md 为主体，完整覆盖其定义的核心主题：项目定位与三大核心特性、平台兼容状态（含x86_64内核恐慌风险与解法）、编译集成流程、安全报告与双许可证结构，并结合仓库源码将 README 中点到为止的每一项能力展开为可验证的实现细节，帮助读者建立从内核 hook 到用户态通信通道的完整认知。
项目定位
KernelSU 是一款基于内核（Kernel）的 Android Root 解决方案，而非传统的 init 注入或系统镜像修改方案。它的 root 能力直接构建在内核层：由内核态代码判定并授予 root 权限，再由用户态工具链（ksud 守护进程、Manager 应用）完成提权、策略管理与模块装载。
从源码结构看，这一“内核 + 用户态”的分层对应仓库的三大组成部分：
- 内核部分位于 kernel/，包含 hook 框架（
hook/）、策略管理（policy/）、supercall 通信（supercall/）、SELinux 策略处理（selinux/）、管理器识别（manager/）等模块； - 用户态工具
ksud位于 userspace/ksud/（Rust 实现，负责启动补丁、模块挂载、SELinux 策略下发等），另有 userspace/ksuinit/； - Manager 应用位于 manager/app/，使用 Kotlin Compose 实现，含 Material 与 Miuix 双风格 UI。
三大核心特性
葡语版 README 列出三项核心特性，下面逐一展开并给出仓库内的实现佐证。
1. 基于内核的su与 root 访问管理
传统 root 方案依赖su二进制与 init 层面的劫持，KernelSU 则把“是否允许该进程提权”的判定下沉到内核：内核通过 UID 白/黑名单与每应用 profile 决定提权结果，用户态再通过 ioctl 通信通道向内核申请 root。
该通道的协议定义见 kernel/include/uapi/supercall.h，核心 ioctl 包括：
| ioctl 命令 | 语义 |
|---|---|
KSU_IOCTL_GRANT_ROOT | 向内核申请 root（'K', 1） |
KSU_IOCTL_GET_INFO | 获取内核版本、能力标志（LKM/Manager/Late-Load/PR-Build）、UAPI 版本 |
KSU_IOCTL_SET_SEPOLICY | 向内核下发序列化后的 SELinux 策略命令 |
KSU_IOCTL_UID_GRANTED_ROOT | 查询某 UID 是否已被授予 root |
KSU_IOCTL_UID_SHOULD_UMOUNT | 查询某 UID 是否应卸载 systemless 挂载 |
KSU_IOCTL_GET_APP_PROFILE/KSU_IOCTL_SET_APP_PROFILE | 读写每应用 root profile |
KSU_IOCTL_GET_FEATURE/KSU_IOCTL_SET_FEATURE | 读写特性开关 |
KSU_IOCTL_GET_SULOG_FD | 获取 SULog 日志文件描述符 |
文件头部定义了当前用户态 API 版本：KERNEL_SU_UAPI_VERSION = 3，注释标明版本 2 引入 allowlist v4 root profile 标志、版本 3 引入按会话范围的 su driver fd。Manager 侧对该协议的封装见 manager/app/src/main/cpp/ksu.cc。
2. 基于 metamodule 的模块系统
README 将模块系统描述为“systemless 修改的可插拔基础设施”。metamodule 的本质是：KernelSU 通过内核态的 systemless 机制把模块目录挂载进系统命名空间，使模块可以在不修改实际文件系统的前提下注入脚本与资源，并复用 Magisk 生态的模块格式，因此“强大的 root 工具 Magisk”的模块体系可以被兼容利用。对应的模块执行入口在用户态 userspace/ksud/src/metamodule.rs 与 userspace/ksud/src/module.rs。
模块机制的细节可在仓库内文档 website/docs/guide/metamodule.md 中进一步阅读。
3. 应用 Profile（App Profile）
“把 root 能力关进笼子”：KernelSU 允许按应用维度定制 root 行为。README 将其概括为把 root 权力限制在笼子里，仓库实现中这体现为每个应用可拥有独立的 profile 结构，通过KSU_IOCTL_GET_APP_PROFILE/KSU_IOCTL_SET_APP_PROFILE在内核与 Manager 之间同步，内核侧策略逻辑位于 kernel/policy/app_profile.c。
值得注意的是，该能力可以被编译期关闭：kernel/Kconfig 中的KSU_DISABLE_POLICY选项（默认n）说明“禁用每应用 root/非 root profile 定制后，提权将始终使用默认的完整 root profile，非 root 处理只遵循全局 umount 策略”。应用侧的配置界面见 manager/app/src/main/java/me/weishu/kernelsu/ui/profile/，文档见 website/docs/guide/app-profile.md。
兼容状态与支持平台
葡语版 README 给出的兼容状态可归纳为四点，均有仓库内依据：
- 官方支持 Android GKI 2.0（内核 5.10+）。GKI 内核采用通用镜像 + 厂商 overlay 的形态，KernelSU 通过 Kconfig 三态选项（
y编入内核，M以 LKM 模块加载）两种模式集成，kernel/Kconfig 中config KSU声明为tristate并要求KPROBES && EXT4_FS（前者用于内核 hook，后者用于ext4_unregister_sysfs相关能力）。 - 4.14+ 的旧内核兼容，但需要手动编译内核。README 明确说明旧内核不在官方预编译产物覆盖范围内，集成方式见 website/docs/guide/how-to-integrate-for-non-gki.md 与 website/docs/guide/unofficially-support-devices.md。
- WSA（Windows Subsystem for Android）、ChromeOS 与基于容器的 Android 均在支持范围内。这一覆盖面正是内核级方案的副产品：只要目标系统的 Linux 内核满足 hook 条件，容器化 Android 同样适用，官方文档见 website/docs/guide/x86_64-support.md（WSA 场景主要落在 x86_64 内核上）。
- 当前支持
arm64-v8a与x86_64两种架构。仓库中 hook 与内存打补丁实现按架构分离：kernel/hook/arm64/ 与 kernel/hook/x86_64/ 各有一份patch_memory.c与syscall_hook.c。
x86_64 的兼容性破坏与两种解法
README 中最重要的告警（!CAUTION）是：近期版本的内核引入了一项破坏性变更，导致 KernelSU 在x86_64上加载失败并可能引发内核恐慌（kernel panic）。其机理与修复方式在 website/docs/guide/x86_64-support.md 中有完整说明，要点如下：
- 上游内核的一次变更把系统调用路径中的间接分支转换为一系列直接条件分支，从而“加固”了 syscall 表。KernelSU 的
syscall_hook机制依赖修改 syscall 表条目把被拦截的系统调用路由到统一分发器，加固后内核会忽略这些修改；若未正确处理，KernelSU 会干净地中止初始化以避免内核恐慌。 - 解法一：启用构建选项
KSU_X86_PATCH_SYSCALL_DISPATCHER。该选项由 KernelSU 3.3.0 引入，启用后 KernelSU 在运行时动态打补丁加固后的 syscall 分发器，使 syscall hook 无需依赖此前的内核源码补丁集即可工作，是 3.3.0+ 的推荐方式。 - 解法二：继续使用原始的内核源码补丁方法（通过
X86_FEATURE_INDIRECT_SAFE特性 + 内核 cmdlinesyscall_hardening=off绕过加固）。两种方案不可同时使用。 - 官方文档同时给出了安全警告：两种方案都会有意绕过针对推测执行漏洞的缓解措施、重新打开系统调用上的间接分支攻击面，不应在生产服务器或对侧信道安全要求严格的系统上使用。
仓库源码与这一叙述严格对应：
- kernel/Kconfig 定义了
KSU_X86_PATCH_SYSCALL_DISPATCHER，依赖KSU && X86_64，默认n，帮助文本明确其为“内核源码补丁的替代方案，适用于 x86_64 LKM 模式”； - kernel/core/init.c 在 x86_64 且未启用该选项时做编译期检查：若内核缺少
X86_FEATURE_INDIRECT_SAFE特性定义，直接#error "FATAL: Your kernel is missing the indirect syscall bypass patches!"拒绝编译，这正是防止带病内核恐慌的第一道闸门； - 动态打补丁的实现位于 kernel/hook/x86_64/patch_memory.c，通过遍历
init_mm页表把内核虚拟地址翻译为物理地址（phys_from_virt），配合stop_machine等机制完成对分发器的运行时改写；同目录 kernel/hook/x86_64/syscall_hook.c 负责 syscall 表 hook 本身。
编译与集成流程
README 将“安装”与“编译”指向官方站点文档，仓库内提供了可对照执行的完整工程入口。
集成到 GKI 内核：setup.sh
kernel/setup.sh 是把 KernelSU 挂入 GKI 内核源码树的标准脚本，用法为：
./kernel/setup.sh [--cleanup | <commit-or-tag>]- 无参数：克隆/更新 KernelSU 仓库并检出最新 tag；
- 传
<commit-or-tag>：检出指定版本后集成； --cleanup：撤销脚本所做的全部修改（删除符号链接、还原drivers/Makefile与drivers/Kconfig、移除 KernelSU 目录）。
脚本的集成动作（见 kernel/setup.sh）为：在drivers/下建立指向KernelSU/kernel的符号链接drivers/kernelsu，向drivers/Makefile追加obj-$(CONFIG_KSU) += kernelsu/，并向drivers/Kconfig注入source "drivers/kernelsu/Kconfig"。随后在make menuconfig中打开 KernelSU 菜单项即可。
关键 Kconfig 选项
结合 kernel/Kconfig，编译时可用选项如下：
| 选项 | 类型 / 默认 | 作用 |
|---|---|---|
KSU | tristate，默认y | 总开关；依赖KPROBES（内核 hook）与EXT4_FS（ext4_unregister_sysfs）；选M则以 LKM 模块（模块名kernelsu）方式加载 |
KSU_DEBUG | bool，默认n | 调试模式（如 kernel/core/init.c 中allow_shell仅在调试模式置true） |
KSU_DISABLE_MANAGER | bool，默认n | 禁用 Manager APK 检测与 Manager 专属处理，退化为纯 root 使用方式 |
KSU_DISABLE_POLICY | bool，默认n | 禁用每应用 profile，提权恒用默认完整 root profile |
KSU_X86_PATCH_SYSCALL_DISPATCHER | bool，默认n | x86_64 专用：运行时动态打补丁加固后的 syscall 分发器 |
构建 ksud 与 Manager
仓库根目录的 justfile 提供用户态构建入口：
just build_ksud # 别名 bk：cross build --target aarch64-linux-android --release just build_manager # 别名 bm：先构建 ksud，再将产物拷入 manager/app/src/main/jniLibs/arm64-v8a/libksud.so，然后 cd manager && ./gradlew aDebug just clippy # cargo fmt + cross clippy --target aarch64-linux-android --release这印证了ksud作为 Android 平台二进制（aarch64-linux-android）被打包进 Manager 的jniLibs分发的流程，与 userspace/ksud/Cargo.toml 定义的 Rust crate 一致。Rust 交叉编译环境可用 scripts/setup_cargo_config.py 配置，x86_64 DDK 环境可用 scripts/prepare-ddk-x64.sh 准备。
安全、翻译与许可证
安全报告
README 将安全问题指引到 SECURITY.md。该文件说明：KernelSU 团队重视安全漏洞的责任披露，可通过 GitHub Security Advisory 的 “Report a Vulnerability” 入口或邮件直接联系维护者 weishu 提交；团队会在初步回复后持续通报修复进展。
翻译
README 的“Tradução”一节说明：KernelSU 的翻译贡献统一通过 Weblate 平台进行，Manager 应用的翻译 PR 不再接受，因为可能与 Weblate 的工作流冲突。仓库内文档的多语言结构（website/docs/ 下的zh_CN/、ja_JP/、pt_BR/等目录）与根目录的多语言 README（本文所依据的 docs/README_PT-BR.md 即其中之一）就是该翻译体系的实际产物。
双许可证结构
README 的许可证说明与仓库文件一一对应：
kernel/目录下的文件为GPL-2.0-only，对应 kernel/LICENSE（GNU GPL v2 全文）；- 除
kernel外的其余部分（用户态userspace/、manager/、website/、scripts/、js/等）为GPL-3.0-or-later，对应仓库根的 LICENSE（GNU GPL v3 全文）。
这种双许可切分与内核代码必须遵循 Linux 内核许可惯例、用户态组件则采用 GPL-3.0 的要求相匹配。
致谢与项目渊源
README 的“Créditos”一节列出了 KernelSU 的四个思想来源，均可在仓库中找到落点：
- Kernel-Assisted Superuser（KAS）：KernelSU 的原始构想来源；
- Magisk：systemless 模块生态的兼容基础（metamodule 机制即建立在此之上，见 website/docs/guide/difference-with-magisk.md）；
- genuine：APK v2 签名校验能力，对应仓库中的 APK 签名校验实现 kernel/manager/apk_sign.c（用于校验 Manager 应用签名，防止恶意应用伪装管理器）与用户态 userspace/ksud/src/apk_sign.rs；
- Diamorphine：部分 rootkit 能力（隐藏、检测对抗），对应内核隐藏类特性如 kernel/feature/selinux_hide.c、kernel/feature/adb_root.c 等。
小结
以 docs/README_PT-BR.md 为骨架，KernelSU 的完整技术图景是：以 GKI 2.0（内核 5.10+，arm64 与 x86_64）为官方支持面、以KSUtristate + supercall ioctl 协议为内核与用户态的契约、以 metamodule 与 per-app profile 为差异化能力、以 GPL-2.0（内核）/ GPL-3.0（其余）双许可与 SECURITY.md 披露流程为治理框架的 Android 内核级 root 方案。对于 x86_64 用户，务必先确认内核的 syscall 加固状态并选择KSU_X86_PATCH_SYSCALL_DISPATCHER或源码补丁二选一，这是避免加载失败乃至内核恐慌的前提。
【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
