libmc4lua ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

libmc4lua 是 openUBMC 的 Lua 微组件基础框架，组件类型为 library。它向 Lua 业务进程提供面向对象、日志、D-Bus/MDB 资源树、ORM 数据库、参数校验、任务管理、MicroComponent 标准接口以及若干 C/C++ 扩展模块。

组件不作为独立业务服务常驻注册自己的 D-Bus 服务名。Lua 库安装到 /opt/bmc/libmc/lualib，C 扩展安装到 /opt/bmc/libmc/luaclib，Skynet 服务脚本安装到 /opt/bmc/libmc/service。CMake 工程名为 libmc，运行时根目录为 /opt/bmc/libmc/。业务组件通过 require 加载本库，在宿主 Skynet 进程内运行。

许可证为 Mulan PSL v2。mds/service.json 中的构建选项包括 chipv2_enable（默认 false）和 hpcomm_enable（默认 false）。

1.2 解决什么问题 ​

openUBMC 的业务组件大量使用 Lua，需要统一完成以下基础能力，而不是由各组件自行封装：

• 在 Lua 中实现类继承、对象生命周期和资源树上树。
• 通过会话总线访问 MDB 资源树对象、属性和方法。
• 将 SQLite 持久化封装为面向对象的 ORM 接口。
• 统一日志、错误消息、调用上下文和参数校验。
• 为异步长流程提供 TaskService 任务对象。
• 为每个微组件自动暴露 bmc.kepler.MicroComponent* 标准接口。

1.3 核心功能 ​

• 面向对象：mc.class 提供类定义、继承、ctor / pre_init / init 生命周期。
• 应用程序骨架：mc.app_base、mc.service_app_base、mc.client_app_base 构造服务名、对象路径并打开会话总线。
• 日志：mc.logging 封装 syslog 调试日志、操作日志和限流输出。
• D-Bus：dbus.core 提供 C 层连接/消息封装，sd_bus 提供 Lua 会话总线 call / pcall / signal / match。
• 资源树：mc.mdb 提供代理对象；mc.mdb.mdb_service 通过 bmc.kepler.maca 的 bmc.kepler.Mdb 查询路径与对象。
• 自发现与信号：mc.mdb.object_manage 注册对象增删回调；mc.mdb.subscribe_signal 订阅属性变更和接口增删。
• MicroComponent：注册健康检查、配置导入导出、Dump、平滑重启/复位等标准接口回调。
• 任务管理：mc.mdb.task_mgmt 创建、更新和销毁 TaskService 任务对象。
• 数据校验：mc.validate 提供枚举、长度、范围、正则和 JSON 校验。
• ORM：database 将 SQLite 表映射为 Lua 类，支持 insert/select/update/delete。
• IPMI 辅助：mc.ipmi 转发请求到 bmc.kepler.ipmi_core 并封装完成码响应。
• C 扩展：cjson、lsqlite3、worker、utils、kmc、syslog 等无 lib 前缀的 .so。

1.4 关键术语表 ​

1.5 外部交互边界图 ​

构建依赖见 mds/service.json，包括 kmc、signature_verify_cbb_library、sqlite3、json、libsoc_adapter 等。运行时还依赖 Skynet、glib、libdbus、securec 以及宿主进程的会话总线。组件自身没有独立监听端口。

2. API 使用说明与示例 ​

以下接口均为 Lua 本地接口。除 MicroComponent 标准接口由框架代为注册到宿主组件的 D-Bus 树上外，不能通过 busctl 直接调用 libmc4lua 本身。

宿主进程通过 dist/config.cfg 将 Lua 搜索路径指向 /opt/bmc/libmc/lualib/?.lua 和 /opt/bmc/libmc/luaclib/?.so。

local Class = require 'mc.class'
local log = require 'mc.logging'
local sdbus = require 'sd_bus'
local mdb = require 'mc.mdb'

2.1 模块加载与部署路径 ​

