thermal 组件新增资源协作接口方法及属性支持主备场景风扇属性同步（两方案供评审选择）

psqk · 2026 年10 月 22 日 14:17

【待评审】thermal 组件新增资源协作接口方法支持主备场景风扇属性同步（两方案供评审选择）

V3 合并版：方案一（按类分散，6 方法）与方案二（组件级汇聚，1 方法）并列呈现，背景与共享信息只写一次，由评委评审选择采纳方案。

背景

在存在两个单板、每个单板各自有一个 BMC 的主备机型中，同一时间只有一个 BMC 为主。为保持主从 BMC 的 thermal 风扇相关资源树信息一致（主备倒换后新主控可基于一致的属性状态继续工作），需要主控 BMC 将 thermal 组件的风扇相关属性周期性同步给从控 BMC。

同步冲突策略：以主控为准，主从属性不一致时主控值覆盖从控。

同步范围口径：仅同步风扇运行状态、风扇手动调速控制及风扇故障自愈配置；自动调速策略类属性（调速曲线、目标温度、PID 参数等）由 CSR 下发、两侧天然一致，不在同步范围。

关联ISSUE

[需求]: thermal 组件主备场景风扇属性同步（占位，提交前请替换为实际 issue 链接）

整体机制（两方案共享）

主控 BMC 周期调用从控 BMC 资源协作接口方法（RPC），将属性值写入从控，达到间接同步效果；RPC 调用链路复用 bmc_datasync 组件既有跨板通道。同步路由细节由组件间约定收敛，不向使用者暴露。

阶段 1：主控侧触发
  └─ thermal_mgmt(主) 周期任务读取本板风扇属性
        │
阶段 2：主控 bmc_datasync
  └─ 将风扇属性同步请求发往对端
        │
阶段 3：CNC 通道
  └─ TLS 传输到从控 bmc_datasync
        │
阶段 4：从控 bmc_datasync
  └─ 按同步请求回调 thermal_mgmt 从控侧同步方法
        │
阶段 5：thermal_mgmt(从) 实现同步方法回调
  └─ 校验入参 → 写入本地（主控值覆盖）

同步范围清单（两方案共享，共 23 项属性 / 6 组对象）

组	接口 / 对象	属性
① 手动调速配置	bmc.kepler.Systems.CoolingConfig	CtrlMode、TimeOut、SmartCoolingMode、ManualLevel
② 风冷手动调速	bmc.kepler.Systems.AirCoolingConfig	CtrlMode、TimeOut、ManualSpeedPercent
③ 风扇状态	bmc.kepler.Systems.CoolingFan（×N 实例）	FrontStatus、RearStatus、FrontSpeed、RearSpeed、Level
④ 风扇状态	bmc.kepler.Systems.Fan（×N 实例）	FrontSpeed、RearSpeed、FrontStatus、RearStatus、PWMPercentage、FanAlarmLed、PartNumber、ExpectedPWM
⑤ 风扇私有状态	（Fan 对象私有属性，不上树/上树见两方案差异）	FaultHealCount、SleepState
⑥ 组级自愈配置	（Fans 组私有属性）	FaultHealEnabled、MaxFaultHealCount

方案一：按类分散同步（6 个方法，各挂目标类接口）

方案一概述

每个目标类/接口各自新增一个 Sync 方法，整组同步该类属性；主控按对象逐个调用。

组	挂载接口	方法	同步属性
①	bmc.kepler.Systems.CoolingConfig	SyncCoolingConfigProperties	CtrlMode、TimeOut、SmartCoolingMode、ManualLevel
②	bmc.kepler.Systems.AirCoolingConfig	SyncAirCoolingConfigProperties	CtrlMode、TimeOut、ManualSpeedPercent
③	bmc.kepler.Systems.CoolingFan	SyncCoolingFanProperties	5 属性整组
④	bmc.kepler.Systems.Fan	SyncFanProperties	8 属性整组
⑤	新建 bmc.kepler.Systems.FanInfo（挂 Fan 类）	SyncFanInfoProperties	FaultHealCount、SleepState（新增上树属性）
⑥	bmc.kepler.Systems.Fans	SyncFansProperties	FaultHealEnabled、MaxFaultHealCount（新增上树属性）

评审点1：bmc.kepler.Systems.CoolingConfig 接口新增方法 SyncCoolingConfigProperties

