mdbctl ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

mdbctl（micro-component command-line interface）是 openUBMC 微组件在线调试命令行客户端。它通过 MDB（Management DataBase）查询资源树元数据，通过 MACA 获取组件信息，再调用目标组件的 D-Bus 对象、属性和方法，实现资源树浏览、属性查询、方法调用、日志控制、组件自定义命令、内存快照、属性跟踪、性能统计和 IPMI 消息跟踪等调试能力。 mdbctl 的组件类型为 command。系统构建阶段会把以下别名追加到 /etc/profile：

alias mdbctl='/opt/bmc/skynet/lua /opt/bmc/apps/mdbctl/service/mdbctl.lua'

mdbctl 支持两种执行方式：

1.2 解决什么问题 ​

• 统一资源树调试入口：开发者无需先查找对象的服务名和对象路径，可用对象名查询类、对象、接口、属性和方法。
• 降低 D-Bus 调试门槛：mdbctl 根据对象自省信息自动解析属性或方法签名，并把命令行参数封装成 D-Bus 消息。
• 提供组件在线调试会话：通过 attach 与目标微组件建立调试控制台连接，获取组件自定义命令并调整其调试日志。
• 支持高风险操作审计：setprop 和 call 的成功或失败结果会通过统一日志接口记录操作日志。
• 提升问题定界效率：可生成内存快照、跟踪属性变化、统计 Signal/RPC 调用、设置预置跟踪采样点并跟踪 IPMI 消息。
• 区分发布与调试能力：Release 包保留只读查询和受控调试能力；Debug 包额外提供属性修改、任意方法调用、快照和性能分析等能力。

1.3 核心功能 ​

• 组件和资源树发现：lsmc、lsclass、lsobj。
• 属性和方法查看：lsprop、getprop、Debug 包中的 lsmethod。
• 组件调试会话：attach、lscmd、目标组件自定义命令。
• 日志控制：dloglevel、dlogtype。
• 跟踪与性能分析：trace、traceipmi、Debug 包中的 traceprop、profiling、snapshot。
• 高风险调试操作：Debug 包中的 setprop、call。
• 命令框架扩展：支持新增内置命令，也支持目标组件通过符合约定的 D-Bus 接口和自省注解动态提供命令。

1.4 关键术语表 ​

1.5 外部交互边界图 ​

1.5.1 主要依赖和调用边界 ​

1.5.2 安装和临时文件 ​

2. API 使用说明与示例 ​

2.1 命令语法和通用规则 ​

功能说明 ​

mdbctl 将 CLI 命令作为用户接口。直接执行形式为：

mdbctl <command> [arguments...]

交互执行形式为：

$ mdbctl
...
% <command> [arguments...]

通用限制条件 ​

• attach 状态只存在于当前 mdbctl 进程；必须连接后再在同一交互会话中执行依赖 attach 的命令。
• 源码没有把每条命令的布尔执行结果作为进程退出参数传给 os.exit。自动化脚本不能只检查 $?，还要检查终端响应中的 Failed、D-Bus 错误或预期成功文本。
• setprop 和 call 会记录完整命令行的成功/失败操作日志。不要把口令、密钥或其他敏感数据作为其明文参数。
• 参数封装支持常用 D-Bus 基础类型、数组、字典和结构体；当前消息封装器不支持直接从 CLI 构造 Variant (v)。
• 数组参数首先填写元素数量。例如签名 as 的两个字符串可写为 2 value1 value2。
• 布尔值接受：1/yes/y/true/t 和 0/no/n/false/f。
• 对象名必须能由 MDB 唯一解析；不存在和重名都会拒绝后续操作。

当前命令矩阵 ​

启动示例 ​

$ mdbctl
**********************************************************************
                             Debug Shell
                          Copyright(C) 2023
**********************************************************************
% help

直接执行只适用于单条无状态命令：

mdbctl lsmc

2.2 help ​

功能说明 ​

显示当前 mdbctl 进程已经注册、且在当前 attach 状态下可见的命令帮助。帮助内容包含命令格式和描述。

参数说明 ​

该命令设计上不需要参数。当前实现会忽略 help 后的多余参数并继续打印帮助，不会返回通用参数错误；该宽松行为不属于稳定接口，调用方不应传入多余参数。

返回值与异常 ​

应用场景 ​

