openUBMC 26.06 版本构建指导书

本文档指导您基于 Ubuntu 24.04 LTS 搭建 openUBMC 构建环境，完成系统准备、环境初始化、工具安装、配置及构建出包的全流程。

---

目录

• 第1章 系统准备
  • 1.1 操作系统要求
  • 1.2 硬件要求
  • 1.3 网络访问要求
  • 1.4 搭建开发环境
• 第2章 环境初始化与工具安装
  • 2.1 注册社区账号
  • 2.2 Git 全局配置
  • 2.3 创建工作目录
  • 2.4 克隆 manifest 仓库
  • 2.5 SDK 下载方式说明
  • 2.6 执行一键环境初始化
  • 2.7 验证初始化结果
  • 2.8 初始化后的目录结构
  • 2.9 APT 源配置（备用）
  • 2.10 配置 PATH 环境变量
• 第3章 构建出包
  • 3.1 整包构建（HPM 升级包）
  • 3.2 构建产物
  • 3.3 组件级构建
• 第4章 常见问题排查
  • 4.1 环境检查失败
  • 4.2 环境相关失败
  • 4.3 APT 源配置失败
  • 4.4 bingo 安装失败（libcurl4t64 版本冲突）
  • 4.5 Conan 登录失败
  • 4.6 Node.js 安装失败
  • 4.7 PATH 环境变量问题
  • 4.8 权限不足
  • 4.9 命令执行超时
  • 4.10 构建失败
  • 4.11 未检测到 /opt/RTOS 目录
• 第5章 其他开发特性
  • 5.1 特性列表

---

第1章 系统准备

本章介绍 openUBMC 构建对操作系统、硬件资源和网络环境的基本要求，并提供开发环境搭建指导。

注意：本文档中所有操作（包括系统包安装、交换分区配置、环境初始化等）均需在 root 权限下执行。请使用 sudo -i 或 su - 切换到 root 身份后再继续。

1.1 操作系统要求

项目	要求
操作系统	Ubuntu 24.04 LTS 或 openEuler 24.03 LTS（当前验证基线为 LTS-SP4）
芯片架构	Ubuntu 验证基线为 x86-64（amd64）；openEuler 验证基线为 aarch64（Kunpeng）
内核版本	6.8+（Ubuntu）；openEuler 以 24.03 LTS-SP4 系统自带内核为准

系统识别说明：init.py 仅按 os-release 的系统 ID 识别并进入对应分支（Ubuntu / openEuler），不校验版本号、SP 与 CPU 架构——架构与版本适配由下游自然暴露（pip 按宿主架构选择 Wheel、deb 源架构、制品校验）。上表为当前验证与验收基线，未列组合未经验证、不在支持承诺内。

Windows 用户需要通过 Docker Desktop 或 WSL 2 部署 Ubuntu 24.04；Mac 用户需要通过 Docker Desktop 或虚拟机部署 Ubuntu 24.04。openEuler 初始化当前定位为 bootstrap 冷启动（安装 bingo 与 pre-commit 工具链）：bingo deps install、install_sdk 等后续流程由 bingo 自身命令管理，init.py 不代为执行；QEMU 与 BMC Studio 暂不覆盖。详细的开发环境搭建指导请参考：环境准备。

1.2 硬件要求

资源	最低配置	推荐配置	说明
可用内存	16 GB	32 GB+	Windows 宿主机建议 32 GB+
交换分区	32 GB	64 GB	强烈建议配置，否则易 OOM
磁盘空间	64 GB	256 GB+（SSD）	构建产生大量中间文件
网络	可访问外网	宽带连接	需下载大量依赖和源码包

1.3 网络访问要求

构建过程须访问以下资源，请确保防火墙已放行：

地址	用途
https://mirrors.huaweicloud.com	华为云镜像站
https://registry.npmmirror.com	npm 淘宝镜像
https://openubmc-apt-repo.obs.cn-north-4.myhuaweicloud.com	openUBMC APT 仓库
https://keyserver.ubuntu.com	Ubuntu GPG 密钥服务器
https://conan.openubmc.cn	Conan 包管理仓库
https://repo.openubmc.cn	openUBMC 工具仓库
https://gitcode.com	代码托管平台

验证网络连通性（在 Ubuntu 终端中执行）：