资源路径：/bmc/kepler/Systems/:SystemId/CoolingConfig（既有）

方法名称	请求签名	请求参数描述	响应签名	响应参数描述	方法描述	访问权限	变更影响
SyncCoolingConfigProperties	susy	CtrlMode(s)：控制模式 enum Auto/Manual/Mixed Timeout(u)：手动模式超时时长，单位秒 SmartCoolingMode(s)：智能调速模式 Custom/HighPerformance/LowNoise/EnergySaving ManualLevel(y)：手动转速级别	NA	NA	主控整组同步 CoolingConfig 手动调速配置到从控	BasicSetting	纯新增方法，向后兼容

变更接口影响

路径	变更接口影响	CSR配置影响	持久化影响	其他影响
/bmc/kepler/Systems/:SystemId/CoolingConfig	新增方法	不涉及	不涉及	不复用现成 Set* 方法的原因见设计说明 5

评审点2：bmc.kepler.Systems.AirCoolingConfig 接口新增方法 SyncAirCoolingConfigProperties

资源路径：/bmc/kepler/Systems/:SystemId/AirCoolingConfig（既有）

方法名称	请求签名	请求参数描述	响应签名	响应参数描述	方法描述	访问权限	变更影响
SyncAirCoolingConfigProperties	suy	CtrlMode(s)：控制模式 enum Auto/Manual/Mixed Timeout(u)：超时时长，单位秒 ManualSpeedPercent(y)：手动转速百分比	NA	NA	主控整组同步 AirCoolingConfig 手动调速配置到从控	BasicSetting	纯新增方法，向后兼容

变更接口影响

路径	变更接口影响	CSR配置影响	持久化影响	其他影响
/bmc/kepler/Systems/:SystemId/AirCoolingConfig	新增方法	不涉及	不涉及	同上

评审点3：bmc.kepler.Systems.CoolingFan 接口新增方法 SyncCoolingFanProperties

资源路径：/bmc/kepler/Systems/:SystemId/CoolingFan/:Id（既有）

方法名称	请求签名	请求参数描述	响应签名	响应参数描述	方法描述	访问权限	变更影响
SyncCoolingFanProperties	yyuuy	FrontStatus(y)、RearStatus(y)：前后风扇状态，枚举 FrontSpeed(u)、RearSpeed(u)：前后风扇转速 Level(y)：调速级别	NA	NA	主控整组同步 CoolingFan 属性到从控	BasicSetting	纯新增方法，向后兼容

变更接口影响

路径	变更接口影响	CSR配置影响	持久化影响	其他影响
/bmc/kepler/Systems/:SystemId/CoolingFan/:Id	新增方法	不涉及	不涉及	无

评审点4：bmc.kepler.Systems.Fan 接口新增方法 SyncFanProperties

资源路径：/bmc/kepler/Systems/:SystemId/Thermal/Fans/:Id（既有）

方法名称	请求签名	请求参数描述	响应签名	响应参数描述	方法描述	访问权限	变更影响
SyncFanProperties	uuyydysd	FrontSpeed(u)、RearSpeed(u)：前后风扇转速 FrontStatus(y)、RearStatus(y)：前后风扇状态，枚举 PWMPercentage(d)：PWM 占空比百分比 FanAlarmLed(y)：风扇告警灯状态，枚举 PartNumber(s)：风扇部件编码 ExpectedPWM(d)：主控期望 PWM 输出百分比	NA	NA	主控整组同步 Fan 属性到从控	BasicSetting	纯新增方法，向后兼容

说明：PWMPercentage / ExpectedPWM 参数类型取 Double，与既有 bmc.kepler.Systems.Fan.SetFanPWM 的 PWM 参数（Double）保持一致。

变更接口影响

路径	变更接口影响	CSR配置影响	持久化影响	其他影响
/bmc/kepler/Systems/:SystemId/Thermal/Fans/:Id	新增方法	不涉及	不涉及	无

评审点5：新增资源协作接口 bmc.kepler.Systems.FanInfo 及方法 SyncFanInfoProperties

资源路径：/bmc/kepler/Systems/:SystemId/Thermal/Fans/:Id（复用 Fan 类路径，不新增对象）