• 查看当前镜像实际安装了哪些 Release/Debug 命令。
• 连接目标组件后查看 attach 相关命令。

限制条件 ​

• help 的可见内容受构建类型和 attach 状态影响。
• 当前实现对 help 后的多余参数不做校验，不应依赖这一行为。

调试示例 ​

mdbctl ​

% help
Usage: help
Get all command help information.
Usage: lsmc
List all micro component names.
...

2.3 bye ​

功能说明 ​

退出交互式 mdbctl。若已 attach，先通知目标组件断开调试控制台，再删除当前进程的 Socket 和心跳 Socket。

参数说明 ​

该命令不接受参数。多余参数通常会返回 Failed: invalid input parameter.。

返回值与异常 ​

应用场景 ​

• 正常结束 attach 调试会话。
• 确保目标组件恢复默认调试输出方式并停止心跳连接。

限制条件 ​

• 建议使用 bye 正常退出，而不是直接关闭终端。
• 异常终止时可能留下临时 Socket；是否需要清理由实际现场状态决定。

调试示例 ​

mdbctl ​

% bye
Byebye. See you next time.

2.4 lsmc ​

功能说明 ​

调用 MACA 的组件管理接口，列出当前系统可识别的全部微组件名称，并按字典序输出。

参数说明 ​

该命令不接受参数。多余参数通常会返回 Failed: invalid input parameter.。

返回值与异常 ​

应用场景 ​

• 确认组件是否已加载。
• 为 attach 或按组件过滤类名提供候选值。

限制条件 ​

• 列表来自运行环境，示例中的组件名不保证在所有产品存在。
• 仅表示组件已被 MACA 枚举，不代表其全部资源对象均正常。

调试示例 ​

mdbctl ​

% lsmc
hwdiscovery  maca  persistence  ...

组件列表和顺序依目标镜像而变化。

busctl 交叉验证 ​

busctl --user call bmc.kepler.maca /bmc/kepler/MacaService bmc.kepler.MCAdmin GetComponentList 'a{ss}' 0

2.5 lsclass ​

功能说明 ​

列出全板资源树中的类名，或只列出指定组件拥有的类名。结果去重后按字典序输出。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 浏览全板资源模型。
• 只查看某个组件注册的资源类。

限制条件 ​

• 组件过滤依赖 MACA 组件名。
• 同名类会去重，输出不体现其归属服务数量。

调试示例 ​

mdbctl ​

% lsclass hwdiscovery
Connector  MicroComponent  ObjectGroup

2.6 lsobj ​

功能说明 ​

查询指定类的全部命名对象，并逐行输出按字典序排列的对象名。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 从类名定位实际对象名。
• 确认某类对象是否已经注册。

限制条件 ​

• 只输出对象名，不显示对象的 service/path。
• 同名对象问题应在后续命令中根据 Duplicated objects 提示定界。

调试示例 ​

mdbctl ​

% lsobj Connector
Connector_Exu_1_01

2.7 lsprop ​

功能说明 ​

列出指定命名对象的公开 D-Bus 属性和 Private 属性。可选接口名用于过滤公开接口；Private 属性仍会单独输出。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 一次查看对象全部属性。
• 只查看某个接口的公开属性。
• 查看资源树 Private 数据。

限制条件 ​

• 指定一个不存在的接口时，当前实现可能只输出 Private 部分而不报“接口不存在”；应检查目标接口标题是否出现。
• 大量数组或字典以 JSON 形式输出。

调试示例 ​

mdbctl ​

% lsprop Connector_Exu_1_01 bmc.kepler.Object.Properties
bmc.kepler.Object.Properties
  ClassName="Connector"
  ObjectName="Connector_Exu_1_01"
Private
  ...

2.8 getprop ​

功能说明 ​

读取指定对象、接口和属性的当前值，并在存在来源详情时输出引用、同步或默认值等详细信息。接口名为 Private 时读取私有属性。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 读取单个关键属性。
• 确认属性的实际来源、引用链或同步表达式。

限制条件 ​

• 当前函数以终端文本表示返回值，不保留 D-Bus 类型元数据。
• Private 属性由目标对象的 GetPrivateProperties 返回 JSON。

调试示例 ​

mdbctl ​

% getprop Connector_Exu_1_01 bmc.kepler.Object.Properties ObjectName
"Connector_Exu_1_01"

2.9 attach ​

