文档中心
白牌包适配与制作指南
更新时间： 2025/11/28
在Gitcode上查看源码

本指南旨在指导如何进行白牌包配置和构建。

白牌包介绍 ​

白牌包本质上就是一个hpm包，该hpm包中只包含白牌内容和信息，通过固件升级的方式来实现定制化能力，可定制范围包括：图片定制、网页风格定制、配置定制、SSL证书定制。 具体支持的定制项如下表所示：

序号定制类别定制项文件属性名
1图片定制浏览ICOfavicon.ico/
2图片定制二维码code1.png/
3图片定制登录界面背景login.png/
4图片定制登录界面图标login_logo.png/
5图片定制主界面机型展示图img_01.png img_02.png img_03.png/
6图片定制主界面左上角图片header_logo.png/
7风格定制主界面风格style_config.jsonpageStyle
8配置定制产品联系人web_custom.xmlsysContact
9配置定制默认安全公告web_custom.xmldBannerContent
10配置定制预置证书Common Nameweb_custom.xmlPreSSLSeverCommonName
11配置定制预置证书Organization Nameweb_custom.xmlPreSSLSeverOrgName
12配置定制预置证书Countryweb_custom.xmlPreSSLSeverCountry
13配置定制官网web_custom.xmlOfficalWeb
14配置定制版权信息web_custom.xmlCopyright
15配置定制技术支持网址web_custom.xmlSupportWeb
16配置定制邮箱web_custom.xmlEmail
17配置定制电话web_custom.xmlPhone
18配置定制独立KVMweb_custom.xmlDownloadKVMLink
19配置定制二维码显示标志位（是否显示）web_custom.xmlDocSupportFlag
20配置定制BMC软件名称web_custom.xmlSoftwareName
21配置定制告警、事件描述web_custom.xmlCustomAlarmName
22配置定制redfish OEM厂商名web_custom.xmlCustomManufacturer
23配置定制BMC主机名称web_custom.xmlHostName
24配置定制客户名称（用于生效指定客户定制的特性）web_custom.xmlCustomer
24证书定制SSL证书（用于生效指定客户定制的SSL证书）customize.pfx/

如何定制白牌包 ​

新建代码仓存放白牌定制文件 ​

新建白牌文件存放的代码仓，或者在已有的代码仓创建新的文件夹存放白牌定制文件。

在正式制作白牌包前，需要做好定制文件准备。 白牌定制文件主要包括主界面风格描述文件、各种定制图片、配置文件web_custom.xml以及文件清单配置filelist.conf。

  • 定制图片名称需要与上述表格中图片定制文件名保持一致。
  • 主界面风格支持定制风格为beautiful、simple、standard，需要新建style_config.json文件

文件配置示例如下：

新建style_config.json文件配置如下 ​

json
{
  "pageStyle": "beautiful"
}

配置filelist.conf ​

filelist.conf用于描述白牌配置文件项，具体配置参考如下示例：

shell
[Basic]
Version=2.00

[Filelist]
FileNum=11

[File0]
Name=code1.png
Path=/data/opt/pme/web/htdocs/theme/custom/img

[File1]
Name=favicon.ico
Path=/data/opt/pme/web/htdocs

[File2]
Name=web_custom.xml
Path=/data/opt/pme/web/conf

[File3]
Name=header_logo.png
Path=/data/opt/pme/web/custom

[File4]
Name=login.png
Path=/data/opt/pme/web/custom

[File5]
Name=login_logo.png
Path=/data/opt/pme/web/custom

[File6]
Name=img_01.png
Path=/data/opt/pme/web/custom

[File7]
Name=img_02.png
Path=/data/opt/pme/web/custom

[File8]
Name=img_03.png
Path=/data/opt/pme/web/custom

[File9]
Name=style_config.json
Path=/data/opt/pme/web/htdocs

[File10]
Name=customize.pfx
Path=/data/opt/bmc/conf
  • [Basic]：描述filelist.conf文件版本
  • [Filelist]：描述配置文件个数
  • [Filex]：描述配置文件名及文件路径

其中FileNum的值需要与下列配置File的个数保持一致，文件名称和文件路径都是一一对应的，不能随意配对，customize.pfx的生成方法联系产品接口人获取，开发者可根据自身需要选择定制。

配置web_custom.xml ​

web_custom.xml用于承载属性配置，具体配置参考如下示例：

xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- 描述：目前官网、版权信息、独立KVM下载链接信息、文档二维码显示标志位在web中有使用 -->
<CUSTOM_CONFIG>
    <!-- 系统联系人(示例：VALUE="https://openubmc.com") -->
    <SysContact VALUE="CustomSysContact" />
    <!-- SSL证书预置信息，当前安装的SSL证书的签发者信息和预置信息一致时，认为当前SSL证书是预置证书，web会提醒用户安装新证书 -->
    <PreSSLSeverCommonName VALUE="CustomCommonName"/>
    <PreSSLSeverOrgName VALUE="CustomOrgName"/>
    <PreSSLSeverCountry VALUE="Country"/>
    <!-- 官方网站 -->
    <OfficalWeb VALUE="CustomOfficalWeb"/>
    <!-- 版权 -->
    <Copyright VALUE="CustomCopyright"/>
    <!-- 技术支持网站 -->
    <SupportWeb VALUE="CustomSupportWeb"/>
    <!-- 邮件 -->
    <Email VALUE="CustomEmail"/>
    <!-- 电话 -->
    <Phone VALUE="CustomPhone"/>
    <!-- 独立KVM客户端下载链接 -->
    <DownloadKVMLink VALUE="CustomDownloadKVMLink"/>
    <!-- 是否支持显示二维码（示例：VALUE="1"， 值为"0"或"1"，其他值默认为"0"，表示不显示） -->
    <DocSupportFlag VALUE="CustomDocSupportFlag"/>
    <!-- 软件名称，用于自定义日志BMC名称和CLP提示符 -->
    <SoftwareName VALUE="openUBMC"/>
    <!-- 主机名 -->
    <HostName VALUE="CustomHostName"/>
    <!-- 安全公告 -->
    <dBannerContent VALUE="CustomdBannerContent"/>
    <!-- 客户名称 -->
    <Customer VALUE="CustomerName"/>
</CUSTOM_CONFIG>

开发者可根据自身需要，选择合适的定制项放入web_custom.xml中，其中VALUE的内容需要替换为定制内容，不需要的定制项可以删除

配置manifest仓中对应产品manifest.yml ​

注意：本节中 manifest.yml 的 files 配置需要与前面 filelist.conf 中的文件保持一致，FileNum 的值必须等于 files 中定制文件的个数。

白牌定制相关文件准备完毕之后，开始构建打包环节，配置步骤如下：

  1. 打开manifest/build/product/BMC/产品名/manifest.yml
  2. 确定构建编码，如WBD
  3. 确定包名package_name
  4. 确定构建类型
  5. 配置白牌包相关配置

构建示例：

yml
manufacture:
    # 构建编码
    WBD:
        # package_name为白牌包存放路径与白牌包名称
        package_name: wbd/wbd_output.zip
        # 构建类型，可选值参考bingo构建类型
        build_type: release
        # 白牌包相关配置
        wbd_hpms:
            # repo为存放白牌包定制文件的仓库地址，需要填写https下载的地址
            - repo: https://test.git
              # tag为存放定制文件的分支tag号
              tag: 0.0.0
              files:
                # path为白牌定制文件存放路径，但是dst路径不可修改，均为"wbd_up_file/文件名"的格式，如下示例
                - file: {path}/favicon.ico
                  dst: wbd_up_file/favicon.ico
                - file: {path}/login_logo.png
                  dst: wbd_up_file/login_logo.png
                - file: {path}/header_logo.png
                  dst: wbd_up_file/header_logo.png
                - file: {path}/filelist.conf
                  dst: wbd_up_file/filelist.conf
                - file: {path}/web_custom.xml
                  dst: wbd_up_file/web_custom.xml
                # 下列文件都是制作白牌包必须文件，路径固定，不可删除
                - file: /usr/share/bmcgo/wbd-packet/beforeaction.sh
                - file: /usr/share/bmcgo/wbd-packet/afteraction.sh
                  dst: afteraction.sh
                - file: /usr/share/bmcgo/wbd-packet/CfgFileList.conf
                - file: /usr/share/bmcgo/wbd-packet/firstboot.sh
                - file: /usr/share/bmcgo/wbd-packet/hpm_wbd.config
                - file: /usr/share/bmcgo/wbd-packet/packetwbd.sh
                - file: /usr/share/bmcgo/wbd-packet/update.cfg
        # dst为最后制作出来的白牌包名称
        files:
          - file: ${work_out}/wbd_hpm1.hpm
            dst: WBD-image.hpm
            verify:
              - pss

