manifest 配置指南

版本信息

项目	内容
组件版本	26.09
首发版本	26.09
文档作者	马思雨
最后更新	2026-07-23

1. 组件概述

1.1 组件简介

manifest 是 openUBMC 的产品集成配置仓，不含组件业务代码，但包含产品层定制代码（build/customization/）和声明式配置（YAML），是构建系统的唯一入口。

1.2 解决什么问题

openUBMC 由多个组件构成，组件之间存在层级依赖关系，每种芯片平台需要不同的工具链、bootloader 和组件组合。开发者面对的核心挑战是：如何将这套相互依赖的组件体系组装为一个可刷机的完整固件包，并保证每次构建结果一致。manifest 解决的就是这个产品集成问题——它作为构建系统的唯一入口，通过声明式配置和产品层裁剪代码，将分散的组件、SDK、签名证书统一编排为可交付的固件包。

1.3 核心功能

环境初始化：python3 init.py 一键安装 bingo、Conan、Node.js、SDK 等全部构建依赖
版本锁定：bingo lock -c / bingo lock -u 生成和维护 openubmc.lock，锁定组件精确版本和 revision
产品构建：bingo build -t personal -b <产品名> 读取 manifest.yml + lockfile，完成依赖解析、rootfs 组装到 HPM 打包全流程
rootfs 裁剪：customization/*.py 脚本对组装后的 rootfs 进行机型差异化裁剪（删除 systemd unit、修改配置文件等）
固件签名：base.signature 配置 RSA/SM2 密钥标识和 CA 证书链，对 rootfs 镜像进行 CMS 数字签名
多场景交付：tosupporte 配置块编排正式版、过站版、QEMU 版、eMMC 版等多种交付形态
Docker 镜像构建：python3 build_image.py 构建 Docker 开发镜像，安全注入 Conan 凭据

1.4 关键术语表

术语	解释
manifest	产品集成配置仓（本仓库）；也指每个产品目录下的 `manifest.yml` 配置文件
bingo	openUBMC 构建编排工具（`openubmc-bingo` Python 包），读取 manifest 配置并执行构建全流程
HPM	Hardware Platform Management Package — BMC 固件升级包格式，含 rootfs 镜像、bootloader、签名文件
GPP	General Purpose Package — 通用打包格式，比 HPM 更完整，含 eMMC 镜像等
CMT	Customer Management Tool — 客户交付工具包，即 `tosupporte` 产出的 zip 包（含 HPM + version.xml + License）
lockfile	`openubmc.lock` — 组件版本锁定文件，记录每个 Conan 包的精确版本号、revision hash 和依赖关系图
Conan	C/C++ 包管理器（Conan 2.x），openUBMC 使用它管理组件的二进制包分发和依赖解析
profile	Conan profile — 编译配置文件（`profile.dt.ini`、`profile_oee.ini`），定义 host/build 架构、编译器、sysroot
revision	Conan recipe revision — 包的构建修订标识（hash），同一版本号可有多个 revision，lockfile 通过 revision 保证精确匹配
RTOS	Real-Time Operating System — Hi1711/1712 芯片使用的实时操作系统
OEE	OpenEuler Embedded — AST2600 芯片使用的 openEuler 嵌入式 Linux 系统
SDK	RTOS 产品使用 `ibmc_sdk`（Conan）+ `openubmc_sdk`（Conan）+ `bmc_sdk_download`（平台整包）；OEE 产品使用 `ibmc_sdk`（Conan）+ `bmc_sdk_download`（平台整包）+ `packages_download` + `tools_install`
ibmc_sdk	平台 SDK 的 Conan 包名，提供 bootloader、RTOS 编译器、内核镜像等底层资源
openubmc_sdk	构建 SDK 的 Conan 包名，提供 bingo 构建运行环境（LuaJIT、Skynet、Conan profile 模板）
board_name	产品板名，`bingo build -b` 的参数值，也出现在 `vpd` 组件的 `board_name` 选项中
board_path	产品板级配置临时目录（`temp/board_<产品名>/`），存放经签名复制和定制化处理后的文件
customization	产品 rootfs 定裁剪脚本（Python），继承 `BaseCustomization` 类，实现 `rootfs_cust` 等方法
CMS	Cryptographic Message Syntax — 固件签名标准（RFC 5652），产出 `rootfs_BMC.img.cms`
CRL	Certificate Revocation List — 证书吊销列表，固件升级时校验签名证书是否仍有效
ICA	Intermediate Certificate Authority — 中间证书机构，签发终端签名证书的 CA
WBD	White-Brand Design — 白牌定制升级包，允许 OEM 客户自定义 WebUI 品牌
eMMC	embedded Multi-Media Card — AST2600 OEE 产品的固件存储介质
GPT	GUID Partition Table — eMMC 分区表格式，OEE 产品通过 `emmc_layout.yml` 定义分区布局
ToSupportE	固件交付包旧称，现通过 `tosupporte` 配置块定义不同交付场景

1.5 外部交互边界

交互对象	方向	内容	协议/格式
Conan 远程仓库 (`conan.openubmc.cn`)	manifest → 远程	拉取组件二进制包、SDK Conan 包；推送本地构建的组件包	Conan 2 API、HTTPS
APT 仓库 (`openubmc-apt-repo.obs`)	manifest → 远程	安装 bingo、bmc-studio、openubmc-qemu deb 包	APT/dpkg、HTTPS
GitCode (`gitcode.com`)	manifest → 远程	克隆组件源码（`bingo fetch` 或 `git clone`）；推送 PR	Git、HTTPS
证书服务 (`openubmc-certs.obs`)	manifest → 远程	下载 RSA/SM2 ICA 证书和 CRL 吊销列表	HTTPS、PEM/CRL
SDK 包仓库 (`repo.openubmc.cn`)	manifest → 远程	下载 bmc_sdk.tar.gz、oee_sdk.tar.gz	HTTPS、tar.gz
bingo 构建工具	manifest → bingo	bingo 读取 manifest.yml、lockfile、customization 脚本执行构建	YAML/Python
Conan 本地缓存 (`~/.conan2/p/`)	manifest → 本地	组件包二进制解压到本地缓存目录，构建时从中复制文件	Conan cache
构建产物 (`output/`)	bingo → manifest	最终产出的 HPM 包写入 output 目录	HPM

1.6 支持的产品列表

产品名	芯片类型	系统架构	说明
`openUBMC`	Hi1711	RTOS	默认社区产品，基于 Hi1711 芯片的 RTOS 系统
`openUBMC_1712`	Hi1712	RTOS	基于 Hi1712 芯片的 RTOS 系统，支持 SM2 国密签名
`openUBMC_ast2600`	AST2600	OEE (OpenEuler Embedded)	基于 AST2600 芯片的 OEE 系统，使用 eMMC 存储

2. 新增机型配置指南

新增机型是 manifest 最核心的扩展场景。manifest.yml 是 bingo 构建的唯一配置入口，以下按步骤详解每个配置项的含义和填写方式，并区分 RTOS（Hi1711/1712）和 OEE（AST2600）两种产品类型的差异。

2.1 步骤一：创建产品目录和辅助文件

bash

cd /home/workspace/manifest
mkdir -p build/product/BMC/<新产品名>

# 从现有产品复制辅助配置文件骨架
cp build/product/BMC/openUBMC/version.xml build/product/BMC/<新产品名>/version.xml
cp build/product/BMC/openUBMC/permissions.ini build/product/BMC/<新产品名>/permissions.ini
cp build/product/BMC/openUBMC/archive.ini build/product/BMC/<新产品名>/archive.ini
cp build/product/BMC/openUBMC/update_ext4.cfg build/product/BMC/<新产品名>/update_ext4.cfg

# 复制 rootfs 目录
mkdir -p build/product/BMC/<新产品名>/rootfs
cp -r build/product/BMC/openUBMC/rootfs/* build/product/BMC/<新产品名>/rootfs/

# 复制 wbd_up_file（白牌定制目录）
cp -r build/product/BMC/openUBMC/wbd_up_file build/product/BMC/<新产品名>/wbd_up_file

# OEE 产品额外需要：
cp build/product/BMC/openUBMC_ast2600/emmc_layout.yml build/product/BMC/<新产品名>/emmc_layout.yml
cp build/product/BMC/openUBMC_ast2600/hpm_layout.yml build/product/BMC/<新产品名>/hpm_layout.yml

需要修改 version.xml 中的 SupportModel、SupportModelUID、PackageName 为新机型的名称。

2.2 步骤二：编写 manifest.yml — 全配置详解

manifest.yml 是 bingo 构建读取的唯一配置文件。以下逐块说明每个配置项，并标注 RTOS/OEE 差异。

2.2.1 `schema`

yaml

schema: /usr/share/bingo/schema/manifest.schema.json

固定值，指定 bingo 的 JSON Schema 校验文件路径，构建时据此校验 YAML 格式合法性。所有产品必须填写，不可修改。

2.2.2 `platform` — 平台 SDK 配置

platform 定义底层芯片 SDK 来源（bootloader、编译器、内核镜像），是所有产品必须配置的核心字段。

yaml

platform:
  conan: "ibmc_sdk/5.14.00.01.b001@openubmc/stable"   # 平台 SDK Conan 包引用
  options:
    rtos_version: rtos_v2       # RTOS 版本标识
    enable_haf: false            # 是否使能 HAF 高可用框架
  package: community_unsign_webvnc_1711   # 平台包名

字段	说明	RTOS 产品取值	OEE 产品取值
`platform.conan`	平台 SDK Conan 包引用（`包名/版本@用户/通道`），提供 RTOS 编译器、bootloader 二进制、内核镜像	`ibmc_sdk/5.14.00.01.b001@openubmc/stable`	同左（OEE 也用 `ibmc_sdk`）
`platform.options.rtos_version`	RTOS 版本标识，决定 SDK 内部选择哪套编译器和内核配置	`rtos_v2`（1711）、`rtos_v2_1712`（1712）	`oee_ast2600`
`platform.options.enable_haf`	是否使能 HAF（High Availability Framework）高可用框架	`true` / `false`	`false`
`platform.package`	平台包名，`ibmc_sdk` 内部的选择器，决定提取哪组 bootloader 和签名工具	见下表	见下表

platform.package 与产品对应关系：

package 值	适用芯片	签名方式	特殊能力
`community_unsign_webvnc_1711`	Hi1711	不签名	WebVNC
`community_sign_webvnc_1711`	Hi1711	RSA4096 签名	WebVNC
`community_unsign_webvnc_1712`	Hi1712	不签名	WebVNC + SM2
`community_ast2600`	AST2600	不签名	OEE
`qemu_1711`	Hi1711	不签名	QEMU 仿真

2.2.3 SDK 拉取方式

SDK 拉取方式因产品类型而异。平台整包（bmc_sdk_download）是 ibmc_sdk>=5.14 起推荐的新方式，将平台组件预先打包为 tar 包（含 Conan 缓存合集和整包 manifest.yml 配置文件），相比传统的逐个引用 Conan 包方式，简化了产品配置、避免组件版本冲突、缩短依赖下载时间。

字段	说明	RTOS 产品 (1711/1712)	OEE 产品 (AST2600)
`openubmc_sdk`	上层构建 SDK（LuaJIT、Skynet、Conan profile 模板）	必须配置	不需要（注释掉）
`bmc_sdk_download`	平台整包下载（推荐方式），下载包含 Conan 缓存合集 + 整包配置的 tar 包，构建时自动解压到 `~/bmc_sdk_download` 并通过 `platform.package` 引用对应整包配置	必须配置（`bmc_sdk.tar.gz` / `bmc_sdk_1712.tar.gz`）	必须配置（`oee_sdk.zip`）
`packages_download`	OEE 交叉编译工具链 + openEuler SDK 整包下载	不需要	必须配置

RTOS 产品示例（1711）：

yaml

bmc_sdk_download:
  url: https://repo.openubmc.cn/26.06/sdk/bmc_sdk.tar.gz
  sha256: 1a83c0aad37377471e50901f0a54c6d728365a963f7bcf6343bb8da395fa78ef
platform:
  conan: "ibmc_sdk/5.14.00.01.b001@openubmc/stable"
  options:
    rtos_version: rtos_v2
    enable_haf: false
  package: community_unsign_webvnc_1711
openubmc_sdk:
  conan: "openubmc_sdk/latest@openubmc/stable"

OEE 产品示例（AST2600）：

yaml

# openubmc_sdk:
#   conan: "openubmc_sdk/latest@openubmc/stable"     # OEE 不需要，注释掉

bmc_sdk_download:
  url: "https://dailybuild.openubmc.cn/oee_sdk/oee_sdk_20260720_095918.zip"
  sha256: "11d64d14fe7892f0a32f5d9216fb35ed5d005ea90836c8df13baf1ffe67122d6"
platform:
  conan: "ibmc_sdk/5.14.00.01.b001@openubmc/stable"
  options:
    rtos_version: "oee_ast2600"
  package: "community_ast2600"

packages_download:
  url: "https://repo.openubmc.cn/26.06_test/oee_sdk/iBMC500_5.14.0.1_oee.tar.gz"
  sha256: "17f7a149c62d750e0e2f428ef62d9656bb9096231ca66df57dd0d70aa96d9637"

与 platform 的关系：platform（ibmc_sdk）提供底层芯片 SDK（bootloader、内核、RTOS 编译器），bmc_sdk_download 提供平台整包（Conan 缓存合集 + 整包配置文件，通过 platform.package 引用），openubmc_sdk 提供上层构建 SDK（bingo 构建运行环境、LuaJIT、Conan profile 模板），packages_download 提供 OEE 交叉编译工具链。三者协同工作：platform 决定选用哪组 bootloader 和签名工具，bmc_sdk_download 提供该组对应的完整组件依赖缓存，openubmc_sdk 提供构建运行环境。

平台整包的三种引用方式：

方式	适用场景	配置
整包文件下载（推荐）	社区统一发布的整包	配置 `bmc_sdk_download`（url + sha256）+ `platform.package`
本地整包目录	本地开发或自定义整包联调	配置 `platform.package` + 构建参数 `--debug_platform_path=<整包路径>`
Conan 包引用（传统方式）	旧版 SDK（ibmc_sdk<5.14），逐个引用组件	仅配置 `platform.conan`，不配置 `bmc_sdk_download` 和 `platform.package`

整包方式下，产品 manifest.yml 中不应再单独定制整包内部组件的 options（如 firmware_mgmt 属于整包内部组件，需删除其 options），否则会导致整包缓存失效。

2.2.4 `tools_install` — OEE 工具链安装策略（仅 OEE 产品）

OEE 产品需要额外的工具链安装配置，RTOS 产品不需要（使用 Conan 自动安装）。

yaml

tools_install:
  build_tool:
    label: "local"
    work_path: "/root/oee_compiler"
    verify: true
    install:
      mode: "oee"          # 执行 openEuler SDK 自解压安装脚本
      path: "/opt/oee-sdk"
  sdk_tool:
    label: "local"
    work_path: "/root/oee_sdk"
    verify: true
    install:
      mode: "default"      # 直接复制
      path: "${sdk_path}"

字段	说明
`build_tool.label`	来源标识：`local`（本地目录）或 `remote`（远程下载）
`build_tool.work_path`	本地工具链文件所在目录
`build_tool.verify`	是否进行 SHA256 校验
`build_tool.install.mode`	安装模式：`oee` = 执行 openEuler SDK 自解压安装脚本；`default` = 直接复制
`build_tool.install.path`	安装目标路径
`sdk_tool.install.mode`	SDK 工具安装模式（`default` = 直接复制）

2.2.5 `base` — 产品基础配置

yaml

base:
  version: "26.09.00.01"
  customization: "customization/prototype.py"
  dependency_buildtools: dependency/dependency_buildtools.xml
  signature:
    files:
      - file: ${product}/ca/rootca.crl
        dst: cms.crl
      - file: ${product}/ca/rootca.der
        dst: rootca.der
      - file: ${product}/ca/rsa_rootca.crt
        dst: rootca.crt
        condition:
          signature_type: rsa4096
    rsa_sign_key: UBMCCMSEE
    rsa_ts_key: UBMCTS
    rsa_rootca_crl_download:
      url: https://openubmc-certs.obs.cn-north-4.myhuaweicloud.com/bb7d00fb-5ca5-476b-bc1a-258105fa0b8f.crl
    rsa_ica_crl_download:
      url: https://openubmc-certs.obs.cn-north-4.myhuaweicloud.com/4277907e-3a28-41e9-b58d-8f54f741dedf.crl
    rsa_ica_download:
      url: https://openubmc-certs.obs.cn-north-4.myhuaweicloud.com/openUBMC-RSA-PSS-Integrity-CA-1_certificate.pem
  profile: "profile_oee.ini"        # 仅 OEE
  skip_linx: true                   # 仅 1712

字段	说明	RTOS 产品取值	OEE 产品取值
`base.version`	四段式版本号 `XX.YY.ZZ.WW`（每段 2 字节、范围 00-99）。变更时需同步修改 `version.json` 的 `BMCSDKVersion` 和 `openUBMCVersion`	如 `"26.09.00.01"`	同左
`base.customization`	rootfs 定制裁剪脚本路径（相对于 `build/`），脚本需继承 `BaseCustomization`（见 2.3 步骤三）	`"customization/prototype.py"` 或自定义脚本	`"customization/oee_ast2600_customize.py"` 或自定义脚本
`base.dependency_buildtools`	构建工具依赖定义 XML 文件路径	`"dependency/dependency_buildtools.xml"`	同左
`base.profile`	Conan profile 文件名	不指定	`"profile_oee.ini"`
`base.skip_linx`	是否跳过 LinX 构建	仅 1712 需 `true`	不指定

签名配置详解：

base.signature 配置固件 CMS 数字签名。签名文件会被复制到 board_path 目录，供签名工具读取。

字段	说明	RTOS 产品取值	OEE 产品取值
`signature.files[].file`	源文件路径，支持 `${product}`、`${board_path}` 变量	见下表	见下表
`signature.files[].dst`	目标文件名（复制到 `board_path` 后的文件名）	—	—
`signature.files[].condition.signature_type`	签名类型条件，匹配时才复制	`rsa4096` / `sm2`	不使用
`rsa_sign_key`	RSA CMS 签名密钥标识	如 `UBMCCMSEE`	不使用
`rsa_ts_key`	RSA TSA 时间戳密钥标识	如 `UBMCTS`	不使用
`rsa_rootca_crl_download.url`	RSA RootCA CRL 下载地址	HTTPS URL	不使用
`rsa_ica_crl_download.url`	RSA ICA CRL 下载地址	HTTPS URL	不使用
`rsa_ica_download.url`	RSA ICA 证书下载地址	HTTPS URL	不使用
`sm2_sign_key`	SM2 签名密钥标识	仅 1712：如 `testsm2ee`	不使用
`sm2_ts_key`	SM2 时间戳密钥标识	仅 1712：如 `testsm2tsa`	不使用
`sm2_crl_download.url`	SM2 CA CRL 下载地址	仅 1712	不使用
`sm2_ica_download.url`	SM2 ICA 证书下载地址	仅 1712	不使用

签名文件作用：

文件	dst 名称	说明	RTOS/OEE
`rootca.crl`	`cms.crl`	证书吊销列表（CRL），固件升级时验证签名证书是否已被吊销	所有产品
`rootca.der`	`rootca.der`	DER 格式 RootCA 根证书，验证固件签名信任链	所有产品
`rsa_rootca.crt`	`rootca.crt`	PEM 格式 RSA RootCA（`signature_type=rsa4096` 时使用）	RTOS 产品
`sm2_rootca.crt`	`rootca.crt`	PEM 格式 SM2 RootCA（`signature_type=sm2` 时使用，覆盖 rsa_rootca.crt 的 dst）	仅 1712

签名证书生成与签名服务器：

固件签名所需的证书链和签名服务器参考 bingo 仓库的 demo 目录（bingo/demo/），包含两类签名方案：

方案	目录	说明
CMS 签名	`bingo/demo/cms_sign/`	生成 RSA4096 证书链（RootCA → 签名证书 → TSA 时间戳证书）和 CRL，并提供 Flask 签名服务器。依次执行 `1_create_ca.sh` → `2_create_sign_ca.sh` → `3_create_crl.sh` → `4_create_sign_ts.sh` → `5_crypto_cert.sh`
ECC 签名	`bingo/demo/ecc_sign/`	生成 ECC 密钥对（device_desc_pubkey.bin + private_key.pem），并提供 HTTP 签名服务器。执行 `1_create_sign_ecc.sh`

CMS 签名服务器启动方式：

bash

# 仅供本地 demo 测试，生产环境密码通过环境变量传入
export SIGN_CERT_PASSWORD="<签名证书加密密码>"
python3 sign_server.py -certs <证书目录>
bingo simple_sign -i unsigned.img -u http://localhost:8098/sign -s "abc-egh"

安全提示：demo 仅用于功能演示，私钥泄露存在严重安全风险。生产环境建议根证书私钥和加密密钥离线分人保存，签名密码通过 CI 环境私密参数或环境变量传入，切勿通过命令行参数传递。

2.2.6 `rule_pack` 和 `rule_engine`

yaml

rule_pack:
  version: "latest"
rule_engine:
  version: "latest"

规则包和规则引擎配置，用于 CSR 检查等合规功能。版本号取 latest 或具体版本号，实际版本由 lockfile 锁定。

2.2.7 `dependencies` — 组件依赖列表

dependencies 控制产品包含哪些组件以及组件的编译选项，是机型差异化最常用的配置项。

yaml

dependencies:
  - conan: iam
  - conan: vpd
    options:
      board_name: openUBMC_custom
  - conan: webui
    options:
      energy_enabled: false
      webvnc_enabled: true
  - conan: compute
    action: delete
  - conan: "vpd/1.90.120@openubmc/stable"

字段	说明
`conan`	Conan 包引用。版本范围写法 `iam`（由 lockfile 决定版本）或锁定版本写法 `"vpd/1.90.120@openubmc/stable"`
`options`	传递给该组件的 Conan 编译选项，各组件支持不同 options
`options.board_name`	`vpd`、`help` 组件的机型名称选项（如 `"openUBMC"`、`"PR2715B"`）
`options.manufacture`	`account` 组件的制造模式选项（`true` / `false`）
`options.energy_enabled`	`webui` 组件的能耗页面选项
`options.webvnc_enabled`	`webui` 组件的 WebVNC 选项
`options.qemu`	部分组件的 QEMU 模式选项（使用模拟数据而非真实硬件）
`action: delete`	从基础产品中移除该组件

RTOS 与 OEE 差异：RTOS 产品通常使用版本范围写法（conan: vpd），OEE 产品通常锁定版本写法（"vpd/1.90.120@openubmc/stable"）。

2.2.8 `gpp` — GPP 打包配置

gpp 定义固件包（HPM/GPP）中包含的文件列表，因产品类型差异较大。

RTOS 产品示例（1711）：

yaml

gpp:
  files:
    - file: ${work_out}/rootfs_BMC.img
    - file: ${work_out}/rootfs_BMC.tar.gz
    - file: ${work_out}/rootfs_BMC.img.cms
    - file: ${board_path}/cms.crl
      dst: cms.crl
    - file: ${board_path}/rootca.der
      dst: rootca.der
    - file: ${sdk_path}/Hi1711_boot_4096_debug.bin
      dst: Hi1711_boot_4096.bin
      condition:
        build_type: debug
    - file: ${sdk_path}/Hi1711_boot_4096.bin
      dst: Hi1711_boot_4096.bin
      condition:
        build_type: release

1712 产品额外配置：

yaml

gpp:
  files:
    # ... 同 1711 的 rootfs 和签名文件 ...
    - file: ${linx_build_dir}/out/LiteOS_M.bin
      dst: LiteOS_M.bin
  pkg_headers:
    gpp_header:
      dst: emmc_header.config
      file: /usr/share/bingo/emmc_uboot_header_1712.config
    hpm_header:
      dst: hpm_header.config
      file: /usr/share/bingo/hpm_header_1712.config
    uboot_header:
      dst: emmc_uboot_header.config
      file: /usr/share/bingo/emmc_uboot_header_1712.config

OEE 产品示例（AST2600）：

yaml

gpp:
  gpt_config: "${board_path}/emmc_layout.yml"
  files:
    - file: ${sdk_path}/fitImage-core-image-tiny-initramfs-ummc-ummc
      dst: kernel.bin
    - file: ${sdk_path}/u-boot-env.bin
    - file: ${sdk_path}/u-boot-spl.bin
    - file: ${sdk_path}/u-boot.bin
    - file: ${sdk_path}/u-boot-env.img
    - file: ${sdk_path}/fitImage.img
    - file: ${work_out}/rootfs_BMC.img
    - file: ${work_out}/rootfs_BMC.tar.gz
    - file: ${work_out}/rootfs_BMC.img.cms
    - file: ${product}/ca/rootca.crl
      dst: cms.crl
    - file: ${product}/ca/rootca.der
      dst: rootca.der

gpp.files 中支持的变量：

变量	值	说明
`${work_out}`	构建输出临时目录	存放 `rootfs_BMC.img`、`rootfs_BMC.tar.gz`、`rootfs_BMC.img.cms`
`${board_path}`	产品板级配置临时目录	存放经定制化处理后的 `cms.crl`、`rootca.der`
`${sdk_path}`	SDK 安装目录	存放 bootloader、内核二进制
`${product}`	`build/product` 目录	存放产品级证书文件
`${output_path}`	`output/` 目录	存放最终的 HPM 包等发布产物
`${linx_build_dir}`	LinX 构建目录	存放 `LiteOS_M.bin`（仅 1712）

字段	说明	RTOS 产品取值	OEE 产品取值
`gpp.files[].file`	源文件路径，支持变量替换	bootloader + rootfs + 签名	kernel + u-boot + rootfs + 签名
`gpp.files[].dst`	目标文件名，不指定时使用源文件原名	—	—
`gpp.files[].condition.build_type`	构建类型条件（`debug` / `release`）	用于选择不同 bootloader	不使用
`gpp.pkg_headers`	eMMC/HPM 分区头部配置	仅 1712	不使用
`gpp.gpt_config`	eMMC GPT 分区布局配置	不指定	`"${board_path}/emmc_layout.yml"`

2.2.9 `linx` — LinX 构建配置（仅 1712）

yaml

linx:
  files:
    - file: ${product}/ca/rootca.der
      dst: host_cms_root_cert_g2.bin

仅在 Hi1712 产品中使用，定义 LinX（轻量级 OS）包内包含的文件列表。

2.2.10 `wbd_up_files` — 白牌升级包配置

yaml

wbd_up_files:
  files:
    - file: ${board_path}/wbd_up_file/favicon.ico
      dst: wbd_up_file/favicon.ico
    - file: ${board_path}/wbd_up_file/filelist.conf
      dst: wbd_up_file/filelist.conf
    - file: ${board_path}/wbd_up_file/web_custom.xml
      dst: wbd_up_file/web_custom.xml

白牌升级包（WBD）的 WebUI 定制文件配置，所有产品类型相同。需要确保产品目录下有对应的 wbd_up_file/ 目录。

2.2.11 `tosupporte` — 发布包配置

tosupporte 定义最终交付给客户的固件包组合，可编排正式版、过站版、QEMU 版、eMMC 版等多种交付形态。

RTOS 产品示例（1711）：

yaml

tosupporte:
  default:
    platform:                                    # 可选，覆盖全局 platform
      conan: "ibmc_sdk/5.14.00.01.b001@openubmc/stable"
      options:
        rtos_version: rtos_v2
        enable_haf: false
      package: community_sign_webvnc_1711
    signature_type: rsa4096
    package_name: "openUBMC/openUBMC_custom-CMT_${version}.zip"
    build_type: release
    files:
      - file: ${product}/License.md
      - file: ${board_path}/version.xml
      - file: "${output_path}/rootfs_${board_name}.hpm"
        dst: openUBMC_custom-CMT_${version}.hpm
  qemu:
    platform:
      package: qemu_1711
    package_name: "openUBMC/openUBMC_custom-CMT_${version}_qemu.zip"
    build_type: debug
    qemu_image: inner/${board_name}_${tosupporte_code}_default.cpio
    dependencies:
      - conan: qemu_drivers
      - conan: fructrl
        options:
          qemu: true
      - conan: bmc_soc
        action: delete
  manufacture:
    transit:
      platform:
        package: community_unsign_webvnc_1711
      signature_type: rsa4096
      package_name: "openUBMC/openUBMC_custom-transit_${version}.zip"
      files:
        - file: "${output_path}/rootfs_${board_name}.hpm"
    sign_hpm:
      platform:
        package: community_sign_webvnc_1711
      signature_type: rsa4096
      package_name: "openUBMC/openUBMC_custom-sign_${version}.zip"
      files:
        - file: "${output_path}/rootfs_${board_name}.hpm"

OEE 产品示例（AST2600）：

yaml

tosupporte:
  default:
    package_name: "openUBMC/openUBMC_ast2600-CMT_${version}.zip"
    build_type: debug
    files:
      - file: ${product}/License.md
      - file: ${board_path}/version.xml
      - file: "${output_path}/rootfs_${board_name}.hpm"
        dst: openUBMC_ast2600-CMT_${version}.hpm
  emmc:
    package_name: "openUBMC/openUBMC_ast2600-CMT_${version}_emmc.zip"
    build_type: debug
    files:
      - file: ${product}/License.md
      - file: ${board_path}/version.xml
      - file: "${output_path}/rootfs_${board_name}.hpm"
        dst: openUBMC_ast2600-CMT_${version}.hpm
      - file: "${output_path}/${board_name}_real.img"
        dst: openUBMC_ast2600-CMT_${version}.img
      - file: "${output_path}/${board_name}_real.wic"
        dst: openUBMC_ast2600-CMT_${version}.wic

发布包配置字段：

字段	说明
`tosupporte.default`	默认发布包配置（必须存在）
`tosupporte.default.platform`	可选，覆盖全局 `platform`（如发布包使用签名版而日常构建使用不签名版）
`signature_type`	发布包使用的签名类型：`rsa4096` / `sm2`
`package_name`	发布 zip 包名称模板，支持 `${version}` 变量
`build_type`	发布包构建类型：`release` / `debug`
`files`	发布 zip 包内包含的文件列表
`qemu.qemu_image`	QEMU cpio 根文件系统镜像路径
`qemu.dependencies`	QEMU 包专用的组件依赖列表（可替换全局 dependencies 中的部分组件）

发布包类型对照：

发布包	适用场景	构建类型	签名	产物	适用产品
`default`	正式交付	release	可选	CMT zip + HPM	所有产品
`qemu`	仿真验证	debug	不签名	CMT zip + QEMU cpio	RTOS
`transit`	产线过站	—	不签名	HPM	RTOS
`sign_hpm`	签名交付	—	RSA4096/SM2	签名 HPM	RTOS
`emmc`	eMMC 刷机	debug	不签名	HPM + eMMC img/wic	OEE

2.3 步骤三：编写定制化脚本

定制化脚本对组装后的 rootfs 进行机型差异化裁剪（如删除不需要的 systemd unit、修改配置文件）。脚本需继承 BaseCustomization 类（位于 build/customization/default.py），并实现以下方法：

方法	说明	触发时机
`rootfs_cust`	rootfs 主裁剪逻辑	rootfs 组装完成后、打包前
`datafs_cust`	datafs 裁剪	datafs 组装完成后
`rootfs_debug_cust`	debug 版 rootfs 裁剪	debug 构建
`rootfs_release_cust`	release 版 rootfs 裁剪	release 构建
`rootfs_common`	通用裁剪	所有构建类型

简单示例（继承 BaseCustomization）：

python

# build/customization/my_customize.py
from customization.default import BaseCustomization
import logging

log = logging.getLogger(__name__)

class Customization(BaseCustomization):
    def rootfs_cust(self, rootfs_path):
        log.info("Start my_customize customization")
        # 添加机型特定的裁剪逻辑

    def datafs_cust(self, rootfs_path):
        pass

    def rootfs_debug_cust(self, rootfs_path):
        pass

    def rootfs_release_cust(self, rootfs_path):
        pass

实际示例（继承已有裁剪脚本）：

RTOS 产品可继承 prototype.py（已内置 subsystem 启动组件裁剪等通用逻辑）：

python

from customization.prototype import Customization as PrototypeCustomization

class Customization(PrototypeCustomization):
    def rootfs_cust(self, rootfs_path):
        PrototypeCustomization.rootfs_cust(self, rootfs_path)
        # 添加机型特定的裁剪逻辑

OEE 产品可继承 prototype.py 和 product_custom.py（如 oee_ast2600_customize.py 的做法）：

python

from customization.prototype import Customization as PrototypeCustomization
from customization.product_custom import Customization as ProductCustomization

class Customization(PrototypeCustomization, ProductCustomization):
    def rootfs_cust(self, rootfs_path):
        PrototypeCustomization.rootfs_cust(self, rootfs_path)
        # 添加机型特定的裁剪逻辑

在 manifest.yml 中指向该脚本：

yaml

base:
  customization: "customization/my_customize.py"

2.4 步骤四：更新 lockfile 并构建验证

bash

# 生成/更新 lockfile
bingo lock -c -r openubmc_opensource

# 构建验证
bingo build -t personal -b <新产品名>

# 验证产物
ls -lh output/rootfs_<新产品名>.hpm

验证方法：

构建无报错退出
output/rootfs_<新产品名>.hpm 文件存在且大小合理（约 60-100 MB）
HPM 包可成功刷入对应 BMC 板子并启动

2.5 RTOS 与 OEE 产品关键配置差异汇总

配置项	RTOS 产品 (1711/1712)	OEE 产品 (AST2600)
`platform.options.rtos_version`	`rtos_v2` / `rtos_v2_1712`	`oee_ast2600`
`platform.package`	`community_unsign_webvnc_1711` / `1712`	`community_ast2600`
`openubmc_sdk`	必须配置	注释掉（不需要）
`bmc_sdk_download`	必须配置（bmc_sdk.tar.gz）	必须配置（oee_sdk.zip）
`packages_download`	不需要	必须配置
`tools_install`	不需要	必须配置
`base.profile`	不指定	`profile_oee.ini`
`base.skip_linx`	仅 1712 需 `true`	不指定
签名方式	rsa4096 + sm2（1712）	仅 cms.crl
SDK 拉取方式	`ibmc_sdk`（Conan）+ `openubmc_sdk`（Conan）	`ibmc_sdk`（Conan）+ `bmc_sdk_download` + `packages_download` + `tools_install`
`gpp.gpt_config`	不指定	需指定 `emmc_layout.yml`
`gpp.pkg_headers`	仅 1712	不指定
`linx`	仅 1712	不指定
组件依赖写法	版本范围（`conan: vpd`）	锁定版本（`"vpd/1.90.120@openubmc/stable"`）
`tosupporte` 发布包类型	default + qemu + manufacture（transit/sign_hpm）	default + emmc

3. 日志说明

3.1 一键日志收集

系统一键日志收集功能会自动收集以下日志文件：

文件路径	内容说明
`temp/log/task.log`	bingo 构建全流程日志：SDK 安装、Conan 依赖解析、rootfs 组装、签名打包
`temp/log/gpt.log`	eMMC GPT 分区布局日志（仅 OEE 产品）
`temp/log/swbom_data/`	SWBOM（软件物料清单）数据，记录固件中包含的所有组件及其版本
`temp/build_<产品名>_*/`	构建中间产物目录，含 Conan 安装日志、graph.order、graph.info
`temp/board_<产品名>/`	产品板级配置临时目录

3.2 关键日志信息

日志片段	日志级别	含义解读	建议处理动作
`获取到依赖: vpd/1.90.120@openubmc/stable`	INFO	Conan 成功解析并缓存了该组件	正常，无需处理
`WARN: lockfile中无法找到满足iam/1.10.3的版本，将使用自声明版本`	WARN	lockfile 中无匹配版本，Conan 将使用 manifest.yml 中声明的版本	检查 lockfile 是否需要更新：`bingo lock -c`
`openubmc-bingo下载失败，请检查apt源是否配置成功`	ERROR	bingo APT 包安装失败，通常是 libcurl4t64 版本冲突导致	见 Q2 详细解决方案
`未检测到/opt/RTOS目录`	ERROR	SDK 安装步骤未执行（通常因 bingo 安装失败被跳过）	先修复 bingo 安装，再重新执行 init.py
`Remote needs authentication`	ERROR	Conan 远程仓库未登录或凭证过期	执行 `conan remote login openubmc_opensource <用户名>`
`TimeoutExpired`	ERROR	命令执行超时（600 秒），通常是网络下载慢导致	检查网络速度，配置加速源或代理
`文件fitImage-core-image-tiny-initramfs-ummc-ummc哈希不匹配，缓存失效`	WARN	SDK 文件的 SHA256 校验不匹配，本地缓存已失效，将重新下载	正常，重新下载即可

4. 问题定界指南

4.1 典型问题定界

现象描述	是否为本组件问题	判断依据	关键证据收集方法
`bingo build` 构建失败，产物未生成	可能是	检查 `temp/log/task.log` 中的错误信息：若为 Conan 认证失败或依赖缺失，属 manifest 配置问题；若为组件自身编译错误，属对应组件问题	`tail -50 temp/log/task.log`
`init.py` 环境初始化失败	是	init.py 是 manifest 仓库的脚本，环境初始化问题属于本组件	查看 init.py 输出的错误步骤
HPM 包刷入后服务启动失败	否	manifest 仅负责组装和打包，服务运行时问题属对应业务组件	在 BMC 上执行 `journalctl -u <服务名>`
Conan 包版本冲突	可能是	若是 lockfile 中版本范围不兼容，属 manifest 配置问题；若是组件内部依赖冲突，属组件问题	`bingo lock -c -r openubmc_opensource` 重新生成 lockfile
QEMU 启动后 Redfish 接口不通	否	QEMU 环境的接口问题属 rackmount 或对应组件	检查 QEMU 配置和 mock 数据

4.2 错误码速查表

错误码	含义	可能原因	排查建议
`仅支持Ubuntu 24.04操作系统`	init.py 系统检查失败	非 Ubuntu 24.04 环境	`cat /etc/issue` 确认版本，使用 Docker/WSL 部署 Ubuntu 24.04
`请直接执行，不支持以sudo环境执行脚本`	init.py 权限检查失败	使用了 `sudo python3 init.py`	使用 `su root` 切换后直接执行
`openubmc-bingo下载失败`	bingo APT 安装失败	libcurl4t64 版本冲突	见 Q2
`Remote needs authentication`	Conan 认证失败	未登录 Conan 远程仓库	`conan remote login openubmc_opensource <用户名>`
`EOF when reading a line`	Conan 交互输入失败	Docker 容器无交互终端	预设许可证自动接受（见 Q3）
`未检测到/opt/RTOS目录`	SDK 安装步骤被跳过	bingo 安装失败导致后续步骤跳过	先修复 bingo，再重新执行 init.py
`Permission denied`	文件写入权限不足	非 root 用户执行	使用 `su root` 切换后执行
`TimeoutExpired`	命令执行超时	网络下载慢	`LOG=debug python3 init.py` 开启调试日志

4.3 调试方法

开启调试日志

bash

# init.py 调试模式
LOG=debug python3 init.py -user <用户名> -psw '<密码>'

# bingo 构建时查看详细日志
tail -f temp/log/task.log

复现问题方法

清理构建缓存：rm -rf temp/ output/
重新执行构建：bingo build -t personal -b <产品名>
观察日志输出：tail -f temp/log/task.log
如需排查 Conan 问题，清除本地缓存后重试：rm -rf ~/.conan2

5. 常见问题解答

Q1：init.py 报错"仅支持Ubuntu 24.04操作系统"

问题描述：执行 python3 init.py 时提示操作系统版本不匹配
一句话答案：manifest 构建仅支持 Ubuntu 24.04 LTS x86-64
根因说明：init.py 的 environ_check 方法检查 /etc/issue 首行，必须以 Ubuntu 24.04 开头
解决方案：使用 Docker Desktop 或 WSL 2 部署 Ubuntu 24.04 环境
规避方案：Mac/Windows 用户通过 Docker 容器构建
适用版本：所有版本

Q2：bingo 安装失败（libcurl4t64 版本冲突）

问题描述：apt install openubmc-bingo 报 libcurl4-openssl-dev 依赖冲突
一句话答案：Ubuntu 安全更新推送了较新版本的 libcurl4t64，与 bingo 的 apt 包依赖不兼容
根因说明：git/curl 安装引入 libcurl4t64，安全更新可能推送 8.5.0-2ubuntu10.10，而 openubmc-bingo 依赖的 libcurl4-openssl-dev 要求精确匹配版本
解决方案：显式指定版本同步安装或手动 pip 安装

bash

apt install -y libcurl4t64=8.5.0-2ubuntu10.9 libcurl4-openssl-dev=8.5.0-2ubuntu10.9
# 或
pip install openubmc-bingo --upgrade

适用版本：所有版本

Q3：Docker 容器中 init.py 因许可证确认阻塞

问题描述：Docker 容器无交互终端，init.py 的 SDK 安装步骤因许可证交互确认而 EOF 失败
一句话答案：预设许可证自动接受环境变量
根因说明：bmc-studio 和 SDK 安装需要用户确认许可证，Docker 容器无 stdin 导致 EOF
解决方案：

bash

echo 'bmc-studio bmc-studio/accept-license boolean true' | debconf-set-selections
export OPENUBMC_LICENSE=true
export AUTO_ACCEPT_LICENSE=true
echo 'Y' | python3 init.py -user <用户名> -psw '<密码>'

适用版本：所有版本

Q4：Conan 登录失败

问题描述：conan remote login 返回认证错误或 EOF when reading a line
一句话答案：确认社区账号正确且网络可访问 Conan 仓库
根因说明：密码错误、网络不通、或密码含特殊字符在非交互环境下输入失败
解决方案：
1. 确认社区账号已注册且密码正确
2. 确认网络可访问 https://conan.openubmc.cn
3. 密码含特殊字符时使用交互式输入
4. 清除缓存后重新配置：

bash

rm -rf ~/.conan2
conan remote add openubmc_opensource https://conan.openubmc.cn/openubmc_opensource --force
conan remote login openubmc_opensource <用户名>

安全提示：仅在 SSL 证书校验失败且确认网络环境安全时，可临时使用 --insecure 标志排障（conan remote add ... --insecure --force）。--insecure 会禁用 TLS 证书校验，存在中间人攻击风险，可能导致下载的组件包被篡改。问题解决后应删除该 remote 并重新以不带 --insecure 的方式配置。

适用版本：所有版本

Q5：构建产物未生成

问题描述：bingo build 执行完成但 output/ 目录无 HPM 包
一句话答案：依次检查 Conan 认证、磁盘空间、内存和构建日志
根因说明：构建过程中某步骤失败（最常见是 Conan 认证过期或磁盘/内存不足）
解决方案：
1. 登录 Conan：conan remote login openubmc_opensource <用户名>
2. 检查磁盘空间：df -h
3. 检查内存：free -h
4. 查看构建日志：tail -50 temp/log/task.log
适用版本：所有版本

Q6：如何更新/添加/删除组件？

问题描述：需要修改产品的组件依赖列表
一句话答案：编辑 manifest.yml 的 dependencies，然后重新生成 lockfile
解决方案：

bash

# 更新特定组件版本
bingo lock -u <组件名> -r openubmc_opensource

# 重新生成完整 lockfile
bingo lock -c -r openubmc_opensource

# 添加组件：在 dependencies 下添加
#   - conan: "<组件名>/<版本>@openubmc/stable"

# 删除组件：使用 action: delete
#   - conan: compute
#     action: delete

适用版本：所有版本

Q7：bingo、conan 等命令提示 command not found

问题描述：初始化完成后工具命令无法执行
一句话答案：工具安装在 ~/.local/bin，需配置 PATH
根因说明：~/.local/bin 不在系统默认 PATH 中
解决方案：

bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

适用版本：所有版本

Q8：如何使用 ccache 加速编译？

问题描述：C/C++ 组件编译耗时过长
一句话答案：构建时添加 --ccache 参数
解决方案：

bash

bingo build -t personal -b <产品名> --ccache

适用版本：26.06+
相关文档链接：bingo使能ccache特性.md

附录

附录A 参考资料

openUBMC 官方文档站：https://www.openubmc.cn/docs/zh
manifest 仓库 README：manifest/README.md
manifest 构建特性说明：manifest/docs/26.06/构建特性说明.md
bingo 仓库文档：https://gitcode.com/openUBMC/bingo/tree/main/docs/26.06/
bingo 特性文档列表：

特性	文档
白牌包出包	bingo支持白牌包出包.md
HPM 重签名	bingo支持SignServer的HPM重签名适配.md
CCache 加速	bingo使能ccache特性.md
C++ 代码生成	C++组件代码自动生成开发指导.md
CSR 检查	bingo支持CSR检查功能扩展详细设计说明书.md
固件完整性签名	bingo支持固件完整性保护签名能力.md
OEE 产品策略	bingo支持OEE产品策略配置.md
组件批量定制	bingo支持组件批量定制.md
平台整包集成	platform_full_package_integration_guide.md

附录B 修订记录

版本	日期	修订人	修订内容
v1.0	2026-07-23	openUBMC 社区	初始版本创建

manifest 配置指南 ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

1.2 解决什么问题 ​

1.3 核心功能 ​

1.4 关键术语表 ​

1.5 外部交互边界 ​

1.6 支持的产品列表 ​

2. 新增机型配置指南 ​

2.1 步骤一：创建产品目录和辅助文件 ​

2.2 步骤二：编写 manifest.yml — 全配置详解 ​

2.2.1 schema ​

2.2.2 platform — 平台 SDK 配置 ​

2.2.3 SDK 拉取方式 ​

2.2.4 tools_install — OEE 工具链安装策略（仅 OEE 产品） ​

2.2.5 base — 产品基础配置 ​

2.2.6 rule_pack 和 rule_engine ​

2.2.7 dependencies — 组件依赖列表 ​

2.2.8 gpp — GPP 打包配置 ​

2.2.9 linx — LinX 构建配置（仅 1712） ​

2.2.10 wbd_up_files — 白牌升级包配置 ​

2.2.11 tosupporte — 发布包配置 ​

2.3 步骤三：编写定制化脚本 ​

2.4 步骤四：更新 lockfile 并构建验证 ​

2.5 RTOS 与 OEE 产品关键配置差异汇总 ​

3. 日志说明 ​

3.1 一键日志收集 ​

3.2 关键日志信息 ​

4. 问题定界指南 ​

4.1 典型问题定界 ​

4.2 错误码速查表 ​

4.3 调试方法 ​

开启调试日志 ​

复现问题方法 ​

5. 常见问题解答 ​

Q1：init.py 报错"仅支持Ubuntu 24.04操作系统" ​

Q2：bingo 安装失败（libcurl4t64 版本冲突） ​

Q3：Docker 容器中 init.py 因许可证确认阻塞 ​

Q4：Conan 登录失败 ​

Q5：构建产物未生成 ​

Q6：如何更新/添加/删除组件？ ​

Q7：bingo、conan 等命令提示 command not found ​

Q8：如何使用 ccache 加速编译？ ​

附录 ​

附录A 参考资料 ​

附录B 修订记录 ​

manifest 配置指南

版本信息

1. 组件概述

1.1 组件简介

1.2 解决什么问题

1.3 核心功能

1.4 关键术语表

1.5 外部交互边界

1.6 支持的产品列表

2. 新增机型配置指南

2.1 步骤一：创建产品目录和辅助文件

2.2 步骤二：编写 manifest.yml — 全配置详解

2.2.1 `schema`

2.2.2 `platform` — 平台 SDK 配置

2.2.3 SDK 拉取方式

2.2.4 `tools_install` — OEE 工具链安装策略（仅 OEE 产品）

2.2.5 `base` — 产品基础配置

2.2.6 `rule_pack` 和 `rule_engine`

2.2.7 `dependencies` — 组件依赖列表

2.2.8 `gpp` — GPP 打包配置

2.2.9 `linx` — LinX 构建配置（仅 1712）

2.2.10 `wbd_up_files` — 白牌升级包配置

2.2.11 `tosupporte` — 发布包配置

2.3 步骤三：编写定制化脚本

2.4 步骤四：更新 lockfile 并构建验证

2.5 RTOS 与 OEE 产品关键配置差异汇总

3. 日志说明

3.1 一键日志收集

3.2 关键日志信息

4. 问题定界指南

4.1 典型问题定界

4.2 错误码速查表

4.3 调试方法

开启调试日志

复现问题方法

5. 常见问题解答

Q1：init.py 报错"仅支持Ubuntu 24.04操作系统"

Q2：bingo 安装失败（libcurl4t64 版本冲突）

Q3：Docker 容器中 init.py 因许可证确认阻塞

Q4：Conan 登录失败

Q5：构建产物未生成

Q6：如何更新/添加/删除组件？

Q7：bingo、conan 等命令提示 command not found

Q8：如何使用 ccache 加速编译？

附录

附录A 参考资料

附录B 修订记录