功能说明 ​

连接指定微组件的调试控制台。mdbctl 校验组件名、Ping 目标 MicroComponent 对象、解除旧连接、通知新组件建立调试连接，并加载目标组件的自定义命令。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 连接组件并显示其自定义命令。
• 调整目标组件调试日志。
• 执行快照或属性变更跟踪。

限制条件 ​

• 必须在交互式 mdbctl 中保留状态；先执行 mdbctl attach hwproxy 再启动另一个 mdbctl dloglevel 无效。
• 一个 mdbctl 进程同一时间只保存一个 attach 目标；再次 attach 会先 detach 旧目标。

调试示例 ​

mdbctl ​

$ mdbctl
...
% attach hwdiscovery
Success
% help
...

busctl 交叉验证 ​

busctl --user call bmc.kepler.hwdiscovery /bmc/kepler/hwdiscovery/MicroComponent org.freedesktop.DBus.Peer Ping

2.10 lscmd ​

功能说明 ​

列出当前 attach 组件通过 Release/Debug 调测接口公开的自定义命令、参数类型、默认值和描述。

参数说明 ​

该命令不接受参数。多余参数通常会返回 Failed: invalid input parameter.。

返回值与异常 ​

应用场景 ​

• 发现目标组件专属调试命令。
• 确认参数是否必选、可选以及默认值。

限制条件 ​

• Release mdbctl 只发现 bmc.<namespace>.Release.* 接口；Debug mdbctl 还发现 bmc.<namespace>.Debug.*。
• 同一命令存在于多个对象时，Usage 会增加 <ObjectName> 参数。

调试示例 ​

mdbctl ​

% attach maca
Success
% lscmd
Usage: mocklog <Count> <Text> [RepeatText]
...

2.11 dloglevel ​

功能说明 ​

查询或临时设置当前 attach 组件的调试日志级别。设置时可指定生效小时数，默认 1 小时。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 临时提升某组件日志级别以复现问题。
• 查询当前组件的调试日志级别。

限制条件 ​

• 设置成功时当前实现可能只输出空行，不打印 Success；应再次查询确认。
• 提高日志级别可能显著增加日志量，定位结束后恢复合理级别。

调试示例 ​

mdbctl ​

% attach maca
Success
% dloglevel
"notice"
% dloglevel debug 1
% dloglevel
"debug"

busctl 交叉验证 ​

busctl --user get-property bmc.kepler.maca /bmc/kepler/maca/MicroComponent bmc.kepler.MicroComponent.Debug DlogLevel

2.12 dlogtype ​

功能说明 ​

查询或设置当前 attach 组件的调试日志输出方式。local 将调试输出导向当前调试控制台，file 恢复文件输出。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 把目标组件调试日志临时输出到当前 mdbctl 会话。
• 恢复文件输出。

限制条件 ​

• local 可能产生大量终端输出，应先缩小复现窗口。
• 正常 detach/bye 时目标组件应恢复 file；异常中止后应重新查询确认。

调试示例 ​

mdbctl ​

% attach hwproxy
Success
% dlogtype local
Success
% dlogtype
"local"
% dlogtype file
Success

busctl 交叉验证 ​

busctl --user get-property bmc.kepler.hwproxy /bmc/kepler/hwproxy/MicroComponent bmc.kepler.MicroComponent.Debug DlogType

2.13 trace ​

功能说明 ​

管理资源对象的预置跟踪采样率。当前源码只注册 sampling 操作：不传对象时查询全部已采样对象；传对象名或类名时设置/取消采样。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 查询当前预置采样点。
• 对单对象或某类全部对象设置采样率。

限制条件 ​

• 对类名操作时会遍历该类对象；应评估日志量和性能开销。
• 当前类级遍历不会汇总每个对象的失败结果，终端可能先打印单对象失败、最后仍打印 Success；批量设置后应执行 trace sampling 或逐对象核验。
• 采样率 0 的实现语义是取消 Override，而不是写入一个永久的 0。

调试示例 ​

mdbctl ​

% trace sampling
LogMock_0  1.0
% trace sampling LogMock_0 0.25
Success
% trace sampling LogMock_0 0
Success

2.14 traceipmi ​

功能说明 ​

启动或停止指定通道的 IPMI 消息跟踪，可按 NetFn 和 Cmd 过滤。当前实现只支持输出到文件。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 抓取特定通道的 IPMI 请求和响应。
• 按 NetFn/Cmd 缩小问题范围。