功能说明 ​

说明库的安装布局和 require 搜索路径，是调用其他 API 的前提。

参数说明 ​

config.cfg 还会把 /opt/bmc/lualib、/opt/bmc/luaclib、/opt/bmc/apps 和 /opt/bmc/plugins 加入搜索路径。

返回值与异常 ​

require 失败时 Lua 抛出 module '...' not found。C 模块符号名须与 luaopen_* 对应，例如 require('dbus.core') 加载 dbus.so 并调用 luaopen_dbus_core。

应用场景 ​

业务组件启动、本地 UT 配置 package.path / package.cpath、排查模块找不到问题。

限制条件 ​

• 不要把本库的 .so 单独拷贝到其他目录而不更新 package.cpath。
• hpcomm 相关 Lua/C 模块仅在 hpcomm_enable=true 时安装；snapshot、memstat 仅在非 Release / 指定条件下编译。

调试示例 ​

print(package.path)
print(package.cpath)
assert(require 'mc.logging')
assert(require 'sd_bus')
assert(require 'cjson')

2.2 mc.class 面向对象 ​

功能说明 ​

require 'mc.class' 返回一个类工厂函数。调用该函数得到类表；通过 ctor、pre_init、init 管理实例生命周期，通过传入父类实现继承。

参数说明 ​

返回值与异常 ​

new 返回实例。若类设置了 __capture_error，生命周期函数中的错误会被捕获；否则按普通 Lua 错误抛出。

应用场景 ​

定义服务类、MDB 对象类、ORM 行对象。mc.service_app_base 中的 Service 即 Class(AppBase)。

限制条件 ​

• 必须通过 cls.new(...) 创建实例，直接当函数调用类表不会执行完整生命周期。
• pre_init / init 在 new 内同步执行，不要在其中做长时间阻塞而不切协程。

调试示例 ​

local Class = require 'mc.class'

local Animal = Class()
function Animal:ctor(name)
    self.name = name
end

local Cat = Class(Animal)
function Cat:ctor(name)
    self.sound = 'meow'
end

local c = Cat.new('tom')
assert(c.name == 'tom')

2.3 mc.logging 日志 ​

功能说明 ​

require 'mc.logging' 返回进程内日志单例，底层通过 syslog.core 输出。支持调试级别过滤、操作审计日志、按周期限流和按 SystemId 前缀。

参数说明 ​

属性参数说明 ​

输出类型：OUT_TYPE_FILE / OUT_TYPE_LOCAL / OUT_TYPE_SHM，字符串分别为 file / local / shm。

方法参数说明 ​

返回值与异常 ​

级别不足时调用直接返回。period 在类型或范围非法时 error。raise 将格式化消息作为 Lua 错误抛出。

应用场景 ​

组件运行日志、操作审计、Dump 前的定位信息、调试控制台。

限制条件 ​

• 默认调试级别为 NOTICE，debug/info 在未调高级别时不会输出。
• 格式化失败时日志内容为 string.format error: ...，不会中断调用方。
• 操作日志需要合法的 initiator；缺少上下文字段时内容不完整。

调试示例 ​

local log = require 'mc.logging'
log:set_log_module_name('example')
log:notice('service started')
log:error('open database failed: %s', err)

local ctx = require('mc.context').get_context_or_default()
log:operation(ctx:get_initiator(), 'example', 'Export config successfully')

2.4 sd_bus 会话总线 ​

功能说明 ​

require 'sd_bus' 封装会话总线连接，供业务发起方法调用、发射信号和订阅 match 规则。默认走非阻塞实现；open_user(true) 会立即 start 事件循环。

参数说明 ​

返回值与异常 ​

call 在对端返回错误或超时时抛出错误对象（mc.error.meta）。pcall 返回 false 和错误。路径、接口名非法会在底层校验失败。

应用场景 ​

