【已评审】支持整包升级资源协作接口和北向接口评审

L_Ling · 2026 年1 月 22 日 02:51

背景

针对产品整机固件升级场景，为解决固件包数量多，固件下载效率低，版本配套管理困难问题，BMC提供产品级固件整包升级能力，避免运维人员由于误操作导致版本不匹配问题，同时提升整机升级效率。

整体方案

支持将配套版本的多个HPM包打包为一个整包，BMC提供北向Redfish、WEB、IPMI接口触发整包升级，升级流程默认走并行流程，提升升级效率，后续生效与并行升级的生效策略一致；
整包升级流程与串行升级、并行升级、暂存生效等流程互斥；

评审点

支持整包升级Redfish接口评审；
支持整包升级ipmi接口评审；
支持整包升级WEB界面评审；
支持整包升级webrest接口评审；
支持整包升级资源协作接口评审（bmc.kepler.UpdateService接口新增方法）

详细描述

评审点一：新增OEM Action资源 FullImageUpdate用于触发固件整包升级

资源URI：/redfish/v1/UpdateService/Actions/Oem/{OemIdentifier}/UpdateService.FullImageUpdate
资源版本：#UpdateService.v1_17_0.UpdateService
操作权限：BasicSetting
输入参数：

参数名	类型	必填	示例/取值约束	描述
ImageURI	string	是	升级包的URL。例如：“sftp://username:password@10.10.10.191/tmp/package.zip” 本地升级：“/tmp/cpldimage.zip”	升级包所在路径，文件为zip格式
TransferProtocol	string	否	枚举值：HTTPS/SCP/SFTP/CIFS/NFS	从远程服务器下载升级包时使用的协议
ForceUpdate	boolean	否	true/false	是否强制升级 true

ActionInfo： /redfish/v1/UpdateService/Actions/Oem/{OemIdentifier}/FullImageUpdateActionInfo

{
    "@odata.context": "/redfish/v1/$metadata#ActionInfo.ActionInfo",
    "@odata.id": "/redfish/v1/UpdateService/FullImageUpdateActionInfo",
    "@odata.type": "#ActionInfo.v1_0_1.ActionInfo",
    "Id": "FullImageUpdateActionInfo",
    "Name": "Full Image Update Action Info",
    "Parameters": [
        {
            "Name": "ImageURI",
            "Required": true,
            "DataType": "String"
        },
        {
            "Name": "TransferProtocol",
            "Required": false,
            "DataType": "String",
            "AllowableValues": [
                "HTTPS",
                "SCP",
                "SFTP",
                "CIFS",
                "NFS"
            ]
        },
        {
            "Name": "ForceUpdate",
            "Required": false,
            "DataType": "boolean"
        },
    ],
    "Oem": {}
}

Schema定义：


{
    "definitions": {
        "FullImageUpdate": {
            "patternProperties": {
                "^([a-zA-Z_][a-zA-Z0-9_]*)?@(odata|Redfish|Message|Privileges)\\.[a-zA-Z_][a-zA-Z0-9_.]+$": {
                    "type": [
                        "array",
                        "boolean",
                        "number",
                        "null",
                        "object",
                        "string"
                    ],
                    "description": "This property shall specify a valid odata or Redfish property."
                }
            },
            "type": "object",
            "parameters": {
                "ImageURI": {
                    "requiredParameter": true,
                    "type": "string"
                },
                "TransferProtocol": {
                    "type": "string",
                    "enum": [
                        "HTTPS",
                        "SCP",
                        "SFTP",
                        "CIFS",
                        "NFS"
                    ]
                },
                "ForceUpdate": {
                    "type": "boolean"
                }
            },
            "additionalProperties": false,
            "properties": {
                "title": {
                    "type": "string",
                    "description": "Friendly action name"
                },
                "target": {
                    "type": "string",
                    "format": "uri",
                    "description": "Link to invoke action"
                },
                "@Redfish.ActionInfo": {
                    "description": "The term can be applied to an action to specify a URI to an ActionInfo resource that describes the parameters supported by this instance of the action.",
                    "type": "string",
                    "format": "uri-reference",
                    "readonly": true
                }
            },
            "description": "This action is used to update software components.",
            "longDescription": "This action shall perform an update of installed software component(s) as contained within a package compressed from multiple software image files located at a URI referenced by the ImageURI parameter."

        },
        "{{OemIdentifier}}Actions": {
            "type": "object",
            "patternProperties": {
                "^([a-zA-Z_][a-zA-Z0-9_]*)?@(odata|Redfish|Message|Privileges)\\.[a-zA-Z_][a-zA-Z0-9_.]+$": {
                    "type": [
                        "array",
                        "boolean",
                        "number",
                        "null",
                        "object",
                        "string"
                    ],
                    "description": "This property shall specify a valid odata or Redfish property."
                }
            },
            "additionalProperties": false,
            "properties": {
                "#UpdateService.ActivateBios": {
                    "$ref": "#/definitions/ActivateBios"
                },
                "#UpdateService.StartActivate": {
                    "$ref": "#/definitions/StartActivate"
                },
                "#UpdateService.ParallelUpdate": {
                    "$ref": "#/definitions/ParallelUpdate"
                },
                "#UpdateService.FullImageUpdate": {
                    "$ref": "#/definitions/FullImageUpdate"
                }
            },
            "readonly": true
        }
    }
}