for url in \
  "https://mirrors.huaweicloud.com" \
  "https://registry.npmmirror.com" \
  "https://openubmc-apt-repo.obs.cn-north-4.myhuaweicloud.com" \
  "https://keyserver.ubuntu.com" \
  "https://conan.openubmc.cn" \
  "https://repo.openubmc.cn" \
  "https://gitcode.com"
do
  echo -n "$url: "
  curl -sL -o /dev/null -w "%{http_code}\n" --max-time 5 "$url"
done

所有地址返回 2xx 或 3xx 状态码表示连通正常；若有失败，请检查网络代理或联系管理员放行。

若下载速度慢，建议配置 apt/pip 加速源，例如华为云镜像站 https://mirrors.huaweicloud.com、阿里云镜像站 https://developer.aliyun.com/mirror/。

1.4 搭建开发环境

详细的开发环境搭建指导请参考：环境准备

原生 Ubuntu / WSL 环境

确认系统版本

cat /etc/issue

确认输出为 Ubuntu 24.04 LTS。

安装系统基础工具

sudo apt-get update
sudo apt-get install -y git python3 python3-pip python3-venv wget curl unzip \
  lsb-release apt-transport-https ca-certificates gnupg2 software-properties-common \
  libcurl4t64 libcurl4-openssl-dev pkg-config

libcurl4t64 和 libcurl4-openssl-dev 必须同步安装，否则 Ubuntu 安全更新推送新版 libcurl4t64 时会因版本严格绑定导致 libcurl4-openssl-dev 安装失败（signer 运行时依赖 libcurl）。新版 init.py 已改为 pip 安装 bingo 平台 Wheel，不再触发 bingo 的 apt 依赖解析；若环境中仍出现版本冲突（如安装其它 apt 包），可显式指定版本同步安装或降级：

# 查看 libcurl4-openssl-dev 可用的旧版本（即 init.py 所需的版本）
apt policy libcurl4-openssl-dev
# 显式指定版本同步安装（版本号以 apt policy 输出为准）
apt install -y libcurl4t64=8.5.0-2ubuntu10.9 libcurl4-openssl-dev=8.5.0-2ubuntu10.9

安装后正常运行 init.py 即可。若降级不可行，也可在 init.py 失败后手动 pip 安装：pip install openubmc-bingo --upgrade。

配置交换分区

# 检查当前交换分区
swapon --show

# 若交换不足 32 GB（最低），创建交换文件（推荐 64 GB）
sudo fallocate -l 64G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 持久化到 /etc/fstab（请先确认 fstab 中无重复 swapfile 条目）
grep -q '/swapfile' /etc/fstab || echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

云服务器厂商通常不配置或只配置少量交换分区，请务必检查并补足。

配置完成后跳至 第 2 章 — 环境初始化与工具安装 继续。

Docker 容器环境

Windows 和 Mac 用户推荐通过 Docker Desktop 使用容器进行构建。

重要：不要使用 -v 挂载宿主机目录到容器的 /home/workspace。挂载宿主机已有的 workspace 目录会导致容器继承宿主机的构建缓存和残留配置，使 init.py 的 install_sdk 步骤因路径冲突而失败。正确做法是在容器内通过 git clone 获取代码，确保容器环境干净完整。

# 拉取推荐镜像
docker pull swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu:24.04.2

# 启动容器（不挂载宿主机目录）
docker run -it --name openubmc-env \
  -w /home/workspace \
  swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu:24.04.2 \
  /bin/bash

# 容器内安装基础工具（裸镜像不含 git/python3/sudo 等，必须先装）
apt-get update && apt-get install -y python3 sudo make locales wget curl git libcurl4t64 libcurl4-openssl-dev pkg-config

容器启动并安装基础工具后，按照 第 2 章 继续操作（从 2.2 Git 全局配置开始；2.1 注册账号可在宿主机浏览器完成），注意在执行 2.6 时使用 Docker 容器非交互环境的流程。

---

第2章 环境初始化与工具安装

系统准备就绪后，按本章步骤完成账号注册、代码下载、工具安装和环境配置。

以下操作需要在 root 身份下执行，否则使用 sudo。普通用户可通过 sudo -i 或 su - 切换到 root 身份；当前用户若不在 sudo 组中，请先联系管理员将用户加入 sudo 组（usermod -aG sudo <用户名>）后重新登录。