组件请求 bmc.kepler.<name>、调用其他组件方法、订阅 PropertiesChanged。

限制条件 ​

• 必须在 Skynet 宿主中使用非阻塞模式；is_block=true 仅适用于特殊阻塞场景。
• 方法第一个业务参数通常是 a{ss} 上下文，应使用 mc.context.get_context_or_default()。
• 同进程共享内存快路径由框架自动选择，调用方仍使用同一套 call 接口。

调试示例 ​

local sdbus = require 'sd_bus'
local context = require 'mc.context'
local bus = sdbus.open_user(true)
bus:request_name('bmc.kepler.example')

local ok, err = bus:pcall(
    'bmc.kepler.maca',
    '/bmc/kepler/MdbService',
    'bmc.kepler.Mdb',
    'GetServiceNames',
    'a{ss}',
    context.get_context_or_default()
)

2.5 mc.mdb 资源树代理对象 ​

功能说明 ​

require 'mc.mdb' 按路径和接口创建代理对象。属性读写走 bmc.kepler.Object.Properties 的 Get/SetWithContext；方法调用按 introspect 结果封包。方法名追加 _PACKED 时返回结构化响应。

参数说明 ​

属性访问：obj.Property 读取，obj.Property = value 写入。方法：obj:Method(args...) 或 obj:Method_PACKED(args...)。

返回值与异常 ​

应用场景 ​

跨组件读属性、调方法、在生成的 client 中获取强/弱依赖对象。

限制条件 ​

• 没有自定义接口的中间路径不能靠本模块的接口匹配找到，需使用 org.freedesktop.DBus.ObjectManager.GetManagedObjects。
• 代理对象默认缓存容量为 100，可通过 init_lru_cache(size) 调整。
• try_get_object 每次失败 skynet.sleep(50)，会占用协程时间。

调试示例 ​

local mdb = require 'mc.mdb'
local obj = mdb.get_object(bus, '/bmc/kepler/Systems/1', 'bmc.kepler.Systems')
local name = obj.Name
local rsp = obj:SomeMethod_PACKED(ctx, arg1)

busctl --user tree bmc.kepler.example
busctl --user introspect bmc.kepler.example /bmc/kepler/example/MicroComponent

2.6 mc.mdb.mdb_service 资源树查询 ​

功能说明 ​

对 bmc.kepler.maca / /bmc/kepler/MdbService / bmc.kepler.Mdb 的 Lua 封装，用于按路径、接口、类名查询对象。

参数说明 ​

返回值与异常 ​

成功时返回 maca 方法的包装响应（含 Object、SubObjects、SubPaths 等字段，以生成代码为准）。调用失败走 sd_bus.call 的错误路径。

应用场景 ​

按接口枚举对象、分页取子路径、根据类名或对象名反查 Path。

限制条件 ​

• 依赖 bmc.kepler.maca 已运行。
• get_sub_paths 只能返回带自定义接口的路径。
• 部分查询走共享内存快路径，结果仍以 maca 数据为准。

调试示例 ​

local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_sub_objects(bus, '/bmc/kepler/Systems/1', 1, 'bmc.kepler.Systems.Processor')

busctl --user call bmc.kepler.storage /bmc/kepler/Systems/1/Storage \
    org.freedesktop.DBus.ObjectManager GetManagedObjects

2.7 信号订阅与自发现 ​

功能说明 ​

mc.mdb.subscribe_signal 订阅 D-Bus 信号；mc.mdb.object_manage 注册 hwdiscovery 派发对象的增删回调。

参数说明 ​

mc.mdb.subscribe_signal：

mc.mdb.object_manage：

返回值与异常 ​

订阅接口返回 match slot。自发现回调中抛错会被框架日志记录，不保证中断整个派发循环。

应用场景 ​

硬件对象上树、监听属性变化、在依赖对象就绪后再启动业务。

限制条件 ​

