product_mgmt（产品信息管理） ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

product_mgmt 是 openUBMC 的产品信息管理应用。它以 Lua/Skynet 服务运行，维护产品、联系信息、BMC 软件信息和电子保单信息，并按构建特性提供资产清单、资产变更、可信供应链检查和系统报废能力。服务入口是 src/service/main.lua，主要初始化流程位于 src/lualib/product_mgmt_app.lua。

1.2 解决什么问题 ​

该组件集中维护需要被其他系统组件读取的产品身份和定制信息，避免产品名、厂商信息、语言集合等数据分散管理；同时将电子保单、白牌升级、装备定制及可选资产安全能力接入同一服务生命周期。

1.3 核心功能 ​

• 资产清单与可信资产变更：查询资产并维护信任记录；受 CONAN_DEFS_FEATURE_ASSET 控制。

1.4 关键术语表 ​

1.5 外部交互边界图 ​

1.6 目录与模块职责 ​

2. API 使用说明与示例 ​

服务名为 bmc.kepler.product_mgmt，生成代码使用 user bus。以下只列当前模型明确发布的主要 D-Bus API；完整定义以 mds/model.json 和 gen/product_mgmt/json_types/ 为准。示例需要服务已部署并在目标 openUBMC 环境运行。

2.1 产品信息接口 ​

功能说明 ​

在 /bmc/kepler/Systems/${SystemId}/Product 发布产品基本信息，以下示例使用 SystemId=1。

参数说明 ​

返回值与异常 ​

应用场景 ​

供系统内管理接口读取产品展示信息、设置允许写入的属性，或在启用报废特性时发起报废流程。

限制条件 ​

报废会执行数据处置并可能触发 BMC 恢复与复位，只应在授权的目标环境调用。属性写入还必须满足模型权限。

调试示例 ​

命令行调试 ​

busctl --user get-property bmc.kepler.product_mgmt \
  /bmc/kepler/Systems/1/Product \
  bmc.kepler.Systems.Product ProductName

busctl --user get-property bmc.kepler.product_mgmt \
  /bmc/kepler/Systems/1/Product \
  bmc.kepler.Systems.Product LanguageSet

2.2 电子保单接口 ​

功能说明 ​

接口 bmc.kepler.Systems.Product.DigitalWarranty 与产品信息共用对象路径 /bmc/kepler/Systems/1/Product，提供首次上电日期和服务期限信息。

参数说明 ​

返回值与异常 ​

写入异常由属性校验与框架以 D-Bus 错误返回，日期格式错误使用 PropertyValueFormatError。

应用场景 ​

用于查询电子保单首次上电时间、服务起点和服务期限，并支持写入服务起止信息。

限制条件 ​

首次上电和默认服务起点的规则如下：

• 服务起点仅在当前值为 N/A 或默认值 1996-04-10 时根据制造日期初始化；制造日期必须晚于 2010-01-01，生成值为制造日期加 100 天。
• 首次上电日期每 2 小时检测一次，初始化异常时最多进行 10 轮拉起尝试。
• 制造日期早于 2010-01-01 时不记录；处于 2010-01-01 至 2020-01-01 之间时，记录制造日期加 365 天。
• 当前时间早于 2020-01-01、累计上电不足 48 小时，或上电时间早于制造日期前一天时不记录。
• 制造日期后 30 天以内的短期上电按工厂操作处理；超过相应窗口后才形成首次上电日期。

调试示例 ​

busctl --user get-property bmc.kepler.product_mgmt \
  /bmc/kepler/Systems/1/Product \
  bmc.kepler.Systems.Product.DigitalWarranty FirstPowerOnTime

2.3 产品定制与设备信息接口 ​

功能说明 ​

提供 OEM 定制数据、厂商名称、短信名称、OID、Redfish 版本及只读设备身份信息。

参数说明 ​

对象路径同为 /bmc/kepler/Systems/1/Product。

返回值与异常 ​

