尧图网站建设 
KernelSU 模組配置系統完全指南ksud module config持久化與暫時鍵值存儲實戰【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU導讀KernelSU 為模組開發者提供了一套內建的鍵值配置系統讓模組可以在/data/adb/ksu/module_configs/module_id/下以二進位格式儲存持久化或暫時性的設定並在模組腳本post-fs-data.sh、service.sh、boot-completed.sh等中以ksud module config子命令輕鬆讀寫。本文將以 KernelSU 官方文件為主體結合 module_config.rs 等真實原始碼完整講解配置類型、命令用法、驗證限制、生命週期以及override.description動態覆寫描述、manage.feature宣告管理功能等進階用法幫助你寫出可持久保存使用者偏好、可動態切換功能開關的成熟模組。配置系統概述KernelSU 的模組配置系統是內建於ksudKernelSU 的使用者空間守護程式中的能力。所有配置以二進位格式儲存在/data/adb/ksu/module_configs/module_id/其中module_id即模組 ID與模組目錄名及module.prop中的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。配置類型配置系統區分兩種存儲類型二者的差異決定了資料的生命週期類型檔名生命週期典型用途持久配置Persist Configpersist.config重新開機後保留直到被明確刪除或模組被解除安裝使用者偏好、安裝設定暫時配置Temp Configtmp.config每次啟動的 post-fs-data 階段自動清除執行時狀態、啟動即重置的功能開關在 module_config.rs 中兩種型別對應ConfigType列舉並透過filename()方法映射到各自的檔名#[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum ConfigType { Persist, Temp, } impl ConfigType { const fn filename(self) - static str { match self { Self::Persist defs::PERSIST_CONFIG_NAME, Self::Temp defs::TEMP_CONFIG_NAME, } } }讀取優先級當讀取某個鍵的值時暫時值優先於持久值。這一合併邏輯在 merge_configs 中實現——先載入持久配置再將暫時配置逐項覆蓋寫入pub fn merge_configs(module_id: str) - ResultHashMapString, String { let mut merged load_config(module_id, ConfigType::Persist)?; let temp load_config(module_id, ConfigType::Temp)?; // Temp config overrides persist config for (key, value) in temp { merged.insert(key, value); } Ok(merged) }這意味著如果同一個鍵同時存在於兩種類型中暫時配置會遮蔽持久配置的值。在模組腳本中使用配置所有模組腳本post-fs-data.sh、service.sh、boot-completed.sh等執行時ksud都會將環境變數KSU_MODULE設定為當前模組 ID。因此模組內可以直接呼叫ksud module config系列命令來管理自己的配置。從 cli.rs 的原始碼可以看到執行配置命令時ksud會從環境變數KSU_MODULE取得模組 ID若環境變數不存在例如在 adb shell 中手動測試則需要透過--internal name指定let module_id match internal { Some(internal_name) format!(internal.{internal_name}), None std::env::var(KSU_MODULE).map_err(|_| { anyhow::anyhow!( This command must be run in the context of a module or passed --internal name ) })?, };基本命令用法以下命令應在模組腳本環境KSU_MODULE已設定中執行# 取得配置值暫時優先於持久 value$(ksud module config get my_setting) # 設定持久配置值 ksud module config set my_setting some value # 設定暫時配置值重新開機後清除 ksud module config set --temp runtime_state active # 列出所有配置項合併持久和暫時配置 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從原始碼看ModuleConfigCmd::Set會在寫入前於 CLI 層先驗證鍵與值再根據--temp旗標選擇ConfigType::Temp或ConfigType::Persist最後呼叫set_config_value完成寫入。從 stdin 設定值對於多行文字或 JSON 等複雜資料可以從標準輸入讀取值。原始碼中當--stdin旗標被指定或未提供值參數時ksud會將整個 stdin 讀入作為值cli.rs# 從 here-document 設定值適用於多行或複雜資料 ksud module config set my_key EOF 多行 文字值 EOF # 從命令管道輸入 echo value | ksud module config set my_key # 明確使用 stdin 旗標 cat file.json | ksud module config set json_data --stdin注意從 stdin 讀入時換行符會被完整保留read_to_string讀取全部內容適合儲存 JSON、Base64 等結構化資料。驗證限制配置系統在寫入時強制執行以下限制違反會直接報錯。這些常量定義於 module_config.rspub const MAX_CONFIG_KEY_LEN: usize 256; pub const MAX_CONFIG_VALUE_LEN: usize 1024 * 1024; // 1MB pub const MAX_CONFIG_COUNT: usize 32;最大鍵長度256 位元組最大值長度1MB1048576 位元組最大配置項數每個模組 32 個鍵格式必須符合^[a-zA-Z][a-zA-Z0-9._-]$與模組 ID 相同的規則必須以字母a-zA-Z開頭後續可包含字母、數字、點.、底線_或連字號-最小長度2 個字元值格式無限制——可包含任何 UTF-8 字元包括換行符、控制字元等鍵格式的驗證在 validate_config_key 中實現與模組 ID 使用同一個正則regex_lite::Regex::new(r^[a-zA-Z][a-zA-Z0-9._-]$)保證了鍵的跨場景一致性而 validate_config_value 只檢查最大長度、不限制字元集因為二進位儲存格式天然保證了任意 UTF-8 資料的安全處理。儲存格式與寫入機制配置檔案採用自訂二進位格式module_config.rsconst MODULE_CONFIG_MAGIC: u32 0x4b53554d; // KSUM const MODULE_CONFIG_VERSION: u32 1;檔案佈局如下魔數4 位元組小端序0x4b53554d即 ASCII 字串KSUM用於識別檔案類型版本號4 位元組目前為1讀取時會校驗版本不符直接拒絕載入配置項數量4 位元組逐項寫入每項由「鍵長度4 位元組 鍵資料 值長度4 位元組 值資料」組成。在載入過程中讀取器依序讀取魔數、版本、數量再迴圈讀取每一項的長度前綴與資料任何一步失敗都會返回錯誤而非靜默損壞。寫入時採用了先寫暫存檔再原子改名的策略save_configlet temp_path config_path.with_extension(tmp); // 寫入暫存檔 ... file.sync_all()?; // 原子改名 fs::rename(temp_path, config_path)?;先將完整內容寫入persist.config.tmp呼叫sync_all()強制刷盤後再用fs::rename原子替換正式檔。這樣即使寫入中途崩潰也不會留下半截的配置檔案保證了資料完整性。生命週期啟動時所有暫時配置在 post-fs-data 階段清除。clear_all_temp_configs 會遍歷配置根目錄下每個模組目錄刪除其中的tmp.config檔案僅保留持久配置。模組解除安裝時所有配置持久和暫時自動刪除。clear_module_configs 直接以fs::remove_dir_all移除整個module_id配置目錄。格式自校驗配置以二進位格式儲存帶魔數0x4b53554dKSUM與版本驗證載入時會校驗魔數與版本防止損壞或不相容的檔案被誤讀。使用場景配置系統適用於以下典型場景使用者偏好儲存使用者透過 WebUI 或 action 腳本配置的模組設定使用持久配置功能開關在不重新安裝的情況下啟用/停用模組功能執行時狀態追蹤應在重新開機時重置的暫時狀態使用暫時配置安裝設定記住模組安裝時做出的選擇複雜資料儲存 JSON、多行文字、Base64 編碼資料或任何結構化內容最多 1MB::: tip 最佳實踐對於應在重新開機後保留的使用者偏好使用持久配置對於應在啟動時重置的執行時狀態或功能開關使用暫時配置在腳本中使用配置值之前驗證它們使用ksud module config list命令偵錯配置問題 :::從原始碼看list命令cli.rs使用merge_configs合併兩種類型後以keyvalue格式逐行輸出是排查「值是否符合預期」最直接的手段。進階功能特殊配置鍵模組配置系統為進階用例提供了兩個特殊的配置鍵模式其實現位於 module.rs 的模組列表組裝邏輯中。覆蓋模組描述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. 模組可以使用manage.feature配置模式宣告它們管理的 KernelSU 功能。支援的功能對應於 KernelSU 內部的FeatureId列舉——定義於 feature.h目前共 5 個功能 IDenum ksu_feature_id { KSU_FEATURE_SU_COMPAT 0, KSU_FEATURE_KERNEL_UMOUNT 1, KSU_FEATURE_SULOG 2, KSU_FEATURE_ADB_ROOT 3, KSU_FEATURE_SELINUX_HIDE 4, KSU_FEATURE_MAX };其中可供模組宣告管理的預定義功能為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工作原理對應 module.rs 的實現manage.feature鍵的存在表示模組正在管理該功能值表示期望的狀態true/1代表啟用false/0或任何其他值代表停用要停止管理某個功能請完全刪除該配置鍵值的解析由 parse_bool_config 完成——先trim()去除空白再忽略大小寫比對true或1pub fn parse_bool_config(value: str) - bool { let trimmed value.trim(); trimmed.eq_ignore_ascii_case(true) || trimmed 1 }被管理且為啟用狀態的功能會透過模組列表 API 以managedFeatures欄位逗號分隔的字串公開module.rs。此外get_managed_features 會聚合所有活躍模組宣告的功能供核心層協調使用。這允許KernelSU 管理器偵測哪些模組管理哪些 KernelSU 功能防止多個模組嘗試管理同一功能時發生衝突更好地協調模組與核心 KernelSU 功能之間的關係::: warning 僅支援預定義功能 僅使用上面列出的預定義功能名稱su_compat、kernel_umount。這些對應於實際的 KernelSU 內部功能。使用其他功能名稱不會導致錯誤但沒有任何功能作用——請勿以sulog、adb_root等列舉中的其他值作為manage.feature鍵它們並未列入官方支援的清單。 :::與其他模組能力的配合配置系統並非孤立存在它與 KernelSU 模組體系的其餘部分緊密配合WebUI / action 腳本使用者可在 WebUI 介面或執行 action 腳本時透過ksud module config set寫入配置讓設定在腳本下一次執行時生效模組生命週期解除安裝時配置目錄隨之清除無需手動清理殘留啟動流程post-fs-data 階段的暫時配置清理clear_all_temp_configs保證每次開機都是乾淨的執行時狀態。如需了解模組的整體規範module.prop欄位、目錄結構、腳本約定可繼續參閱 module.md若想深入配置命令在 CLI 層的完整分支邏輯可直接閱讀 cli.rs 與 module_config.rs 的原始碼。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 KernelSU 模組配置系統完全指南：`ksud module config` 持久化與暫時鍵值存儲實戰
KernelSU 模組配置系統完全指南ksud module config持久化與暫時鍵值存儲實戰【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU導讀KernelSU 為模組開發者提供了一套內建的鍵值配置系統讓模組可以在/data/adb/ksu/module_configs/module_id/下以二進位格式儲存持久化或暫時性的設定並在模組腳本post-fs-data.sh、service.sh、boot-completed.sh等中以ksud module config子命令輕鬆讀寫。本文將以 KernelSU 官方文件為主體結合 module_config.rs 等真實原始碼完整講解配置類型、命令用法、驗證限制、生命週期以及override.description動態覆寫描述、manage.feature宣告管理功能等進階用法幫助你寫出可持久保存使用者偏好、可動態切換功能開關的成熟模組。配置系統概述KernelSU 的模組配置系統是內建於ksudKernelSU 的使用者空間守護程式中的能力。所有配置以二進位格式儲存在/data/adb/ksu/module_configs/module_id/其中module_id即模組 ID與模組目錄名及module.prop中的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。配置類型配置系統區分兩種存儲類型二者的差異決定了資料的生命週期類型檔名生命週期典型用途持久配置Persist Configpersist.config重新開機後保留直到被明確刪除或模組被解除安裝使用者偏好、安裝設定暫時配置Temp Configtmp.config每次啟動的 post-fs-data 階段自動清除執行時狀態、啟動即重置的功能開關在 module_config.rs 中兩種型別對應ConfigType列舉並透過filename()方法映射到各自的檔名#[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum ConfigType { Persist, Temp, } impl ConfigType { const fn filename(self) - static str { match self { Self::Persist defs::PERSIST_CONFIG_NAME, Self::Temp defs::TEMP_CONFIG_NAME, } } }讀取優先級當讀取某個鍵的值時暫時值優先於持久值。這一合併邏輯在 merge_configs 中實現——先載入持久配置再將暫時配置逐項覆蓋寫入pub fn merge_configs(module_id: str) - ResultHashMapString, String { let mut merged load_config(module_id, ConfigType::Persist)?; let temp load_config(module_id, ConfigType::Temp)?; // Temp config overrides persist config for (key, value) in temp { merged.insert(key, value); } Ok(merged) }這意味著如果同一個鍵同時存在於兩種類型中暫時配置會遮蔽持久配置的值。在模組腳本中使用配置所有模組腳本post-fs-data.sh、service.sh、boot-completed.sh等執行時ksud都會將環境變數KSU_MODULE設定為當前模組 ID。因此模組內可以直接呼叫ksud module config系列命令來管理自己的配置。從 cli.rs 的原始碼可以看到執行配置命令時ksud會從環境變數KSU_MODULE取得模組 ID若環境變數不存在例如在 adb shell 中手動測試則需要透過--internal name指定let module_id match internal { Some(internal_name) format!(internal.{internal_name}), None std::env::var(KSU_MODULE).map_err(|_| { anyhow::anyhow!( This command must be run in the context of a module or passed --internal name ) })?, };基本命令用法以下命令應在模組腳本環境KSU_MODULE已設定中執行# 取得配置值暫時優先於持久 value$(ksud module config get my_setting) # 設定持久配置值 ksud module config set my_setting some value # 設定暫時配置值重新開機後清除 ksud module config set --temp runtime_state active # 列出所有配置項合併持久和暫時配置 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從原始碼看ModuleConfigCmd::Set會在寫入前於 CLI 層先驗證鍵與值再根據--temp旗標選擇ConfigType::Temp或ConfigType::Persist最後呼叫set_config_value完成寫入。從 stdin 設定值對於多行文字或 JSON 等複雜資料可以從標準輸入讀取值。原始碼中當--stdin旗標被指定或未提供值參數時ksud會將整個 stdin 讀入作為值cli.rs# 從 here-document 設定值適用於多行或複雜資料 ksud module config set my_key EOF 多行 文字值 EOF # 從命令管道輸入 echo value | ksud module config set my_key # 明確使用 stdin 旗標 cat file.json | ksud module config set json_data --stdin注意從 stdin 讀入時換行符會被完整保留read_to_string讀取全部內容適合儲存 JSON、Base64 等結構化資料。驗證限制配置系統在寫入時強制執行以下限制違反會直接報錯。這些常量定義於 module_config.rspub const MAX_CONFIG_KEY_LEN: usize 256; pub const MAX_CONFIG_VALUE_LEN: usize 1024 * 1024; // 1MB pub const MAX_CONFIG_COUNT: usize 32;最大鍵長度256 位元組最大值長度1MB1048576 位元組最大配置項數每個模組 32 個鍵格式必須符合^[a-zA-Z][a-zA-Z0-9._-]$與模組 ID 相同的規則必須以字母a-zA-Z開頭後續可包含字母、數字、點.、底線_或連字號-最小長度2 個字元值格式無限制——可包含任何 UTF-8 字元包括換行符、控制字元等鍵格式的驗證在 validate_config_key 中實現與模組 ID 使用同一個正則regex_lite::Regex::new(r^[a-zA-Z][a-zA-Z0-9._-]$)保證了鍵的跨場景一致性而 validate_config_value 只檢查最大長度、不限制字元集因為二進位儲存格式天然保證了任意 UTF-8 資料的安全處理。儲存格式與寫入機制配置檔案採用自訂二進位格式module_config.rsconst MODULE_CONFIG_MAGIC: u32 0x4b53554d; // KSUM const MODULE_CONFIG_VERSION: u32 1;檔案佈局如下魔數4 位元組小端序0x4b53554d即 ASCII 字串KSUM用於識別檔案類型版本號4 位元組目前為1讀取時會校驗版本不符直接拒絕載入配置項數量4 位元組逐項寫入每項由「鍵長度4 位元組 鍵資料 值長度4 位元組 值資料」組成。在載入過程中讀取器依序讀取魔數、版本、數量再迴圈讀取每一項的長度前綴與資料任何一步失敗都會返回錯誤而非靜默損壞。寫入時採用了先寫暫存檔再原子改名的策略save_configlet temp_path config_path.with_extension(tmp); // 寫入暫存檔 ... file.sync_all()?; // 原子改名 fs::rename(temp_path, config_path)?;先將完整內容寫入persist.config.tmp呼叫sync_all()強制刷盤後再用fs::rename原子替換正式檔。這樣即使寫入中途崩潰也不會留下半截的配置檔案保證了資料完整性。生命週期啟動時所有暫時配置在 post-fs-data 階段清除。clear_all_temp_configs 會遍歷配置根目錄下每個模組目錄刪除其中的tmp.config檔案僅保留持久配置。模組解除安裝時所有配置持久和暫時自動刪除。clear_module_configs 直接以fs::remove_dir_all移除整個module_id配置目錄。格式自校驗配置以二進位格式儲存帶魔數0x4b53554dKSUM與版本驗證載入時會校驗魔數與版本防止損壞或不相容的檔案被誤讀。使用場景配置系統適用於以下典型場景使用者偏好儲存使用者透過 WebUI 或 action 腳本配置的模組設定使用持久配置功能開關在不重新安裝的情況下啟用/停用模組功能執行時狀態追蹤應在重新開機時重置的暫時狀態使用暫時配置安裝設定記住模組安裝時做出的選擇複雜資料儲存 JSON、多行文字、Base64 編碼資料或任何結構化內容最多 1MB::: tip 最佳實踐對於應在重新開機後保留的使用者偏好使用持久配置對於應在啟動時重置的執行時狀態或功能開關使用暫時配置在腳本中使用配置值之前驗證它們使用ksud module config list命令偵錯配置問題 :::從原始碼看list命令cli.rs使用merge_configs合併兩種類型後以keyvalue格式逐行輸出是排查「值是否符合預期」最直接的手段。進階功能特殊配置鍵模組配置系統為進階用例提供了兩個特殊的配置鍵模式其實現位於 module.rs 的模組列表組裝邏輯中。覆蓋模組描述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. 模組可以使用manage.feature配置模式宣告它們管理的 KernelSU 功能。支援的功能對應於 KernelSU 內部的FeatureId列舉——定義於 feature.h目前共 5 個功能 IDenum ksu_feature_id { KSU_FEATURE_SU_COMPAT 0, KSU_FEATURE_KERNEL_UMOUNT 1, KSU_FEATURE_SULOG 2, KSU_FEATURE_ADB_ROOT 3, KSU_FEATURE_SELINUX_HIDE 4, KSU_FEATURE_MAX };其中可供模組宣告管理的預定義功能為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工作原理對應 module.rs 的實現manage.feature鍵的存在表示模組正在管理該功能值表示期望的狀態true/1代表啟用false/0或任何其他值代表停用要停止管理某個功能請完全刪除該配置鍵值的解析由 parse_bool_config 完成——先trim()去除空白再忽略大小寫比對true或1pub fn parse_bool_config(value: str) - bool { let trimmed value.trim(); trimmed.eq_ignore_ascii_case(true) || trimmed 1 }被管理且為啟用狀態的功能會透過模組列表 API 以managedFeatures欄位逗號分隔的字串公開module.rs。此外get_managed_features 會聚合所有活躍模組宣告的功能供核心層協調使用。這允許KernelSU 管理器偵測哪些模組管理哪些 KernelSU 功能防止多個模組嘗試管理同一功能時發生衝突更好地協調模組與核心 KernelSU 功能之間的關係::: warning 僅支援預定義功能 僅使用上面列出的預定義功能名稱su_compat、kernel_umount。這些對應於實際的 KernelSU 內部功能。使用其他功能名稱不會導致錯誤但沒有任何功能作用——請勿以sulog、adb_root等列舉中的其他值作為manage.feature鍵它們並未列入官方支援的清單。 :::與其他模組能力的配合配置系統並非孤立存在它與 KernelSU 模組體系的其餘部分緊密配合WebUI / action 腳本使用者可在 WebUI 介面或執行 action 腳本時透過ksud module config set寫入配置讓設定在腳本下一次執行時生效模組生命週期解除安裝時配置目錄隨之清除無需手動清理殘留啟動流程post-fs-data 階段的暫時配置清理clear_all_temp_configs保證每次開機都是乾淨的執行時狀態。如需了解模組的整體規範module.prop欄位、目錄結構、腳本約定可繼續參閱 module.md若想深入配置命令在 CLI 層的完整分支邏輯可直接閱讀 cli.rs 與 module_config.rs 的原始碼。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考