• on_add_object 会启动 discovery，需在总线和模型初始化之后调用。
• preprocess_cb 若返回 false，业务必须自行 register_mdb_objects。

调试示例 ​

local object_manage = require 'mc.mdb.object_manage'
object_manage.on_add_object(bus, function(class_name, object, position)
    -- 创建业务对象
end)

2.8 MicroComponent 标准接口回调 ​

功能说明 ​

框架在宿主组件上注册 bmc.kepler.MicroComponent* 对象。业务通过回调接入健康检查、配置管理、Dump、重启和复位。mc.service_app_base 会调用 mc.mdb.default.register_default_handler。

参数说明 ​

HealthCheck 返回值（intf_mc.HEALTH）：NEED_RESTART_NOW = -2，ABNORMAL = -1，NORMAL = 0，HW_INIT_COMPLETED = 1。

Status 字符串：Starting、InitCompleted、HardwareInit、HardwareCompleted、ServiceInit、ServiceCompleted。

返回值与异常 ​

回调按各接口生成代码的签名返回。未注册时使用默认空实现（配置导入导出仅打 info 日志）。

应用场景 ​

组件健康监控、配置导入导出、一键收集、升级前的平滑重启。

限制条件 ​

• 必须在 register_default_handler 之后注册业务回调。
• Dump 路径由调用方传入；框架会在该目录写入 mdb_info.log，非 Release 还会写 skynet_info.json。

调试示例 ​

local mc = require 'mc.mdb.micro_component'
mc.on_health_check(function()
    return 0
end)

local debug = require 'mc.mdb.micro_component.debug'
debug.on_dump(function(ctx, path)
    -- 将业务快照写入 path
end)

busctl --user call bmc.kepler.example \
  /bmc/kepler/example/MicroComponent \
  bmc.kepler.MicroComponent HealthCheck

2.9 mc.mdb.task_mgmt 任务管理 ​

功能说明 ​

创建 Redfish TaskService 风格的任务对象，路径为 <parent_path>/TaskService/Tasks/<id>。单组件最多 32 个任务。

参数说明 ​

state：New、Starting、Running、Suspended、Interrupted、Pending、Stopping、Completed、Killed、Exception、Cancelled。

status：OK、Warning、Error、Critical。

Progress=100 或 State 为 Completed / Exception / Cancelled 时，默认 10 分钟后销毁。

返回值与异常 ​

创建码：0 成功，-1 任务数达上限，-2 超时值为负。

更新码：0 成功，-1 ID 不存在，-2 data 非 table，-3 Progress 越界，-4 State 非法，-5 Status 非法，-6 Parameters 非 table，-7 MessageId 非 string，-8 MessageArgs 非 table，-9 任务已结束。

应用场景 ​

固件升级、配置导入等长流程，先返回任务 ID 再在 skynet.fork_once 中更新进度。

限制条件 ​

• 单 APP 最多 32 个任务。
• 只能操作本服务创建的任务。
• 资源树方法应先返回 ID，再异步更新，避免调用方拿不到任务对象。

调试示例 ​

local task_mgmt = require 'mc.mdb.task_mgmt'
local create, err, id = task_mgmt.create_task(bus, 'FirmwareUpdate', '/bmc/kepler/UpdateService', 30)
assert(create == task_mgmt.create_code.TASK_CREATE_SUCCESSFUL, err)
skynet.fork_once(function()
    task_mgmt.update_task(id, { State = task_mgmt.state.Running, Progress = 10 })
    task_mgmt.update_task(id, { State = task_mgmt.state.Completed })
end)
return id

2.10 mc.validate 数据校验 ​

功能说明 ​

对资源树属性或方法入参做语义校验。失败时抛出 messages.base / messages.custom 错误，或写入 errs 表。need_convert 为真时属性名/值按 %Name、%Name:value 格式转换，以便北向映射。

参数说明 ​

*_or_none 与 Optional* 在 val == nil 时视为通过。

返回值与异常 ​