UpdateService下新增OEM接口
URI: https://ip/redfish/v1/UpdateService
操作类型：GET
响应：
{    
    "@odata.context": "/redfish/v1/$metadata#UpdateService.UpdateService",
    "Id": "UpdateService",
    "Actions": {
        "#UpdateService.SimpleUpdate": {
            "target": "/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate",
            "@Redfish.ActionInfo": "/redfish/v1/UpdateService/SimpleUpdateActionInfo"
        },
        "Oem": {
            "Huawei": {
                "#UpdateService.ParallelUpdate": {
                    "target": "/redfish/v1/UpdateService/Actions/Oem/ /{OemIdentifier}//UpdateService.ParallelUpdate",
                    "@Redfish.ActionInfo": "/redfish/v1/UpdateService/ParallelUpdateActionInfo“
                }, 
               "#UpdateService.FullImageUpdate": {
                    "target": "/redfish/v1/UpdateService/Actions/Oem/{OemIdentifier}/UpdateService.FullImageUpdate", 
                   "@Redfish.ActionInfo": "/redfish/v1/UpdateService/Actions/Oem/{OemIdentifier}/FullImageUpdateActionInfo"
                }
            }
        }
    }
}

评审点二：新增OEM IPMI命令用于触发固件整包升级和查询整包升级进度

命令名称： Full Image Update
命令说明： 启动整包升级
命令权限： BasicSetting
是否锁定之后可以访问： 是
是否有敏感数据： 否
命令样式：

请求：ipmitool raw 0x30 <ManufacturerID> <SubCmd> <Length> <Filename>
响应：<ManufacturerID>

命令请求参数：

字节顺序	域取值说明
NetFn	30h
Cmd	93h
1:3	Manufacturer ID，LB Byte first。长度固定 3 个字节，例如，某厂家ID时 2011，对应十六进制为0x0007DB，则字节序为第1个字节为 DBh，第二个字节为 07h，第三个字节为 00h。
4	94h
5	Operation type: AA initiate upgrade
6	Reserved，当前统一填0，为后续可能添加的参数做预留
7	Reserved，当前统一填0，为后续可能添加的参数做预留
8	Length：路径名长度，大小不超过128字节
9:N	Filename：绝对路径名

命令响应参数：

字节顺序	域取值说明
1	Completion Code
2:4	Manufacturer ID，LB Byte first。长度固定 3 个字节，例如，某厂家ID时 2011，对应十六进制为0x0007DB，则字节序为第1个字节为 DBh，第二个字节为 07h，第三个字节为 00h。

命令示例：
样例：开始升级整包/tmp/fullimage.zip

请求：ipmitool raw 0x30 0x93 0xdb 0x07 0x00 0x94 0xaa 0x00 0x00 0x00 0x12 0x2F 0x74 0x6D 0x70 0x2F 0x66 0x75 0x6C 0x6C 0x69 0x6D 0x61 0x67 0x65 0x2E 0x7A 0x69 0x70
响应：0xdb 0x07 0x00

