KernelSU 模块配置系统完全指南持久化键值存储、生命周期与高级特性【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSUKernelSU 为模块提供了一套内建配置系统允许模块以键值对形式保存持久或临时配置并在模块脚本post-fs-data.sh、service.sh、boot-completed.sh等中通过ksud module config命令行随时读写。本文基于官方文档 模块配置指南及日文版 module-config.md结合 配置系统核心实现 的源码细节完整讲解配置类型、命令用法、校验限制、生命周期以及override.description与manage.feature两项高级特性帮助你为模块构建可靠的用户设置、功能开关与运行时状态管理。配置系统概览模块配置以二进制格式保存在/data/adb/ksu/module_configs/module_id/目录下每个模块拥有独立配置目录。目录与文件名常量定义于 defs.rspub const MODULE_CONFIG_DIR: str concatcp!(WORKING_DIR, module_configs/); pub const PERSIST_CONFIG_NAME: str persist.config; pub const TEMP_CONFIG_NAME: str tmp.config;即一个模块的配置目录中可能包含两个文件persist.config持久配置与tmp.config临时配置。文件采用带魔数与版本校验的二进制格式存储任何 UTF-8 数据包括换行、控制字符都能被安全地读写。配置类型类型文件名生命周期持久配置persist.config重启后保留直到显式删除或模块被卸载临时配置tmp.config每次开机时在 post-fs-data 阶段自动清空优先级规则读取配置时对同一个键临时值优先于持久值。这一合并逻辑在 module_config.rs 的merge_configs函数中实现——先加载持久配置再用临时配置逐键覆盖// Temp config overrides persist config for (key, value) in temp { merged.insert(key, value); }在模块脚本中使用配置所有模块脚本post-fs-data.sh、service.sh、boot-completed.sh等运行时KSU_MODULE环境变量会被设置为当前模块 ID。从源码看这一环境变量由 module.rs 中的get_common_script_envs统一注入同时注入的还有KSU、KSU_VER、KSU_KERNEL_VER_CODE等变量。因此脚本内可以直接执行ksud module config系列命令而无需显式指定模块 ID。读取配置值value$(ksud module config get my_setting)写入配置值# 设置持久配置值重启后保留 ksud module config set my_setting some value # 设置临时配置值重启后清空 ksud module config set --temp runtime_state active从 stdin 写入适合多行或复杂数据当值包含换行、JSON 等结构化内容时可省略位置参数而从 stdin 读取# 使用 heredoc 写入多行文本 ksud module config set my_key EOF 多行 文本值 EOF # 或从命令管道写入 echo value | ksud module config set my_key # 显式指定 stdin 标志即使提供了位置参数也强制读 stdin cat file.json | ksud module config set json_data --stdin从 cli.rs 的ModuleConfigCmd::Set实现看stdin 读取逻辑是当--stdin标志为真、或未提供位置参数时读取整个 stdin 直到 EOF 作为值。这意味着--stdin可用于显式区分“以命令行参数传值”和“以 stdin 传值”两种场景。列出、删除与清空# 列出全部配置项合并持久与临时临时优先 ksud module config list # 删除配置项默认删除持久配置中的项 ksud module config delete my_setting # 删除临时配置项 ksud module config delete --temp runtime_state # 清空全部持久配置 ksud module config clear # 清空全部临时配置 ksud module config clear --templist命令同样基于merge_configs输出合并结果格式为keyvalue逐行打印若配置为空则输出No config entries found。校验限制配置系统在写入时会强制执行以下限制常量与校验函数均定义于 module_config.rs限制项数值源码常量最大键长度256 字节MAX_CONFIG_KEY_LEN 256最大值长度1MB1048576 字节MAX_CONFIG_VALUE_LEN 1024 * 1024每个模块最大配置条目数32 个MAX_CONFIG_COUNT 32键格式必须匹配正则^[a-zA-Z][a-zA-Z0-9._-]$与模块 ID 相同的校验规则必须以字母a-zA-Z开头可包含字母、数字、点号.、下划线_、连字符-最小长度为 2 个字符。校验实现在validate_config_key中它复用regex_lite对同一正则进行匹配与模块 ID 校验保持一致见 module.rs 的validate_module_id。值格式无任何字符限制——可以包含换行、控制字符等任意 UTF-8 字符。值以“长度前缀 原始字节”的二进制形式存储确保所有数据安全处理validate_config_value仅检查长度上限不限制字符集。条目数校验save_config在写盘前会通过validate_config_count检查条目总数是否超过 32超限直接报错。生命周期开机时所有模块的临时配置会在 post-fs-data 阶段被自动清空。对应实现为clear_all_temp_configs()它遍历module_configs/下每个模块目录并删除其中的tmp.config文件。模块卸载时该模块的所有配置持久与临时会随配置目录一起被删除。对应实现为clear_module_configs(module_id)直接移除整个module_id配置目录该函数在卸载流程中被调用见 module.rs 中卸载相关逻辑。文件格式配置文件使用魔数0x4b53554d即 ASCII 字符串 KSUM与版本号当前为 1进行校验读取时魔数或版本不匹配会直接报错避免解析损坏数据。写入采用“先写临时文件再原子重命名”的方式save_config中先创建name.tmp再fs::rename并调用sync_all确保落盘防止意外断电导致文件损坏。典型使用场景配置系统最适合以下需求用户偏好设置存储用户通过 WebUI 或 action 脚本配置的模块选项功能开关无需重新安装即可启用/禁用模块的某个功能运行时状态跟踪应在重启时重置的临时状态使用临时配置安装期设置记住模块安装时用户做出的选择复杂数据保存 JSON、多行文本、Base64 编码数据或任意结构化内容上限 1MB。最佳实践需要跨重启保留的用户偏好使用持久配置应在开机时重置的运行时状态或功能开关使用临时配置在脚本中使用配置值之前先做校验排查配置问题时使用ksud module config list查看合并后的完整配置。高级特性覆盖模块描述override.description通过设置override.description配置键可以动态覆盖module.prop中的description字段# 覆盖模块描述 ksud module config set override.description 在管理器里显示的自定义描述当获取模块列表时如果override.description配置存在它会替换module.prop中的原始描述。从 module.rs 的模块列表构建逻辑可以看到这一替换过程// Apply override.description if let Some(desc) config.get(override.description) { module_prop_map.insert(description.to_owned(), desc.clone()); }该特性适用于在模块描述中显示动态状态信息向用户展示运行时配置详情无需重新安装即可根据模块状态更新描述。声明托管功能manage.feature模块可以使用manage.feature配置模式声明其托管哪些 KernelSU 功能。这些功能与 KernelSU 内部的FeatureId枚举相对应完整枚举见 feature.rs共包含su_compat、kernel_umount、sulog、adb_root、selinux_hide五个成员。本配置模式支持的功能su_compat—— SU 兼容模式kernel_umount—— 内核自动卸载# 声明本模块托管 SU 兼容模式并将其启用 ksud module config set manage.su_compat true # 声明本模块托管内核卸载并将其禁用 ksud module config set manage.kernel_umount false # 移除功能托管模块不再控制该功能 ksud module config delete manage.su_compat工作原理manage.feature键的存在即表示模块正在托管该功能值表示期望状态true/1表示启用false/0或任何其他值表示禁用要停止托管某个功能直接删除该配置键。布尔值的解析在 module_config.rs 的parse_bool_config中实现对值做 trim 后true或1不区分大小写视为真其余一律视为假。托管功能的暴露与冲突控制托管功能会通过模块列表 API 以managedFeatures字段逗号分隔字符串暴露。在 module.rs 的列表构建中所有以manage.开头且值为真的配置键会被收集并拼成该字段。其作用包括让 KernelSU 管理器检测哪些模块托管了哪些 KernelSU 功能防止多个模块尝试托管同一功能时产生冲突——feature.rs 的set_feature在写入前会检查该功能是否已被其他模块托管若被托管且调用方不是托管模块会直接拒绝修改实现模块与 KernelSU 核心功能之间的更好协调——初始化阶段init_features会自动跳过被模块托管的功能把控制权交给对应模块。警告仅使用受支持的功能名。请只使用上文列出的预定义功能名su_compat、kernel_umount它们对应 KernelSU 内部真实存在的功能。使用其他功能名不会报错但没有任何实际作用。总结KernelSU 的模块配置系统为模块开发提供了一套安全、可靠且功能完整的键值存储方案持久/临时双文件模型配合“临时优先”的合并语义覆盖了从用户偏好到运行时状态的各类需求严格的键名校验与二进制长度前缀存储保证了数据安全override.description与manage.feature两个高级特性则让模块能够动态影响管理器展示和 KernelSU 核心功能状态。结合 配置实现源码、CLI 定义 与 模块列表逻辑 阅读本文即可完整掌握这一机制并应用于实际模块开发。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考