接口描述：承载 Fan 对象私有运行状态属性（故障自愈计数、休眠状态）的同步接口，挂载于 model.json 既有 Fan 类下（一个类挂多个接口，社区既有模式）。

方法名称	请求签名	请求参数描述	响应签名	响应参数描述	方法描述	访问权限	变更影响
SyncFanInfoProperties	yy	FaultHealCount(y)：风扇已恢复次数，0–255 SleepState(y)：风扇休眠状态，1 唤醒，0 休眠	NA	NA	主控同步 FanInfo 属性到从控	BasicSetting	纯新增方法，向后兼容

新增属性

变更类型	属性名称	签名	只读	变化通知	属性描述	访问权限	属性来源	持久化类型	变更影响
新增	FaultHealCount	y	true	true	风扇已经恢复的次数	Read: ReadOnly	组件内部计数，经同步写入	复位持久	无影响
新增	SleepState	y	true	true	风扇休眠状态，1 唤醒，0 休眠	Read: ReadOnly	风扇对象运行态，经同步写入	不持久化	同步写入需与从控本地休眠状态机协同（见设计说明 7）

变更接口影响

路径	变更接口影响	CSR配置影响	持久化影响	其他影响
/bmc/kepler/Systems/:SystemId/Thermal/Fans/:Id	新增接口及属性	需确认 CSR 键名映射（alias）无冲突	不涉及新增和废弃主键	FaultHealCount 为复位持久化属性，同步写入需处理从控持久化恢复时序

评审点6：bmc.kepler.Systems.Fans 接口新增属性及方法 SyncFansProperties

资源路径：/bmc/kepler/Systems/:SystemId/Thermal/Fans（既有）

方法名称	请求签名	请求参数描述	响应签名	响应参数描述	方法描述	访问权限	变更影响
SyncFansProperties	by	FaultHealEnabled(b)：恢复功能使能开关 MaxFaultHealCount(y)：最大恢复次数	NA	NA	主控同步组级自愈配置到从控	BasicSetting	纯新增方法，向后兼容

新增属性

变更类型	属性名称	签名	只读	变化通知	属性描述	访问权限	属性来源	持久化类型	变更影响
新增	FaultHealEnabled	b	true	true	风扇恢复功能的使能开关	Read: ReadOnly	组件内部配置，经同步写入	不持久化	双定义设计（见设计说明 8）
新增	MaxFaultHealCount	y	true	true	风扇的最大恢复次数	Read: ReadOnly	组件内部配置，经同步写入	不持久化	双定义设计（见设计说明 8）

变更接口影响

路径	变更接口影响	CSR配置影响	持久化影响	其他影响
/bmc/kepler/Systems/:SystemId/Thermal/Fans	新增属性及方法	需确认 CSR 键名映射无冲突	不涉及	无

方案二：组件级汇聚同步（1 个方法，挂 ThermalMgmt 接口）

方案二概述

在组件级单例接口 bmc.kepler.ThermalMgmt（ThermalMgmt 类，path=/bmc/kepler/ThermalMgmt，既有对象）下新增唯一一个方法，将 23 项同步属性一把同步：参数按对象域分层组织（结构体/结构体数组），约定式寻址（参数只携带值与实例标识 FanId，目标对象映射由从控实现内部约定，不暴露 path/interface/method）；主控每周期仅 1 次调用；私有 4 项属性不上树（主控组件内部读取、从控方法内部直写）。

评审项对比方案一：1 方法 + 0 新接口 + 0 属性上树（私有属性走组件内部路径）。

评审点7：bmc.kepler.ThermalMgmt 接口新增方法 SyncThermalProperties

资源路径：/bmc/kepler/ThermalMgmt（既有单例对象）

新增方法

方法名称	请求参数（分层结构体）	响应参数	方法描述	访问权限	变更影响
SyncThermalProperties	ConfigProps: #/defs/ThermalConfigSyncProps AirConfigProps: #/defs/AirThermalConfigSyncProps FanProps: Array<#/defs/FanSyncProps> CoolingFanProps: Array<#/defs/CoolingFanSyncProps> FansProps: #/defs/FansSyncProps	FailedObjects: Array<#/defs/SyncFailedObject>	主控将 23 项风扇同步属性一把同步到从控；尽力而为，失败项经 rsp 返回，周期重试自愈	BasicSetting	纯新增方法，向后兼容

