UBTurbo 安装指南 ​

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

1. 环境准备与安装
2. 构建项目与单元测试

环境要求 ​

节点规划 ​

• UBTurbo 为节点内资源管理框架，单节点独立部署即可，不依赖集群组网。

• 如需与 UBS-Engine（UBSE）配合使用，建议先安装 UBTurbo，再将 UBSE 的 ubse 用户加入 ubturbo 用户组（见“安装注意事项”）。

• SMAP 为必须安装的组件，需提前规划对应前置依赖（见“安装SMAP”）；RMRS 内存迁移能力为可选插件，如需使用请规划其前置依赖。

安装注意事项 ​

• UBTurbo RPM 包安装时会通过安装脚本自动创建 ubturbo 系统用户和用户组（登录shell为 /sbin/nologin），无需手动创建。
• UBSE 需要调用 UBTurbo 接口，UBTurbo 接口有权限校验，需要将 ubse 用户加到 ubturbo 用户组中，该用户组由 UBTurbo 服务创建。如果 UBTurbo 服务未在 UBSE 前安装，ubse 用户可能无法加入 ubturbo 用户组，导致 UBSE 服务调用 UBTurbo 接口异常。待 UBTurbo 安装完成后，需手动执行 sudo usermod -aG ubturbo ubse 将 ubse 用户加入 ubturbo 用户组。
• SMAP 为 UBTurbo 必须安装的组件，需安装 ubturbo-smap 包并按 SMAP 安装流程加载驱动，才能启动 ubturbo 服务（安装包只部署文件，不插入驱动，见“安装SMAP”）。
• /dev/shm/smap_config 保存了 NUMA 和进程配置等信息，如果 UBTurbo 进程需要切换用户，则需要先删除该文件。
• /dev/shm/ubturbo_page_type.dat 保存了 SMAP 的初始化类型信息，如果 UBTurbo 进程需要切换用户或者场景（例如虚拟化场景切换到大数据场景），则需要先删除该文件。
• UBTurbo 默认不启用任何插件，需依据业务场景在 ubturbo_plugin_admission.conf 中打开插件（取消对应插件的注释）。打开插件前，需保证插件的动态库和配置文件已分别放置在 /opt/ubturbo/lib 和 /opt/ubturbo/conf 下，否则 UBTurbo 及对应插件将启动异常。

执行安装 ​

• 在线安装

  说明

  在线安装过程中，所需依赖会自动进行安装。 需要系统已配置包含 ubturbo 组件的 openEuler 镜像源。

  bash

  # ubturbo 为主框架包，ubturbo-rmrs 为 RMRS 插件包（依赖 ubturbo）
  # dnf 会自动解析依赖并一并安装
  sudo dnf install -y ubturbo ubturbo-rmrs

• 离线安装

  说明

  离线安装需要提前安装所需依赖。 UBTurbo 运行依赖信息记录在 spec 文件（ubturbo.spec）中。 运行依赖所需系统库，通常由包管理器自动安装。

  bash

  # 通过rpm包安装运行包
  # 先安装主框架包 ubturbo，再安装 RMRS 插件包 ubturbo-rmrs
  sudo rpm -ivh ubturbo-<version>-<release>.aarch64.rpm
  sudo rpm -ivh ubturbo-rmrs-<version>-<release>.aarch64.rpm
  # 如需覆盖安装，可执行如下命令：
  sudo rpm -ivh ubturbo-<version>-<release>.aarch64.rpm ubturbo-rmrs-<version>-<release>.aarch64.rpm --force

容器镜像部署（可选） ​

容器环境部署方式：

• 基于镜像构建容器环境

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

基于镜像构建容器环境，首先需要获取镜像。通过 Dockerfile 预先将全部构建依赖安装进镜像，后续进入容器即可直接编译，无需重复安装工具链，节省环境准备时间。

步骤 1：获取镜像

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

docker pull swr.cn-north-4.myhuaweicloud.com/ubscore/ubturbo:24.03-lts

选项二：基于 Dockerfile 构建镜像

Dockerfile 位于仓库 docker/ubturbo.Dockerfile，内容如下：

ARG BASE_IMAGE=openeuler/openeuler:24.03-lts
FROM ${BASE_IMAGE}

RUN dnf install -y \
        make gcc gcc-c++ cmake ninja-build dos2unix \
        chrpath patchelf findutils git \
        libboundscheck libvirt-devel \
    && dnf clean all \
    && rm -rf /var/cache/dnf

WORKDIR /workspace
CMD ["/bin/bash"]

构建镜像：

cd ubturbo
docker build -f docker/ubturbo.Dockerfile -t ubturbo-build:24.03-lts .

步骤 2：创建容器

以 aarch64 服务器为例，创建容器（源码目录以数据卷方式挂载到 /workspace）：

docker run -d --privileged --name ubturbo-build \
    -v /home/workspace/ubturbo:/workspace \
    ubturbo-build:24.03-lts \
    sleep infinity