未传 errs 时直接 error(message)。传入 errs 时写入 errs[name]。典型错误包括 PropertyValueNotInList、PropertyValueTypeError、PropertyValueOutOfRange、PropertyValueFormatError、StringValueTooShort / StringValueTooLong、PropertyUnknown、PropertyMissing。

应用场景 ​

生成代码中的属性 Set 校验、Redfish/CLI 入参校验。

限制条件 ​

• 正则使用 utils.core.g_regex_match（GLib）。
• enum_name 参数在实现中未参与校验逻辑，有效约束来自 enum_type 表。

调试示例 ​

local validate = require 'mc.validate'
validate.ranges('ValidateTime', 200, 100, 5000)
validate.lens('FilePath', path, 1, 2048)
validate.regex('Medium', medium, [=[^(Air|Liquid)$]=])
validate.Json('{"a":1}')

2.11 mc.signal 进程内信号 ​

功能说明 ​

与 D-Bus 信号不同，该模块只在当前 Lua 服务内做发布/订阅。

参数说明 ​

返回值与异常 ​

槽回调中的错误会记录到 sig.errors；多个错误时仅重新抛出最后一个，其余打 log:error('ignore slot run error: ...')。emit 嵌套超过 MAX_EMIT_NESTED_DEPTH（90）时抛 emit signal: nesting is not allowed。同名 with_name 冲突时抛 slot name conflict。

应用场景 ​

服务内属性变更通知、数据库 hook（database 的 on_insert / on_update / on_delete）。

限制条件 ​

不要在回调中无界递归 emit 同一信号。

调试示例 ​

local signal = require 'mc.signal'
local sig = signal.new()
sig:on(function(v)
    print(v)
end)
sig:emit(1)

2.12 mc.context 调用上下文 ​

功能说明 ​

在当前协程上保存 Interface、UserName、ClientAddr 等调用者信息，随 D-Bus 方法在组件间传递。

参数说明 ​

返回值与异常 ​

空上下文的 is_empty() 为 true。白名单校验失败时拒绝非法字段覆盖。

应用场景 ​

资源树方法第一个 a{ss} 参数、操作日志 initiator、权限校验。

限制条件 ​

上下文以协程为键，跨 skynet.fork 时需显式传递或使用 set_skynet_context。

调试示例 ​

local context = require 'mc.context'
local ctx = context.new('Redfish', 'Administrator', '127.0.0.1')
context.set_context(ctx)

2.13 database ORM ​

功能说明 ​

require 'database' 返回 function(path)，打开 SQLite 并返回 DataBase 对象。database.column 提供字段类型。mc.mdb.micro_component.db 在此之上封装组件内存库。

参数说明 ​

打开数据库：

local open_db = require 'database'
local db = open_db('/data/opt/bmc/data/example.db')  -- 或 ':memory:'

字段类型（database.column）：TextField、BolbField、IntegerField、RealField、BooleandField、DateTimeField、EnumField、JsonField。链式配置：cid、unique、null、default、primary_key、max_length。

where 条件：Field:eq/ne/lt/le/gt/ge/like/in_，以及 or_(...)。排序分页：order_by、desc、limit、offset。

磁盘库打开后权限设为 0640。空间不足时可能抛 InsufficientFreeSpace。

返回值与异常 ​

open_db 失败抛 open database failed: <path>。约束冲突、SQL 错误走 SQLite errmsg。

应用场景 ​

组件持久化配置、对象属性落库、与 class_mgnt/ORM 生成代码配合。

限制条件 ​

• 字段类名 BolbField、BooleandField 与源码拼写一致。
• 用类构造函数查询时必须提供主键或唯一键，多行只返回第一行；不存在则创建新对象。
• 写保护状态下文件写入受 filehook / mc.nandflash 限制。

调试示例 ​

