产品模型（Metadata）归档与发布指南

kailai20011221_qpvt9 · 2026 年8 月 6 日 07:17

产品模型（Metadata）归档与发布指南

本文面向 openUBMC 社区贡献者和产品维护者，介绍产品模型归档制品的用途、生成方式、发布流程及常见问题。

文档重点覆盖以下使用场景：

在本机生成并使用 metadata 制品；

将 metadata 发布到企业内网 Conan 仓；

在完全隔离的气隙环境中搬运和使用 metadata。

如需了解该功能的详细设计，可参阅binggo代码仓中的《bingo 支持模型归档功能详细设计说明书》（docs/26.03/）。本文主要介绍实际使用方法。

1. 快速了解

1.1 metadata 制品是什么

可以把产品模型 metadata 理解为：

与某个产品固件版本对应的一份完整模型快照。

openUBMC 中的各个组件在构建时会分别生成自己的 MDS / MDB 模型文件，例如：

model.json
service.json
schema.json
types.xml

这些文件用于描述组件对外提供的 D-Bus 资源树和接口。

当一个产品完成构建后，bingo 会将分散在各组件中的模型统一收集，并补充 schema、拓扑配置、事件定义和规则包等内容，最终生成一个可以独立使用的 Conan 制品。

下游工具可以直接使用这份制品，而无需重新编译固件，例如：

openUBMC Studio IDE
CI 模型检查和规则门禁
调试器
现场分析工具
规则检查器

metadata 制品的 Conan 引用格式为：

metadata-<board>-<code>/<version>@openubmc/stable

例如：

metadata-openubmc-default/26.09.00.01@openubmc/stable

1.2 使用前必须知道的三件事

重要：metadata 只在 publish 构建时产生，是固件发布构建的附带产物。

bingo publish（等价于 bingo build -t publish）的本意是构建固件发布包（产出 output/rootfs_<board>.hpm）。metadata 归档只是这条构建流水线里的一个附带步骤，并不存在专门用来「发布 metadata」的命令。

之所以绑定 publish：归档任务要求 tosupporte_code 非空，而 publish 构建会把它兜底为 default（也可用 -sc 指定具体码值）；-t personal 构建不设该值，因此不会归档 metadata。

metadata 归档会在满足以下三个条件时自动触发：

使用 Conan v2；
使用 publish 构建（-t publish，即 bingo publish）；
构建过程中已经生成非空的 output/mdb/ 目录。

满足条件后，metadata 默认只通过 conan export-pkg 写入本机 Conan 缓存。只有显式设置环境变量 UPLOAD_METADATA_REMOTE 后，bingo 才会把它上传到远程仓。

如果构建完成后没有生成 metadata，优先检查这三项。

2. 根据使用目标选择操作方式

使用目标	推荐方式	是否需要远程仓
只在本机生成并验证 metadata	执行 `bingo publish`（默认只写本地缓存）	不需要
生成正式固件发布包，metadata 随之产生	执行 `bingo publish`（固件发布构建）	不需要
让内网多台机器共享 metadata	构建时配置内网 Conan remote，并设置 `UPLOAD_METADATA_REMOTE`	需要
在完全隔离环境中使用 metadata	在构建机生成后离线搬运	不需要持续联网

3. 五分钟快速开始

3.1 准备参数

执行命令前，需要确认以下参数：

参数	含义	配置位置
`<board>`	目标产品单板名称	`manifest/build/product/BMC/<board>/`
`<SupportE码>`	产品对应的 SupportE 码	产品的 `manifest.yml` 配置
`<version>`	产品版本号	`manifest.yml` 中的 `base/version`
`<remote>`	Conan 远程仓别名	`conan remote list`

本文中的“产品”“单板”“机型”和命令参数 board 均指由 manifest 仓定义的目标产品单板。

3.2 在本机生成 metadata

metadata 是 publish 构建的附带产物，无需额外命令。进入 manifest 仓根目录：

cd <manifest 仓根目录>

执行固件发布构建（-sc 可选，不传则用 default）：

bingo publish -b <board> -sc <SupportE码>

该命令等价于：

bingo build -t publish -b <board> -sc <SupportE码>

