KernelSU 非 GKI 内核集成实战kprobe 自动挂载与手动源码移植全指南【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU本文以 KernelSU 官方文档葡萄牙语版 为骨架结合当前仓库的 setup.sh、Kconfig、init.c 等源码进行印证与扩充。由于原文档已声明“不再维护”本文所有命令与版本号均以其标注的v0.9.5为准供正在维护旧内核的开发者参考。导读KernelSU 是一个基于内核的 Android Root 方案其官方支持重心是 GKIGeneric Kernel Image内核但对于 4.14 及更早版本的非 GKI 内核KernelSU 也提供了完整的移植路径。本指南面向能够自行编译可启动内核的设备维护者系统讲解两条非 GKI 集成路线——kprobe 自动挂载与手动源码修改涵盖 defconfig 配置、四处关键 hook 点的补丁、安全模式Safe Mode、pm命令修复以及path_umount移植等完整实战细节。读完本文你将掌握把 KernelSUv0.9.5集成进自有内核源码并规避 bootloop 的完整方法论。⚠️重要前提KernelSU 自 v1.0 起已放弃对非 GKI 设备的官方支持最后一个支持非 GKI 内核的版本是v0.9.5。因此本文所有命令均固定使用该版本请勿使用更新的版本进行非 GKI 集成。一、集成前的前置条件非 GKI 内核因厂商碎片化严重不存在通用的构建方法官方也因此无法为非 GKI 设备提供现成的 boot.img。集成的前提是你能够从内核源码编译出一个可启动的内核——这是硬性门槛若内核不是开源的则基本无法完成 KernelSU 的集成在满足上述条件后有两条集成路径可选方式一使用kprobe自动集成推荐前提是 kprobe 在你的内核上工作正常方式二手动修改内核源码适用于 kprobe 不可用或存在 bug 的内核。两种方式的共同第一步都是先把 KernelSU 源码添加到内核源码树中。二、方式一使用 kprobe 自动集成KernelSU 依赖 kprobe 机制完成内核 hook。如果 kprobe 在你的内核上工作良好这是最省力的集成方式。2.1 添加 KernelSU 到内核源码树在内核源码根目录执行以下命令即可拉取并接入 KernelSU v0.9.5curl -LSs https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh | bash -s v0.9.5ℹ️版本提醒KernelSU 1.0 及以后版本不再支持非 GKI 内核请务必使用v0.9.5否则集成将无法正常工作。这一命令对应的正是当前仓库中的 kernel/setup.sh 脚本。从其源码结构看脚本的核心逻辑是在drivers/目录下为 KernelSU 内核源码创建kernelsu符号链接ln -sf ... kernelsu在drivers/Makefile追加obj-$(CONFIG_KSU) kernelsu/在drivers/Kconfig的endmenu前插入source drivers/kernelsu/Kconfig支持通过--cleanup参数一键还原所有改动。也就是说setup.sh所做的本质工作就是把 KernelSU 作为内核 drivers 的一个子模块挂进 Kbuild 体系之后是否参与编译完全由CONFIG_KSU配置项决定。2.2 检查并开启 kprobe 相关配置接入源码后需要确认内核配置中已开启 kprobe。若未开启请在 defconfig 中补充以下三项CONFIG_KPROBESy CONFIG_HAVE_KPROBESy CONFIG_KPROBE_EVENTSy这与当前仓库 kernel/Kconfig 中的依赖关系完全吻合——CONFIG_KSU明确声明depends on KPROBES EXT4_FS即 kprobe 与 ext4 文件系统支持是编译 KernelSU 的硬性依赖config KSU tristate KernelSU function support depends on KPROBES EXT4_FS default y若开启上述三项后KPROBES仍未生效可尝试再开启CONFIG_MODULES若仍无效请使用make menuconfig检查 KPROBES 的其他依赖项。完成配置后重新编译内核KernelSU 即应正常工作。2.3 集成后 bootloop 的排查如果集成 KernelSU 后设备陷入 bootloop很可能意味着kprobe 在你的内核上是损坏的。此时要么修复 kprobe 的 bug要么改用下文的手动集成方式。如何验证 kprobe 是否损坏官方给出的排查手段是临时注释掉KernelSU/kernel/ksu.c中的ksu_sucompat_init()与ksu_ksud_init()两个初始化调用重新编译后若设备能正常启动即可基本断定问题出在 kprobe 上。这一排查思路与当前仓库的初始化代码一脉相承——在 kernel/core/init.c 的kernelsu_init()中ksu_ksud_init()等初始化函数处于启动流程的关键位置若其所依赖的 hook 机制如 kprobe失效将直接导致启动失败。2.4 让“卸载模块”功能在非 GKI 上生效若你的内核版本低于 5.9必须将path_umount移植到fs/namespace.c否则“卸载模块Umount modules”功能将无法工作。具体移植方法见本文第六节。三、方式二手动修改内核源码当 kprobe 不可用时可能是上游内核 bug或内核版本低于 4.8就需要手动在源码层面接入 KernelSU。3.1 添加源码并开启 CONFIG_KSU同样先执行 setup 命令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/your_defconfig等厂商目录。无论哪个 defconfig都必须显式配置CONFIG_KSU# KernelSU CONFIG_KSUyy编译进内核n禁用。从当前仓库 kernel/Kconfig 看CONFIG_KSU实际是一个tristate选项还支持m编译为名为kernelsu的内核模块并提供了KSU_DEBUG、KSU_DISABLE_MANAGER、KSU_DISABLE_POLICY、KSU_X86_PATCH_SYSCALL_DISPATCHER等附加开关非 GKI 手动集成时只需保证CONFIG_KSUy即可。3.2 添加 KernelSU 调用四处核心 hook 点开启CONFIG_KSU后需要在内核源码中手动添加 KernelSU 的调用。下面依次给出官方提供的参考补丁。你需要在源码中找到四个函数并按照补丁插入#ifdef CONFIG_KSU包裹的调用函数通常所在文件do_faccessatfs/open.cdo_execveat_commonfs/exec.cvfs_readfs/read_write.cvfs_statxfs/stat.c①fs/exec.cexecveat hookdiff --git a/fs/exec.c b/fs/exec.c index ac59664eaecf..bdd585e1d2cc 100644 --- a/fs/exec.c b/fs/exec.c -1890,11 1890,14 static int __do_execve_file(int fd, struct filename *filename, return retval; } #ifdef CONFIG_KSU extern bool ksu_execveat_hook __read_mostly; extern int ksu_handle_execveat(int *fd, struct filename **filename_ptr, void *argv, void *envp, int *flags); extern int ksu_handle_execveat_sucompat(int *fd, struct filename **filename_ptr, void *argv, void *envp, int *flags); #endif static int do_execveat_common(int fd, struct filename *filename, struct user_arg_ptr argv, struct user_arg_ptr envp, int flags) { #ifdef CONFIG_KSU if (unlikely(ksu_execveat_hook)) ksu_handle_execveat(fd, filename, argv, envp, flags); else ksu_handle_execveat_sucompat(fd, filename, argv, envp, flags); #endif return __do_execve_file(fd, filename, argv, envp, flags, NULL); }②fs/open.cfaccessat hookdiff --git a/fs/open.c b/fs/open.c index 05036d819197..965b84d486b8 100644 --- a/fs/open.c b/fs/open.c -348,6 348,8 SYSCALL_DEFINE4(fallocate, int, fd, int, mode, loff_t, offset, loff_t, len) return ksys_fallocate(fd, mode, offset, len); } #ifdef CONFIG_KSU extern int ksu_handle_faccessat(int *dfd, const char __user **filename_user, int *mode, int *flags); #endif /* * access() precisa usar o uid/gid real, não o uid/gid efetivo. * Fazemos isso limpando temporariamente todos os recursos relacionados ao FS e -355,6 357,7 SYSCALL_DEFINE4(fallocate, int, fd, int, mode, loff_t, offset, loff_t, len) */ long do_faccessat(int dfd, const char __user *filename, int mode) { const struct cred *old_cred; struct cred *override_cred; struct path path; struct inode *inode; struct vfsmount *mnt; int res; unsigned int lookup_flags LOOKUP_FOLLOW; #ifdef CONFIG_KSU ksu_handle_faccessat(dfd, filename, mode, NULL); #endif if (mode ~S_IRWXO) /* wheres F_OK, X_OK, W_OK, R_OK? */ return -EINVAL;③fs/read_write.cvfs_read hookdiff --git a/fs/read_write.c b/fs/read_write.c index 650fc7e0f3a6..55be193913b6 100644 --- a/fs/read_write.c b/fs/read_write.c -434,10 434,14 ssize_t kernel_read(struct file *file, void *buf, size_t count, loff_t *pos) } EXPORT_SYMBOL(kernel_read); #ifdef CONFIG_KSU extern bool ksu_vfs_read_hook __read_mostly; extern int ksu_handle_vfs_read(struct file **file_ptr, char __user **buf_ptr, size_t *count_ptr, loff_t **pos); #endif ssize_t vfs_read(struct file *file, char __user *buf, size_t count, loff_t *pos) { ssize_t ret; #ifdef CONFIG_KSU if (unlikely(ksu_vfs_read_hook)) ksu_handle_vfs_read(file, buf, count, pos); #endif if (!(file-f_mode FMODE_READ)) return -EBADF; if (!(file-f_mode FMODE_CAN_READ))④fs/stat.cvfs_statx hookdiff --git a/fs/stat.c b/fs/stat.c index 376543199b5a..82adcef03ecc 100644 --- a/fs/stat.c b/fs/stat.c -148,6 148,8 int vfs_statx_fd(unsigned int fd, struct kstat *stat, } EXPORT_SYMBOL(vfs_statx_fd); #ifdef CONFIG_KSU extern int ksu_handle_stat(int *dfd, const char __user **filename_user, int *flags); #endif /** * vfs_statx - Get basic and extra attributes by filename * dfd: A file descriptor representing the base directory for a relative filename -170,6 172,7 int vfs_statx(int dfd, const char __user *filename, int flags, int error -EINVAL; unsigned int lookup_flags LOOKUP_FOLLOW | LOOKUP_AUTOMOUNT; #ifdef CONFIG_KSU ksu_handle_stat(dfd, filename, flags); #endif if ((flags ~(AT_SYMLINK_NOFOLLOW | AT_NO_AUTOMOUNT | AT_EMPTY_PATH | KSTAT_QUERY_FLAGS)) ! 0) return -EINVAL;3.3 内核没有vfs_statx改用vfs_fstatat老版本内核如 4.14 时代往往没有vfs_statx函数。此时应改用vfs_fstatatdiff --git a/fs/stat.c b/fs/stat.c index 068fdbcc9e26..5348b7bb9db2 100644 --- a/fs/stat.c b/fs/stat.c -87,6 87,8 int vfs_fstat(unsigned int fd, struct kstat *stat) } EXPORT_SYMBOL(vfs_fstat); #ifdef CONFIG_KSU extern int ksu_handle_stat(int *dfd, const char __user **filename_user, int *flags); #endif int vfs_fstatat(int dfd, const char __user *filename, struct kstat *stat, int flag) { -94,6 96,8 int vfs_fstatat(int dfd, const char __user *filename, struct kstat *stat, int error -EINVAL; unsigned int lookup_flags 0; #ifdef CONFIG_KSU ksu_handle_stat(dfd, filename, flag); #endif if ((flag ~(AT_SYMLINK_NOFOLLOW | AT_NO_AUTOMOUNT | AT_EMPTY_PATH)) ! 0) goto out;3.4 内核低于 4.17直接在faccessat系统调用处 hook对于 4.17 之前的内核如果找不到do_faccessat直接定位到faccessat系统调用定义处插入调用diff --git a/fs/open.c b/fs/open.c index 2ff887661237..e758d7db7663 100644 --- a/fs/open.c b/fs/open.c -355,6 355,9 SYSCALL_DEFINE4(fallocate, int, fd, int, mode, loff_t, offset, loff_t, len) return error; } #ifdef CONFIG_KSU extern int ksu_handle_faccessat(int *dfd, const char __user **filename_user, int *mode, int *flags); #endif /* * access() precisa usar o uid/gid real, não o uid/gid efetivo. * Fazemos isso limpando temporariamente todos os recursos relacionados ao FS e -370,6 373,8 SYSCALL_DEFINE3(faccessat, int, dfd, const char __user *, filename, int, mode) int res; unsigned int lookup_flags LOOKUP_FOLLOW; #ifdef CONFIG_KSU ksu_handle_faccessat(dfd, filename, mode, NULL); #endif if (mode ~S_IRWXO) /* wheres F_OK, X_OK, W_OK, R_OK? */ return -EINVAL;3.5 源码印证这些 hook 在 KernelSU 中做什么虽然 v0.9.5 的ksu.c与当前仓库代码已有所不同但从当前仓库 kernel/feature/sucompat.c 的ksu_handle_faccessat_sucompat()实现可以清晰看到这套 hook 的设计意图当某个已授权应用访问/system/bin/su时KernelSU 会把该访问透明重定向到ksudKSUD_PATH从而实现对su命令的兼容支持ksu_handle_execveat_sucompat()与ksu_handle_stat_sucompat()同理。而 kernel/runtime/ksud_integration.c 中的ksu_handle_execveat_ksud()则利用 execveat hook 感知/system/bin/init的second_stage与 zygoteapp_process -Xzygote启动时机用于注入 SELinux 规则、缓存 SID 等初始化动作——这正是手动集成时这几个 hook 点缺一不可的原因。四、启用内置安全模式Safe ModeKernelSU 内置了安全模式在启动早期按住音量减键即可跳过模块加载是防止模块导致 bootloop 的“救命稻草”官方强烈建议开启。启用方法修改drivers/input/input.c中的input_handle_event函数diff --git a/drivers/input/input.c b/drivers/input/input.c index 45306f9ef247..815091ebfca4 100755 --- a/drivers/input/input.c b/drivers/input/input.c -367,10 367,13 static int input_get_disposition(struct input_dev *dev, return disposition; } #ifdef CONFIG_KSU extern bool ksu_input_hook __read_mostly; extern int ksu_handle_input_handle_event(unsigned int *type, unsigned int *code, int *value); #endif static void input_handle_event(struct input_dev *dev, unsigned int type, unsigned int code, int value) { int disposition input_get_disposition(dev, type, code, value); #ifdef CONFIG_KSU if (unlikely(ksu_input_hook)) ksu_handle_input_handle_event(type, code, value); #endif if (disposition ! INPUT_IGNORE_EVENT type ! EV_SYN) add_input_randomness(type, code, value);⚠️关键警告误入安全模式怎么办如果使用手动集成方式必须同时关闭CONFIG_KPROBES否则 kprobe 路径下的 hook 仍会生效用户可能在开机后仅凭音量减键就意外触发安全模式。五、修复终端中pm命令失败的问题若集成后出现终端里pm命令无法执行的情况需要修改fs/devpts/inode.c参考补丁如下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); #ifdef CONFIG_KSU if (dentry-d_sb-s_magic ! DEVPTS_SUPER_MAGIC) return NULL; return dentry-d_fsdata;提示上述补丁末尾保留了原文中出现的两个#ifdef CONFIG_KSU嵌套写法实际应用时请以 KernelSU 官方补丁为准核对预处理指令的配对避免编译告警。六、如何移植path_umount让“卸载模块”在旧内核上工作“卸载模块”功能在低于 5.9 的内核上需要手动移植path_umount到fs/namespace.c。官方参考补丁如下--- a/fs/namespace.c b/fs/namespace.c -1739,6 1739,39 static inline bool may_mandlock(void) } #endif static int can_umount(const struct path *path, int flags) { struct mount *mnt real_mount(path-mnt); if (flags ~(MNT_FORCE | MNT_DETACH | MNT_EXPIRE | UMOUNT_NOFOLLOW)) return -EINVAL; if (!may_mount()) return -EPERM; if (path-dentry ! path-mnt-mnt_root) return -EINVAL; if (!check_mnt(mnt)) return -EINVAL; if (mnt-mnt.mnt_flags MNT_LOCKED) /* Check optimistically */ return -EINVAL; if (flags MNT_FORCE !capable(CAP_SYS_ADMIN)) return -EPERM; return 0; } int path_umount(struct path *path, int flags) { struct mount *mnt real_mount(path-mnt); int ret; ret can_umount(path, flags); if (!ret) ret do_umount(mnt, flags); /* não devemos chamar path_put() pois isso limparia mnt_expiry_mark */ dput(path-dentry); mntput_no_expire(mnt); return ret; } /* * Agora o umount pode lidar com pontos de montagem e também com dispositivos bloqueados. * Isto é importante para filesystems que usam dispositivos bloqueados sem nome.该补丁的意义可以从当前仓库 kernel/feature/kernel_umount.c 得到印证kernel_umount特性模块通过extern int path_umount(struct path *path, int flags);声明直接调用这个函数并在应用切换到非 root 身份如 zygote fork 出的普通应用、isolated process、webview_zygote 等场景时将已挂载的模块从内核命名空间卸载。若内核缺少path_umount这一整套卸载逻辑将无法编译或运行模块目录也就无法从普通应用视角“隐藏”。七、编译验证与收尾完成上述所有修改后重新编译内核若采用kprobe 方式确认CONFIG_KPROBESy、CONFIG_HAVE_KPROBESy、CONFIG_KPROBE_EVENTSy均已生效编译出的内核应能正常集成 KernelSU若采用手动方式确认CONFIG_KSUy且CONFIG_KPROBES已关闭防止意外触发安全模式四个 hook 点补丁、安全模式补丁、devpts 补丁与path_umount移植均无遗漏。从当前仓库 kernel/core/init.c 的初始化顺序可以看出KernelSU 在启动时会依次完成符号解析、syscall hook、SELinux 规则注入、白名单加载、ksud 守护进程对接等动作——这些环节任一出错都可能导致启动异常因此在刷入前务必完整核对上述集成步骤并优先开启安全模式作为兜底。本文所有代码补丁均直接继承自 KernelSU 官方非 GKI 集成文档v0.9.5 时期并已与当前仓库源码中的对应实现sucompat.c、ksud_integration.c、kernel_umount.c、Kconfig交叉印证。因原文档已停止维护实际移植时请以你所用内核版本的具体函数签名为准做适配。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考