2.1 注册社区账号

构建过程需要 Conan 包管理器登录认证，请先注册社区账号。

1. 访问 openUBMC 用户中心
2. 填写信息完成注册
3. 此账号将用于：Conan 包管理器认证、社区资源访问、bmcsdk 下载鉴权

2.2 Git 全局配置

git config --global user.name "<你的用户名>"
git config --global user.email "<你的邮箱>"

重要：提交 PR 时社区 CI 会基于此邮箱检查 CLA 签署状态，请确保与 GitCode 注册邮箱一致。

2.3 创建工作目录

后续所有代码和构建产物均放在 /home/workspace 下。

# 注意：Docker 容器中的工作目录固定为 /home/workspace
# WSL / 原生 Ubuntu 用户自行创建
mkdir -p /home/workspace
cd /home/workspace

2.4 克隆 manifest 仓库

manifest 仓库是构建的入口，管理所有子仓库的版本依赖和构建策略。

git clone https://gitcode.com/openUBMC/manifest.git
cd manifest

如果本地已有 manifest 代码，请先同步最新代码：

cd /home/workspace/manifest
git pull -r origin main

2.5 SDK 下载方式说明

26.06 版本不再需要手动下载 bmcsdk zip 包，SDK 由 manifest.yml 中的配置自动管理。产品 manifest 文件（例如：manifest/build/product/BMC/openUBMC/manifest.yml）已预置以下关键配置：

openubmc_sdk:
  conan: "openubmc_sdk/latest@openubmc/stable"

openubmc_sdk 字段指定了 SDK 的 Conan 包引用，bingo 在构建时自动通过 Conan 拉取对应版本的交叉编译器、工具链等，用户无需手动下载或解压。

平台 SDK 通过 platform 字段管理（已预置 ibmc_sdk Conan 引用），如需使用平台整包（packages_download + platform.package）方式，请参考 platform_full_package_integration_guide.md。

2.6 执行一键环境初始化

init.py 脚本自动完成工具安装与系统配置：

#	步骤	说明
1	操作系统检查	按系统 ID 识别分支（Ubuntu / openEuler，验证基线见 1.1 节；不校验版本/SP/架构）
2	系统依赖安装	Ubuntu 走既有全量链；openEuler 按最小集 dnf 安装（含 pre-commit 前置）
3	APT 源配置	添加 openUBMC 仓库和 GPG 密钥（仅 Ubuntu 分支）
4	bingo 安装	Ubuntu 走既有 deb 源 + deb 包 + pip 链；openEuler 走 pip 安装（冷启动）
5	Conan 配置与登录	安装 C/C++ 包管理器并配置远程仓库、使用社区账号登录
6	pre-commit 工具	node/stylua/luacheck 两平台必装（node 版本满足时跳过 n 链）
7	SDK/QEMU（仅 Ubuntu）	install_sdk 与 QEMU 链为 Ubuntu 既有行为；openEuler 冷启动不执行
8	环境变量配置	设置 PATH 等

BMC Studio 已移出默认初始化主链，如需安装参见「BMC Studio 手工安装」章节。

2.6.1 工具安装清单

以下为 init.py 自动安装的完整工具列表，供问题排查和环境验证参考：

工具	安装方式	包名/引用	版本/来源	说明
Conan	pip	conan=2.13.0	2.13.0	C/C++ 包管理器
bingo	Ubuntu: apt deb 源+deb 包（既有链）；openEuler: pip	openubmc-bingo	openUBMC APT 仓库 / 华为云 pypi 镜像	openUBMC 构建工具链
Node.js	Ubuntu: npm n；openEuler: dnf	-	v20.18（openEuler 源实测 20.18.2）	JavaScript 运行环境，pre-commit 依赖
npm	随 Node.js / npm	-	10.8.2	Node.js 包管理器
stylua/luacheck	npm / luarocks	@johnnymorganz/stylua-bin、luacheck rock	dailybuild.openubmc.cn	pre-commit Lua 工具，两平台必装
cangjie-runtime	apt	cangjie-runtime	openUBMC APT 仓库	仓颉语言运行时（仅 Studio 手工安装场景需要）
openubmc-qemu	apt	openubmc-qemu	openUBMC APT 仓库	QEMU 虚拟机（仅 Ubuntu；openEuler 暂不支持）
gcc/g++	apt	gcc-9, g++-9	9.x	C/C++ 编译器