限制条件 ​

• 跟踪可能包含敏感管理报文，需按安全要求保存和传递。
• 启动后应成对执行 stop，避免长期产生大量日志。
• 源码未包含跟踪文件的最终收集路径配置，需按目标平台确认。

调试示例 ​

mdbctl ​

$ mdbctl traceipmi start file bt 0x30 0x01
Success.
$ mdbctl traceipmi stop file bt 0x30 0x01
Success.

busctl 交叉验证 ​

busctl --user introspect bmc.kepler.ipmi_core /bmc/kepler/Debug/IpmiCore/TraceIpmi bmc.kepler.Debug.IpmiCore.TraceIpmi

2.15 lsmethod ​

功能说明 ​

通过对象自省列出指定命名对象的 BMC 接口方法、输入签名和参数名。可按接口过滤。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 在使用 call 前确认方法名和输入签名。
• 检查目标对象是否公开预期接口。

限制条件 ​

• 仅 Debug 包安装。
• 只展示以 bmc 开头且含方法的接口；系统通用接口可能不列出。

调试示例 ​

mdbctl ​

% lsmethod Connector_Exu_1_01 bmc.kepler.Connector
bmc.kepler.Connector
Reload a{ss}sssy <Context> <Bom> <Id> <AuxId> <IdentifyMode>

2.16 setprop ​

功能说明 ​

设置、取消覆盖或常规修改指定对象属性。命令先读取属性当前 D-Bus 签名，再按签名解析命令行值，最后调用 SetWithContext。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 临时覆盖只读或业务驱动属性，用于受控故障注入。
• 取消先前的 Override。
• 对目标明确支持写入的属性执行正常修改。

限制条件 ​

• 仅 Debug 包安装，并会记录操作日志。
• set 是 Override：不会自动等同于持久化或写硬件；unset 恢复原始值；modify 走普通属性写入语义，影响由目标组件决定。
• 禁止在不了解业务影响时修改关键电源、散热、安全或升级属性。
• 当前 CLI 参数封装不支持 Variant (v)。

调试示例 ​

mdbctl ​

% setprop set Connector_Exu_1_01 bmc.kepler.Connector GroupPosition test_value
Success
% getprop Connector_Exu_1_01 bmc.kepler.Connector GroupPosition
"test_value"
% setprop unset Connector_Exu_1_01 bmc.kepler.Connector GroupPosition
Success

2.17 call ​

功能说明 ​

调用指定命名对象的任意 D-Bus 方法。mdbctl 先自省目标方法，获取输入和输出签名，再封装参数并以 JSON/文本打印响应。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 调用只在 D-Bus 上暴露、但无专用 mdbctl 命令的方法。
• 快速验证目标接口和参数封装。

限制条件 ​

• 仅 Debug 包安装，并会记录完整命令行操作日志。
• 可调用方法的业务影响由目标组件决定；在生产环境执行前必须完成风险评估。
• 无返回正文不代表业务状态一定符合预期，应查询目标属性或日志。

调试示例 ​

mdbctl ​

% call Connector_Exu_1_01 org.freedesktop.DBus.Properties GetAll bmc.kepler.Object.Properties
{"ClassName":"Connector","ObjectName":"Connector_Exu_1_01",...}

2.18 snapshot ​

功能说明 ​

请求当前 attach 组件生成基线内存对象快照或差异快照。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 分析组件内存对象分布。
• 对复现前后快照做差，辅助定位增长对象。

限制条件 ​

• 仅 Debug 包安装。
• diff 应在同一目标上先执行 start。
• 操作可能增加内存消耗；低内存场景必须谨慎。
• 快照位于 tmpfs /dev/shm，重启后通常不可保留，应及时导出。

调试示例 ​

mdbctl ​

% attach maca
Success
% snapshot start
snapshot file: /dev/shm/snapshot_maca
notice: this operation may cause memory consumption.
% snapshot diff
diff snapshot file: /dev/shm/snapshotdiff_maca
notice: this operation may cause memory consumption.

2.19 traceprop ​

功能说明 ​

启动或停止指定属性的变更跟踪。目标对象必须归属于当前 attach 的组件。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 定位属性被谁、在何时修改。
• 在复现窗口内临时开启高价值属性跟踪。