属性写入失败时由框架返回权限、格式或属性值错误对象。

应用场景 ​

用于装备定制、白牌定制和系统身份信息展示。

限制条件 ​

可写属性需要 BasicSetting 权限，只读属性不能通过资源协作接口修改。

调试示例 ​

busctl --user get-property bmc.kepler.product_mgmt   /bmc/kepler/Systems/1/Product bmc.kepler.Systems.Product.Custom OemData

2.4 联系信息接口 ​

功能说明 ​

提供版权、邮箱、官网、支持网站、联系电话和 KVM 客户端下载地址等联系信息。

参数说明 ​

对象路径为 /bmc/kepler/Systems/1/Contact，接口为 bmc.kepler.Systems.Contact。

返回值与异常 ​

写入校验失败时返回属性格式、权限或值域错误。

应用场景 ​

用于展示和维护产品对外联系信息。

限制条件 ​

这些属性均要求 ReadOnly 读权限、BasicSetting 写权限。

调试示例 ​

busctl --user get-property bmc.kepler.product_mgmt   /bmc/kepler/Systems/1/Contact bmc.kepler.Systems.Contact Email

2.5 BMC 软件信息接口 ​

功能说明 ​

提供 BMC 软件名称、软件类型和软件包名称。

参数说明 ​

对象路径为 /bmc/kepler/Managers/1/BMC，接口为 bmc.kepler.Managers.BMC。

返回值与异常 ​

SoftwareName 写入失败时由框架返回权限或属性格式错误。

应用场景 ​

用于产品信息展示和 BMC 版本信息查询。

限制条件 ​

SoftwareName 写入需要 BasicSetting 权限，其余属性只读。

调试示例 ​

busctl --user get-property bmc.kepler.product_mgmt \
  /bmc/kepler/Managers/1/BMC bmc.kepler.Managers.BMC SoftwareName

2.6 资产清单接口 ​

功能说明 ​

提供完整资产列表和按条件过滤的资产查询能力，受资产构建特性控制。

参数说明 ​

AssetType 可留空或为 CPU、NetworkAdapter、NPU、GPU。上下文字典由调用框架传入，本仓库未提供可直接执行的 busctl call 示例。

GetSpecificAssetList 的 SystemId 仅接受 1 或 0xff；属性列表留空时返回全部可选字段。可选字段包括 AssetName、AssetType、AssetTag、SerialNumber、PartNumber、PCBVersion、FirmwareVersion、Manufacturer、ManufactureDate、Slot、Model、UUID 和 UniqueIdentifier。非法参数通过 PropertyValueNotInList 返回。

GetAssetList 按 AssetType、AssetName 排序。缺失字段在完整列表中以 N/A 填充；Redfish 上下文比其他调用上下文多返回 Slot 和资源对象 path。对于 GetSpecificAssetList，网卡的 UniqueIdentifier 来自主端口永久 MAC 地址，其他设备由序列号与 UUID 拼接。

返回值与异常 ​

查询成功返回 JSON 字符串；非法字段、SystemId 或 AssetType 通过 PropertyValueNotInList 返回。

应用场景 ​

供 Redfish、Web 和资产管理服务读取或筛选资产清单。

限制条件 ​

接口只在资产特性启用时注册；本仓库未提供可直接执行的 busctl call 示例。

调试示例 ​

优先通过上层资产管理接口查询；资源调试时先执行 busctl --user introspect bmc.kepler.product_mgmt /bmc/kepler/AssetService/AssetList。

2.7 资产变更与可信供应链接口 ​

功能说明 ​

维护资产签名与信任记录，并检测和确认可信供应链基线变化。

参数说明 ​

这些对象只在对应源码模块被构建并成功加载时创建。方法结果中的 JSON 结构以实现和测试为准。

返回值与异常 ​

方法成功时返回数据或空返回；模块未构建、依赖缺失或状态不支持时返回框架错误或对象不存在。