BMC Studio 手工安装

init.py 不再自动安装 BMC Studio。如需使用，请在初始化完成后手工执行：

# Studio 运行依赖（含 cangjie-runtime）
sudo apt-get install -y wslu xdg-utils nginx
sudo apt install -y cangjie-runtime   # 需先配置 openUBMC APT 源
# 下载并安装 Studio deb
wget https://repo.openubmc.cn/latest/tools/BMC%20Studio.zip -O studio.zip
unzip studio.zip
sudo dpkg -i <解出的deb>
# 如依赖报错，执行修复后重试
sudo apt install -y -f
sudo dpkg -i <解出的deb>

系统依赖（通过 apt 批量安装）：

python3, python3-pip, python3-dev, git, wget, curl, ca-certificates,
ipmitool, dbus-x11, libdbus-1-dev, dbus, pkgconf, libglib2.0-dev,
gcc-9, g++-9, unzip, npm

bmcsdk 不再需要手动下载和解压，26.06 版本通过 manifest.yml 中的 openubmc_sdk 字段由 Conan 在构建时自动拉取。

常规环境（有交互终端）

所有环境（含常规终端和 Docker 容器）均建议预先设置许可证自动接受，防止 init.py 的 install_sdk 因许可证交互确认而阻塞或失败。

预设许可证自动接受（在运行 init.py 之前执行）

# 设置环境变量，让 init.py 和 install_sdk 自动接受许可证
export OPENUBMC_LICENSE=true

执行 init.py

必须指定 Conan 用户名密码，否则 Conan 登录步骤将失败。

cd /home/workspace/manifest
python3 init.py -user <用户名> -psw '<密码>'

重要：如果 init.py 执行过程中某个步骤失败，失败摘要会标注失败阶段与已完成项；在修复失败原因后，需要重新再执行一次 init.py，各阶段可安全重跑，确保所有初始化步骤均成功完成。

Docker 容器非交互环境

Docker 容器无交互终端，init.py 的 install_sdk 步骤会因许可证交互确认而 EOF 失败。必须按以下顺序逐步执行，不得跳过任何步骤：

前提：容器已按 1.4 节 Docker 环境启动并安装基础工具，并完成了 2.2（Git 全局配置）、2.3（创建工作目录）和 2.4（克隆 manifest 仓库），当前在 /home/workspace/manifest 目录下。

第 1 步：预设许可证自动接受（在运行 init.py 之前执行）

# 设置环境变量，让 init.py 和 install_sdk 自动接受许可证
export OPENUBMC_LICENSE=true

第 2 步：执行 init.py

cd /home/workspace/manifest
echo 'Y' | python3 init.py -user <用户名> -psw '<密码>'

echo 'Y' 通过管道为代理确认等交互步骤提供输入，配合第 1 步的环境变量，避免交互式确认阻塞。

第 3 步：验证初始化是否完整

init.py 可能因环境问题中断，导致部分步骤未完成。必须逐项检查：

# 检查 Conan profile 是否生成（至少应有 default、profile.dt.ini、profile.luajit.ini）
ls ~/.conan2/profiles/

# 检查 /opt/RTOS 是否存在且包含版本号目录（如 208.11.0）
ls /opt/RTOS/

# 检查 hcc 交叉编译器是否已安装
ls /opt/hcc_arm64le/

# 检查 Conan 远程仓库是否配置且可访问
conan remote list
conan search -r openubmc_opensource "*" 2>/dev/null | head -3

/opt/RTOS/ 下应存在版本号目录（如 208.11.0），/opt/hcc_arm64le/ 下应存在 aarch64-target-linux-gnu 等交叉编译工具。这两个目录是 bingo 检测构建工具和生成 Conan profile 的关键依据，缺失会导致后续构建失败。

2.7 验证初始化结果

# 检查关键工具
bingo --version
conan --version
node --version
npm --version

# 确认命令可执行
which bingo conan n node npm

若出现 command not found，刷新 PATH：

source ~/.bashrc
which bingo conan   # 再次验证

2.8 初始化后的目录结构

