KernelSU 模块配置系统实战指南用ksud module config管理持久化与临时配置、覆盖描述与声明托管功能【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU本文系统讲解 KernelSU 内置的模块配置Module Configuration系统模块如何在/data/adb/ksu/module_configs/module_id/下以二进制格式存储持久persist与临时tmp两类 key-value 配置如何在post-fs-data.sh、service.sh、boot-completed.sh等模块脚本中用ksud module config系列命令读写配置以及override.description动态覆盖描述、manage.feature声明托管内核功能等高级用法。读完本文你将能在自己的 KernelSU 模块中实现用户偏好持久化、功能开关、运行时状态跟踪等完整能力并理解其底层校验与生命周期机制。本文基于仓库文档 module-config.md 并结合 userspace/ksud/src/module_config.rs 等源码编写。配置系统概览存储位置与文件格式KernelSU 的模块配置系统为每个模块提供独立的配置空间配置以二进制格式存放在/data/adb/ksu/module_configs/module_id/其中module_id与模块的module.prop中声明的id一致。目录常量与文件名常量定义在 defs.rsMODULE_CONFIG_DIR/data/adb/ksu/module_configs/PERSIST_CONFIG_NAMEpersist.configTEMP_CONFIG_NAMEtmp.config也就是说每个模块目录下最多出现两个文件persist.config持久配置与tmp.config临时配置。配置文件的二进制结构在 module_config.rs 中定义Magic Number固定为0x4b53554d即 ASCII KSUM用于识别合法配置文件版本号当前为1MODULE_CONFIG_VERSION读取时校验防止格式不兼容条目计数4 字节小端无符号整数表示配置条目数量条目序列每条由key 长度4 字节 key 字节 value 长度4 字节 value 字节组成长度前缀设计保证了任意 UTF-8 内容含换行、控制字符都能被安全读写。写入时 save_config 采用先写临时文件、sync_all落盘、再原子rename的策略避免中途断电或进程被杀导致配置文件损坏。两种配置类型持久与临时配置类型存储文件生命周期持久配置Persistpersist.config跨重启保留直到被显式删除或模块被卸载临时配置Temptmp.config每次开机在post-fs-data 阶段自动清除对应源码中的 ConfigType 枚举ConfigType::Persist与ConfigType::Temp分别映射到上述两个文件名。一个关键行为是读取优先级当同一个 key 同时存在于持久与临时配置中时临时值优先于持久值。这在 merge_configs 中实现——先加载 persist 配置再以 temp 配置逐条覆盖同名 key。临时配置的清理发生在开机早期init_event.rs的on_post_data_fs()会调用clear_all_temp_configs()见 init_event.rs遍历module_configs/下所有模块目录并删除其中的tmp.config。因此临时配置非常适合只活一个开机周期的运行时状态。在模块脚本中使用配置命令所有模块脚本post-fs-data.sh、service.sh、boot-completed.sh等运行时ksud都会把环境变量KSU_MODULE设置为当前模块的 ID见 module.rs。ksud module config子命令默认通过读取KSU_MODULE确定操作对象因此模块脚本内可直接调用无需手写模块 ID。读取配置值value$(ksud module config get my_setting)get走的是 merge_configs即返回的是合并后的结果临时值优先其次持久值若 key 不存在则报错退出。写入配置值# 设置持久配置默认 ksud module config set my_setting some value # 设置临时配置重启后自动清除 ksud module config set --temp runtime_state active # 从 stdin 读取值适合多行文本或复杂数据 ksud module config set my_key EOF teks multiline nilai EOF # 或从命令管道输入 echo value | ksud module config set my_key # 显式指定 --stdin 标志 cat file.json | ksud module config set json_data --stdinset命令的参数解析逻辑见 cli.rs--temp决定写入ConfigType::Temp--stdin或省略 value 参数时从标准输入完整读取字符串作为值。写入前会先在 CLI 层调用validate_config_key与validate_config_value做快速校验再交由 set_config_value 落盘。列举、删除与清空# 列出全部配置条目持久 临时合并结果 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 --tempdelete在 key 不存在时会报错见 delete_config_valueclear则是直接删除对应配置文件见 clear_config文件不存在时静默成功。完整的子命令定义Get/Set/List/Delete/Clear在 cli.rs 的ModuleConfigCmd枚举中Set支持--stdin与--temp两个可选标志Delete与Clear支持--temp。验证限制key 与 value 的边界配置系统在写入时会强制执行以下限制规则实现在 module_config.rs 与校验函数中限制项上限说明key 最大长度256 字节超长直接报错value 最大长度1MB1048576 字节二进制长度前缀存储每个模块配置条目数32 条超限报错key 格式^[a-zA-Z][a-zA-Z0-9._-]$与模块 ID 规则一致key 的具体约束见 validate_config_key必须以字母a-zA-Z开头可包含字母、数字、点.、下划线_、连字符-最小长度 2 个字符正则中表示至少一个后续字符非空、且字节长度不超过 256。value 则没有任何字符限制见 validate_config_value可以是任意 UTF-8 文本包括换行、控制字符、JSON、Base64 编码数据等唯一约束是字节长度不超过 1MB。由于采用二进制 长度前缀存储所有数据都能安全往返这也是value 无格式限制得以成立的根本原因。条目总数在 validate_config_count 中校验上限 32 条/模块写入前由save_config统一检查。配置生命周期开机清理与卸载清理开机时post-fs-data 阶段调用clear_all_temp_configs()清除所有模块的临时配置init_event.rs持久配置不受影响模块卸载时调用clear_module_configs()直接删除整个/data/adb/ksu/module_configs/module_id/目录见 module_config.rs持久与临时配置一并移除。模块移除流程在 module.rs 中会先清理配置目录再删除模块本体文件格式校验读取时校验 magic0x4b53554d/ KSUM与版本号不匹配即拒绝加载load_config。典型使用场景配置系统在设计上覆盖了模块开发的常见需求用户偏好用户在 WebUI 或 action 脚本中设置的选项写入持久配置重启不丢失功能标志Feature Flags无需重装模块即可开/关模块内功能运行时状态需要每次开机重置的临时状态使用临时配置安装设置记录模块安装过程中的选择如是否安装附带组件复杂数据JSON、多行文本、Base64 数据或任意结构化内容上限 1MB。最佳实践需要跨重启保留的用户偏好 → 用持久配置应在开机时重置的运行时状态/功能开关 → 用临时配置脚本中使用配置值前先做校验如判断是否为空、是否合法数值排查问题时先用ksud module config list查看合并后的实际条目确认是持久还是临时值生效。高级功能动态覆盖模块描述配置系统提供了一个特殊 keyoverride.description可动态覆盖module.prop中的description字段而无需重新安装模块# 覆盖模块描述在管理器/列表中显示自定义描述 ksud module config set override.description Deskripsi kustom yang ditampilkan di pengelola # 取消覆盖 ksud module config delete override.description其实现位于 module.rs 的list_module枚举模块时一次性加载全部模块配置get_all_module_configs若某模块配置中存在override.description就用该值替换从module.prop读出的description字段。这一能力非常适合在描述中展示动态状态信息如已启用 X 功能向用户呈现运行时配置细节根据模块状态实时更新描述全程无需重装。高级功能声明托管的内核功能manage.feature模块可通过manage.feature形式的配置键声明自己托管了 KernelSU 的某个内核功能。可用的功能名与 KernelSU 内部 FeatureId 枚举对应文档明确支持以下两个功能名含义su_compatSU 兼容模式kernel_umount内核自动卸载unmount其余FeatureIdsulog、adb_root、selinux_hide也在源码中定义但模块配置层面当前仅开放上述两个。用法示例# 声明本模块托管 SU 兼容功能并开启它 ksud module config set manage.su_compat true # 声明本模块托管内核卸载功能并关闭它 ksud module config set manage.kernel_umount false # 取消托管模块不再控制该功能 ksud module config delete manage.su_compat工作机制key 存在即代表模块在托管该功能值表示期望状态true/1大小写不敏感视为启用false/0或其他任意值视为禁用。判定逻辑在 parse_bool_config停止托管的方法是直接删除整个 key。当manage.feature的值为真时该功能名会被收集进模块列表 API 的managedFeatures字段逗号分隔字符串见 module.rs。聚合后的托管关系由get_managed_features()返回module.rs并被用于让 KernelSU 管理器识别哪些模块托管了哪些内核功能在多个模块尝试托管同一功能时预防冲突在feature相关命令如 set 功能值中检查功能是否被模块托管feature.rs实现模块与内核核心功能间的协调。安装器脚本同样会读取managedFeatures属性用于模块安装时的功能检查见 installer.sh。::: warning 仅支持预定义功能名 请只使用上表列出的预定义功能名su_compat、kernel_umount它们与 KernelSU 实际内核功能一一对应。使用其他名称虽然不会报错但没有任何功能效果。 :::总结KernelSU 的模块配置系统为模块开发提供了零学习成本、开箱即用的状态存储方案ksud module config子命令与KSU_MODULE环境变量配合让脚本内读写配置像 shell 变量一样自然持久/临时双通道 临时优先的合并语义恰好覆盖长期偏好与开机重置状态两类需求256 字节 key / 1MB value / 32 条上限的明确边界配合 magic 版本校验的二进制格式保证了存储的健壮性。override.description与manage.feature两个高级键则把配置系统延伸到模块元数据与内核功能协调层面是构建复杂 KernelSU 模块时不可错过的能力。如需查阅英文原版文档可阅读 website/docs/guide/module-config.md底层实现可深入 userspace/ksud/src/module_config.rs。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
KernelSU 模块配置系统实战指南用ksud module config管理持久化与临时配置、覆盖描述与声明托管功能【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU本文系统讲解 KernelSU 内置的模块配置Module Configuration系统模块如何在/data/adb/ksu/module_configs/module_id/下以二进制格式存储持久persist与临时tmp两类 key-value 配置如何在post-fs-data.sh、service.sh、boot-completed.sh等模块脚本中用ksud module config系列命令读写配置以及override.description动态覆盖描述、manage.feature声明托管内核功能等高级用法。读完本文你将能在自己的 KernelSU 模块中实现用户偏好持久化、功能开关、运行时状态跟踪等完整能力并理解其底层校验与生命周期机制。本文基于仓库文档 module-config.md 并结合 userspace/ksud/src/module_config.rs 等源码编写。配置系统概览存储位置与文件格式KernelSU 的模块配置系统为每个模块提供独立的配置空间配置以二进制格式存放在/data/adb/ksu/module_configs/module_id/其中module_id与模块的module.prop中声明的id一致。目录常量与文件名常量定义在 defs.rsMODULE_CONFIG_DIR/data/adb/ksu/module_configs/PERSIST_CONFIG_NAMEpersist.configTEMP_CONFIG_NAMEtmp.config也就是说每个模块目录下最多出现两个文件persist.config持久配置与tmp.config临时配置。配置文件的二进制结构在 module_config.rs 中定义Magic Number固定为0x4b53554d即 ASCII KSUM用于识别合法配置文件版本号当前为1MODULE_CONFIG_VERSION读取时校验防止格式不兼容条目计数4 字节小端无符号整数表示配置条目数量条目序列每条由key 长度4 字节 key 字节 value 长度4 字节 value 字节组成长度前缀设计保证了任意 UTF-8 内容含换行、控制字符都能被安全读写。写入时 save_config 采用先写临时文件、sync_all落盘、再原子rename的策略避免中途断电或进程被杀导致配置文件损坏。两种配置类型持久与临时配置类型存储文件生命周期持久配置Persistpersist.config跨重启保留直到被显式删除或模块被卸载临时配置Temptmp.config每次开机在post-fs-data 阶段自动清除对应源码中的 ConfigType 枚举ConfigType::Persist与ConfigType::Temp分别映射到上述两个文件名。一个关键行为是读取优先级当同一个 key 同时存在于持久与临时配置中时临时值优先于持久值。这在 merge_configs 中实现——先加载 persist 配置再以 temp 配置逐条覆盖同名 key。临时配置的清理发生在开机早期init_event.rs的on_post_data_fs()会调用clear_all_temp_configs()见 init_event.rs遍历module_configs/下所有模块目录并删除其中的tmp.config。因此临时配置非常适合只活一个开机周期的运行时状态。在模块脚本中使用配置命令所有模块脚本post-fs-data.sh、service.sh、boot-completed.sh等运行时ksud都会把环境变量KSU_MODULE设置为当前模块的 ID见 module.rs。ksud module config子命令默认通过读取KSU_MODULE确定操作对象因此模块脚本内可直接调用无需手写模块 ID。读取配置值value$(ksud module config get my_setting)get走的是 merge_configs即返回的是合并后的结果临时值优先其次持久值若 key 不存在则报错退出。写入配置值# 设置持久配置默认 ksud module config set my_setting some value # 设置临时配置重启后自动清除 ksud module config set --temp runtime_state active # 从 stdin 读取值适合多行文本或复杂数据 ksud module config set my_key EOF teks multiline nilai EOF # 或从命令管道输入 echo value | ksud module config set my_key # 显式指定 --stdin 标志 cat file.json | ksud module config set json_data --stdinset命令的参数解析逻辑见 cli.rs--temp决定写入ConfigType::Temp--stdin或省略 value 参数时从标准输入完整读取字符串作为值。写入前会先在 CLI 层调用validate_config_key与validate_config_value做快速校验再交由 set_config_value 落盘。列举、删除与清空# 列出全部配置条目持久 临时合并结果 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 --tempdelete在 key 不存在时会报错见 delete_config_valueclear则是直接删除对应配置文件见 clear_config文件不存在时静默成功。完整的子命令定义Get/Set/List/Delete/Clear在 cli.rs 的ModuleConfigCmd枚举中Set支持--stdin与--temp两个可选标志Delete与Clear支持--temp。验证限制key 与 value 的边界配置系统在写入时会强制执行以下限制规则实现在 module_config.rs 与校验函数中限制项上限说明key 最大长度256 字节超长直接报错value 最大长度1MB1048576 字节二进制长度前缀存储每个模块配置条目数32 条超限报错key 格式^[a-zA-Z][a-zA-Z0-9._-]$与模块 ID 规则一致key 的具体约束见 validate_config_key必须以字母a-zA-Z开头可包含字母、数字、点.、下划线_、连字符-最小长度 2 个字符正则中表示至少一个后续字符非空、且字节长度不超过 256。value 则没有任何字符限制见 validate_config_value可以是任意 UTF-8 文本包括换行、控制字符、JSON、Base64 编码数据等唯一约束是字节长度不超过 1MB。由于采用二进制 长度前缀存储所有数据都能安全往返这也是value 无格式限制得以成立的根本原因。条目总数在 validate_config_count 中校验上限 32 条/模块写入前由save_config统一检查。配置生命周期开机清理与卸载清理开机时post-fs-data 阶段调用clear_all_temp_configs()清除所有模块的临时配置init_event.rs持久配置不受影响模块卸载时调用clear_module_configs()直接删除整个/data/adb/ksu/module_configs/module_id/目录见 module_config.rs持久与临时配置一并移除。模块移除流程在 module.rs 中会先清理配置目录再删除模块本体文件格式校验读取时校验 magic0x4b53554d/ KSUM与版本号不匹配即拒绝加载load_config。典型使用场景配置系统在设计上覆盖了模块开发的常见需求用户偏好用户在 WebUI 或 action 脚本中设置的选项写入持久配置重启不丢失功能标志Feature Flags无需重装模块即可开/关模块内功能运行时状态需要每次开机重置的临时状态使用临时配置安装设置记录模块安装过程中的选择如是否安装附带组件复杂数据JSON、多行文本、Base64 数据或任意结构化内容上限 1MB。最佳实践需要跨重启保留的用户偏好 → 用持久配置应在开机时重置的运行时状态/功能开关 → 用临时配置脚本中使用配置值前先做校验如判断是否为空、是否合法数值排查问题时先用ksud module config list查看合并后的实际条目确认是持久还是临时值生效。高级功能动态覆盖模块描述配置系统提供了一个特殊 keyoverride.description可动态覆盖module.prop中的description字段而无需重新安装模块# 覆盖模块描述在管理器/列表中显示自定义描述 ksud module config set override.description Deskripsi kustom yang ditampilkan di pengelola # 取消覆盖 ksud module config delete override.description其实现位于 module.rs 的list_module枚举模块时一次性加载全部模块配置get_all_module_configs若某模块配置中存在override.description就用该值替换从module.prop读出的description字段。这一能力非常适合在描述中展示动态状态信息如已启用 X 功能向用户呈现运行时配置细节根据模块状态实时更新描述全程无需重装。高级功能声明托管的内核功能manage.feature模块可通过manage.feature形式的配置键声明自己托管了 KernelSU 的某个内核功能。可用的功能名与 KernelSU 内部 FeatureId 枚举对应文档明确支持以下两个功能名含义su_compatSU 兼容模式kernel_umount内核自动卸载unmount其余FeatureIdsulog、adb_root、selinux_hide也在源码中定义但模块配置层面当前仅开放上述两个。用法示例# 声明本模块托管 SU 兼容功能并开启它 ksud module config set manage.su_compat true # 声明本模块托管内核卸载功能并关闭它 ksud module config set manage.kernel_umount false # 取消托管模块不再控制该功能 ksud module config delete manage.su_compat工作机制key 存在即代表模块在托管该功能值表示期望状态true/1大小写不敏感视为启用false/0或其他任意值视为禁用。判定逻辑在 parse_bool_config停止托管的方法是直接删除整个 key。当manage.feature的值为真时该功能名会被收集进模块列表 API 的managedFeatures字段逗号分隔字符串见 module.rs。聚合后的托管关系由get_managed_features()返回module.rs并被用于让 KernelSU 管理器识别哪些模块托管了哪些内核功能在多个模块尝试托管同一功能时预防冲突在feature相关命令如 set 功能值中检查功能是否被模块托管feature.rs实现模块与内核核心功能间的协调。安装器脚本同样会读取managedFeatures属性用于模块安装时的功能检查见 installer.sh。::: warning 仅支持预定义功能名 请只使用上表列出的预定义功能名su_compat、kernel_umount它们与 KernelSU 实际内核功能一一对应。使用其他名称虽然不会报错但没有任何功能效果。 :::总结KernelSU 的模块配置系统为模块开发提供了零学习成本、开箱即用的状态存储方案ksud module config子命令与KSU_MODULE环境变量配合让脚本内读写配置像 shell 变量一样自然持久/临时双通道 临时优先的合并语义恰好覆盖长期偏好与开机重置状态两类需求256 字节 key / 1MB value / 32 条上限的明确边界配合 magic 版本校验的二进制格式保证了存储的健壮性。override.description与manage.feature两个高级键则把配置系统延伸到模块元数据与内核功能协调层面是构建复杂 KernelSU 模块时不可错过的能力。如需查阅英文原版文档可阅读 website/docs/guide/module-config.md底层实现可深入 userspace/ksud/src/module_config.rs。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
