UBS-Engine (UBSE) 安装指南 ​

当前 UBSE 提供两种环境部署方式：RPM 包安装、容器镜像部署。环境部署流程包含以下主要步骤：

1. 环境准备与安装
2. 构建项目与单元测试
3. 运行示例与验证

环境要求 ​

节点规划 ​

• 所有集群节点均需安装 ubs-engine 主包。

• 建议提前规划节点 IP 地址列表（用于 TCP 模式）。

安装注意事项 ​

• 非高安场景下，UBSE与UBM使用UDS通信，需要将ubse用户加到ubm_nuds用户组中，该用户组由UBM服务创建，如果UBM服务未在UBSE前安装，ubse用户可能无法加入ubm_nuds用户组，导致UBSE服务与UBM服务通信异常。待UBM服务完成安装后，需手动将ubse用户加入ubm_nuds用户组。
• UBSE需要调用ubturbo接口，ubturbo接口有权限校验，需要将ubse用户加到ubturbo用户组中，该用户组由ubturbo服务创建，如果ubturbo服务未安装，ubse用户可能无法加入ubturbo用户组，导致UBSE服务调用ubturbo接口异常。待ubturbo安装完成后，需手动将ubse用户加入ubturbo用户组。

执行安装 ​

RPM 包安装 ​

在线安装

