企业官网建设流程全解析

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.rs：

• MODULE_CONFIG_DIR=/data/adb/ksu/module_configs/
• PERSIST_CONFIG_NAME=persist.config
• TEMP_CONFIG_NAME=tmp.config

也就是说，每个模块目录下最多出现两个文件：persist.config（持久配置）与tmp.config（临时配置）。配置文件的二进制结构在 module_config.rs 中定义：

• Magic Number：固定为0x4b53554d（即 ASCII "KSUM"），用于识别合法配置文件；
• 版本号：当前为1（MODULE_CONFIG_VERSION），读取时校验，防止格式不兼容；
• 条目计数：4 字节小端无符号整数，表示配置条目数量；
• 条目序列：每条由"key 长度（4 字节）+ key 字节 + value 长度（4 字节）+ value 字节"组成，长度前缀设计保证了任意 UTF-8 内容（含换行、控制字符）都能被安全读写。

写入时 save_config 采用"先写临时文件、sync_all落盘、再原子rename"的策略，避免中途断电或进程被杀导致配置文件损坏。

两种配置类型：持久与临时

对应源码中的 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 --stdin

set命令的参数解析逻辑见 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 --temp

delete在 key 不存在时会报错（见 delete_config_value）；clear则是直接删除对应配置文件（见 clear_config），文件不存在时静默成功。

完整的子命令定义（Get/Set/List/Delete/Clear）在 cli.rs 的ModuleConfigCmd枚举中，Set支持--stdin与--temp两个可选标志，Delete与Clear支持--temp。

验证限制：key 与 value 的边界

配置系统在写入时会强制执行以下限制，规则实现在 module_config.rs 与校验函数中：

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 中会先清理配置目录再删除模块本体；
• 文件格式校验：读取时校验 magic（0x4b53554d/ "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 枚举对应，文档明确支持以下两个：

其余FeatureId（sulog、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