说明：bingo publish 的目的是构建固件发布包（HPM），metadata 是其附带产物。只有 publish 构建会产生 metadata，-t personal 不会。 构建完成后，metadata 默认只写入本地 Conan 缓存，不会上传到远程仓。

3.3 查看生成结果

conan list "metadata-<board>-<SupportE码>/*@openubmc/stable"

例如，假设：

board: openUBMC
SupportE 码: default
版本: 26.09.00.01

生成的制品引用为：

metadata-openubmc-default/26.09.00.01@openubmc/stable

可使用以下命令查询：

conan list \
  "metadata-openubmc-default/26.09.00.01@openubmc/stable"

4. metadata 制品包含什么

4.1 制品目录

一个 metadata 制品通常包含以下内容：

目录或文件	来源	用途
`mdb/`	各组件 Conan 包内的 `usr/share/doc/openubmc/`（MDS 模型）与 `opt/bmc/apps/mdb_interface/`（MDB 接口数据）	汇聚后的全产品 MDS / MDB 模型
`schemas/`	bingo 安装目录中的 `base.json`、`csr.schema.json`	模型校验所需的基础 schema
`events/event_def.json`	VPD 组件构建产物中的 `opt/bmc/conf/event_def.json`	VPD 事件定义
`sr/root.sr`	当前机型的 `opt/bmc/sr/root.sr`	根 SR，即签名资源
`topology-config.yml`	单板目录下的产品拓扑配置（可选，部分产品提供，缺失则跳过）	产品拓扑信息
`rule_pack/`	Conan 包 `openubmc-studio-rulepack`	规则包
`rule_engine/`	Conan 包 `openubmc-studio-rule-engine`	规则引擎
`metadata.yml`	bingo 自动生成	本次归档的自描述清单
`conanfile.py`	mako 模板渲染生成	Conan v2 配方

其中部分文件为可选内容。

如果构建产物中不存在对应源文件，例如缺少 root.sr 或 event_def.json，归档流程会按实际情况跳过这些文件，并在 metadata.yml 中记录实际归档结果。

4.2 `metadata.yml`

bingo 会在制品根目录生成 metadata.yml，用于描述本次归档的产品、版本、发布阶段和实际文件内容。

示例：

metadata:
  board_name: openUBMC
  version: 26.09.00.01
  build_type: publish
  stage: dev
  rule_pack_version: 1.2.3
  rule_engine_version: 1.0.5
  archived_files:
    event_def: events/event_def.json
    root_sr: sr/root.sr
    topology_config: topology-config.yml
    rule_pack: rule_pack/
    rule_engine: rule_engine/

字段说明：

字段	说明
`board_name`	产品单板名称
`version`	产品版本
`build_type`	构建类型，例如 `publish` 或 `personal`
`stage`	产品发布阶段，例如 `dev`、`rc` 或 `stable`
`rule_pack_version`	规则包版本
`rule_engine_version`	规则引擎版本
`archived_files`	本次实际归档成功的额外文件和目录

archived_files 只记录实际存在并成功归档的内容。

如果某个源文件不存在，对应字段不会出现在清单中。

5. 场景一：本地生成和使用

5.1 本地生成（不上传远程仓）

在本机做一次 publish 构建，metadata 会作为附带产物产生并写入本地 Conan 缓存：

cd <manifest 仓根目录>

bingo publish \
  -b <board> \
  -sc <SupportE码>

-sc 可选：不传时归档使用的码值为 default，传了则用指定码值。metadata.yml 中的 build_type 字段记为 publish。

构建完成后，可以在本机 Conan 缓存中查询 metadata：

conan list "metadata-<board>-<SupportE码>/*@openubmc/stable"

默认情况下，metadata 只进行本地 conan export-pkg，不会上传。

日志中如果出现类似以下提示，属于正常情况：

仅本地创建 conan 制品，不上传到远程仓库

这表示当前没有设置 UPLOAD_METADATA_REMOTE。

5.2 完全离线环境的前提

如果构建机完全无法访问任何远程仓，仍然可以生成本地 metadata，但需要满足一个前提：