限制条件 ​

• 仅 Debug 包安装。
• 跟踪可能显著增加日志量，应在复现后执行 untrace。
• 对象必须属于已 attach 组件。

调试示例 ​

mdbctl ​

% attach hwdiscovery
Success
% traceprop trace Connector_Exu_1_01 bmc.kepler.Connector GroupPosition
Success
% traceprop untrace Connector_Exu_1_01 bmc.kepler.Connector GroupPosition
Success

2.20 profiling ​

功能说明 ​

统计组件进程在指定时长内的 Signal 和 RPC 调用信息。未 attach 时尝试对全部组件启动统计；已 attach 时只统计当前组件。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 分析单组件 RPC/Signal 热点。
• 对全系统组件做短时调用统计。

限制条件 ​

• 仅 Debug 包安装。
• 未 attach 时会遍历多个组件，开销更大；建议先缩小范围。
• 未 attach 的全组件路径不会汇总每个目标调用的失败结果，Success 只表示遍历流程完成，不保证所有组件都已启动统计；必须结合各组件日志或结果逐项确认。
• 当前命令只表示启动统计成功；结果输出位置由目标组件实现决定，需结合组件日志或返回机制。

调试示例 ​

mdbctl ​

% profiling 5
Success
% attach hwproxy
Success
% profiling 5
Success

2.21 组件自定义命令 ​

功能说明 ​

在 attach 后，mdbctl 把目标组件符合命名和自省注解约定的方法动态映射为顶层命令。命令名可来自方法名，也可由 cmd 注解指定。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 运行目标组件专属诊断。
• 避免为每个组件把专属命令硬编码进 mdbctl。

限制条件 ​

• 必须先 attach 并执行 lscmd 确认命令格式。
• Release 非超级用户调用会携带鉴权和权限上下文；可执行性由目标组件最终决定。
• 命令参数中的 Variant (v) 不能由当前通用解析器直接构造。

调试示例 ​

mdbctl ​

% attach maca
Success
% lscmd
Usage: mocklog <Count> <Text> [RepeatText]
...
% mocklog 2 hello world
...

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

mdbctl 有两类扩展方式：

1. 目标组件自定义命令（推荐）：目标组件通过符合命名规则的 D-Bus 接口和自省注解公开方法。mdbctl 本体无需随每个业务命令修改。
2. 新增 mdbctl 内置命令：在 command/release 或 command/debug 新增命令类，并加入对应 init.lua 注册列表。适合跨组件通用能力。

3.2 扩展点一：目标组件自定义命令 ​

3.2.1 接口发现规则 ​

mdbctl attach 目标组件后，查询该服务中匹配以下规则的对象：

3.2.2 自省注解约定 ​

mdbctl 从 D-Bus Introspection XML 读取以下信息：

• 方法上的 annotation name="cmd"：值是 JSON，可包含 cmd 和 description。
• 以入参名为 annotation name 的参数注解：值是 JSON，可包含 optional、default、description 和 struct。
• 第一个名字为空的入参通常为 Context。mdbctl 在 CLI 帮助中跳过它，并在实际调用前自动添加 a{ss} 鉴权上下文。
• 若未配置 cmd，默认使用 D-Bus 方法名作为命令名。
• 同一命令/接口由多个对象提供时，mdbctl 自动把 <ObjectName> 放到命令参数首位。 下面是 mdbctl 能识别的自省输出契约示例。具体 MDS/代码生成源文件写法由目标组件的建模工具决定：

<interface name="bmc.kepler.Release.Example">
  <method name="DumpState">
    <annotation name="cmd"
      value="{&quot;cmd&quot;:&quot;dumpstate&quot;,&quot;description&quot;:&quot;Dump component state.&quot;}"/>
    <arg name="" type="a{ss}" direction="in"/>
    <arg name="Detail" type="b" direction="in"/>
    <annotation name="Detail"
      value="{&quot;optional&quot;:true,&quot;default&quot;:false,&quot;description&quot;:&quot;Print detailed data.&quot;}"/>
    <arg name="Result" type="s" direction="out"/>
  </method>
</interface>

期望的 mdbctl 展示和调用形式：

% attach example
Success
% lscmd
Usage: dumpstate [Detail]
Dump component state.
Detail [Type:b][Def:false] Print detailed data.
% dumpstate true
{"status":"ok"}