命令名称： Get Full Image Update Status
命令说明： 获取整包升级状态
命令权限： ReadOnly
是否锁定之后可以访问： 是
是否有敏感数据： 否
命令样式：

请求：ipmitool raw 0x30 <ManufacturerID> <SubCmd>
响应：<ManufacturerID> <SubCmd> <Length> <Data>

命令请求参数：

字节顺序	域取值说明
NetFn	30h
Cmd	93h
1:3	Manufacturer ID，LB Byte first。长度固定 3 个字节，例如，某厂家ID时 2011，对应十六进制为0x0007DB，则字节序为第1个字节为 DBh，第二个字节为 07h，第三个字节为 00h。
4	95h
5	Reserved，当前统一填0，为后续可能添加的参数做预留
6	Reserved，当前统一填0，为后续可能添加的参数做预留

命令响应参数：

字节顺序	域取值说明
1	Completion Code
2:4	Manufacturer ID，LB Byte first。长度固定 3 个字节，例如，某厂家ID时 2011，对应十六进制为0x0007DB，则字节序为第1个字节为 DBh，第二个字节为 07h，第三个字节为 00h。
5	Length，返回数据长度
6:N	整包中各固件升级进度和状态，每两个字节描述一个固件，其中进度百分比使用低字节，升级状态码使用高字节的低4bit，高字节的高4bit预留，状态码定义如下： 0：正常 1：升级失败 2：未匹配到具体板卡而未升级如：0x00 0x50固件升级进度为80%，当前状态码为0 0x01 0x00固件升级进度为0%，当前状态码为1

命令示例：
样例1：查询整包升级进度及状态

请求：ipmitool raw 0x30 0x93 0xdb 0x07 0x00 0x95 0x00 0x00
响应：0xdb 0x07 0x00 0x0a 0x00 0x50 0x00 0x53 0x01 0x00 0x00 0x64 0x02 0x00
固件1、2升级到80%，固件3升级失败，固件4升级到100%，固件5未匹配到具体板卡而未升级

评审点三：支持整包升级WEB界面评审

内部图片无法上传，评审时展示

评审点四：新增webrest接口用于触发固件整包升级和查询整包升级进度

说明：WEB进行整包升级需要支持固件包二次选择，整体方案如下：

sequenceDiagram
    participant 用户
    participant web_backend
    participant redfish
    participant firmware_mgmt

    用户->>web_backend: 整包升级
    web_backend->>firmware_mgmt: 整包升级
    firmware_mgmt->>firmware_mgmt: 整包基础格式校验、冲突校验
    firmware_mgmt->>firmware_mgmt: 整包拆解，校验
    firmware_mgmt->>web_backend: 返回整包升级结果
    web_backend->>firmware_mgmt: 获取整包校验结果及详细固件状态
    firmware_mgmt->>web_backend: 返回固件状态

    alt web固件整包升级锁定时间为1min
        用户->>web_backend: Redfish/ipmi整包升级
        web_backend->>firmware_mgmt: 整包升级
        firmware_mgmt->>firmware_mgmt: 整包基础格式校验、冲突校验
        firmware_mgmt->>web_backend: 升级失败
        web_backend->>用户: 升级失败
    end

    alt 其他接口是否调用整包升级
        opt Redfish接口调用整包升级
            用户->>redfish: 整包升级
            redfish->>firmware_mgmt: 整包升级
            firmware_mgmt->>firmware_mgmt: 整包基础格式校验、冲突校验
            firmware_mgmt->>firmware_mgmt: 删除之前未二次确认的整包升级任务
            firmware_mgmt->>redfish: 返回任务进度
            redfish->>用户: 返回任务进度
            web_backend->>firmware_mgmt: 获取整包校验结果及详细固件状态
            firmware_mgmt->>web_backend: 返回错误
        end
        opt 其他接口未调用整包升级
            用户->>web_backend: 二次确认下发升级请求
            web_backend->>firmware_mgmt: 二次确认下发升级请求
            firmware_mgmt->>web_backend: 开始进行固件升级
            web_backend->>firmware_mgmt: 获取整包升级各固件进度和状态
            firmware_mgmt->>web_backend: 返回各固件的升级进度和状态
            web_backend->>用户: 返回各固件的升级进度和状态
        end
    end