req defs 结构定义

defs 名称	字段（类型）
ThermalConfigSyncProps	CtrlMode(s, enum Auto/Manual/Mixed)、Timeout(u)、SmartCoolingMode(s)、ManualLevel(y)
AirThermalConfigSyncProps	CtrlMode(s, enum Auto/Manual/Mixed)、Timeout(u)、ManualSpeedPercent(y)
FanSyncProps（数组元素，每实例一个）	FanId(y)、FrontSpeed(u)、RearSpeed(u)、FrontStatus(y)、RearStatus(y)、PWMPercentage(d)、FanAlarmLed(y)、PartNumber(s)、ExpectedPWM(d)、FaultHealCount(y)、SleepState(y)
CoolingFanSyncProps（数组元素）	FanId(y)、FrontStatus(y)、RearStatus(y)、FrontSpeed(u)、RearSpeed(u)、Level(y)
FansSyncProps	FaultHealEnabled(b)、MaxFaultHealCount(y)

rsp defs 结构定义

defs 名称	字段
SyncFailedObject	ObjectName(s)：失败对象标识；Reason(s)：失败原因

说明：① Fan/CoolingFan 实例经 FanId 寻址（每实例一个数组元素），FanInfo 私有属性（FaultHealCount/SleepState）合并进 FanSyncProps 元素，无需独立接口；② 私有 4 项属性不上树——主控经组件内部 ORM 读取，从控方法直接写入内部对象；③ 结构体/结构体数组方法参数有社区先例（UpdateService.ParallelUpdate(Packages) 等 28 个 req 先例）。

req defs 接口定义示例（mdb_interface JSON 风格）

{
  "bmc.kepler.ThermalMgmt": {
    "methods": {
      "SyncThermalProperties": {
        "req": {
          "ConfigProps": { "$ref": "#/defs/ThermalConfigSyncProps" },
          "AirConfigProps": { "$ref": "#/defs/AirThermalConfigSyncProps" },
          "FanProps": { "baseType": "Array", "items": { "$ref": "#/defs/FanSyncProps" } },
          "CoolingFanProps": { "baseType": "Array", "items": { "$ref": "#/defs/CoolingFanSyncProps" } },
          "FansProps": { "$ref": "#/defs/FansSyncProps" }
        },
        "rsp": {
          "FailedObjects": { "baseType": "Array", "items": { "$ref": "#/defs/SyncFailedObject" } }
        }
      }
    }
  },
  "defs": {
    "ThermalConfigSyncProps": {
      "CtrlMode": { "baseType": "String", "enum": ["Auto", "Manual", "Mixed"] },
      "Timeout": { "baseType": "U32", "description": "手动模式超时时长，单位秒" },
      "SmartCoolingMode": { "baseType": "String" },
      "ManualLevel": { "baseType": "U8" }
    },
    "FanSyncProps": {
      "FanId": { "baseType": "U8" },
      "FrontSpeed": { "baseType": "U32" }, "RearSpeed": { "baseType": "U32" },
      "FrontStatus": { "baseType": "U8" }, "RearStatus": { "baseType": "U8" },
      "PWMPercentage": { "baseType": "Double" },
      "FanAlarmLed": { "baseType": "U8" },
      "PartNumber": { "baseType": "String" },
      "ExpectedPWM": { "baseType": "Double" },
      "FaultHealCount": { "baseType": "U8" },
      "SleepState": { "baseType": "U8" }
    }
  }
}

（AirThermalConfigSyncProps / CoolingFanSyncProps / FansSyncProps / SyncFailedObject 结构同理，完整定义见前述 defs 字段表）

变更接口影响

路径	变更接口影响	CSR配置影响	持久化影响	其他影响
/bmc/kepler/ThermalMgmt	新增方法（含 req/rsp defs）	不涉及	不涉及	无

两方案对比（供评审参考）

维度	方案一（评审点 1–6）	方案二（评审点 7）
评审项	6 方法 + 4 属性上树 + 1 新接口	1 方法（含 defs）
主控调用	6 类 × 实例数	每周期 1 次
寻址方式	方法挂各类接口（天然寻址）	约定式（参数仅 FanId，路由收敛组件内部）
扩展性	新增属性可能加方法	新增属性仅扩 defs
可观测性	rsp 全 NA	rsp 失败清单
私有属性	上树（北向可见）	不上树（北向不可见，内部直写）
参数复杂度	每方法简单	单方法复杂（分层结构体）