/home/workspace/
├── manifest/
│   ├── init.py                 # 环境初始化脚本
│   ├── build/
│   │   └── product/
│   │       └── BMC/
│   │           └── openUBMC/
│   │               ├── manifest.yml      # 产品组件清单（含 openubmc_sdk 配置）
│   │               ├── archive.ini       # 归档配置
│   │               ├── permissions.ini   # 权限配置
│   │               ├── rootfs/           # 根文件系统配置
│   │               ├── update_ext4.cfg   # 分区配置
│   │               └── version.xml       # 版本信息
│   └── output/                 # 构建产物输出目录（初始为空）

# SDK 相关目录（由 Conan 在构建时自动拉取安装）
/root/packages_download/        # 平台整包下载缓存（使用 packages_download 时）
/root/rtos_compiler/            # RTOS 交叉编译器（root 环境下 ~ 为 /root）
/root/sdk/                      # SDK 工具
/root/oee_compiler/             # OEE 交叉编译器（可选）
/root/oee_sdk/                  # OEE SDK（可选）

bmcsdk 由 Conan 在构建时自动拉取并安装到上述目录（通过 openubmc_sdk 配置），无需手动下载解压。

2.9 APT 源配置（备用）

初始化脚本会自动配置 openUBMC APT 源。如果脚本跳过此项或需要手动配置，按以下步骤操作：

# 安装 gnupg（如未安装）
apt-get update && apt-get install -y gnupg

# 创建密钥存放目录
mkdir -p /etc/apt/keyrings

# （方式一）从华为云直接下载 GPG 公钥
wget -O- https://openubmc-apt-repo.obs.cn-north-4.myhuaweicloud.com/Ubuntu/gpg_key.public \
  | gpg --dearmor -o /etc/apt/keyrings/openubmc.gpg

# （方式二）从密钥服务器导入（方式一失败时使用）
# gpg --keyserver keyserver.ubuntu.com --recv-keys BF3B2D407FDEDEA0DC91CC9412640FBCB175287A
# gpg --export BF3B2D407FDEDEA0DC91CC9412640FBCB175287A | tee /etc/apt/keyrings/openubmc.gpg >/dev/null

# 配置 apt 源
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/openubmc.gpg] https://openubmc-apt-repo.obs.cn-north-4.myhuaweicloud.com/Ubuntu/ noble main" \
  | tee /etc/apt/sources.list.d/openubmc.list

# 验证配置
apt-get update
apt policy openubmc-bingo

正确输出应包含：

openubmc-bingo:
  Installed: (none)
  Candidate: 0.0.1
  Version table:
     0.0.1 500
       500 https://openubmc-apt-repo.obs.cn-north-4.myhuaweicloud.com/Ubuntu noble/main amd64 Packages

2.10 配置 PATH 环境变量

初始化脚本会将部分工具安装到 ~/.local/bin，建议提前配置 PATH：

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

---

第3章 构建出包

本章提供两种构建场景，请根据您的需求选择对应章节，无需按章节顺序执行：

场景	说明	章节
我需要最终固件升级包（HPM）	执行产品级整包构建，产出可用于刷机的 HPM 文件	3.1 整包构建、3.2 构建产物
我只需要构建单个组件进行验证	进入组件目录执行组件级构建，产物发布到本地 Conan 缓存	3.3 组件级构建

3.1 整包构建（HPM 升级包）

HPM（Hardware Platform Management Package）是 openUBMC 的固件升级包格式。

26.06 版本支持以下产品的 HPM 包构建（产品定义见 manifest/build/product/BMC/ 目录）：

构建前请确认 Conan 已登录：bingo build 需要从 Conan 远程仓库拉取组件包，若凭证缺失或过期将导致构建失败。26.06 版本仅需登录 openubmc_opensource 远程仓库（SDK 包已包含在该远程中），请依次操作：

# 登录 Conan 远程仓库（使用 openUBMC 社区账号）
conan remote login openubmc_opensource <你的社区用户名>
# 若提示输入密码，请输入社区账号密码
# 验证登录是否生效
conan search --remote openubmc_opensource "*" 2>/dev/null | head -3

产品名	芯片类型	系统架构
openUBMC	1711	RTOS
openUBMC_1712	1712	RTOS
openUBMC_ast2600	ast2600	OEE（OpenEuler Embedded）

