【待评审】支持框级固件管理北向接口评审

Interface SIG Interface评审
1

背景

针对框式设备当前openUBMC缺少通过管理板对框内其他单板（如业务板等）进行固件升级的统一北向入口，运维人员无法在Web页面上集中发起框内单板的HPM包或整包ZIP升级，也无法统一查询框内单板的升级进度。为补齐框级固件管理能力，需要新增webrest接口和资源协作接口方法，实现通过管理板对框内单板触发HPM升级、整包ZIP升级以及升级进度查询。

关联ISSUE

无

整体方案

框级固件管理北向接口需要实现以下功能：

  1. 查询框内单板升级进度：支持通过Web页面获取框内单板固件升级进度信息，用于集中展示
  2. 触发框内单板HPM升级：支持通过Web页面通过管理板对框内指定单板发起HPM包升级
  3. 触发框内单板整包升级：支持通过Web页面通过管理板对框内指定单板发起ZIP整包升级
  4. 批量升级板级大包：资源协作接口支持一次请求对框内多个单板下发整包升级任务

本次新增3个webrest接口、1个资源协作接口方法。

评审点

本次评审项汇总：

评审点 标题 接口类型
评审点一 新增webrest接口 /UI/Rest/Chassis/AggregationService/UpdateService/UpdateProgress webrest
评审点二 新增webrest接口 /UI/Rest/Chassis/AggregationService/UpdateService/Actions/Update.FirmwareUpdate webrest
评审点三 新增webrest接口 /UI/Rest/Chassis/AggregationService/UpdateService/Actions/Update.FullImageUpdate webrest
评审点四 变更资源协作接口 bmc.kepler.AggregationService.Update 新增FullImageUpdate方法 资源协作

评审点一：新增webrest接口，用于获取框内单板固件升级进度

uri：/UI/Rest/Chassis/AggregationService/UpdateService/UpdateProgress

变化类型：新增uri

操作类型：GET

应用场景：Web页面集中获取框内单板固件升级进度，用于升级进度显示

请求参数：见下表

响应参数：见下表

操作权限：ReadOnly

请求参数说明：

属性名称 取值类型 说明 取值范围 默认值 是否允许为null 约束
Ids array 需要查询升级进度的单板Id列表 单板Id字符串数组，如[“Blade1”,“Blade2”] 空数组 否 为空时返回空任务列表

响应参数说明：

属性名称 取值类型 说明 取值范围 默认值 是否允许为null 约束
UpdateMode string 当前升级模式 “Serial”、“Parallel” “Serial” 否 无
UpdateTasks array 升级任务进度信息列表 json对象，具体见下表 空表 否 无

UpdateTasks对象参数说明：

属性名称 取值类型 说明 取值范围 是否允许为null
TaskName string 升级任务名称 合法任务名称字符串 否
Component string 升级固件描述 “BMC”、“CPLD”、"BIOS"等 否
FileName string 升级包名称 合法文件名字符串 否
Percentage string 升级进度百分比 “0%”~“100%” 否
TaskState string 升级状态 “New”、“Starting”、“Running”、“Suspended”、“Completed”、“Cancelled”、“Exception” 否
ErrorCode integer 升级任务错误码 0表示成功 否
EstimatedRemainingTime integer 预计剩余时间（秒） 非负整数 是
Id string 升级单板标识 合法单板Id字符串，如"Blade1" 否

样例展示：

URL: /UI/Rest/Chassis/AggregationService/UpdateService/UpdateProgress
操作类型：GET
请求参数：
{
    "Ids": ["Blade1", "Blade2"]
}
响应消息体举例：
{
    "UpdateMode": "Serial",
    "UpdateTasks": [
        {
            "TaskName": "CPLD Upgrade Task",
            "Component": "CPLD",
            "FileName": "CPLD.hpm",
            "Percentage": "50%",
            "TaskState": "Running",
            "ErrorCode": 0,
            "EstimatedRemainingTime": 75,
            "Id": "Blade1"
        }
    ]
}

评审点二：新增webrest接口，用于通过管理板升级框内单板HPM包

uri：/UI/Rest/Chassis/AggregationService/UpdateService/Actions/Update.FirmwareUpdate

变化类型：新增uri

操作类型：POST

应用场景：Web页面通过管理板对框内指定单板发起HPM包固件升级

请求参数：见下表

操作权限：BasicSetting

属性名称 取值类型 说明 取值范围 默认值 是否允许为null 约束
Id string 需要升级的单板标识 合法单板Id字符串，如"Blade1" 无 否 无
FilePath string HPM升级包路径 合法本地文件路径，如"/tmp/image.hpm" 无 否 文件必须存在且可读
ForceUpdate boolean 是否强制升级 true、false false 是 可选参数，为true时跳过版本校验等前置检查

响应参数：通用任务uri

样例展示：

URL: /UI/Rest/Chassis/AggregationService/UpdateService/Actions/Update.FirmwareUpdate
操作类型：POST
请求参数：
{
    "Id": "Blade1",
    "FilePath": "/tmp/image.hpm",
    "ForceUpdate": false
}
响应消息体举例：
{"url":"/UI/Rest/Task/1"}