3.2.3 验证方法 ​

1. 确认目标组件已出现在 lsmc 中。
2. 在同一 mdbctl 交互会话执行 attach <module>。
3. 执行 lscmd，确认命令名、参数和默认值符合预期。
4. 用最小合法参数调用命令，确认响应和目标组件日志。
5. 使用权限不同的账号分别验证允许和拒绝场景。
6. Release 接口还应在 Release 镜像验证；Debug 接口只在 Debug 镜像验证。

3.2.4 注意事项 ​

• 自定义命令调用超时为 180 秒。
• Release 非超级用户调用会带鉴权标志和权限位；不要在目标组件中绕过权限校验。
• 参数顺序应保持“必选参数在前、可选参数在后”。
• 不要把密码、私钥或 Token 作为可回显的命令参数。
• 输出为单个字符串且内容是合法 JSON 时，mdbctl 会直接格式化输出该 JSON；其他返回值按 D-Bus 签名转换后编码为 JSON。

3.3 扩展点二：新增内置命令 ​

3.3.1 新建命令类 ​

以下示例新增一个无参数 version 命令：

local class = require 'mc.class'
local cmd_base = require 'command.base'
local version = class(cmd_base)
function version:ctor()
    self.name = 'version'
    self.desc = 'Print mdbctl component version.'
end
function version:init()
    self.super.init(self)
end
function version:execute(args)
    if not self.super.execute(self, args) then
        return false
    end
    print('1.120.4\n')
    return true
end
return version

Release 通用命令放置到：

src/lualib/command/release/version.lua

Debug 专用命令放置到：

src/lualib/command/debug/version.lua

3.3.2 注册命令 ​

在对应包的 init.lua 的 cmd_list 中加入 version：

local cmd_list = {
    -- existing commands
    'version'
}

命令对象构造时会通过基类自动注册到 commandset。

3.3.3 参数和校验 ​

• self.required：必选参数，帮助中显示为 <...>。
• self.optional：可选参数，帮助中显示为 [...]。
• self.flexible：签名相关的可变参数。
• 自定义 check_<parameter_name>：参数解析后自动调用。例如 operation type 对应 check_operation_type。
• execute 返回 true/false，并向终端打印清晰、可定界的响应。

3.3.4 验证方法 ​

# 静态检查命令已注册
mdbctl help | grep -A1 'Usage: version'
# 直接执行
mdbctl version
# 多余参数拒绝
mdbctl version extra

预期：

1.120.4
Failed: invalid input parameter.

3.4 扩展注意事项 ​

• Release 命令始终安装；Debug 命令目录仅在 CMAKE_BUILD_TYPE=DEBUG 时安装。
• 新命令应优先复用 cmd_base:get_named_object、transport.message 和 transport.introspect，避免重复实现对象解析和签名转换。
• 所有 D-Bus 连接都应在成功和失败路径关闭。
• 高风险命令必须增加权限控制和操作审计；当前 mdbctl 入口只对内置 setprop、call 自动记录操作日志。
• 新增命令时同步补充单元测试、集成测试、帮助输出、错误场景和本文档。

4. 日志说明 ​

4.1 一键日志收集 ​

mdbctl 是短生命周期 CLI，不是常驻服务。源码没有创建独立的 mdbctl.log，也没有包含系统“一键日志收集”的文件映射配置。社区现有《mdbctl setprop 命令介绍》示例将操作日志展示在 /var/log/operation.log；当前源码也能确认 setprop、call 通过统一操作日志接口记录成功或失败，但仅凭本组件源码仍无法确认目标 SDK 的一键日志包是否收集该文件、以及它在收集包中的最终相对路径。 发布前应由组件维护者和一键日志负责人确认目标 SDK 的实际收集项。当前能够确认的证据如下：

script -q /tmp/mdbctl-session.log
mdbctl
# 在 mdbctl 内复现并执行 bye
exit

查看保存结果：

sed -n '1,240p' /tmp/mdbctl-session.log

4.2 关键日志和终端信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误信息速查表 ​

mdbctl 没有统一数字错误码，主要通过固定文本和目标 D-Bus 错误定界。

5.3 调试方法 ​

5.3.1 确认安装和基线 ​

type mdbctl
ls -l /opt/bmc/apps/mdbctl/service/mdbctl.lua
find /opt/bmc/apps/mdbctl/lualib/command -maxdepth 2 -type f -name '*.lua' | sort