通过 -b 参数指定产品名，执行以下命令构建 HPM 包：

cd /home/workspace/manifest

# 构建 openUBMC（1711）产品的 HPM 包
bingo build -t personal -b openUBMC

# 也可指定其他产品
# bingo build -t personal -b openUBMC_1712
# bingo build -t personal -b openUBMC_ast2600

-t personal 表示个人构建目标（即构建 HPM 包）；-b 指定产品名，默认为 openUBMC。

构建过程：

1. 解析 manifest.yml，获取所有组件依赖清单
2. 通过 Conan 自动拉取 openubmc_sdk（交叉编译器、工具链等）
3. 安装构建工具链（根据 tools_install 策略自动选择）
4. 通过 Conan 从本地缓存或远程仓库下载各组件构建包
5. 组装 rootfs 根文件系统
6. 打包生成 HPM 固件升级文件

如需加速 C/C++ 编译，可添加 --ccache 参数。详见ccache 加速构建。

首次构建耗时较长（取决于网络速度和机器性能），后续构建会利用缓存加速。

3.2 构建产物

# 确认 HPM 包已生成
ls -lh /home/workspace/manifest/output/rootfs_openUBMC.hpm

产物路径：/home/workspace/manifest/output/rootfs_openUBMC.hpm

3.3 组件级构建

进入组件目录后，执行以下命令进行组件级独立构建：

组件源码需提前 clone 到工作目录。可通过以下方式获取：

# 方式一：使用 bingo fetch 拉取组件源码（推荐）
cd /home/workspace
bingo fetch -pi <组件包名>/<版本>@openubmc/stable -p ./source_code

# 示例：拉取 mdb_interface 组件源码
bingo fetch -pi mdb_interface/1.110.9@openubmc/stable -p ./source_code

# 方式二：手动从 GitCode clone
cd /home/workspace
git clone https://gitcode.com/openUBMC/<组件名>.git

# 示例：手动 clone mdb_interface 组件
git clone https://gitcode.com/openUBMC/mdb_interface.git

cd /home/workspace/<组件目录>

# 组件级构建，默认 dev 阶段
bingo build --stage=dev

# 构建并发布到 stable 阶段（供整包集成使用）
bingo build --stage=stable

完整命令参数：

bingo build [-h] [-bt BUILD_TYPE] [--stage STAGE] [-u] [-r REMOTE] [--conan2] [-nc] [-o OPTIONS] [--user USER] [-wb] [--ccache]