构建所需的组件依赖、规则包和规则引擎已经存在于本地 Conan 缓存或其他可访问的本地来源中。

metadata 本身不要求配置远程上传仓。

6. 场景二：发布到内网 Conan 仓

metadata 默认只写本地缓存。当内网中有多台开发机、CI 节点或工具需要共享同一份 metadata 时，可以在产品构建时通过 UPLOAD_METADATA_REMOTE 把这份附带产物上传到企业内部 Conan 仓。注意：这里「发布」指的只是把 metadata 推到 Conan 仓共享，构建命令本身（bingo publish）的目的仍是出固件发布包。

内网仓可以是：

conan-server
Artifactory
JFrog
其他兼容 Conan 的服务

6.1 典型场景：发布包含企业自研模型的产品

企业内网开发者经常会在 openUBMC 公共组件之外，开发自己的业务组件和 MDB 模型。例如：

企业自研的传感器管理组件；
自定义设备和资源模型；
企业内部 D-Bus 服务接口；
尚未向社区公开的板级功能；
只适用于某个内部产品的模型扩展。

开发者通常希望将这些自研模型与产品中的其他组件模型统一归档，形成一份完整的产品级 metadata，并发布到企业内网 Conan 仓，供内网的 BMC Studio、CI、调试器和其他开发者使用。

生成后的制品形式仍然是：

metadata-<board>-<SupportE码>/<version>@openubmc/stable

但制品中的 mdb/ 会同时包含：

mdb/
├── openUBMC 公共组件模型
├── 企业自研组件模型
└── 当前产品的其他组件模型

自研模型如何进入 metadata

metadata 归档不会直接扫描开发者的源码目录。

自研模型需要先作为产品组件构建产物进入 bingo 的模型收集流程：

自研组件源码
    ↓
组件构建并生成 MDS 模型
    ↓
模型打包进组件包 usr/share/doc/openubmc/
    ↓
bingo 收集到 output/mdb/
    ↓
task_package_metadata 统一归档
    ↓
生成包含自研模型的 metadata 制品

因此，自研组件通常需要满足以下条件：

自研组件已经被当前产品的 manifest.yml 引用；
bingo 能够获取并构建该组件；
组件构建过程能够正常生成 MDS 模型，并打包进组件包内的 usr/share/doc/openubmc/；
该目录下的模型文件能够被 bingo 收集到 output/mdb/；
构建命令使用 Conan v2，并传入 -sc 参数。

如果自研模型没有进入 output/mdb/，最终生成的 metadata 中也不会包含这些模型。

发布前检查自研模型

发布前，建议先检查自研模型是否已经进入模型汇总目录：

find output/mdb/ -type f | sort

也可以根据自研模型的文件名、服务名或组件名进行查询：

find output/mdb/ -type f | grep "<自研组件或模型关键字>"

如果这里找不到自研模型，应先排查组件构建和模型收集过程，而不是继续排查 metadata 上传流程。

发布后验证

检查内网仓中是否存在目标制品：

conan list \
  "metadata-company-board-company-a/26.09.00.01@openubmc/stable" \
  -r intranet

在另一台内网开发机上安装该制品：

conan install \
  --requires=metadata-company-board-company-a/26.09.00.01@openubmc/stable \
  -r intranet

安装后检查：

metadata.yml 中的产品名和版本是否正确；
mdb/ 中是否包含企业自研模型；
公共组件和自研组件的模型是否同时存在；
schemas/、rule_pack/ 和 rule_engine/ 是否符合当前产品配置。

常见问题：制品发布成功，但缺少自研模型

如果 metadata 已经成功生成并上传，但其中没有自研模型，通常说明问题发生在上传之前。

建议按以下顺序排查：

自研组件是否被 manifest 引用
    ↓
自研组件是否实际参与构建
    ↓
组件是否生成 MDS 模型并打包到 usr/share/doc/openubmc/
    ↓
模型是否被复制到 output/mdb/
    ↓
metadata 是否完成归档

其中最直接的判断方式是检查：

find output/mdb/ -type f

如果 output/mdb/ 中已经存在自研模型，但最终 metadata 中缺失，再进一步检查 task_package_metadata 的归档日志。