1. 安装主程序包。

   • 智算场景，执行如下命令。
   bash

   sudo env ENABLE_AI=true dnf install -y ubs-engine

   • 通算场景，执行如下命令。
   bash

   sudo dnf install -y ubs-engine
       ```

2. 安装客户端运行时库（第三方集成必需）。

   bash

   sudo dnf install -y ubs-engine-client-libs

3. 安装python 模块（可选，使用UBSE Python API时需要安装）。

   bash

   sudo dnf install -y python3-ubs-engine

离线安装

通过rpm包安装运行包。

1. 安装主程序包。

   • 智算场景，执行如下命令。
   bash

   sudo env ENABLE_AI=true dnf install -y ubs-engine-<version>-<release>.aarch64.rpm

   • 通算场景，执行如下命令。
   bash

   sudo dnf install -y ubs-engine-<version>-<release>.aarch64.rpm

2. 安装客户端运行时库（第三方集成必需）。

   bash

   sudo dnf install -y ubs-engine-client-libs-<version>-<release>.aarch64.rpm

3. 安装python 模块（可选，使用UBSE Python API时需要安装）。

   bash

   sudo dnf install -y python3-ubs-engine-<version>-<release>.aarch64.rpm

容器镜像部署（可选） ​

容器环境部署有两种方式：

• 基于镜像构建容器环境
• 基于 openEuler 基础环境从零安装

方式一：基于镜像构建容器环境 ​

基于镜像构建容器环境，首先需要获取镜像。获取镜像有两种方式：

• 直接从镜像仓库拉取预构建镜像
• 从 Dockerfile 构建镜像

步骤 1：获取镜像

选项一：直接拉取预构建镜像

docker pull swr.cn-north-4.myhuaweicloud.com/opentile/ubs-engine:24.03-sp3-1.0.1

选项二：从 Dockerfile 构建镜像

Dockerfile 位于仓库 docker/ubs-engine.Dockerfile，内容如下：

ARG BASE_IMAGE=hub.oepkgs.net/openeuler/openeuler:24.03-lts-sp3
FROM ${BASE_IMAGE}

ARG BUILD_TYPE=Release
ARG ENABLE_UT=OFF
ARG JOBS=8
ARG REPO_DIR=/workspace

COPY ubs-engine.spec /tmp/ubs-engine.spec
RUN dnf install -y "dnf-command(builddep)" \
        gcc gcc-c++ make cmake git python3 python3-pip \
    && dnf builddep -y /tmp/ubs-engine.spec \
    && dnf install -y numactl-devel gtest gtest-devel gmock gmock-devel \
        python3-setuptools util-linux-user patch bc bash coreutils sudo tar \
    && dnf clean all

WORKDIR ${REPO_DIR}
COPY . ${REPO_DIR}

RUN bash build.sh -T ${BUILD_TYPE} -j ${JOBS} \
    && if [ "${ENABLE_UT}" = "ON" ]; then \
           bash build.sh ut -j ${JOBS} \
               || echo "WARNING: unit tests FAILED, image built without UT verification"; \
       fi \
    && BUILD_DIR="cmake-build-$(echo "${BUILD_TYPE}" | tr 'A-Z' 'a-z')" \
    && cmake --install "${BUILD_DIR}" --component ubse_sdk --prefix /usr

WORKDIR ${REPO_DIR}
CMD ["/bin/bash"]

构建镜像：

cd ubs-engine
docker build -f docker/Dockerfile.openeuler -t ubs-engine:24.03-sp3-1.0.1 .

步骤 2：创建容器

以 x86_64 服务器为例，创建容器：

docker run -d --privileged --name ubs-engine-ttfhw \
    -v /home/workspace/ubs-engine-verify:/workspace \
    swr.cn-north-4.myhuaweicloud.com/opentile/ubs-engine:24.03-sp3-1.0.1 \
    sleep infinity

构建/UT 场景无需挂载 NPU 设备；镜像默认工作目录为 /workspace，不建议挂载整个 /home 目录。

步骤 3：进入容器

docker exec -it ubs-engine-ttfhw bash

方式二：基于 openEuler 基础环境从零安装 ​

不使用镜像时，可通过仓库内一键式环境配置脚本自动安装全部依赖并构建：

cd ubs-engine
bash docker/build_env.sh

脚本会安装全部构建/UT 依赖（openEuler 仓库无 ubs-comm-devel 时按《构建指导》3.1.2源码编译），并执行 Release 构建与 SDK 安装；仅安装依赖可执行 bash docker/build_env.sh --skip-build。该方式耗时较长，推荐使用方式一。

容器卸载与清理 ​

步骤 1. 停止并删除容器

docker ps -a
docker stop <container_id>
docker rm <container_id>

步骤 2. 删除镜像

docker rmi swr.cn-north-4.myhuaweicloud.com/opentile/ubs-engine:24.03-sp3-1.0.1

安装结果 ​

• ubs-engine 主程序安装结果

  路径	用途
  /usr/bin/ubse, /usr/bin/ubsectl	主程序与 CLI
  /usr/lib/systemd/system/ubse.service	systemd 服务
  /etc/ubse/	配置目录
  /var/log/ubse/	日志目录
  /var/lib/ubse/cert/	证书目录
  /var/lib/ubse/data	持久化数据
  /var/lib/ubse/lcne_cert/	高安部署证书目录
  /var/run/ubse/	运行时 socket
  /etc/sudoers.d/ubse-sei	SEI降级sysctl提权
  /lib/modules/ubse/bandbridge.ko	NPU直通虚机和LCNE进行带外通信
  /lib/modules/$(uname -r)/extra/bandbridge.ko	软链接，指向/lib/modules/ubse/bandbridge.ko

• ubs-engine 客户端运行库安装结果

  文件	其它说明
  /usr/lib64/libubse-client.so.1.0.0	二进制动态库实体
  /usr/lib64/libubse-client.so.1	软链接，指向 /usr/lib64/libubse-client.so.1.0.0

• ubs-engine Python API 包安装结果

  文件/目录	其它说明
  /usr/lib/python3.11/site-packages/ubse	内部文件（*.py）权限：644
  /usr/lib/python3.11/site-packages/ubse-xx.xx.xx-py3.11.egg-info	内部文件权限：644，Python包相关信息。

（可选）修改配置 ​

1. 编辑配置文件。

   bash

   sudo vi /etc/ubse/ubse.conf

2. 修改以下配置项(默认无此配置项，打开此配置时，使用tcp通信，否则默认使用urma通信)。

   ini

   [ubse.rpc]
   cluster.ipList=192.168.100.100-192.168.100.102

   说明

   支持配置IP地址范围，例如：192.168.100.100-192.168.100.102。 默认使用urma通信时，需已安装urma。 未配置 cluster.ipList 且未开启 URMA 特性时，UBSE 无可用建链方式，服务启动失败。 cert.use=true（默认）开启 TLS 证书认证，需导入证书；测试环境可置 false 关闭。

   ubs engine支持两种通信模式，可根据硬件和网络环境选择。

   通信方式	URMA(默认)	TCP
   性能	高性能、低延迟、零拷贝	标准 TCP，性能适中
   硬件要求	需支持 URMA 的智能网卡	普通以太网卡即可
   配置复杂度	免配置，自动发现节点	需手动配置 IP 列表
   使用场景	高性能计算、金融交易	普通数据中心、开发测试

3. 启动ubs engine服务。

   bash

   sudo systemctl start ubse
   sudo systemctl enable ubse

（可选）安装URMA ​

默认使用urma通信时需确保部署环境中已安装URMA驱动和运行时库，并开启URMA特性；如果未配置 cluster.ipList 且未开启 URMA 特性，服务将无法启动。

# 示例：安装 URMA 运行时包（具体包名根据发行版可能不同）
sudo yum install -y umdk-urma-lib    # OpenEuler
sudo yum install -y umdk-urma-kmod

安装后重启ubs engine服务。

sudo systemctl restart ubse

（可选）安装Bash Completion脚本库 ​

使用ubsectl工具进行命令补全时依赖该脚本库。

使用DNF源安装Bash Completion脚本库

1. 安装Bash Completion，根据终端交互信息提示完成安装。

   shell

   dnf install bash-completion

2. 后续如需卸载Bash Completion，可执行以下命令并根据终端交互信息完成卸载。

   shell

   dnf remove bash-completion

使用RPM包安装Bash Completion脚本库

1. 获取Bash Completion脚本库。

2. 安装Bash Completion，根据终端交互信息提示完成安装。

   shell

   rpm -ivh bash-completion-version.rpm

3. 后续如需卸载Bash Completion，可执行以下命令并根据终端交互信息完成卸载。

   shell

   rpm -e bash-completion

验证部署 ​

检查服务状态 ​

systemctl is-active ubse  # 应输出 "active"

查看日志 ​

• 方式一

  bash

  journalctl -u ubse -f

• 方式二

  bash

  /var/log/ubse/xxx

使用CLI工具 ​

sudo /usr/bin/ubsectl --help