注意：files中定制文件需要和filelist.conf中文件个数保持一致，不一致则会导致升级白牌包失败，{path}就是对应代码仓中白牌文件存放路径

在manifest仓build目录下执行白牌构建命令 ​

进入manifest/build目录下，执行命令：

bmcgo publish -bt release -z WBD -b openUBMC -r openubmc_dev，其中-z 参数为白牌包构建编码，-b 参数为机型, -bt 构建类型，-r conan远程仓库

社区版本只有bingo工具，无法编译白牌包，白牌包只能用bmcgo工具编译，bmcgo工具需要联系产品接口人获取

取包地址：manifest/output/packet/wbd/wbd_output.zip

升级白牌包 ​

进入openUBMC首页，进入固件升级->固件更新->升级文件，若白牌包中配置了Customer字段，升级完成后会自动重启生效。 白牌包中的web_custom.xml配置项查看，升级完成重启起来后，进入openUBMC首页，进入配置更新->配置导出，查看product_mgmt组件下的相关配置是否达到预期。

如何定制清白牌包 ​

定制白牌包后，如果需要恢复到原来的配置，需要升级清白牌包。实际上，清白牌包也是一个白牌包，只是里面的配置为默认配置，需要构建一个默认配置的白牌包。

  1. 配置定制类只需修改web_custom.xml中定制项为想要的默认值即可
  2. 风格定制类将style_config.json文件置为空对象即可
  3. 图片定制类若恢复默认，需要配置filelist.conf，把原来的Name配置为CLEAR_ALL，然后创建一个空文件，命名为CLEAR_ALL即可。注意在manifest配置白牌包时，也需要加上CLEAR_ALL文件的配置。

filelist.conf示例：

shell
# 需要恢复默认的配置，Name更改为CLEAR_ALL
[Basic]
Version=2.02

[Filelist]
FileNum=9

[File0]
Name=code1.png
Path=/data/opt/pme/web/htdocs/theme/custom/img

[File1]
Name=favicon.ico
Path=/data/opt/pme/web/htdocs

[File2]
Name=web_custom.xml
Path=/data/opt/pme/web/conf

[File3]
Name=CLEAR_ALL
Path=/data/opt/pme/web/custom

[File4]
Name=CLEAR_ALL
Path=/data/opt/pme/web/custom

[File5]
Name=CLEAR_ALL
Path=/data/opt/pme/web/custom

[File6]
Name=CLEAR_ALL
Path=/data/opt/pme/web/custom

[File7]
Name=img_02.png
Path=/data/opt/pme/web/custom

[File8]
Name=img_03.png
Path=/data/opt/pme/web/custom

manifest.yml示例：

yml
manufacture:
    # 构建编码
    WBD:
        # package_name为白牌包存放路径与白牌包名称
        package_name: wbd/wbd_output.zip
        # 构建类型，可选值参考bingo构建类型
        build_type: release
        # 白牌包相关配置
        wbd_hpms:
            # repo为存放白牌包定制文件的仓库地址，需要填写https下载的地址
            - repo: https://test.git
              # tag为存放定制文件的分支tag号
              tag: 0.0.0
              files:
                # path为白牌定制文件存放路径，但是dst路径不可修改，均为"wbd_up_file/文件名"的格式，如下示例
                - file: {path}/CLEAR_ALL
                  dst: wbd_up_file/CLEAR_ALL
                - file: {path}/style_config.json
                  dst: wbd_up_file/style_config.json
                - file: {path}/filelist.conf
                  dst: wbd_up_file/filelist.conf
                - file: {path}/web_custom.xml
                  dst: wbd_up_file/web_custom.xml
                # 下列文件都是制作白牌包必须文件，路径固定，不可删除
                - file: /usr/share/bmcgo/wbd-packet/beforeaction.sh
                - file: /usr/share/bmcgo/wbd-packet/afteraction.sh
                  dst: afteraction.sh
                - file: /usr/share/bmcgo/wbd-packet/CfgFileList.conf
                - file: /usr/share/bmcgo/wbd-packet/firstboot.sh
                - file: /usr/share/bmcgo/wbd-packet/hpm_wbd.config
                - file: /usr/share/bmcgo/wbd-packet/packetwbd.sh
                - file: /usr/share/bmcgo/wbd-packet/update.cfg
        # dst为最后制作出来的白牌包名称
        files:
          - file: ${work_out}/wbd_hpm1.hpm
            dst: WBD-image.hpm
            verify:
              - pss
上一篇白牌包定制指南
下一篇组件配置导入导出指南