如果 output/mdb/ 中本身没有自研模型，应优先检查自研组件的模型生成方式、构建产物目录以及 bingo 的模型收集过程。

6.2 上传命令与配方说明

6.1 的示例已经演示了完整的发布流程。这里补充上传环节的内部行为。

本地 conan export-pkg 成功后，当设置了 UPLOAD_METADATA_REMOTE，bingo 会自动执行类似以下命令：

conan upload \
  metadata-<board>-<code>/<version>@openubmc/stable \
  --only-recipe \
  -r <remote> \
  -c

注意使用了 --only-recipe：当前 metadata 配方使用：

build_policy = "never"

归档文件通过 exports_sources 随 recipe 管理，因此只需上传 recipe，下游 conan install 时 Conan 会自动把 exports_sources 的文件铺出来。这也是 metadata 适合内网和气隙搬运的原因之一。

6.3 内网环境中的依赖拉取

UPLOAD_METADATA_REMOTE 只控制 metadata 的上传目标。

构建 metadata 之前，bingo 还需要拉取各组件 Conan 包、规则包和规则引擎。在纯内网环境中，通常还需要把依赖来源也指向内网仓：

export OPENUBMC_DEFAULT_CONAN_REMOTE=<内网仓别名>

这样可以使：

组件依赖拉取；
规则包和规则引擎拉取；
metadata 上传；

都通过同一个内网仓完成。

6.4 相关环境变量

环境变量	默认值	作用
`UPLOAD_METADATA_REMOTE`	未设置	metadata 上传开关；值为 Conan remote 别名
`OPENUBMC_DEFAULT_CONAN_REMOTE`	`openubmc_dev`	拉取组件依赖时使用的默认远程仓
`OPENUBMC_DEFAULT_CONAN_USER`	v1: `openUBMC.release` / v2: `openubmc`	默认 Conan user（metadata 要求 Conan v2，故实际生效值为 `openubmc`）
`OPENUBMC_DEFAULT_CONAN_USER_DEV`	`openubmc.dev`	开发场景默认 Conan user（仅在 Conan v2 下读取）

7. 场景三：气隙环境中离线搬运

气隙环境是指构建机或消费机无法访问外网，也无法连接内网 Conan 服务。

在这种环境中，可以先在有依赖条件的构建机上生成 metadata，再通过 U 盘或中转机搬运到无网消费机。

7.1 在构建机生成制品

先在有依赖条件的构建机上做一次产品构建，让 metadata 作为附带产物生成：

bingo publish \
  -b <board> \
  -sc <SupportE码>

确认制品已经进入本地缓存：

conan list \
  "metadata-<board>-<code>/<version>@openubmc/stable"

7.2 查找本地缓存位置

conan cache path \
  metadata-<board>-<code>/<version>@openubmc/stable

根据命令输出找到对应 recipe 目录，再将所需目录打包并通过 U 盘或中转机搬运。

也可以先从已有远程仓下载到本地缓存：

conan download \
  metadata-<board>-<code>/<version>@openubmc/stable \
  -r <源仓>

7.3 在无网消费机重新导入

在搬运得到的 conanfile.py 所在目录中执行：

conan export-pkg . \
  --name=metadata-<board>-<code> \
  --version=<version> \
  --user=openubmc \
  --channel=stable

导入后确认制品存在：

conan list \
  "metadata-<board>-<code>/<version>@openubmc/stable"

随后，本机工具即可通过 Conan 使用该 metadata。

7.4 气隙场景注意事项

metadata 是纯数据制品，不包含需要重新编译的二进制依赖，并使用：

build_policy = "never"

因此它不需要根据不同 ABI 或编译 profile 重新构建，适合在隔离环境中搬运。

直接复制 Conan 缓存目录时，应确保 recipe 及其归档文件完整，避免只复制部分缓存内容。

8. 验证发布结果

无论使用本地、内网还是气隙方式，建议在发布后完成以下检查。

8.1 检查本地缓存

conan list \
  "metadata-<board>-<code>/*@openubmc/stable"

检查指定版本：

conan list \
  "metadata-<board>-<code>/<version>@openubmc/stable"