方案选择说明（请评委先定方案再逐点评审）：两方案为同一同步需求的互斥实现选择——若采纳方案一，评审点 1–6 生效、评审点 7 不实施；若采纳方案二，仅评审点 7 生效、评审点 1–6 不实施。评审结论请先明确采纳方案，再针对所选方案的评审点逐项给出结论。

设计说明（两方案共享条款 1–5、9–11；方案一特有 6–8；方案二特有 12–14）

方法命名：Sync*Properties（复数）表示一次性同步整组属性；Sync 前缀与北向用户 Set* 系方法区分，表明主从间内部协作同步语义（先例：bmc.kepler.EventService.EventSync.SyncEvent、bmc.kepler.Managers.DataSync.SyncProperties）。同步方法不是用户配置读写动作，不适用 Set*/Get* 惯例动词。
强类型参数：请求参数逐属性强类型定义（带 baseType/范围/描述），不采用字典弱类型打包。
权限设计：方法供 bmc_datasync 主从同步链路内部调用，privilege 由组件模型（model.json）定义为内部调用权限，避免北向直接调用改写属性（接口侧 BasicSetting 仅为对齐既有同步类方法先例）。
FanInfo 接口挂载方式（方案一）：挂 model.json 既有 Fan 类下，复用 Fan 对象路径与生命周期（类挂多接口社区既有模式，如 Fan 类已挂 Fan 与 Metric）。
为何不复用现成 Set 方法*（两案同因）：既有 SetCtrlMode/SetManualLevel 等实现中存在 FanCtrlEnable ≠ Enabled 时的对板命令重定向守卫（不满足条件直接返回、不写入），从控侧会被拦截导致同步不生效，故新增专用同步方法。
从控侧数据流协同（两案同需）：从控（非主状态）对被同步属性抑制既有"设备树→资源树"本地写入链路，被同步属性值完全由主控周期同步维护，避免本地实测与同步值互相覆盖抖动。
SleepState 同步协同（两案同需）：从控本地休眠等待逻辑以同步值为准；从控为从状态时不本地改写（SleepLock/SleepControl 不同步，由主控统一决策）。
双定义设计（方案一）：FaultHealEnabled/MaxFaultHealCount 上树采用 WorkInStandby 既有双定义模式（SystemsFans 接口属性 + Fans 内部属性），实现写两侧。
失败恢复与审计（两案同需）：周期同步天然自愈，单次失败下周期重试，连续失败告警；方法实现采用组件标准操作日志记录同步来源、属性值与结果。
与 DataSync 既有同步框架的关系（含 TriggerSync 与新提案 SyncRemoteData，见论坛 8026 帖）：- TriggerSync 为框架级全量同步，不支持按接口选择与业务自控周期，与本方案互补不冲突；- 与 SyncRemoteData 提案的差异化：① SyncRemoteData 采用 a{ss} 弱类型字典（键值均为字符串、总量上限 32768 字节）且要求目标方法输入签名固定为 a{ss}a{ss}，无法承载本方案所需的分层结构体（跨对象、多实例、强类型校验）；② SyncRemoteData 需调用方指定对板 Service/Path/Interface/Method，将底层路由细节暴露给使用者；本方案（尤其方案二约定式寻址）同步编排收敛在组件内部；③ 场景差异：SyncRemoteData 面向未上树配置的一次性下发，本方案为 thermal 风扇属性周期性状态与控制同步，需业务校验（如 LevelPercentRange 范围校验）与本地数据流协同。
与既有命令重定向机制的关系：现成 Set* 方法的北向设置语义与重定向逻辑维持不变；Sync* 方法为主控→从控单向同步专用，不经守卫与重定向路径。
约定式寻址（方案二）：参数只携带属性值与实例标识（FanId），目标对象映射由从控实现内部约定——同步编排收敛在组件间，不向使用者暴露底层路径/接口/方法细节。
私有属性内部直写（方案二）：FaultHealCount/SleepState/FaultHealEnabled/MaxFaultHealCount 不上树，主控经组件内部 ORM 读取、从控方法直接写入内部对象（若未来需北向可见可另行评审上树）。
扩展性（方案二）：后续新增同步属性仅扩展对应 defs 结构体定义，无需新增方法。

