KernelSU 构建指南：从 GKI 内核源码到集成 KernelSU 的完整实战

KernelSU 构建指南从 GKI 内核源码到集成 KernelSU 的完整实战【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU本文基于 KernelSU 官方《如何构建 KernelSU》文档整理扩充结合当前仓库中的kernel/setup.sh、kernel/Kconfig、kernel/Kbuild与scripts/prepare-ddk-x64.sh等源码系统讲解如何在 GKI 设备上同步内核源码、编译内核、集成 KernelSU 并完成可开机镜像的构建同时覆盖 LKM 模式、内核编译选项与常见排错要点。读完本文你将掌握一套可复现、可预测的 KernelSU 内核构建流程。构建方式变更与适用前提::: warning 重要说明 该构建文档在官网中已标注为仅供存档参考不再维护更新。自 KernelSU v3.0 版本之后为了更快的迭代和构建速度项目放弃了对 GKI 镜像模式的官方支持推荐使用Ylarod/ddk构建 LKMLoadable Kernel Module使用。 :::在开始构建之前需要明确两点适用范围本文档描述的镜像内联in-tree构建流程适用于GKI 设备如果你的设备是旧内核非 GKI请参考如何为非 GKI 内核集成 KernelSU该文档介绍了基于 kprobe 自动集成与手动修改内核源码两种方案最低可支持到内核 4.14。官方支持的内核范围为 GKI 2.0内核 5.10旧内核4.14虽然也可支持但需要手动构建内核当前支持arm64-v8a与x86_64两种架构。第一步先阅读 Android 官方内核构建文档构建 KernelSU 的前提是能够独立完成 Android 内核的编译因此在动手之前建议先阅读 Android 官方的两份文档《构建内核》Building Kernels介绍内核构建的整体流程与环境准备《通用内核映像 (GKI) 发布构建》GKI Release Builds介绍如何获取与使用官方发布的 GKI 构建产物及清单文件。这两份文档是理解后续所有命令的基础GKI 构建通过清单manifest文件锁定源码版本从而实现可重新预测的构建——这也是 KernelSU 构建流程与官方流程保持一致的关键。第二步同步内核源码使用repo工具同步 Android 官方内核源码树repo init -u https://android.googlesource.com/kernel/manifest mv kernel_manifest.xml .repo/manifests repo init -m manifest.xml repo sync其中kernel_manifest.xml是一个可以唯一确定构建的清单文件你应当从《通用内核映像 (GKI) 发布构建》页面下载对应的清单文件。使用清单文件构建可以保证同一份源码在不同时间、不同机器上得到一致的构建结果便于问题复现与版本回溯。第三步构建内核请先阅读 Android 官方《构建内核》文档确认构建环境如 clang 工具链、repo等就绪。例如我们需要构建 aarch64 内核镜像LTOthin BUILD_CONFIGcommon/build.config.gki.aarch64 build/build.sh不要忘记添加LTOthin——如果你的计算机内存小于 24GB使用非 thin 的 LTO链接时优化构建很可能会因为内存不足而失败。LTOthin通过并行化的方式显著降低链接阶段的内存峰值。从 Android 13 开始内核改由bazel构建对应的构建命令为tools/bazel build --configfast //common:kernel_aarch64_dist两条命令二选一即可取决于你同步的源码版本所使用的构建系统。第四步使用 KernelSU 构建内核如果你可以成功构建内核那么构建 KernelSU 就很容易了。根据自己的需求在内核源代码根目录中运行以下任一命令# 方式一最新 tag稳定版本 curl -LSs https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh | bash - # 方式二main 分支开发版本 curl -LSs https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh | bash -s main # 方式三指定 tag例如 v0.5.2 curl -LSs https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh | bash -s v0.5.2命令执行完毕后重新构建内核你将获得带有 KernelSU 的内核映像。这里使用了仓库内的kernel/setup.sh脚本它通过 curl 管道直接执行无需手动克隆 KernelSU 仓库。setup.sh 到底做了什么从源码结构看kernel/setup.sh的核心逻辑分为三部分理解它有助于排查集成失败的问题定位驱动目录initialize_variables脚本会依次探测common/drivers与drivers目录是否存在若都不存在则报错退出drivers/ directory not found.。这是为了让脚本同时兼容 GKI 的common子目录布局与传统内核根目录布局。拉取并切换 KernelSU 源码setup_kernelsu若内核源码树中不存在KernelSU目录则执行git clone随后git stash暂存本地改动、git pull更新仓库无参数时通过git describe --abbrev0 --tags检出最新 tag传入参数则检出指定分支或 tag。接入内核构建系统在驱动目录创建指向KernelSU/kernel的符号链接kernelsu并向驱动目录的Makefile追加obj-$(CONFIG_KSU) kernelsu/向Kconfig的endmenu之前插入source drivers/kernelsu/Kconfig。这样内核的 menuconfig 与编译流程就能识别 KernelSU。脚本还提供了--cleanup参数用于撤销上述全部修改删除符号链接、还原 Makefile 与 Kconfig、删除克隆的 KernelSU 目录方便你干净地重试或回退bash kernel/setup.sh --cleanup集成后的内核配置项集成完成后在make menuconfig中会出现KernelSU菜单。当前仓库的kernel/Kconfig定义了以下编译选项配置项类型默认值说明KSUtristateyKernelSU 功能总开关依赖KPROBES内核 hook 支持与EXT4_FS用于ext4_unregister_sysfs选M可编译为名为kernelsu的模块KSU_DEBUGbooln开启 KernelSU 调试模式KSU_DISABLE_MANAGERbooln禁用 Manager APK 检测与 Manager 专属逻辑root 权限将替代 Manager 功能KSU_DISABLE_POLICYbooln禁用按应用定制的 root/非 root 配置文件提权将始终使用默认完整 root 配置KSU_X86_PATCH_SYSCALL_DISPATCHERbooln依赖KSU X86_64在运行时动态 patch x86_64 的加固 syscall dispatcher用于 x86_64 LKM 模式其中KSU_X86_PATCH_SYSCALL_DISPATCHER对应较新 x86_64 内核的 syscall 加固问题详见x86_64 支持说明KernelSU 3.3.0 起可启用该选项在运行时动态 patch 已加固的 syscall dispatcher替代旧的内核源码补丁方案。KernelSU 内核模块由哪些部分组成从kernel/Kbuild可以看出kernelsu.o由多个子模块聚合而成覆盖了 KernelSU 的核心能力核心与特性core/init.o初始化、feature/kernel_umount.o卸载内核挂载、feature/sucompat.osu 兼容、feature/adb_root.oADB root、feature/selinux_hide.oSELinux 隐藏Hook 层hook/lsm_hook.o、hook/setuid_hook.o、hook/syscall_event_bridge.o、hook/syscall_hook_manager.o、hook/tp_marker.o并按架构编译hook/arm64/或hook/x86_64/下的patch_memory.o与syscall_hook.o基础设施infra/file_wrapper.o、infra/event_queue.o、infra/seccomp_cache.o、infra/su_mount_ns.o、infra/symbol_resolver.oManager 集成CONFIG_KSU_DISABLE_MANAGER未开启时manager/apk_sign.o、manager/pkg_observer.o、manager/throne_tracker.o策略与运行时policy/allowlist.o、policy/app_profile.o、policy/feature.o、runtime/boot_event.o、runtime/ksud_integration.oSELinux 与 supercallselinux/selinux.o、selinux/rules.o、selinux/sepolicy.o、supercall/dispatch.o、supercall/perm.o、supercall/supercall.oSulogsu 日志sulog/event.o、sulog/fd.o。另外Kbuild中通过KSU_VERSION宏30000 git 提交数无 git 仓库时回退为 16向内核暴露版本号并通过KSU_EXPECTED_SIZE/KSU_EXPECTED_HASH可用KSU_MANAGER_PACKAGE指定 Manager 包名校验 Manager 应用的签名只有签名匹配的 Manager 才能与内核通信。第五步LKM 模式构建v3.0 之后的推荐方式自 KernelSU v3.0 起官方不再支持 GKI 镜像模式推荐使用Ylarod/ddk构建 LKM。LKM 模式下 KernelSU 以kernelsu.ko内核模块形式加载无需把源码直接编入内核镜像。仓库内kernel/Makefile提供了独立模块构建入口它根据内核目录名判断 KMI如android17-6.18选择M$(MDIR) MO$(ODIR)或M$(ODIR) src$(MDIR)的构建参数执行make ... modules生成kernelsu.ko随后调用kernel/tools/check_symbol.c编译出的check_symbol工具校验模块符号与vmlinux的一致性。针对 x86_64 的 LKM 场景仓库还提供了scripts/prepare-ddk-x64.sh参考脚本覆盖android12-5.10至android17-6.18多个 KMI展示了典型的 LKM 构建环境准备流程为每个 KMI 指定对应的 clang 与 rust 工具链版本并加入PATH使用gki_defconfig生成配置并通过scripts/config关闭LTO_CLANG、THINLTO等链接时优化与文档中内存不足时加LTOthin的思路一致LKM 场景则直接禁用 LTO执行modules_prepare并单独构建 SELinux 头文件security/selinux/built-in.a为后续编译kernelsu.ko铺路。如果你的目标设备是 x86_64 且内核较新务必阅读x86_64 支持说明中关于 syscall 加固的注意事项并按需启用KSU_X86_PATCH_SYSCALL_DISPATCHER。常见问题与排错构建失败且内存不足检查是否遗漏了LTOthinLKM 场景可参考prepare-ddk-x64.sh直接禁用 LTO。内核源码树中没有drivers/目录setup.sh会直接报错退出请确认命令是在 GKI 内核源码根目录下执行的。KernelSU 编译选项未生效确认Kconfig中已成功插入source drivers/kernelsu/Kconfig可用grep检查并在 defconfig 或 menuconfig 中将CONFIG_KSU置为y。x86_64 新内核加载 KernelSU 导致 panic这是上游 syscall 加固导致的已知问题需启用KSU_X86_PATCH_SYSCALL_DISPATCHER或应用对应内核补丁详见x86_64 支持说明。非 GKI 设备如何集成请参考如何为非 GKI 内核集成 KernelSU注意 KernelSU 1.0 及更高版本已不再支持非 GKI 内核最后支持版本为v0.9.5。总结完整的 KernelSU 构建链路可以概括为阅读官方内核构建文档 → 用 repo 同步内核源码锁定清单→ 用build.sh或 bazel 构建出可用内核 → 执行kernel/setup.sh集成 KernelSU → 按需配置Kconfig选项 → 重建内核。对于 v3.0 及以后的版本建议直接走Ylarod/ddk的 LKM 构建路线以获得更快的迭代与构建速度。无论走哪条路线kernel/setup.sh、kernel/Kconfig与kernel/Kbuild都是理解构建行为、排查问题的关键源码入口。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考