8.2 检查远程仓

conan list \
  "metadata-<board>-<code>/*@openubmc/stable" \
  -r <remote>

8.3 安装并检查内容

从本地缓存安装：

conan install \
  --requires=metadata-<board>-<code>/<version>@openubmc/stable

从指定远程仓安装：

conan install \
  --requires=metadata-<board>-<code>/<version>@openubmc/stable \
  -r <remote>

安装后重点检查以下内容：

metadata.yml
mdb/
schemas/
events/
sr/
topology-config.yml
rule_pack/
rule_engine/

实际目录以本次归档结果为准。

部分可选文件不存在时，应同时检查 metadata.yml 中的 archived_files，确认清单与实际制品内容一致。

9. 下游如何使用 metadata

9.1 BMC Studio

BMC Studio 可以使用：

mdb/：构建产品资源树；
schemas/：执行模型校验；
metadata.yml：识别产品、版本和发布阶段。

9.2 CI 规则检查

CI 可以读取：

rule_pack/
rule_engine/
events/event_def.json
topology-config.yml

用于执行模型一致性检查和规则门禁。

9.3 调试器和现场工具

调试工具可以根据 metadata.yml 中的以下信息匹配固件：

board_name
version
stage
build_type

从而使用与目标固件对应的模型和规则数据。

10. metadata 是如何生成的

10.1 manifest 与 bingo 的分工

metadata 归档涉及两个主要仓库。

仓库	角色	对 metadata 的职责
`manifest`	产品配置和数据层	定义产品组成、版本、依赖、规则包、签名和打包策略
`bingo`	固件构建引擎	构建固件时顺带收集模型、补充文件、生成清单、渲染配方并归档为 Conan 制品

可以简单理解为：

manifest 描述产品是什么；bingo 在构建固件的过程中，把模型归档成一份附带的可独立使用的 Conan 制品。

manifest 本身不生成各组件的模型。

模型最初由各组件在构建过程中产出，bingo 再根据 manifest 的产品定义完成汇聚。

10.2 端到端流程

flowchart TD
    subgraph COMP["各组件仓"]
        C1["生成 MDS / MDB 模型<br/>model.json / service.json / schema.json"]
        C2["组件构建并打成 Conan 包"]
        C1 --> C2
    end

    subgraph MANIFEST["manifest 仓"]
        M1["manifest.yml<br/>产品定义、版本、SupportE 码<br/>rule_pack / rule_engine 配置"]
        M2["subsys/*.yml<br/>openubmc.lock"]
        M1 --- M2
    end

    CMD["执行命令<br/>bingo publish -b &lt;board&gt; -sc &lt;SupportE码&gt;"]

    subgraph BINGO["bingo 引擎"]
        B1["1. pre_cook_manifest<br/>合并多层 manifest.yml"]
        B2["2. 拉取组件 Conan 包"]
        B3["3. 收集组件模型<br/>usr/share/doc/openubmc/(MDS)<br/>+ opt/bmc/apps/mdb_interface/(MDB)<br/>→ output/mdb/"]
        B4["4. 归档 metadata<br/>补充 schemas、events、sr、topology、规则包"]
        B5["5. 生成 metadata.yml<br/>渲染 conanfile.py"]
        B6["6. conan export-pkg"]
        B1 --> B2 --> B3 --> B4 --> B5 --> B6
    end

    GATE{"是否设置<br/>UPLOAD_METADATA_REMOTE"}

    LOCAL["仅写入本地 Conan 缓存"]
    UPLOAD["上传到指定 Conan remote"]

    COMP --> MANIFEST
    MANIFEST --> CMD
    CMD --> BINGO
    B6 --> GATE
    GATE -- "未设置" --> LOCAL
    GATE -- "已设置" --> UPLOAD

10.3 模型收集

各组件在构建时生成模型文件，并按约定打包进组件 Conan 包内的特定目录。

task_build_conan.py 中的 _copy_files() 会遍历每个组件包，把以下两类内容收集到：

output/mdb/

两类来源各不相同，注意区分：

