介绍openUBMC安装部署过程中的常见问题。

初始化常见问题 ​

在执行 python3 init.py -path /home/workspace/bmc_sdk_26.03.zip 时，可能会遇到以下失败场景。请根据错误信息对照排查。

环境检查失败 ​

网络相关失败 ​

初始化过程需要访问多个在线资源（华为云apt源、npm 淘宝镜像、openUBMC仓库等），网络不通或网络传递慢是最常见的失败或超时的原因。

问题现象：apt-get update、wget、pip install、npm install 等命令超时或返回连接错误。

解决措施：

1. 参照《开发环境初始化》中"网络配置"章节，逐一检测各资源站的连通性。

2. 检查代理配置：脚本会检测 https_proxy 环境变量，如果配置了不需要的代理，请在初始化前执行：

   shell

   unset https_proxy && unset HTTPS_PROXY

3. 如果在公司内网环境，请确认防火墙放行了《开发环境初始化》中"网络配置"章节列出的域名。

4. 如果使用 Docker 环境，检查 Docker 网络模式是否正确配置。

5. 如果使用 Windows WSL 环境，且处于受限的内部网络，或需要通过代理服务器才能访问外网资源，请在 WSL 终端中配置环境变量。

   • 临时生效（仅当前终端会话）：

     bash

     export http_proxy="http://<您的代理服务器IP>:<端口>"
     export https_proxy="http://<您的代理服务器IP>:<端口>"

   • 永久生效（写入环境变量）：

     bash

     echo 'export http_proxy="http://<您的代理服务器IP>:<端口>"' >> ~/.bashrc
     echo 'export https_proxy="http://<您的代理服务器IP>:<端口>"' >> ~/.bashrc
     source ~/.bashrc

   TIP

   如果配置代理后仍然提示 Could not resolve host，通常是 WSL 的 DNS 解析异常。请尝试修改 /etc/resolv.conf 为可用 DNS。

6. 如果你访问的软件源慢，建议配置包管理器加速源，可以参考 华为云、阿里云，以及其它云厂商或各大学提供的加速源。

gpg: keyserver 无法连接问题 ​

初始化脚本会自动配置 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

Conan 登录失败 ​

问题现象：conan remote login 命令返回认证错误。

解决措施：

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

2. 如果密码包含特殊字符，建议使用交互式输入（不传 -user 和 -psw 参数），避免 shell 转义问题。

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

4. 如果之前配置过 conan，可以尝试清除配置后重试：

   shell

   rm -rf ~/.conan2

BMC SDK 解压或安装失败 ​

问题现象：unzip 报错，或 SDK 文件解压不完整，或提示 安装 sdk 失败。

解决措施：

1. 确认 bmcsdk 文件下载完整，检查文件大小是否正常。

2. 确认 bmcsdk 版本与 manifest 代码版本一致（如 26.03）。

3. 确认文件路径正确，建议使用绝对路径。

4. 如果之前已有安装残留，手动清理后重试：

   shell

   rm -rf ~/rtos_compiler ~/sdk ~/oee_compiler ~/oee_sdk

Node.js 安装失败 ​

问题现象：n 20.18.0 或 npm install 报错。

解决措施：

1. 确认可以访问 registry.npmmirror.com。

2. 如果之前已安装 Node.js 其他版本，尝试先卸载旧版本：

   shell

   sudo apt remove -y nodejs npm

3. 检查磁盘空间是否充足：df -h。

PATH 环境变量未包含 ~/.local/bin ​

**问题现象：**初始化完成后执行 conan、n 等命令提示 command not found，但初始化过程未报错。

**可能原因：**部分工具（如 conan、Node.js 版本管理器 n）安装到 ~/.local/bin 目录，该目录不在系统默认 PATH 中。

解决措施：

手动将 ~/.local/bin 加入 PATH：

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

添加后可通过 which conan 或 which n 验证命令是否可正常访问。

权限不足 ​

问题现象：Permission denied 或写入 /usr/bin、/etc/apt/ 等目录失败。

解决措施：

1. 确认当前用户是 root 身份，且是直接root登录或使用su root登录。
2. 如果使用非 root 用户，初始化完成后需要手动配置环境变量，请参考上方"PATH 环境变量未包含 ~/.local/bin"章节。

命令超时 ​

**问题现象：**某个步骤长时间无响应后报 TimeoutExpired 或命令执行超过 600 秒自动终止。

解决措施：

1. 通常是网络问题导致下载过慢，检查网络连接速度。
2. 开启详细日志定位具体卡在哪个命令：LOG=debug python3 init.py -path /home/workspace/bmc_sdk_26.03.zip。
3. 如果是特定包下载缓慢，可考虑配置系统级代理加速。

SDK 下载 sha256 校验失败 ​

**问题现象：**在 26.06_2026.06.30 tag 下执行 python3 init.py 下载 SDK 时报错，提示下载文件的 sha256 与预期值不一致：

[ERROR] cli.py:367 下载文件 https://repo.openubmc.cn/26.06/sdk/bmc_sdk.tar.gz 校验sha256失败，预期 290625fd61fb6ff49a9bd4ec5f24234bee67e2207edb266453f6520e7c49d402， 实际 1a83c0aad37377471e50901f0a54c6d728365a963f7bcf6343bb8da395fa78ef，请检查配置！

**原因：**manifest.yml 中记录的 SDK sha256 校验值与下载源上的实际文件不一致。SDK 包在仓库侧发生过更新，而您使用的版本 tag 中的 manifest.yml 未同步更新该校验值。

**解决措施：**将本地 manifest.yml 中的 sha256 更新为当前 SDK 文件的实际哈希值。

1. 确定实际哈希值。以下两种方式二选一：

   方式一（推荐）：从官方 .sha256 文件直接获取。适用于 26.06_2026.06.30 tag 版本的 SDK SHA256 值已随 SDK 发布在如下文件中：

   shell

   curl -s https://repo.openubmc.cn/26.06/sdk/bmc_sdk.sha256 | awk '{print $1}'

   TIP

   .sha256 文件为 sha256sum 格式（哈希 + 文件名），复制时只取哈希部分；该输出应与报错信息中的「实际」值一致。

   方式二：自行下载 SDK 文件并计算 sha256：

   shell

   wget https://repo.openubmc.cn/26.06/sdk/bmc_sdk.tar.gz
   sha256sum bmc_sdk.tar.gz

   计算结果应与报错信息中的「实际」值一致。

2. 修改 manifest.yml 中的 SHA256 预期值，修改 build/product/BMC/openUBMC/manifest.yml 中的 sha256 字段为如下格式：

   yaml

   bmc_sdk_download:
     url: https://repo.openubmc.cn/26.06/sdk/bmc_sdk.tar.gz
     sha256: <上一步得到的哈希>

3. 回到manifest仓库根目录，重新执行初始化命令python3 init.py -user <用户名> -psw '<密码>'。