在开始使用 openUBMC 之前，您需要先完成开发环境的快速搭建。快速入门推荐使用 Docker + 社区开发镜像方式：镜像已内置完整开发环境（构建工具、SDK 与依赖缓存），拉取后无需执行初始化即可直接构建，是最快、最稳定的路径。

系统环境要求（Docker 方式下为宿主机要求） ​

配置宿主机交换分区（可选，建议） ​

openUBMC 组件数量较多，编译过程内存占用大（系统要求建议交换分区 32GB）。物理内存不足时，可在宿主机上通过创建 swap 文件配置交换分区，避免编译期间因 OOM 被杀进程。以下配置命令仅适用于 Linux 宿主机；Windows（Docker Desktop/WSL2）宿主机可通过 .wslconfig 中的 swap= 配置交换分区（与 memory= 同一文件）。

通过下面的命令检查当前Swap交换分区大小，系统要求建议交换分区 32GB：

free -h

（容器创建后）检查运行中的容器是否设置了内存上限：

# 返回 0 表示未限制，返回具体数值（字节）表示已设置上限
docker inspect <容器名> --format '{{.HostConfig.Memory}}'
# 或用 docker stats 查看内存 LIMIT 列
docker stats <容器名>

以创建 4 个 8GB swap 文件（共 32GB）为例：

# 创建 4 个 8GB swap 文件并启用
for i in 1 2 3 4; do
  sudo dd if=/dev/zero of=/swapfile${i} bs=1M count=8192
  sudo chmod 600 /swapfile${i}
  sudo mkswap /swapfile${i}
  sudo swapon /swapfile${i}
done

swapon 仅在当前会话生效，重启后失效。需写入 /etc/fstab 持久化，开机自动挂载：

for i in 1 2 3 4; do
  echo "/swapfile${i} none swap sw 0 0" | sudo tee -a /etc/fstab
done

验证配置是否生效：

sudo swapon -a
swapon --show
free -h

swapon --show 能列出 4 个 swap 文件即配置成功，再用 free -h 确认 Swap 总容量为 32G。

Docker 环境检查 ​

在终端运行 docker ps：

• 能正常输出（无报错）说明 Docker 已就绪，请继续下一节；
• 报错或命令不存在，请先完成 Docker 安装，详见《Docker开发环境搭建》的"安装Docker工具"章节（Windows / Ubuntu Desktop 桌面用户装 Docker Desktop；Ubuntu Server 及其他 Linux 命令行用户装 Docker CE），安装完成后回到本页继续。

网络配置 ​

构建过程需要访问以下在线资源，需要确保网络连通。

• mirrors.huaweicloud.com - 华为云镜像
• registry.npmmirror.com - npm 淘宝镜像
• openubmc-apt-repo.obs.cn-north-4.myhuaweicloud.com - openUBMC apt 仓库
• conan.openubmc.cn - openUBMC conan 仓库
• repo.openubmc.cn - openUBMC 工具仓库

在终端中运行以下命令检查连通性（bash 命令：Linux 终端、Git Bash、WSL 中执行；Windows 用户建议在 Git Bash 或 WSL 中运行，也可跳过本检查、进入容器后再执行——容器内自带 curl）。

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

拉取镜像并创建容器 ​

拉取镜像 ​

1. 打开命令行，运行docker pull拉取镜像

   bash

   docker pull swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu:24.04.2_26.09

   说明

   镜像版本号格式为 {Ubuntu基础版本}_{openUBMC版本}，其中 Ubuntu 基础版本可能随镜像更新而变化。

2. 运行docker image ls查看镜像是否加载成功

   bash

   docker image ls

   输出示例：

   text

   IMAGE                                                            ID             DISK USAGE   CONTENT SIZE   EXTRA
   swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu:24.04.2_26.09   d4588fdb06db       13.6GB         3.33GB    U

创建容器实例 ​

1. 在主机侧创建工作文件夹，用于主机与容器间共享数据（Linux 下承载代码与构建产物；Windows 下作为与容器互传文件的通道，见下方创建容器后的说明）：

   bash

   # Linux
   sudo mkdir -p /root/workspace

   TIP

   非 root 的 Linux 用户可改用家目录：mkdir -p ~/workspace，并将下方 docker run 中 --mount 的 source=/root/workspace 替换为 source=$HOME/workspace。

   powershell

   # Windows（CMD / PowerShell 均可，与下方 windows 容器命令的挂载路径对应）
   mkdir C:\workspace

   TIP

   路径可按需更换（如 D:\workspace），更换后请同步修改下方 docker run 命令中 --mount 的 source 参数。

2. 运行docker run创建容器实例openubmc（端口映射可按需调整）：

   bash

   # linux 命令
   docker run -itd --init --pids-limit=32768 --privileged=true -p 10000:10000 -p 10022:10022 -p 10023:10023 -p 10443:10443 -p 10623:10623 --mount type=bind,source=/root/workspace,target=/home/workspace --restart=always --name openubmc swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu:24.04.2_26.09 /bin/bash
   # windows 命令
   docker run -itd --init --pids-limit=32768 --privileged=true -p 10000:10000 -p 10022:10022 -p 10023:10023 -p 10443:10443 -p 10623:10623 --mount type=bind,source=C:\workspace,target=/home/data --restart=always --name openubmc swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu:24.04.2_26.09 /bin/bash

   NOTE

   容器名具有唯一性：重复执行上述命令会产生重名冲突，需先执行 docker stop openubmc、docker rm openubmc 删除已创建的容器。 完整参数说明（--init、--pids-limit、--privileged、端口映射等）与 Windows（NTFS）文件权限注意事项，见《Docker开发环境搭建》的"创建容器实例"章节。

3. 通过docker exec -it进入容器进行操作（容器内默认即 root 用户，无需切换）：

   bash

   docker exec -it openubmc /bin/bash

   必要时，可输入exit退出容器。之后可通过docker exec -it再次进入容器。

   NOTE

   Windows 用户：Windows 容器命令将 C:\workspace 挂载到容器 /home/data，该目录用于容器与宿主机互传文件（Windows 文件系统与 Linux 存在权限模型差异，不宜作为构建目录）。代码克隆与构建产物位于容器内 /home/workspace；如需保存到宿主机，可将产物复制到 /home/data。删除容器前请注意备份。

获取代码并登录 ​

GitCode 配置 ​

openUBMC 社区使用 GitCode 管理代码，如果您需要为社区提交代码：

1. 请完成 GitCode SSH 密钥配置。

2. 注册并绑定邮箱，之后在终端中配置本地 git。

git config --global user.name <your username>
# 邮箱务必与 CLA 签署地址一致
git config --global user.email <your email>

克隆 manifest 仓库 ​

manifest 仓库是构建的入口，管理所有子仓库的版本依赖和构建策略。在容器内执行：

mkdir -p /home/workspace && cd /home/workspace
git clone https://gitcode.com/openUBMC/manifest.git
cd manifest

登录 conan ​

准备 openUBMC 社区账号（构建拉取依赖包时需登录 conan，账号同 openUBMC 社区用户名和密码）。如已有账号可直接使用，没有则先到openUBMC社区账号注册页面进行注册。

在容器内执行登录（<用户名> 为注册时绑定的手机号或自定义用户名）：

conan remote login openubmc_opensource <用户名> -p '<密码>'

问题排查 ​

构建过程中如果遇到问题，请参考《常见问题》进行排查处理。

完成后请参考《构建你的BMC》开始开发。