是否准备好AI预审

是

评审结论

（待评审会议后填写：先结论采纳方案一或方案二，再针对所选方案的各评审点给出详细结论）

遗留问题

无

ubmc_assistant · 2026 年10 月 22 日 14:34

预审答案内容由AI生成，仅供参考：

帖子评审结论：thermal 组件新增资源协作接口方法及属性支持主备场景风扇属性同步

帖子相关性：相关（MDB 相关: 标题含强特征: 资源协作）

总评审点数：4
MDB 资源协作接口评审点：4
其他评审点：0

总体结果：通过（4/4 个评审点通过）

评审点 1：bmc.kepler.Systems.CoolingFan 接口新增方法 SyncCoolingFanProperties【MDB】

结果：通过

规则合规性检查：通过（29 项检查全部通过）

评审点 2：bmc.kepler.Systems.Fan 接口新增方法 SyncFanProperties【MDB】

结果：通过

规则合规性检查：通过（29 项检查全部通过）

评审点 3：新增资源协作接口 bmc.kepler.Systems.FanInfo 及方法 SyncFanInfoProperties【MDB】

结果：通过

规则合规性检查：通过（29 项检查全部通过）

评审点 4：bmc.kepler.Systems.Fans 接口新增属性及方法 SyncFansProperties【MDB】

结果：通过

规则合规性检查：通过（29 项检查全部通过）

话题		回复	浏览量
【待评审】资源协作接口新增远程单板BMC配置同步接口与方法 Interface评审方案评审	2	32	2026 年10 月 22 日
【待评审】管理板风扇、电源、电子保单聚合管理接口评审 Interface评审	0	31	2026 年10 月 10 日
【已评审】thermal_mgmt 共享风扇控制权属性新增 Hardware评审方案评审	0	75	2026 年8 月 1 日
【已评审】新增数据同步资源协作接口 Interface评审	0	122	2025 年8 月 19 日
【已评审】redfish&rest接口新增MCU类型风扇管理信息属性 Interface评审	1	104	2026 年5 月 20 日

thermal 组件新增资源协作接口方法及属性支持主备场景风扇属性同步（两方案供评审选择）

【待评审】thermal 组件新增资源协作接口方法支持主备场景风扇属性同步（两方案供评审选择）

背景

关联ISSUE

整体机制（两方案共享）

同步范围清单（两方案共享，共 23 项属性 / 6 组对象）

方案一：按类分散同步（6 个方法，各挂目标类接口）

方案一概述

评审点1：bmc.kepler.Systems.CoolingConfig 接口新增方法 SyncCoolingConfigProperties

评审点2：bmc.kepler.Systems.AirCoolingConfig 接口新增方法 SyncAirCoolingConfigProperties

评审点3：bmc.kepler.Systems.CoolingFan 接口新增方法 SyncCoolingFanProperties

评审点4：bmc.kepler.Systems.Fan 接口新增方法 SyncFanProperties

评审点5：新增资源协作接口 bmc.kepler.Systems.FanInfo 及方法 SyncFanInfoProperties

评审点6：bmc.kepler.Systems.Fans 接口新增属性及方法 SyncFansProperties

方案二：组件级汇聚同步（1 个方法，挂 ThermalMgmt 接口）

方案二概述

评审点7：bmc.kepler.ThermalMgmt 接口新增方法 SyncThermalProperties

两方案对比（供评审参考）

设计说明（两方案共享条款 1–5、9–11；方案一特有 6–8；方案二特有 12–14）

是否准备好AI预审

评审结论

遗留问题

帖子评审结论：thermal 组件新增资源协作接口方法及属性支持主备场景风扇属性同步

总体结果：通过（4/4 个评审点通过）

评审点 1：bmc.kepler.Systems.CoolingFan 接口新增方法 SyncCoolingFanProperties【MDB】

评审点 2：bmc.kepler.Systems.Fan 接口新增方法 SyncFanProperties【MDB】

评审点 3：新增资源协作接口 bmc.kepler.Systems.FanInfo 及方法 SyncFanInfoProperties【MDB】

评审点 4：bmc.kepler.Systems.Fans 接口新增属性及方法 SyncFansProperties【MDB】

相关话题