参数	说明	默认值
-bt / --build_type	构建类型，可选 debug、release	debug
--stage	包发布阶段，可选 dev、pre、rc、stable	dev
-u / --upload	上传组件包到 Conan 仓库	—
-r / --remote	Conan 仓库别名，通过 conan remote list 查看	—
--conan2	强制使用 Conan2 构建组件（用于临时兼容 Conan1/Conan2 构建场景）	—
-nc / --no_cache	强制更新 Conan 缓存依赖	—
-o / --options	定义组件选项值，如 -o Pkg/*:with_qt=True	—
--user	指定 Conan 包的 user 字段，未指定时依次尝试读取 mds/service.json，均未指定时使用 openubmc	openubmc
-wb / --without_build	不强制源码构建组件自身	—
--ccache	使用 ccache 加速 C/C++ 编译	—

构建产物发布到本地 Conan 缓存后，可在 manifest.yml 中添加组件依赖并执行整包构建集成。

# 确认组件 Conan 包已生成
conan cache path <组件名>

产物路径（Conan 本地缓存）：~/.conan2/p/<组件名>/

示例：以 mdb_interface 组件为例

cd /home/workspace/mdb_interface
bingo build --stage=dev

将新组件加入产品：编辑 manifest/build/product/BMC/openUBMC/manifest.yml，在 dependencies: 下添加：

dependencies:
  - conan: "<组件名>/<版本>@openubmc/stable"

然后重新执行 bingo build 进行整包构建。

---

第4章 常见问题排查

4.1 环境检查失败

错误信息	原因	解决方案
仅支持Ubuntu 24.04操作系统	系统版本不是 Ubuntu 24.04	cat /etc/issue 确认版本
请直接执行，不支持以sudo环境执行脚本	用了 sudo python3 init.py	用 su root 切换 root 后直接执行
xxx不存在，请检查命令或环境配置	系统缺少基础命令或 PATH 错误	确认命令已安装，检查 $PATH

4.2 网络相关失败

症状：apt-get update、wget、pip install、npm install 等命令超时或连接错误。

排查步骤：

1. 重新执行网络连通性测试（见 1.3 节）

2. 检查代理配置，根据需要取消或设置代理（常见环境变量：http_proxy、https_proxy、HTTP_PROXY、HTTPS_PROXY）；

3. 内网环境确认防火墙已放行所有必需域名

4. Docker 环境检查 Docker 网络模式

5. 配置包管理器加速源（华为云、阿里云等）

4.3 APT 源配置失败

症状：apt-get update 报 GPG 错误或仓库不可达。

排查：

# 检查 GPG 密钥
gpg --list-keys BF3B2D407FDEDEA0DC91CC9412640FBCB175287A

# 查看 openUBMC APT 源文件
cat /etc/apt/sources.list.d/openubmc.list

正确内容应包含：

deb [arch=amd64 signed-by=/etc/apt/keyrings/openubmc.gpg] https://openubmc-apt-repo.obs.cn-north-4.myhuaweicloud.com/Ubuntu/ noble main

如密钥服务器不可达，可手动从华为云下载 GPG 文件（见 2.9 节）。

4.4 bingo 安装失败（libcurl4t64 版本冲突，历史问题）

适用范围：仅旧版本 init.py（经 apt 安装 openubmc-bingo deb）。新版 init.py 已改为 pip 安装 bingo 平台 Wheel 并执行 bingo deps install，不再触发本问题；保留本节供旧环境排查。

症状：init.py 输出 openubmc-bingo下载失败，请检查apt源是否配置成功，apt 安装 openubmc-bingo 报 libcurl4-openssl-dev 依赖冲突。

原因：安装 git 或 curl 会引入 libcurl4t64 包，Ubuntu 24.04 安全更新可能推送较新版本（如 8.5.0-2ubuntu10.10），而 openubmc-bingo apt 包依赖的 libcurl4-openssl-dev 要求精确匹配的版本（如 8.5.0-2ubuntu10.9），apt 无法自动降级已安装包导致冲突。

排查与解决：

# 查看当前 libcurl4t64 版本和可用版本
apt policy libcurl4t64

# 方案一（推荐）：显式指定版本同步安装，让 apt 自动降级 libcurl4t64 配合 libcurl4-openssl-dev
apt install -y libcurl4t64=8.5.0-2ubuntu10.9 libcurl4-openssl-dev=8.5.0-2ubuntu10.9

# 方案二：单独降级 libcurl4t64，再由 init.py 安装 bingo 时自动装 libcurl4-openssl-dev
apt install -y libcurl4t64=8.5.0-2ubuntu10.9

# 方案三：手动 pip 安装 bingo（旧版 init.py 的 pip fallback 因同一 try 块被跳过）
pip install openubmc-bingo --upgrade

4.5 Conan 登录失败

症状：conan remote login 返回认证错误。

排查：

1. 确认社区账号已注册且用户名密码正确

2. 密码含特殊字符时使用交互式输入，不传 -user / -psw

3. 确认网络可访问 conan.openubmc.cn

4. 清除缓存后重新配置远程仓库并登录：

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

4.6 Node.js 安装失败

症状：n 20.18.0 或 npm install 报错。

排查：

# 卸载旧版本 Node.js
sudo apt-get remove -y nodejs npm

# 检查磁盘空间
df -h

# 确认 registry.npmmirror.com 可访问
curl -s -o /dev/null -w "%{http_code}" --max-time 5 https://registry.npmmirror.com

4.7 PATH 环境变量问题

症状：初始化完成后 conan、n、bingo 等命令提示 command not found，但初始化过程无报错。

原因：工具安装到 ~/.local/bin，该系统默认不在 PATH 中。

解决：

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

# 验证
which conan n bingo

4.8 权限不足

症状：Permission denied 或写入 /usr/bin、/etc/apt/ 目录失败。

解决：使用 su root 直接切换为 root 后执行，不要使用 sudo python3 init.py。

4.9 命令执行超时

症状：某步骤长时间无响应（超时 600 秒），提示 TimeoutExpired。

排查：

1. 通常是网络下载慢导致，检查网络连接速度

2. 开启调试日志定位卡点：

   LOG=debug python3 init.py
   

3. 特定包下载慢时配置系统级代理或加速源

4.10 构建失败

症状：bingo build 报错，产物未生成。

排查：

1. 确认初始化已完成且无报错
2. 检查 Conan 认证状态（最常见的构建失败原因）：
   • bingo build 需要从 openubmc_opensource 远程仓库拉取组件（26.06 版本的 SDK 包已合并到该远程中，不再需要单独的 openubmc_sdk 远程），若 Conan 凭证缺失或过期会报 Remote needs authentication 或 ERROR: EOF when reading a line 错误
   • 使用社区账号重新登录远程仓库：

     conan remote login openubmc_opensource <你的社区用户名>
     # 输入密码后验证
     conan search --remote openubmc_opensource "*" 2>/dev/null | head -3
     

   • 若仍然失败，清除 Conan 缓存后重新登录：

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

   • 社区账号即 openUBMC 用户中心 注册的账号，与 init.py 初始化时使用的账号相同
3. 检查磁盘空间：df -h
4. 检查内存和交换分区：free -h
5. 检查网络连接是否正常
6. 查看 bingo 构建日志定位具体错误：

   tail -50 /home/workspace/manifest/temp/log/task.log
   

4.11 未检测到 /opt/RTOS 目录

症状：执行 bingo --version 或 bingo build 时提示 未检测到/opt/RTOS目录，请正确安装构建工具（可以manifest仓执行init.py或bingo build）。

原因：bingo 安装失败导致 init.py 的后续步骤（包括 SDK 安装）被跳过，/opt/RTOS 目录未生成。最常见的 bingo 安装失败原因是 libcurl4t64 版本冲突（详见 4.4 bingo 安装失败）。

解决：

1. 先按 4.4 节 修复 bingo 安装问题，确认 bingo 可正常执行：

   bingo --version
   

2. 预设许可证自动接受（防止后续 init.py 的 SDK 安装步骤因许可证交互阻塞）：

   export OPENUBMC_LICENSE=true
   

3. 重新执行 init.py 完成 SDK 安装：

   cd /home/workspace/manifest
   python3 init.py -user <用户名> -psw '<密码>'
   

4. 验证 /opt/RTOS 已生成：

   ls /opt/RTOS/
   # 应输出版本号目录，如 208.11.0
   

---

第5章 其他开发特性

5.1 特性列表

以下开发特性不在本文档覆盖范围内，请参考对应文档获取详细指导：

特性	说明	参考文档
白牌包出包	使用 bingo wbd_build 制作白牌升级包	bingo支持白牌包出包.md
HPM 重签名	使用 bingo hpm_signer 对 HPM 包进行外层 CMS 重签名	bingo支持SignServer的HPM重签名适配.md
CCache 加速构建	使用 bingo build --ccache 加速 C/C++ 编译	bingo使能ccache特性.md
C++ 组件代码自动生成	自动生成 Interface、Proxy、Data 等 C++ 代码	C++组件代码自动生成开发指导.md
CSR 检查功能	构建时执行 CSR（Change Summary Report）合规检查	bingo支持CSR检查功能扩展详细设计说明书.md
固件完整性保护签名	为固件添加完整性保护签名	bingo支持固件完整性保护签名能力.md
SignServer CSR 整包签名	通过 SignServer 完成 CSR 整包签名和 EEPROM ECC 签名	[bingo支持SignServer的CSR整包签名和EEPROM ECC签名适配.md](https://gitcode.com/openUBMC/bingo/blob/main/docs/26.06/bingo支持SignServer的CSR整包签名和EEPROM ECC签名适配.md)
OEE 产品策略配置	OEE 产品自定义工具链安装策略	bingo支持OEE产品策略配置.md
组件批量定制	通过 manifest default_options 批量定制组件特性	bingo支持组件批量定制.md
平台整包集成	使用平台整包简化产品配置，避免组件版本冲突	platform_full_package_integration_guide.md

---

本文档基于 openUBMC 社区文档编写，更详细的场景化指导请查阅 https://www.openubmc.cn/docs/zh