来源路径（组件包内）	内容	说明
`usr/share/doc/openubmc/`	MDS 模型文件：`model.json`、`service.json`、`schema.json`、`types.xml` 等	即本指南所说的「模型」，是 metadata 制品真正依赖的部分（即 openubmc/docs 目录）
`opt/bmc/apps/mdb_interface/`	MDB 接口数据	运行期 D-Bus 资源树接口数据，与上面的 MDS 模型文档是两类内容

提示：判断「模型是否被收集成功」，应检查 usr/share/doc/openubmc/ 是否有产物落到 output/mdb/，而不是 mdb_interface/。这条路径在工具链其他环节也有体现——例如 CSR 增量检查曾修正过 metadata mdb 路径推导（commit 96f79c8，改动在 functional/check.py，针对的是 CSR 检查侧的路径推导，而非此处的 _copy_files() 收集逻辑）。

10.4 metadata 归档

模型收集完成后，task_package_metadata.run() 会继续处理：

mdb/
schemas/
events/
sr/
topology-config.yml
rule_pack/
rule_engine/

随后生成：

metadata.yml
conanfile.py

最后执行：

conan export-pkg .

并指定：

--name=metadata-<board>-<code>
--version=<version>
--user=openubmc
--channel=stable

11. metadata 归档的触发条件

task_package_metadata 在执行归档前，会通过 _check_need_package() 检查是否需要生成 metadata。

只有以下条件全部满足时，才会继续归档。

11.1 必须使用 Conan v2

Conan v1 环境会直接跳过 metadata 归档。

可先检查 Conan 版本：

conan --version

11.2 必须是 publish 构建（`tosupporte_code` 非空）

归档的实际门控是 tosupporte_code 不为空（_check_need_package() 检查 tosupporte_code is None 时跳过）。tosupporte_code 在以下情况被设置：

使用 publish 构建（-t publish / bingo publish），且没有传 -z 时——此时会被兜底为 default；
或显式传了 -sc <SupportE码>。

因此最常见的触发方式就是直接执行 publish 构建：

bingo publish \
  -b <board> \
  -sc <SupportE码>

-sc 可选：不传则码值为 default。

反之，-t personal 构建、或只使用 -z（manufacture/zip）的构建不会设置 tosupporte_code，因此不会触发 metadata 归档。

11.3 `output/mdb/` 必须存在且非空

output/mdb/ 中的内容来自前序组件构建，主要取决于各组件是否在包内 usr/share/doc/openubmc/ 产出了 MDS 模型文件（详见 10.3）。

如果该目录：

不存在；
为空；
组件没有产出 MDS 模型（即 usr/share/doc/openubmc/ 为空）；

metadata 归档将被跳过。

12. 包名和版本规则

12.1 包名格式

metadata 包名格式为：

metadata-{board}-{code}

包名统一转为小写。

完整引用为：

metadata-{board}-{code}/{version}@openubmc/stable

12.2 code 的选择优先级

code 的取值优先级为：

manufacture_code > tosupporte_code > default

在本文介绍的发布场景中，通常会传入：

-sc <SupportE码>

因此 code 通常就是 tosupporte_code。

13. 常见问题排查

13.1 构建日志中没有 metadata 打包信息

现象：

构建日志中没有出现“开始打包 MDS/MDB”等 metadata 相关信息。

可能原因：

当前使用 Conan v1；
构建命令没有传入 -sc；
output/mdb/ 不存在或为空。

处理方式：

conan --version

确认使用 Conan v2。

检查构建命令：

bingo publish \
  -b <board> \
  -sc <SupportE码>

检查模型目录：

ls -la output/mdb/

13.2 日志提示只在本地创建制品

现象：

仅本地创建 conan 制品，不上传到远程仓库

原因：

没有设置 UPLOAD_METADATA_REMOTE。

处理方式：

如果只需要本地使用，无需处理。

如果需要上传：

export UPLOAD_METADATA_REMOTE=<remote别名>

然后重新执行：

bingo publish \
  -b <board> \
  -sc <SupportE码>

13.3 上传提示 `remote not found`

原因：

UPLOAD_METADATA_REMOTE 的值不在：

conan remote list

的结果中。

处理方式：

