KernelSU 卡开机Bootloop自救完全指南安全模式、ksud 命令行与 Recovery 手动清理【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU导读刷机、安装模块或刷写 boot 分区时设备可能因为格式错误、AVB 校验、内核不兼容或模块异常而陷入 变砖bootloop状态。本文基于 KernelSU 官方文档website/docs/id_ID/guide/rescue-from-bootloop.md英文原版见 website/docs/guide/rescue-from-bootloop.md系统梳理三类典型的 bootloop 场景及其恢复手段刷回原厂 boot、内核级 Safe Mode安全模式、通过ksud命令行或 Recovery 手动清理模块。读完本文你将掌握在不开机情况下逐级自救的完整操作链路并了解这些机制在 KernelSU 内核与用户态中的真实实现原理。一、刷写 boot 分区导致的 Bootloop在 KernelSU 中刷写 boot 分区引发 bootloop 的常见原因有三种镜像格式错误例如设备 boot 分区原本是gz格式却刷入了lz4格式的镜像内核无法解压设备自然无法启动。AVB 校验未处理设备需要关闭 AVBAndroid Verified Boot校验才能正常引导而关闭 AVB 通常需要清除设备全部数据wipe data。内核本身有问题你编译或刷入的内核存在 bug或者与当前设备的硬件/固件不匹配。无论属于哪一种情况恢复手段都是统一的——刷回原厂stockboot 镜像。因此在官方安装教程的开头KernelSU 就强烈建议刷机前务必先备份原始 boot 镜像。如果当时没有备份可以从同型号设备的其他用户处获取或从官方固件factory firmware中提取。这一环节的要点是boot 分区刷写属于底层操作只要你能进入 fastboot 模式就可以通过fastboot flash boot stock_boot.img恢复从而绕开所有与 KernelSU 或模块相关的问题。二、模块导致的 Bootloop先认清风险边界安装模块是导致设备变砖的更常见原因。文档给出了明确的警告绝不安装来源不明的模块模块拥有 root 权限一旦执行恶意或错误操作可能对设备造成永久性损坏。因此在继续自救之前请先判断你安装的模块是否属于已知安全但导致无法开机的类型。对于这类模块KernelSU 提供了多层内置救援机制可以按下面章节的顺序逐级尝试。三、第一层救援Safe Mode安全模式Safe Mode 是 KernelSU 内置的模块级救援机制进入安全模式后所有模块都会被禁用系统可以正常启动然后你再在 KernelSU Manager 中逐个排查、卸载问题模块。3.1 两种进入方式方式一系统自带的安全模式部分系统固件自带安全模式有的可以通过长按音量减键进入有的如 MIUI/HyperOS需要从 Recovery 中开启。当系统进入其安全模式时KernelSU 会同步感知并自动禁用模块。方式二KernelSU 自带的内核级安全模式操作方法是在开机第一屏出现后连续快速按音量减键三次以上。注意动作要领是按下-松开、按下-松开、按下-松开的连续点按不是长按。3.2 底层实现内核态按键监听KernelSU 的 Safe Mode 直接在内核中实现因此不存在因用户态拦截而丢失关键事件的可能性。核心逻辑位于 kernel/runtime/ksud_integration.c内核维护一个计数器volumedown_pressed_count并通过ksu_handle_input_handle_event监听输入事件当type EV_KEY code KEY_VOLUMEDOWN且按键按下value非零时计数加一static unsigned int volumedown_pressed_count 0; static bool is_volumedown_enough(unsigned int count) { return count 3; // 连续按 3 次即触发 } int ksu_handle_input_handle_event(unsigned int *type, unsigned int *code, int *value) { if (*type EV_KEY *code KEY_VOLUMEDOWN) { int val *value; if (val) { volumedown_pressed_count 1; if (is_volumedown_enough(volumedown_pressed_count)) { ksu_stop_input_hook_runtime(); } } } return 0; }当ksu_is_safe_mode()被用户态查询时若计数达到 3 次及以上则置位safe_mode标志并返回true见 kernel/runtime/ksud_integration.c#L496-L520。用户态ksud的is_safe_mode()会先检查系统属性persist.sys.safemode/ro.sys.safemode对应系统自带安全模式再通过check_kernel_safemode()查询内核判定结果见 userspace/ksud/src/utils.rs#L152-L166。3.3 进入安全模式后发生了什么ksud检测到安全模式后会跳过所有模块的post-fs-data脚本并禁用全部模块同时仍确保模块目录存在以便你在安全模式下继续操作见 userspace/ksud/src/init_event.rs 中safe mode, skip post-fs-data scripts and disable all modules!等日志分支。进入安全模式后KernelSU Manager 模块页会显示所有模块处于禁用状态此时你可以直接对问题模块执行 uninstall 彻底移除。3.4 时序警告与局限::: warning监听窗口很短KernelSU 在内核模块初始化阶段LKM 模式下内核执行 init 进程时注册音量键监听并在on_post_fs_data阶段开机动画出现前注销。对应实现见 kernel/runtime/boot_event.c#L17-L34 中的on_post_fs_data()其中调用了ksu_stop_input_hook_runtime()。因此你需要把握时机在第一屏出现后迅速点按音量减三次如果设备开机过快或操作不及时Safe Mode 可能无法触发。initrc 恶意代码无法被豁免如果模块在 initrc 中写入了导致无法开机的代码那么即使在安全模式下这些代码依然会被执行——因为 Safe Mode 只负责禁用模块加载无法阻止已被注入到 init 脚本中的内容。非 GKI 内核需手动集成Safe Mode 由内核实现对于非 GKI 内核可能需要手动集成相关代码请参考官方集成文档如 website/docs/guide/how-to-integrate-for-non-gki.md。 :::四、第二层救援手动救援Manual Rescue当 Safe Mode 无法解决问题时根据设备当前状态选择以下两种手动方案之一。4.1 方法一通过 ADB 使用ksud命令管理模块适用前提设备还能通过 ADB 获取 root shell。直接使用ksud命令行禁用或卸载问题模块adb shell su ksud module list # 列出所有模块 ksud module disable id # 禁用有问题的模块 ksud module uninstall id # 或者直接卸载 reboot::: tipRecovery 模式下也可用挂载metadata与data分区后可以在 Recovery 模式下执行/data/adb/ksud来管理模块。由于 GKI 设备共享initRecovery 模式下 KernelSU 内核模块仍然会被加载因此ksud的大部分功能如设置 feature都可以正常使用。 :::从源码看ksud的子命令在 userspace/ksud/src/cli.rs 中分发Module::List对应列出模块Module::Disable对应module::disable_module(id)Module::Uninstall对应module::uninstall_module(id)另有Module::UndoUninstall可恢复误卸载见 userspace/ksud/src/cli.rs#L531-L534 与 userspace/ksud/src/module.rs 中的对应实现。4.2 方法二通过 Recovery 手动清理文件适用前提完全无法进入系统连 ADB 都无法连接。此时需要在设备上安装第三方 Recovery如 TWRP。KernelSU 的模块加载依赖两样东西内核侧的 init.rc 注入文件与用户态的 ksud 进程。删除这些文件并重启后KernelSU 将不再加载任何模块。操作步骤进入 Recovery如 TWRP。挂载 data 分区mount /data如果分区已加密可能需要先解密具体操作取决于设备与解密方式。删除 ksud阻止模块加载rm -f /data/adb/ksud可选挂载 metadata 分区删除模块生成的 init.rc 注入文件mount /metadata rm -f /metadata/ksu/modules.rc rm -f /metadata/watchdog/ksu/modules.rc重启设备reboot重启后 KernelSU 会跳过所有模块的加载进入系统后重新打开 KernelSU Manager 处理模块问题即可。上述路径与源码中的常量一一对应在 userspace/ksud/src/defs.rs#L26-L30 中定义了PREINIT_DIR_WATCHDOG /metadata/watchdog/ksu/、PREINIT_DIR_DEFAULT /metadata/ksu/以及MODULES_RC_FILE modules.rc而ksud正是通过将这些目录下各模块的*.rc拼接生成modules.rc来实现 init.rc 注入见 userspace/ksud/src/module.rs 中关于 Rebuild PREINITDIR/modules.rc by concatenating *.rc from every enabled 的逻辑并优先使用/metadata/watchdog/目录。这也解释了为什么文档要求同时删除两个位置的modules.rc设备可能因 watchdog 机制而使用任一路径。五、最后手段格式化数据或联系售后如果以上方法都无法救回设备那么大概率你安装的模块本身包含恶意操作或者已经通过其他方式损坏了设备。此时只剩两条建议清除数据并完整刷入官方系统wipe data flash official firmware。联系设备售后/维修服务。六、总结与最佳实践场景首选方案备选方案刷 boot 分区变砖刷回原厂 stock boot 镜像从同型号用户/官方固件获取原厂 boot安全模块导致 bootloop内核级 Safe Mode开机第一屏连按音量减 3 次系统自带 Safe ModeSafe Mode 无效ksud module disable/uninstallADB 或 Recovery 下均可Recovery 手动删除 ksud 与 modules.rc疑似恶意模块/硬件损坏清数据刷官方系统联系售后三个关键预防与自救要点刷机前先备份原厂 boot 镜像这是成本最低的保险只安装可信来源的模块从根源上降低 bootloop 风险牢记内核级 Safe Mode 的触发时序内核在模块初始化时注册音量键监听、在on_post_fs_data阶段注销窗口很短第一屏出现后立即连续点按音量减三次。上述自救机制均有源码级支撑内核判定逻辑见 kernel/runtime/ksud_integration.c监听窗口控制见 kernel/runtime/boot_event.c用户态安全模式判断与模块管理见 userspace/ksud/src/utils.rs、userspace/ksud/src/init_event.rs、userspace/ksud/src/module.rs 与 userspace/ksud/src/cli.rs。如需了解非 GKI 设备的内核集成方式可参考 website/docs/guide/how-to-integrate-for-non-gki.md关于模块的安装与配置可阅读 website/docs/guide/module.md 与 website/docs/guide/module-config.md。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 KernelSU 卡开机（Bootloop）自救完全指南：安全模式、ksud 命令行与 Recovery 手动清理
KernelSU 卡开机Bootloop自救完全指南安全模式、ksud 命令行与 Recovery 手动清理【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU导读刷机、安装模块或刷写 boot 分区时设备可能因为格式错误、AVB 校验、内核不兼容或模块异常而陷入 变砖bootloop状态。本文基于 KernelSU 官方文档website/docs/id_ID/guide/rescue-from-bootloop.md英文原版见 website/docs/guide/rescue-from-bootloop.md系统梳理三类典型的 bootloop 场景及其恢复手段刷回原厂 boot、内核级 Safe Mode安全模式、通过ksud命令行或 Recovery 手动清理模块。读完本文你将掌握在不开机情况下逐级自救的完整操作链路并了解这些机制在 KernelSU 内核与用户态中的真实实现原理。一、刷写 boot 分区导致的 Bootloop在 KernelSU 中刷写 boot 分区引发 bootloop 的常见原因有三种镜像格式错误例如设备 boot 分区原本是gz格式却刷入了lz4格式的镜像内核无法解压设备自然无法启动。AVB 校验未处理设备需要关闭 AVBAndroid Verified Boot校验才能正常引导而关闭 AVB 通常需要清除设备全部数据wipe data。内核本身有问题你编译或刷入的内核存在 bug或者与当前设备的硬件/固件不匹配。无论属于哪一种情况恢复手段都是统一的——刷回原厂stockboot 镜像。因此在官方安装教程的开头KernelSU 就强烈建议刷机前务必先备份原始 boot 镜像。如果当时没有备份可以从同型号设备的其他用户处获取或从官方固件factory firmware中提取。这一环节的要点是boot 分区刷写属于底层操作只要你能进入 fastboot 模式就可以通过fastboot flash boot stock_boot.img恢复从而绕开所有与 KernelSU 或模块相关的问题。二、模块导致的 Bootloop先认清风险边界安装模块是导致设备变砖的更常见原因。文档给出了明确的警告绝不安装来源不明的模块模块拥有 root 权限一旦执行恶意或错误操作可能对设备造成永久性损坏。因此在继续自救之前请先判断你安装的模块是否属于已知安全但导致无法开机的类型。对于这类模块KernelSU 提供了多层内置救援机制可以按下面章节的顺序逐级尝试。三、第一层救援Safe Mode安全模式Safe Mode 是 KernelSU 内置的模块级救援机制进入安全模式后所有模块都会被禁用系统可以正常启动然后你再在 KernelSU Manager 中逐个排查、卸载问题模块。3.1 两种进入方式方式一系统自带的安全模式部分系统固件自带安全模式有的可以通过长按音量减键进入有的如 MIUI/HyperOS需要从 Recovery 中开启。当系统进入其安全模式时KernelSU 会同步感知并自动禁用模块。方式二KernelSU 自带的内核级安全模式操作方法是在开机第一屏出现后连续快速按音量减键三次以上。注意动作要领是按下-松开、按下-松开、按下-松开的连续点按不是长按。3.2 底层实现内核态按键监听KernelSU 的 Safe Mode 直接在内核中实现因此不存在因用户态拦截而丢失关键事件的可能性。核心逻辑位于 kernel/runtime/ksud_integration.c内核维护一个计数器volumedown_pressed_count并通过ksu_handle_input_handle_event监听输入事件当type EV_KEY code KEY_VOLUMEDOWN且按键按下value非零时计数加一static unsigned int volumedown_pressed_count 0; static bool is_volumedown_enough(unsigned int count) { return count 3; // 连续按 3 次即触发 } int ksu_handle_input_handle_event(unsigned int *type, unsigned int *code, int *value) { if (*type EV_KEY *code KEY_VOLUMEDOWN) { int val *value; if (val) { volumedown_pressed_count 1; if (is_volumedown_enough(volumedown_pressed_count)) { ksu_stop_input_hook_runtime(); } } } return 0; }当ksu_is_safe_mode()被用户态查询时若计数达到 3 次及以上则置位safe_mode标志并返回true见 kernel/runtime/ksud_integration.c#L496-L520。用户态ksud的is_safe_mode()会先检查系统属性persist.sys.safemode/ro.sys.safemode对应系统自带安全模式再通过check_kernel_safemode()查询内核判定结果见 userspace/ksud/src/utils.rs#L152-L166。3.3 进入安全模式后发生了什么ksud检测到安全模式后会跳过所有模块的post-fs-data脚本并禁用全部模块同时仍确保模块目录存在以便你在安全模式下继续操作见 userspace/ksud/src/init_event.rs 中safe mode, skip post-fs-data scripts and disable all modules!等日志分支。进入安全模式后KernelSU Manager 模块页会显示所有模块处于禁用状态此时你可以直接对问题模块执行 uninstall 彻底移除。3.4 时序警告与局限::: warning监听窗口很短KernelSU 在内核模块初始化阶段LKM 模式下内核执行 init 进程时注册音量键监听并在on_post_fs_data阶段开机动画出现前注销。对应实现见 kernel/runtime/boot_event.c#L17-L34 中的on_post_fs_data()其中调用了ksu_stop_input_hook_runtime()。因此你需要把握时机在第一屏出现后迅速点按音量减三次如果设备开机过快或操作不及时Safe Mode 可能无法触发。initrc 恶意代码无法被豁免如果模块在 initrc 中写入了导致无法开机的代码那么即使在安全模式下这些代码依然会被执行——因为 Safe Mode 只负责禁用模块加载无法阻止已被注入到 init 脚本中的内容。非 GKI 内核需手动集成Safe Mode 由内核实现对于非 GKI 内核可能需要手动集成相关代码请参考官方集成文档如 website/docs/guide/how-to-integrate-for-non-gki.md。 :::四、第二层救援手动救援Manual Rescue当 Safe Mode 无法解决问题时根据设备当前状态选择以下两种手动方案之一。4.1 方法一通过 ADB 使用ksud命令管理模块适用前提设备还能通过 ADB 获取 root shell。直接使用ksud命令行禁用或卸载问题模块adb shell su ksud module list # 列出所有模块 ksud module disable id # 禁用有问题的模块 ksud module uninstall id # 或者直接卸载 reboot::: tipRecovery 模式下也可用挂载metadata与data分区后可以在 Recovery 模式下执行/data/adb/ksud来管理模块。由于 GKI 设备共享initRecovery 模式下 KernelSU 内核模块仍然会被加载因此ksud的大部分功能如设置 feature都可以正常使用。 :::从源码看ksud的子命令在 userspace/ksud/src/cli.rs 中分发Module::List对应列出模块Module::Disable对应module::disable_module(id)Module::Uninstall对应module::uninstall_module(id)另有Module::UndoUninstall可恢复误卸载见 userspace/ksud/src/cli.rs#L531-L534 与 userspace/ksud/src/module.rs 中的对应实现。4.2 方法二通过 Recovery 手动清理文件适用前提完全无法进入系统连 ADB 都无法连接。此时需要在设备上安装第三方 Recovery如 TWRP。KernelSU 的模块加载依赖两样东西内核侧的 init.rc 注入文件与用户态的 ksud 进程。删除这些文件并重启后KernelSU 将不再加载任何模块。操作步骤进入 Recovery如 TWRP。挂载 data 分区mount /data如果分区已加密可能需要先解密具体操作取决于设备与解密方式。删除 ksud阻止模块加载rm -f /data/adb/ksud可选挂载 metadata 分区删除模块生成的 init.rc 注入文件mount /metadata rm -f /metadata/ksu/modules.rc rm -f /metadata/watchdog/ksu/modules.rc重启设备reboot重启后 KernelSU 会跳过所有模块的加载进入系统后重新打开 KernelSU Manager 处理模块问题即可。上述路径与源码中的常量一一对应在 userspace/ksud/src/defs.rs#L26-L30 中定义了PREINIT_DIR_WATCHDOG /metadata/watchdog/ksu/、PREINIT_DIR_DEFAULT /metadata/ksu/以及MODULES_RC_FILE modules.rc而ksud正是通过将这些目录下各模块的*.rc拼接生成modules.rc来实现 init.rc 注入见 userspace/ksud/src/module.rs 中关于 Rebuild PREINITDIR/modules.rc by concatenating *.rc from every enabled 的逻辑并优先使用/metadata/watchdog/目录。这也解释了为什么文档要求同时删除两个位置的modules.rc设备可能因 watchdog 机制而使用任一路径。五、最后手段格式化数据或联系售后如果以上方法都无法救回设备那么大概率你安装的模块本身包含恶意操作或者已经通过其他方式损坏了设备。此时只剩两条建议清除数据并完整刷入官方系统wipe data flash official firmware。联系设备售后/维修服务。六、总结与最佳实践场景首选方案备选方案刷 boot 分区变砖刷回原厂 stock boot 镜像从同型号用户/官方固件获取原厂 boot安全模块导致 bootloop内核级 Safe Mode开机第一屏连按音量减 3 次系统自带 Safe ModeSafe Mode 无效ksud module disable/uninstallADB 或 Recovery 下均可Recovery 手动删除 ksud 与 modules.rc疑似恶意模块/硬件损坏清数据刷官方系统联系售后三个关键预防与自救要点刷机前先备份原厂 boot 镜像这是成本最低的保险只安装可信来源的模块从根源上降低 bootloop 风险牢记内核级 Safe Mode 的触发时序内核在模块初始化时注册音量键监听、在on_post_fs_data阶段注销窗口很短第一屏出现后立即连续点按音量减三次。上述自救机制均有源码级支撑内核判定逻辑见 kernel/runtime/ksud_integration.c监听窗口控制见 kernel/runtime/boot_event.c用户态安全模式判断与模块管理见 userspace/ksud/src/utils.rs、userspace/ksud/src/init_event.rs、userspace/ksud/src/module.rs 与 userspace/ksud/src/cli.rs。如需了解非 GKI 设备的内核集成方式可参考 website/docs/guide/how-to-integrate-for-non-gki.md关于模块的安装与配置可阅读 website/docs/guide/module.md 与 website/docs/guide/module-config.md。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考