步骤 3：进入容器

docker exec -it ubturbo-build bash

构建项目与单元测试 ​

进入容器后，在 /workspace 下执行：

cd /workspace
git submodule update --init --recursive
./build.sh              # Release 构建，产物 dist/release/
./build.sh -D           # Debug 构建
./build.sh ubturbo      # 基于 ubturbo.spec 通过 rpmbuild 构建 ubturbo RPM，产物 output/
./build.sh ubturbo-rmrs # 构建 ubturbo-rmrs RPM，产物 output/

单元测试：

./build.sh -t test      # 编译并运行全部 UT，生成覆盖率报告

详细用法见仓内 README.md。

安装结果 ​

UBTurbo 安装结果（ubturbo 为主框架包，ubturbo-rmrs 为 RMRS 插件包）：

• UBTurbo 客户端运行库安装结果：

  文件	其它说明
  /usr/lib64/libubturbo_client.so	客户端 SDK 动态库，供外部进程通过 IPC 访问 UBTurbo，属主 ubturbo:ubturbo，权限 550

• SMAP 安装结果（ubturbo-smap 为必须安装的组件包）：

  路径	所属包	用途
  /usr/lib64/libsmap.so	ubturbo-smap	SMAP 用户态库
  /lib/modules/smap/	ubturbo-smap	SMAP 内核模块目录（tracking、tiering 等）
  /etc/udev/rules.d/99-smap.rules	ubturbo-smap	设备权限 udev 规则

  说明

  安装完成后，安装脚本已自动执行 systemctl enable ubturbo.service，服务已设置为开机自启，无需重复配置。

安装SMAP ​

SMAP（分级内存）为 UBTurbo 必须安装的组件，未安装 SMAP 包或未加载 SMAP 驱动时，UBTurbo 服务将启动失败（日志提示 Start module failed, name:Smap）。需在启动 ubturbo 服务前完成 SMAP 的安装与驱动加载。

1. 查询 SMAP 包是否已安装：

rpm -qa | grep ubturbo-smap

若返回如下信息，表示安装成功。

[root@controller ~]# rpm -qa | grep ubturbo-smap
ubturbo-smap-*.aarch64

2. 如未安装，执行如下命令安装：

# 在线安装
sudo dnf install -y ubturbo-smap

# 或离线安装
sudo rpm -ivh ubturbo-smap-<version>-<release>.aarch64.rpm

3. 安装完成后，按 SMAP 自身安装流程插入驱动（按顺序加载内核模块）。

4. 若 ubturbo 服务已在运行，需重启服务使 SMAP 生效：

sudo systemctl restart ubturbo

（可选）修改配置 ​

1. 编辑主配置文件：

   bash

   sudo vi /opt/ubturbo/conf/ubturbo.conf

2. UBTurbo 主配置说明：

   参数	说明	取值
   log.level	日志等级	默认值：INFO，取值范围：DEBUG、INFO、WARN、ERROR、CRIT

3. 按业务场景启用插件：

   bash

   sudo vi /opt/ubturbo/conf/ubturbo_plugin_admission.conf

   ini

   # code 必须大于200
   rmrs=777
   #turbo_ucache=778

   说明

   只有在该准入配置中配置的插件才会被加载并初始化，未配置的插件不予加载。 配置中 key 对应插件的插件名称，value 为插件初始化时使用的 moduleCode（唯一值）。 RMRS 插件自身的详细配置见 plugin_rmrs.conf，参数说明参见 RMRS 插件用户指南。

4. 启动 ubturbo 服务

   bash

   sudo systemctl start ubturbo

   说明

   启动前需确保已完成“安装SMAP”章节中的包安装与驱动加载，否则服务将启动失败。

验证部署 ​

检查安装结果 ​

rpm -qa | grep ubturbo  # 应输出 ubturbo-*.aarch64、ubturbo-rmrs-*.aarch64 与 ubturbo-smap-*.aarch64
lsmod | grep smap       # 应输出已加载的 SMAP 内核模块（如 smap_tracking_core、smap_tiering 等）

检查服务状态 ​

systemctl is-active ubturbo  # 应输出 "active"
ps -ef | grep ub_turbo_exec  # 观察进程是否存在

查看日志 ​

• 方式一

  bash

  journalctl -u ubturbo -f

• 方式二

  bash

  /var/log/ubturbo/ubturbo.log

  启动成功的标志：日志中出现 TurboMain::Run end.

检查插件加载 ​

cat /var/log/ubturbo/ubturbo.log | grep "loaded successfully"

卸载与清理 ​

1. 停止并删除容器

   bash

   docker ps -a
   docker stop ubturbo-build
   docker rm ubturbo-build

2. 删除镜像

   bash

   docker rmi ubturbo-build:24.03-lts

3. 卸载 RPM 包

   bash

   sudo dnf remove -y ubturbo-smap ubturbo-rmrs ubturbo