先添加 remote：

conan remote add <remote别名> <remote地址>

再设置变量：

export UPLOAD_METADATA_REMOTE=<remote别名>

注意环境变量填写的是 remote 别名，不是 URL。

13.4 本地能查到制品，远程仓查不到

可能原因：

没有设置 UPLOAD_METADATA_REMOTE；
设置的 remote 别名不正确；
上传过程失败；
查询远程仓时使用了错误的 remote。

检查方式：

echo "$UPLOAD_METADATA_REMOTE"
conan remote list

查询远程仓：

conan list \
  "metadata-<board>-<code>/*@openubmc/stable" \
  -r <remote>

13.5 `rule_pack.version: latest` 解析失败

原因：

内网仓和本地缓存中都没有可用的：

openubmc-studio-rulepack

处理方式：

可以采用以下方式之一：

在 manifest.yml 中将 rule_pack.version 固定为具体版本；
预先将对应规则包放入本地缓存；
将规则包上传到内网 Conan 仓。

13.6 制品中缺少 `events/`、`sr/` 等目录

原因：

对应源文件没有出现在当前构建产物中，例如：

rootfs 中不存在 root.sr；
VPD 构建产物中不存在 event_def.json。

处理方式：

这种情况属于预期降级。

检查：

metadata.yml

中的：

archived_files:

确认其记录与实际归档内容一致。

13.7 完全离线环境中无法开始构建

原因：

虽然 metadata 默认不需要远程上传，但构建阶段仍可能需要获取：

组件 Conan 包；
规则包；
规则引擎；
其他产品依赖。

处理方式：

在进入气隙环境前，确保相关依赖已经存在于本地 Conan 缓存，或者已经通过离线方式准备完成。

14. 关键文件索引

14.1 manifest 仓

产品定义：

manifest/build/product/BMC/<board>/manifest.yml

其中包括：

base/version
tosupporte
rule_pack
rule_engine
产品组成和其他发布配置

子系统版本范围：