评审点三：新增webrest接口，用于通过管理板升级框内单板ZIP整包

uri：/UI/Rest/Chassis/AggregationService/UpdateService/Actions/Update.FullImageUpdate

变化类型：新增uri

操作类型：POST

应用场景：Web页面通过管理板对框内指定单板发起ZIP整包升级，一次升级包内多个固件

请求参数：见下表

操作权限：BasicSetting

属性名称 取值类型 说明 取值范围 默认值 是否允许为null 约束
Id string 需要升级的单板标识 合法单板Id字符串，如"Blade1" 无 否 无
FilePath string ZIP整包升级包路径 合法本地文件路径，如"/tmp/fullimage.zip" 无 否 文件必须存在且可读，包内需包含合法profile.json清单
SignaturePath string ZIP整包签名文件路径 合法本地文件路径，如"/tmp/fullimage.p7s" 无 否 文件必须存在且可读
ForceUpdate boolean 是否强制升级 true、false false 是 可选参数，为true时跳过版本校验等前置检查

响应参数：通用任务uri

样例展示：

URL: /UI/Rest/Chassis/AggregationService/UpdateService/Actions/Update.FullImageUpdate
操作类型：POST
请求参数：
{
    "FilePath": "/tmp/fullimage.zip",
    "SignaturePath": "/tmp/fullimage.p7s",
    "Id": "Blade1",
    "ForceUpdate": false
}
响应消息体举例：
{"url":"/UI/Rest/Task/1"}

评审点四：变更资源协作接口 bmc.kepler.AggregationService.Update 新增FullImageUpdate方法

接口描述：在现有框级固件升级接口基础上，新增FullImageUpdate方法，支持通过管理板对框内指定单板下发ZIP整包升级任务，一次请求升级一个单板，ZIP包内可包含多个固件并行升级。

资源树路径：/bmc/kepler/AggregationService/Aggregates/${AggregateId}/UpdateService
接口：bmc.kepler.AggregationService.Update

方法评审点

新增方法

方法名称 请求签名 请求参数描述 响应签名 响应参数描述 方法描述 访问权限
FullImageUpdate sssa{ss} Id：签名为 s，表征本次升级单板Id
FilePath：签名为 s，表征ZIP整包升级包路径
SignaturePath：签名为 s，表征ZIP整包签名文件路径
AdditionalOptions：签名为 a{ss}，表征固件升级可选参数，用于各种升级扩展场景		 uau TaskId：签名为 u，表征当前升级请求的主任务Id
SubTaskIds：签名为 au，表征ZIP包内每个固件升级对应的子任务Id集合		 通过管理板升级框内指定单板ZIP整包 BasicSetting

FullImageUpdate参数说明：

参数属性名称 参数属性取值 取值说明
Id String 本次升级单板Id，如"Blade1"
FilePath String ZIP整包升级包路径，如 /tmp/fullimage.zip
SignaturePath String ZIP整包签名文件路径，如 /tmp/fullimage.p7s

FullImageUpdate - AdditionalOptions(a{ss})参数属性说明：

参数属性名称 参数属性取值 取值说明
ForceUpdate “true”/“false” 是否强制升级，为"true"时跳过版本校验等前置检查

接口变更影响

路径 变更接口影响 北向呈现 已有消费方行为 CSR配置影响 持久化影响 兼容性影响
/bmc/kepler/AggregationService/Aggregates/${AggregateId}/UpdateService 新增FullImageUpdate方法，对外提供管理板升级框内指定单板ZIP整包能力 北向通过 webrest 接口 /UI/Rest/Chassis/AggregationService/UpdateService/Actions/Update.FullImageUpdate 呈现 现有 StartUpdate/ParallelUpdate/GetUpdateProgress 等方法行为不变，已有消费方无影响 不涉及重名属性，无影响 不涉及新增和废弃主键，无影响 新增方法不影响现有接口契约，向后兼容

是否准备好AI预审

是

评审结论

遗留问题

2

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

帖子评审结论：【待评审】支持框级固件管理北向接口评审

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

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

总体结果：不通过（0/1 个评审点通过）

评审点 1：变更资源协作接口 bmc.kepler.AggregationService.Update 新增FullImageUpdate方法【MDB】

结果：不通过

  • 规则合规性检查：不通过（1/29 项失败）
    • 规则合规性失败项（必须项）：
      规则ID：MDB-REVIEW-002
      级别：必须项
      问题描述：评审点明确新增方法，但正文完全缺失能力描述、变更原因及影响说明，导致无法判断契约边界与影响范围。
      处理建议：在正文中补充 Update 方法新增的业务能力描述、消费方/使用场景、变更原因，以及接口影响（如北向呈现、已有消费方行为、CSR/现网/持久化/兼容性影响等）信息。
    • 警告项（建议性）：
      规则ID：MDB-REVIEW-003
      级别：建议性
      问题描述：评审点新增方法但未提供业务背景、消费方场景及文档同步项，触发建议条件。
      处理建议：severity=‘should’ 建议性规则，建议修改以提升规范符合性