应用场景 ​

用于可信资产变更检测、信任状态更新和供应链基线确认。

限制条件 ​

ConfirmChangedEvents 会关闭检查、清空变化列表并请求清除指纹，不会自动重新生成基线；只能在授权流程中调用。

调试示例 ​

先通过 busctl --user tree bmc.kepler.product_mgmt 确认对象是否存在，再使用上层可信供应链流程验证，不直接对生产数据执行确认操作。

资产变更模块从 Assembly/FruData 等对象收集部件信息，维护签名和信任记录；可信供应链模块将配置基线保存为 trusted_supply_chain_config.json，检测到变化后由 GetChangedEvents 返回。ConfirmChangedEvents 会关闭检查、清空变化列表、删除主备基线并请求安全资产服务清除指纹；代码不会在该方法内自动重新生成基线。具体文件位置由 src/lualib/trusted_supply_chain/trusted_supply_chain_check.lua 中的外部路径常量组合，部署时应以目标系统为准。

2.8 系统报废接口 ​

功能说明 ​

系统报废流程通过 2.1 节产品接口触发，并按 BIOS、RAID、Disk、BMC 子任务汇总进度。

参数说明 ​

报废方法发布在 2.1 节产品接口上。实现会按 BIOS、RAID、Disk、BMC 四个子任务计算进度，权重分别为 10%、10%、70%、10%。

BIOS 擦除和 RAID 擦除超时均为 600 秒；SP 启动和业务上电超时均为 1800 秒。PreserveLog 只影响源码列出的 SEL、Maintenance、FaultDiagnosis 日志保留类型。

返回值与异常 ​

RetireSystem 成功时返回任务 ID；状态查询返回状态、进度和详情。权限、状态或依赖异常通过任务状态或框架错误返回。

应用场景 ​

用于产品生命周期结束时的授权报废和状态跟踪。

限制条件 ​

该流程会控制电源、调用外部生命周期/存储服务并执行 BMC 恢复，不能在生产环境作为普通调试命令调用。

调试示例 ​

仅在隔离环境验证；调用前确认 UserMgmt 权限、报废特性开关、电源状态和恢复路径。

2.9 OEM IPMI 接口 ​

功能说明 ​

mds/ipmi.json 定义产品、电子保单、白牌、装备定制、板卡采集和供应链等 OEM 命令，生成定义位于 gen/product_mgmt/ipmi/cmds/，业务实现位于 src/lualib/ipmi/。接口包含厂商 IANA、字节序、角色与选择器约束；为避免在真实设备上误操作，本文不提供执行命令。集成时应逐项依据 mds/ipmi.json 生成请求。

参数说明 ​

表中权限与名称来自 mds/ipmi.json。其中 SetFirstPowerOnTime 的权限配置为 ReadOnly，集成时应按该定义进行权限校验。

返回值与异常 ​

成功返回标准 OEM IPMI 完成码；参数、权限、长度和状态错误通过错误符号或非零完成码返回。

应用场景 ​

供 IPMI 客户端使用产品、电子保单、白牌、装备定制、板卡采集和供应链管理命令。

限制条件 ​

必须满足 IANA、字节序、角色、选择器和系统锁定策略；文档不提供可能影响生产数据的执行命令。

调试示例 ​

在隔离环境通过 mds/ipmi.json 和 gen/product_mgmt/ipmi/cmds/ 核对请求字段后再执行。

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

组件支持三类代码级扩展：在模型文件中增加 D-Bus 对象/成员并重新生成代码；在 mds/ipmi.json 增加 OEM IPMI 定义并实现处理器；在白牌、装备定制和配置管理映射中增加经过校验的配置项。它不是通用运行时插件系统。

3.2 扩展点说明 ​

3.3 二次开发指导 ​

步骤一 ​

D-Bus 接口变更应修改 mds/model.json 和 mds/schema.json，IPMI 变更应修改 mds/ipmi.json，配置扩展应修改对应映射与校验逻辑；同时确认权限、持久化 usage 和构建特性边界。