manifest/build/subsys/*.yml

版本锁定：

manifest/build/openubmc.lock

拓扑配置（可选，部分产品提供）：

manifest/build/product/BMC/<board>/topology-config.yml

说明：该文件并非所有产品都提供。若单板目录下不存在 topology-config.yml，归档流程会自动跳过该项，metadata.yml 的 archived_files 中也不会出现对应条目。

14.2 bingo 仓

metadata 发布核心代码：

bingo/bmcgo/tasks/task_package_metadata.py

组件模型收集：

bingo/bmcgo/tasks/task_build_conan.py

模型复制逻辑：

_copy_files()

发布流水线：

bingo/bmcgo/target/publish.yml

personal 流水线：

bingo/bmcgo/target/personal.yml

metadata 上传开关实现：

bingo/bmcgo/misc.py

15. 发布检查清单

构建前

当前位于 manifest 仓根目录；
Conan 版本为 v2；
已确认正确的 board；
已确认正确的 SupportE 码；
构建所需组件依赖可从本地缓存或配置的 remote 获取；
需要上传时，已经配置目标 Conan remote。

执行构建

下面这些都是产品固件构建命令，metadata 会作为附带产物自动产生：

本地生成（metadata 只写本地缓存）：

bingo publish \
  -b <board> \
  -sc <SupportE码>

需要把 metadata 上传内网仓共享时：

export UPLOAD_METADATA_REMOTE=<remote别名>

bingo publish \
  -b <board> \
  -sc <SupportE码>

构建后

output/mdb/ 存在且非空；
本地缓存中可以查询到 metadata；
metadata.yml 中的版本和单板信息正确；
archived_files 与实际内容一致；
需要远程共享时，远程仓中可以查询到制品；
下游机器可以成功执行 conan install。

16. 小结

产品模型 metadata 是与产品固件版本对应的一份完整模型归档。

其核心流程为：

各组件生成模型
    ↓
manifest 提供产品和版本配置
    ↓
bingo 汇聚模型与附加文件
    ↓
生成 metadata.yml 和 Conan 配方
    ↓
导出到本地缓存
    ↓
按需上传远程仓

需要记住以下几点：

metadata 是 publish 构建的附带产物，不是某个命令的目的，也不存在专门发布 metadata 的命令。
bingo publish（等价 bingo build -t publish）的本意是构建固件发布包（HPM）；metadata 只在 publish 构建时产生，-t personal 不会产生。
metadata 是纯数据 Conan 制品。
归档触发条件：Conan v2 + publish 构建（tosupporte_code 非空）+ 非空的 output/mdb/。
是否上传到远程仓只由 UPLOAD_METADATA_REMOTE 控制。
内网环境通常还需要通过 OPENUBMC_DEFAULT_CONAN_REMOTE 配置依赖来源。
metadata 不包含需要重新编译的二进制依赖，适合离线和气隙环境搬运。

如需进一步查看实现逻辑，可重点阅读：

bmcgo/tasks/task_package_metadata.py
bmcgo/tasks/task_build_conan.py
bmcgo/target/publish.yml
bmcgo/target/personal.yml

话题		回复	浏览量
sig-CICD 2026年3月第一次例会会议录屏和文字/2026-03-11 CICD SIG	2	67	2026 年3 月 12 日
BMC Studio网页一直卡在仓库部署中交流互助区提问求助	39	348	2026 年3 月 3 日
2512 LTS 环境构建成功，整包构建失败交流互助区提问求助	8	149	2026 年3 月 31 日
manifest整包构建，work.build.conan一直等待交流互助区提问求助	10	90	2026 年7 月 18 日
组件打包conan包操作交流互助区提问求助	3	98	2026 年2 月 5 日

产品模型（Metadata）归档与发布指南

产品模型（Metadata）归档与发布指南

1. 快速了解

1.1 metadata 制品是什么

1.2 使用前必须知道的三件事

2. 根据使用目标选择操作方式

3. 五分钟快速开始

3.1 准备参数

3.2 在本机生成 metadata

3.3 查看生成结果

4. metadata 制品包含什么

4.1 制品目录

4.2 metadata.yml

5. 场景一：本地生成和使用

5.1 本地生成（不上传远程仓）

5.2 完全离线环境的前提

6. 场景二：发布到内网 Conan 仓

6.1 典型场景：发布包含企业自研模型的产品

自研模型如何进入 metadata

推荐操作流程

发布前检查自研模型

发布后验证

常见问题：制品发布成功，但缺少自研模型

6.2 上传命令与配方说明

6.3 内网环境中的依赖拉取

6.4 相关环境变量

7. 场景三：气隙环境中离线搬运

7.1 在构建机生成制品

7.2 查找本地缓存位置

7.3 在无网消费机重新导入

7.4 气隙场景注意事项

8. 验证发布结果

8.1 检查本地缓存

8.2 检查远程仓

8.3 安装并检查内容

9. 下游如何使用 metadata

9.1 BMC Studio

9.2 CI 规则检查

9.3 调试器和现场工具

10. metadata 是如何生成的

10.1 manifest 与 bingo 的分工

10.2 端到端流程

10.3 模型收集

10.4 metadata 归档

11. metadata 归档的触发条件

11.1 必须使用 Conan v2

11.2 必须是 publish 构建（tosupporte_code 非空）

11.3 output/mdb/ 必须存在且非空

12. 包名和版本规则

12.1 包名格式

12.2 code 的选择优先级

13. 常见问题排查

13.1 构建日志中没有 metadata 打包信息

13.2 日志提示只在本地创建制品

13.3 上传提示 remote not found

13.4 本地能查到制品，远程仓查不到

13.5 rule_pack.version: latest 解析失败

13.6 制品中缺少 events/、sr/ 等目录

13.7 完全离线环境中无法开始构建

14. 关键文件索引

14.1 manifest 仓

14.2 bingo 仓

15. 发布检查清单

构建前

执行构建

构建后

16. 小结

相关话题

4.2 `metadata.yml`

11.2 必须是 publish 构建（`tosupporte_code` 非空）

11.3 `output/mdb/` 必须存在且非空

13.3 上传提示 `remote not found`

13.5 `rule_pack.version: latest` 解析失败

13.6 制品中缺少 `events/`、`sr/` 等目录