基于以上方案，需要如下webrest接口：

整包上传接口

uri：/UI/Rest/BMCSettings/UpdateService/Actions/UpdateService.FullImageUnpack
变化类型：新增uri
操作类型： POST
应用场景：整包解包
请求参数：见下表

属性名称	取值类型	说明	取值范围	默认值	是否允许为null	约束
FilePath	string	升级包所在路径	-	否	无

响应参数：见下表
操作权限：BasicSetting
样例展示：

URL: /UI/Rest/BMCSettings/UpdateService/Actions/UpdateService.FullImageUnpack
操作类型：POST
请求参数：
{
    "FilePath": "/tmp/fullimage.zip",
}
响应消息体举例：
{
    "url":"/UI/Rest/Task/1"
}

并行升级接口新增参数标识整包模式升级和选择的固件包

uri：/UI/Rest/BMCSettings/UpdateService/ParallelUpdate
变化类型：新增请求参数
操作类型： POST
应用场景：整包升级下发二次确认的升级请求
请求参数：见下表

属性名称	取值类型	说明	取值范围	默认值	是否允许为null	约束
ImageType	string	升级包所在路径	“SingleImage” “FullImage”	“SingleImage”	是
FullImageNames	string数组	整包升级各固件名称	-	-	是（ImageType为FullImage时不允许为null）

获取并行升级各固件信息

uri：/UI/Rest/BMCSettings/UpdateService/UpdateProgress
变化类型：新增uri
操作类型： GET
应用场景：获取整包升级各固件名称，升级进度等信息
请求参数：见下表

属性名称	取值类型	说明	取值范围	默认值	是否允许为null	约束
UpgradeMode	string	“Serial”（历史已有） “Parallel”（历史已有） “FullImageUnpacking”（新增）	表明当前升级模式：串行升级中、并行升级中、整包解包中	null	是

评审点五：支持整包升级资源协作接口评审（`bmc.kepler.UpdateService`接口新增方法）

方法评审点

方法名称	请求签名	请求参数描述	响应签名	响应参数描述	方法描述	访问权限
FullImageUnpack	s	整包路径	u	任务id	将整包进行解析、校验	BasicSetting

评审结论

通过，具体结论如下：
1. 同意新增Redfish OEM接口/redfish/v1/UpdateService/Actions/Oem/{OemIdentifier}/UpdateService.FullImageUpdate用于触发固件整包升级，接口操作类型为 POST，操作权限为 BasicSetting；
2. 同意新增IPMI命令用于触发整包升级和查询整包升级各固件的进度和状态，具体命令字如下：
触发整包升级：netfn=30h，cmd=93h，subcmd=94h
查询整包升级各固件的进度和状态：netfn=30h，cmd=93h，subcmd=95h
3. 同意WEB界面整包升级接口设计，通过升级文件格式来判断是否需要弹出二次选择界面；
4. 同意新增webrest接口/UI/Rest/BMCSettings/UpdateService/Actions/UpdateService.FullImageUnpack用于整包固件解包，接口操作类型为 POST，操作权限为 BasicSetting；
5. 同意bmc.kepler.UpdateService接口新增方法FullImageUnpack用于整包固件解包，请求参数为FilePath，代表整包路径，响应参数为TaskId，操作权限为 BasicSetting；

话题		回复	浏览量
【已评审】支持并行升级和统一生效redfish接口评审 Interface评审方案评审	3	148	2025 年6 月 7 日
【已评审】并行升级新增webreset接口评审 Interface评审方案评审	1	146	2025 年6 月 26 日
【已评审】Redfish并行升级接口支持指定固件升级 Interface评审	1	52	2026 年4 月 23 日
【待评审】新增本地固件仓Redfish接口、Web界面、UIRest接口评审 Interface评审	0	33	2026 年4 月 7 日
【已评审】并行升级新增资源协作接口及错误引擎 Interface评审方案评审	4	123	2025 年5 月 17 日