local Col = require 'database.column'
local User = db:Table('t_user', {
    user_name = Col.TextField():cid(1):max_length(32):unique(),
    user_id = Col.IntegerField():cid(2):primary_key(1):max_length(8),
}):create()
User({ user_name = 'abc', user_id = 1 }):save()
local row = db:select(User):where(User.user_id:eq(1)):first()

2.14 mc.ipmi IPMI 辅助接口 ​

功能说明 ​

向 bmc.kepler.ipmi_core 发送 Request，并提供完成码响应封装和操作日志。

参数说明 ​

返回值与异常 ​

request 返回对端 Request 的结果。response 在 cc 越界时 assert。

应用场景 ​

业务组件实现 IPMI 命令处理函数，或向 ipmi_core 转发。

限制条件 ​

依赖 bmc.kepler.ipmi_core 服务；通道类型取值见 mc.ipmi.types。

调试示例 ​

local ipmi = require 'mc.ipmi'
-- chan_type 为数字；指定 instance 时传入 {chan_type, instance}
local cc, rsp = ipmi.request(bus, 1, {
    DestNetFn = 0x30,
    Cmd = 0x98,
    Payload = '\x00\x07\xdb\x01\x00',
})
return ipmi.responseSuccess(rsp)

2.15 C 扩展模块一览 ​

以下模块由 src/lualib-src 编译，安装到 /opt/bmc/libmc/luaclib（cutils / filehook 安装到 usr/lib64）。仅列出已核实的 luaopen_* 与典型 require 名。

dbus.core 额外导出 get_private、new_session、new_system、open、validate_path / check_path 等，以及 DBusConnection、DBusMessage、DBusVariant、SharedMemory 等类型。

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

libmc4lua 作为基础库，扩展方式主要是：

• 上层业务组件依赖本库，通过 mc.plugin.loader 加载组件插件和定制插件。
• 在本仓库新增 Lua 模块或 C 扩展，并注册 luaopen_*。
• 通过 bingo gen 根据 MDS 生成 mdb.* 接口代码，由 mc.mdb.register_interface 注册。

mds/service.json 的 required 为空，本库不声明对其他业务组件的运行时资源协作依赖。

3.2 扩展点说明 ​

3.3 二次开发指导 ​

步骤一：业务侧使用现有 API ​

在组件中 require 所需模块，通过 mc.service_app_base 继承服务类，在 init 中注册对象和回调。

步骤二：新增 Lua 模块 ​

在 src/lualib/ 添加模块，保持 require 路径与目录一致（mc/xxx.lua 对应 mc.xxx）。

步骤三：新增 C 模块 ​

1. 实现 luaopen_<mod> 并在 luaL_Reg 中注册函数。
2. 在对应 CMakeLists.txt 中 PREFIX "" 安装到 opt/bmc/libmc/luaclib。
3. 同步更新本节与第 2 章接口表。

步骤四：插件 ​

local loader = require 'mc.plugin.loader'
loader.load()

插件目录必须是子目录；pcall(require, ...) 失败时只跳过该插件。成功时日志为 load component plugin feature[%s] successfully 或 load customized plugin feature[%s] successfully。

验证方法 ​

1. 在组件仓执行既有 bingo 构建，确认 /opt/bmc/libmc/lualib 与 luaclib 已部署。
2. 运行 test/unit 下与目标模块对应的用例。
3. 用 busctl --user 检查宿主组件的 MicroComponent 接口。

注意事项 ​

• 保持 Lua 模块名、D-Bus 接口名和错误消息 ID 向后兼容。
• 不得在日志中输出密钥、口令或完整敏感配置。
• hpcomm、chipv2 相关代码受构建选项控制，文档与产物需同时说明。

4. 日志说明 ​

4.1 一键日志收集 ​

libmc4lua 不单独注册 Dump 服务。宿主组件执行 bmc.kepler.MicroComponent.Debug.Dump 时，框架 debug.lua 先收集公共信息，再调用业务 on_dump。

