企业官网建设流程全解析

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 方案，其官方支持重心是 GKI（Generic Kernel Image）内核；但对于 4.14 及更早版本的非 GKI 内核，KernelSU 也提供了完整的移植路径。本指南面向能够自行编译可启动内核的设备维护者，系统讲解两条非 GKI 集成路线——kprobe 自动挂载与手动源码修改，涵盖 defconfig 配置、四处关键 hook 点的补丁、安全模式（Safe Mode）、pm命令修复以及path_umount移植等完整实战细节。读完本文，你将掌握把 KernelSU（v0.9.5）集成进自有内核源码并规避 bootloop 的完整方法论。

⚠️重要前提：KernelSU 自 v1.0 起已放弃对非 GKI 设备的官方支持，最后一个支持非 GKI 内核的版本是v0.9.5。因此本文所有命令均固定使用该版本，请勿使用更新的版本进行非 GKI 集成。

一、集成前的前置条件

非 GKI 内核因厂商碎片化严重，不存在通用的构建方法，官方也因此无法为非 GKI 设备提供现成的 boot.img。集成的前提是：

1. 你能够从内核源码编译出一个可启动的内核——这是硬性门槛；
2. 若内核不是开源的，则基本无法完成 KernelSU 的集成；
3. 在满足上述条件后，有两条集成路径可选：
   • 方式一：使用kprobe自动集成（推荐，前提是 kprobe 在你的内核上工作正常）；
   • 方式二：手动修改内核源码（适用于 kprobe 不可用或存在 bug 的内核）。

两种方式的共同第一步，都是先把 KernelSU 源码添加到内核源码树中。

二、方式一：使用 kprobe 自动集成

KernelSU 依赖 kprobe 机制完成内核 hook。如果 kprobe 在你的内核上工作良好，这是最省力的集成方式。

2.1 添加 KernelSU 到内核源码树

在内核源码根目录执行以下命令，即可拉取并接入 KernelSU v0.9.5：

curl -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_KPROBES=y CONFIG_HAVE_KPROBES=y CONFIG_KPROBE_EVENTS=y

这与当前仓库 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_KSU=y

• y：编译进内核；
• n：禁用。

从当前仓库 kernel/Kconfig 看，CONFIG_KSU实际是一个tristate选项（还支持m编译为名为kernelsu的内核模块），并提供了KSU_DEBUG、KSU_DISABLE_MANAGER、KSU_DISABLE_POLICY、KSU_X86_PATCH_SYSCALL_DISPATCHER等附加开关，非 GKI 手动集成时只需保证CONFIG_KSU=y即可。

3.2 添加 KernelSU 调用：四处核心 hook 点

开启CONFIG_KSU后，需要在内核源码中手动添加 KernelSU 的调用。下面依次给出官方提供的参考补丁。你需要在源码中找到四个函数，并按照补丁插入#ifdef CONFIG_KSU包裹的调用：

①fs/exec.c：execveat hook

diff --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.c：faccessat hook

diff --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) /* where's F_OK, X_OK, W_OK, R_OK? */ return -EINVAL;

③fs/read_write.c：vfs_read hook

diff --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.c：vfs_statx hook

diff --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_fstatat：

diff --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) /* where's 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 会把该访问透明重定向到ksud（KSUD_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与 zygote（app_process -Xzygote）启动时机，用于注入 SELinux 规则、缓存 SID 等初始化动作——这正是手动集成时这几个 hook 点缺一不可的原因。

四、启用内置安全模式（Safe Mode）

KernelSU 内置了安全模式：在启动早期按住音量减键即可跳过模块加载，是防止模块导致 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_KPROBES=y、CONFIG_HAVE_KPROBES=y、CONFIG_KPROBE_EVENTS=y均已生效，编译出的内核应能正常集成 KernelSU；
• 若采用手动方式：确认CONFIG_KSU=y且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