若 alias 未生效，可使用完整命令：

/opt/bmc/skynet/lua /opt/bmc/apps/mdbctl/service/mdbctl.lua lsmc

5.3.2 分层验证资源查询 ​

% lsmc
% lsclass hwdiscovery
% lsobj Connector
% lsprop Connector_Exu_1_01
% getprop Connector_Exu_1_01 bmc.kepler.Object.Properties ObjectName

判断分层：

1. lsmc 失败：先查 MACA/用户总线。
2. lsmc 成功而 lsclass/lsobj 失败：查 MDB 服务和模型数据。
3. 对象可列出但 lsprop/getprop 失败：查对象归属组件、接口和属性。
4. attach 成功但自定义命令失败：查目标调测接口、参数、权限和业务处理。

5.3.3 busctl 交叉验证 ​

# 组件列表
busctl --user call bmc.kepler.maca /bmc/kepler/MacaService bmc.kepler.MCAdmin GetComponentList 'a{ss}' 0
# MDB 服务是否存在
busctl --user introspect bmc.kepler.maca /bmc/kepler/MdbService bmc.kepler.Mdb
# 目标 MicroComponent 是否可达
MODULE=hwdiscovery
busctl --user call "bmc.kepler.${MODULE}" "/bmc/kepler/${MODULE}/MicroComponent" org.freedesktop.DBus.Peer Ping

6. 常见问题解答 ​

Q1：mdbctl 是常驻服务吗？ ​

• 问题描述：在 systemd 中找不到 mdbctl 服务。
• 一句话答案：mdbctl 是按需启动的命令组件，不是常驻 daemon。
• 根因说明：组件元数据类型是 command，通过 /etc/profile alias 启动 Lua 入口脚本。
• 解决方案：检查 alias、入口脚本和依赖服务；不要查找不存在的 mdbctl.service。
• 规避方案：自动化脚本可直接调用完整 Lua 命令路径。
• 适用版本：1.130.2。

Q2：为什么先执行 mdbctl attach hwproxy，再执行 mdbctl dloglevel 仍提示未 attach？ ​

• 问题描述：两条 shell 命令分别显示 attach 成功和 attach 无效。
• 一句话答案：两条命令启动了两个进程，attach 状态没有跨进程保存。
• 根因说明：直接执行模式一条命令后立即退出；attach 上下文保存在进程内存中。
• 解决方案：先运行 mdbctl，再在同一 % 提示符中执行 attach 和后续命令。
• 规避方案：不要把 attach 依赖命令拆成多个独立 shell 进程。
• 适用版本：全部版本。

Q3：为什么 help 中没有 setprop、call、snapshot 或 lsmethod？ ​

• 问题描述：文档有命令，但目标镜像 help 不显示。
• 一句话答案：这些命令只安装在 Debug 构建；snapshot 还要求当前已 attach 才在 help 中显示。
• 根因说明：CMake 仅在 CMAKE_BUILD_TYPE=DEBUG 时安装 command/debug；help 还会隐藏 need_attach=true 的命令。
• 解决方案：确认镜像构建类型；attach 后再次执行 help。
• 规避方案：Release 现场不要依赖 Debug 命令。
• 适用版本：1.130.2。

Q4：<> 和 [] 分别表示什么？ ​

• 问题描述：不清楚 Usage 中参数是否必填。
• 一句话答案：<> 是必选参数，[] 是可选或可变参数。
• 根因说明：命令基类分别根据 required、optional、flexible 生成帮助。
• 解决方案：按从左到右顺序输入；带空格的单个值使用引号。
• 规避方案：先执行 help/lscmd 复制 Usage。
• 适用版本：全部版本。

Q5：setprop set、unset 和 modify 有什么区别？ ​

• 问题描述：三种操作看起来都在改属性。
• 一句话答案：set 建立 Override，unset 移除 Override，modify 执行普通写属性。
• 根因说明：set/unset 通过 Context.OverrideMode 控制覆盖值；modify 清除 OverrideMode 后按目标属性写入规则处理。
• 解决方案：临时故障注入用 set/unset；只有确认属性可写和业务影响时才用 modify。
• 规避方案：每次操作前后执行 getprop，并保存操作日志。
• 适用版本：1.130.2。

附录 ​

附录 A 修订记录 ​