步骤二 ​

使用仓库生成目标更新 gen/，实现业务回调并补充 test/unit/ 或 test/integration/ 用例。

示例代码 ​

现有方法注册模式如下（摘自 src/lualib/product_mgmt_app.lua）：

c_product_mgmt_service:ImplAssetListAssetListGetAssetList(function(object, ctx)
    return asset_list.get_instance():get_asset_list()
end)

验证方法 ​

1. 运行代码生成并确认生成文件与模型一致。
2. 在已准备 Conan/Skynet 测试根目录的环境执行统一通过bingo test -it、bingo test -ut执行组件的it、ut测试
3. 在隔离目标环境 introspect 对象，确认成员签名、权限和特性开关。

注意事项 ​

• 不要直接手改生成文件作为长期方案，模型重新生成会覆盖变更。
• 新功能必须考虑 CMakeLists.txt 中的特性裁剪。
• 报废、证书、持久化和 OEM IPMI 变更可能影响设备数据或安全边界，应只在隔离环境验证。

3.4 白牌定制案例 ​

处理流程 ​

白牌升级的组件类型为 WhiteBranding、组件 ID 为 17，实现分为三个阶段：

1. prepare：创建 /data/opt/bmc/web/custom 和 /data/opt/bmc/conf/product_mgmt/oem/profile 等定制目录。
2. process：通过安全代理将包解压到 /dev/shm/upgrade，解析 filelist.conf，按文件表复制或清理目标资源。
3. finish：发送完成信号，随后处理证书、web_custom.xml 和模型属性。

随 BMC 镜像提供的白牌包路径为 /opt/bmc/white_branding/wbd_up_file.tar.gz。升级标志位 /data/opt/bmc/product_mgmt/upgrade_with_bmc_flag 用于避免重启后重复处理。安全解压调用传入的大小上限为 100 MiB、文件数上限为 512；复制前还会检查目标完整路径长度是否接近代码中的 256 字节缓冲区上限。

包内约束 ​

• filelist.conf 的 Basic.Version 主版本必须为 2。
• 每个 FileN 条目需要同时提供 Name 和 Path。
• 名称为 CLEAR_ALL 时清理指定白牌目录，否则以临时文件复制后原子替换目标文件。
• 所有路径仍需通过安全代理的真实路径和特殊字符检查；不能把这些路径约束理解为允许任意文件部署。

验证方法 ​

1. 检查日志是否依次出现 prepare upgrade、process upgrade 和 finish upgrade。
2. 检查 [WBD] complete processing upgrade, ret=...；非零时根据 5.2 节返回值定位阶段。
3. 读取受影响的 Product、Contact 或 BMC 属性，并检查包声明的目标资源是否存在。

3.5 装备定制案例 ​

装备定制接收 /tmp/customset.ini，将其安全复制到 /dev/shm/tmp/product_mgmt/customset.ini 后解析，并把结果保存到 /data/opt/bmc/conf/product_mgmt/custom_settings.json。校验临时结果位于 /tmp/custom_settings_result.json，最长进度等待时间为 5 分钟。

当前 attribute_map 可处理以下键：

未识别的键会记录 Custom attribute name(...) is invalid 并跳过；Import=false 的条目不执行。应通过制造流程或测试桩提供输入，不建议在运行设备上手工写这些临时文件。

4. 日志说明 ​

4.1 一键日志收集 ​

组件通过 src/lualib/dump/init.lua 注册 on_dump 回调，生成 product_mgmt_dumpinfo、hardware_inventory.json 和 product_info.txt 等文件，分别记录电子保单/产品信息、资产清单和产品唯一标识。

4.2 关键日志信息 ​

日志片段来自 src/service/main.lua、src/lualib/product_mgmt_app.lua、src/lualib/digital_warranty/service.lua、src/lualib/whilte_branding/upgrade_mgmt.lua 和 src/lualib/board_info/collector.lua。

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误码速查表 ​