4.2 关键日志信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误码速查表 ​

完整 D-Bus 方法错误以对端组件和 messages.* 生成为准。

5.3 最小化复现与证据收集 ​

1. 记录 require 模块名、D-Bus 服务/路径/接口/方法、上下文和返回错误。
2. 执行宿主组件 Dump，收集 mdb_info.log 与进程日志。
3. 用 busctl --user tree/introspect/call 确认 maca 与目标对象。
4. 无自定义接口的路径改用 GetManagedObjects。
5. 保留插件目录列表和 service.json 依赖声明。

5.4 调试方法 ​

busctl --user tree bmc.kepler.maca
busctl --user introspect bmc.kepler.example /bmc/kepler/example/MicroComponent
busctl --user call bmc.kepler.example \
  /bmc/kepler/example/MicroComponent \
  bmc.kepler.MicroComponent.Debug SetDlogLevel a{ss}sy 0 debug 1

单元测试位于组件仓 test/unit/（如 test_mdb、test_logging、test_validate、test_dbus、test_database）。

6. 常见问题解答 ​

Q1：require 'mc.mdb' 或 require 'dbus.core' 失败怎么办？ ​

• 问题描述：Lua 报 module not found。
• 一句话答案：检查 /opt/bmc/libmc 部署和 package.path / package.cpath。
• 根因说明：config.cfg 未执行 done()，或产物未安装到 lualib/luaclib。
• 解决方案：确认 lua_path 含 /opt/bmc/libmc/lualib/?.lua，lua_cpath 含 /opt/bmc/libmc/luaclib/?.so。
• 规避方案：通过 bingo/Conan 正式部署，不要只拷贝单个文件。
• 适用版本：1.130.38。

Q2：为什么出现 invalid interface？ ​

• 问题描述：mdb.get_object 抛 invalid interface:<name>。
• 一句话答案：当前进程没有注册该接口的 introspect/元数据。
• 根因说明：未在 service.json 声明接口依赖，或 bingo gen / register_interface 未执行。
• 解决方案：补齐 MDS 依赖，重新生成并确认启动时已注册。
• 规避方案：对尚未依赖的接口改用 bus:call 显式调用，并补依赖。
• 适用版本：1.130.38。

Q3：get_sub_paths 查不到已知子路径？ ​

• 问题描述：busctl tree 看得到路径，查询 API 返回空。
• 一句话答案：该方法只返回带自定义接口的路径。
• 根因说明：中间目录节点可能没有业务接口，maca 的 GetSubPaths 不会列出它们。
• 解决方案：对父对象调用 org.freedesktop.DBus.ObjectManager.GetManagedObjects。
• 规避方案：为该节点补充接口，或在业务侧改用 GetManagedObjects。
• 适用版本：1.130.38。

Q4：任务创建失败或进度无法更新？ ​

• 问题描述：create_task 返回非 0，或 update_task 返回 -9。
• 一句话答案：任务数上限为 32；已结束任务不能再更新。
• 根因说明：未及时销毁已完成任务，或在 Completed/Exception/Cancelled 之后仍 update。
• 解决方案：查询本服务任务对象并 destroy_task；仅在结束前更新 Progress/State。
• 规避方案：长流程使用 skynet.fork_once，先返回任务 ID。
• 适用版本：1.130.38。

Q5：如何提高框架调试日志级别？ ​

• 问题描述：只有 NOTICE/ERROR，看不到 debug。
• 一句话答案：通过 MicroComponent.Debug.SetDlogLevel 或 mc.logging 的 set_debug_log_level 接口提升级别。
• 根因说明：默认 dlog_level 为 DLOG_NOTICE，更低级别被过滤。
• 解决方案：调用 SetDlogLevel 并指定有效小时数；到期后恢复 NOTICE。
• 规避方案：在复现窗口内打开 debug，避免生产环境长期 MASS/DEBUG。
• 适用版本：1.130.38。