E_* 是白牌升级流程的内部返回值，不是 D-Bus 通用错误码。表中仅列出当前实现存在返回路径的值。OEM IPMI 处理成功时返回 0x00；失败路径通过 messages.base 或 messages.custom 中的错误符号交给框架转换。

业务错误符号 ​

当前源码使用的主要错误符号如下。仓库未包含 messages.base 和 messages.custom 的定义文件，因此这里只记录本组件中的触发条件，不扩展未在本仓库定义的数值错误码。

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

1. 记录接口或命令、对象路径、输入参数、权限和完整错误对象。
2. 保存 product_mgmt_dumpinfo、hardware_inventory.json 和 product_info.txt。
3. 白牌升级问题应记录包版本、filelist.conf、阶段日志和升级标志位。
4. 报废或供应链问题必须保留任务状态、子任务进度和外部依赖返回。

5.4 调试方法 ​

• 使用 busctl --user introspect 确认对象和接口是否随特性构建注册。
• 使用产品信息、资产和供应链的只读接口复现，修改类操作只在隔离环境执行。
• 对可选模块先检查 CONAN_DEFS_FEATURE_ASSET 和 CONAN_DEFS_FEATURE_TRUSTED_SUPPLY_CHAIN。

6. 常见问题解答 ​

Q1：为什么服务存在，但资产或可信供应链接口不存在？ ​

• 问题描述：product_mgmt 服务可用，但资产或供应链对象不存在。
• 一句话答案：这些是受构建特性控制的可选模块。
• 根因说明：CONAN_DEFS_FEATURE_ASSET、CONAN_DEFS_FEATURE_TRUSTED_SUPPLY_CHAIN 未启用，或模块加载时 pcall(require, ...) 失败。
• 解决方案：检查构建选项、安装结果和模块加载错误日志。
• 规避方案：在产品配置阶段明确可选能力，升级后使用 introspect 验证对象。
• 适用版本：1.140.2。

Q2：为什么设置 LanguageSet 失败？ ​

• 问题描述：写入 LanguageSet 返回属性值错误。
• 一句话答案：语言集合必须同时包含 zh 和 en，且只能使用支持的语言。
• 根因说明：src/lualib/language_mgmt/init.lua 与 src/lualib/config_mgmt/bmc_config.lua 对语言集合执行白名单和完整性校验。
• 解决方案：仅使用 zh、en、ja、fr、ru，并同时提供 zh 与 en。
• 规避方案：变更前读取当前语言集合并保存原值。
• 适用版本：1.140.2。

Q3：电子保单首次上电时间为什么没有记录？ ​

• 问题描述：FirstPowerOnTime 为空或长期不更新。
• 一句话答案：制造日期、当前时间或累计上电时长尚未满足记录条件。
• 根因说明：代码会拒绝异常制造日期和当前日期，并要求满足上电时长和检测窗口。
• 解决方案：核对 FruData 制造日期、Managers.Time 当前时间和 WARN 日志。
• 规避方案：不要通过直接改写持久化数据绕过规则，等待条件满足后复核。
• 适用版本：1.140.2。

附录 ​

附录 A 参考资料 ​

• mds/service.json：组件元数据、版本和外部依赖。
• mds/model.json、mds/schema.json：D-Bus 对象、权限、属性和方法模型。
• mds/ipmi.json：OEM IPMI 命令定义。
• CMakeLists.txt、conanfile.py、Makefile：安装、特性裁剪、打包和测试入口。
• src/service/main.lua、src/lualib/product_mgmt_app.lua：服务入口和初始化流程。
• test/unit/、test/integration/：单元与集成测试。
• docs/sfmea-failure-modes.md：仓库内失效模式分析资料。
• LICENSE：Mulan PSL v2 许可证文本。

附录 B 修订记录 ​