UB最佳实践¶

灵衢（UnifiedBus，UB）是一种面向超节点的互联协议，将 IO、内存访问和各类处理单元间的通信统一在同一互联技术体系，实现高性能数据搬移、资源统一管理、资源灵活组合、处理单元间高效协同和高效编程。

openYuanrong datasystem 现已集成对 UB 的支持，实现了分布式缓存在超节点内的硬件级加速。基于 UB 构建的全局缓存抽象，透明化了下层拓扑，使得应用能够以极简的编程方式，在超节点拓扑中实现数据直通，充分释放底层硬件性能。

源码编译安装¶

源码编译安装前请确保编译环境中具备如下软件依赖：

软件名称	版本	作用
openEuler	24.03	UB环境依赖的操作系统
UB	2.0	UB软件依赖
Python	3.9-3.11	openYuanrong datasystem的编译依赖Python环境
GCC	7.5.0+	用于编译openYuanrong datasystem的C编译器
G++	7.5.0+	用于编译openYuanrong datasystem的C++编译器
libtool	-	编译构建openYuanrong datasystem的工具
git	-	openYuanrong datasystem使用的源代码管理工具
Make	-	openYuanrong datasystem使用的编译构建工具
CMake	3.18.3+	编译构建openYuanrong datasystem的工具
patch	2.5+	openYuanrong datasystem使用的源代码补丁工具

下载源码¶

git clone https://gitcode.com/openeuler/yuanrong-datasystem.git

编译¶

默认配置下数据系统会启用异构能力的编译，需要编译环境中具备CANN依赖，如无需异构能力支持，可禁用异构能力。

编译数据系统时，请确保编译环境中的 URMA 版本与运行环境中的 URMA 版本一致，否则可能导致 UB 能力异常。可通过以下命令查看当前环境中的 URMA 版本：

rpm -qa | grep urma

启用 UB 支持

bash build.sh -M on

启用 UB，禁用异构能力

bash build.sh -M on -X off

编译成功后，会在output目录下产生如下编译产物：

output/
├── openyuanrong_datasystem-x.x.x-cp311-cp311-manylinux_2_34_x86_64.whl
└── yr-datasystem-vx.x.x.tar.gz

通过下载包编译（可选）¶

默认情况下，编译时 URMA 的头文件和共享库来自编译环境的系统路径（/usr/include、/usr/lib64），要求编译机预先安装 URMA SDK。若编译环境不便于安装 URMA SDK，可改用下载包方式：编译时从指定 URL 下载 URMA 头文件与共享库压缩包，自动定位并使用，编译产物（whl 包与 SDK 的 lib/ 目录）会内置 URMA 相关的 6 个共享库（libtpsa.so、libummu.so、liburma.so、liburma_common.so、liburma_ubagg.so、liburma-udma.so），运行环境无需再单独安装 URMA 库。

下载包的内部布局应为：

<任意顶层目录>/
├── include/
│   ├── urma_api.h
│   ├── urma_perf.h
│   └── urma_ubagg.h
└── lib/
    ├── libtpsa.so / libtpsa.so.0
    ├── libummu.so / libummu.so.0
    ├── liburma.so / liburma.so.0
    ├── liburma_common.so / liburma_common.so.0
    ├── liburma_ubagg.so / liburma_ubagg.so.0
    └── liburma-udma.so / liburma-udma.so.0

说明：压缩包内部的中间层目录名（如示例中的 umdk_lib）不做硬性要求，编译脚本会递归搜索 urma_api.h 与 liburma.so 自动定位 include 与 lib 根，头文件会被重组到 ub/umdk/urma/ 路径下以匹配源码的 #include <ub/umdk/urma/*.h>。只需保证压缩包内同时存在上述头文件与 6 个共享库即可。

CMake 编译

编辑 cmake/external_libs/urma.cmake，将 URMA_PKG_URL 与 URMA_PKG_SHA256 设置为压缩包的下载地址与 SHA256 校验值（文件顶部已有默认的空值声明，取消注释或直接修改即可）：

set(URMA_PKG_URL "https://example.com/urma_package.zip" CACHE STRING "URMA package download URL (empty = use system URMA SDK)")
set(URMA_PKG_SHA256 "<sha256-of-the-zip>" CACHE STRING "URMA package SHA256 checksum")

留空则回退到系统路径方式（默认行为）。设置后执行：

bash build.sh -M on -X off

Bazel 编译

编辑 .bazelrc，在 build:urma 段下取消注释（或新增）两行 --repo_env，填入压缩包的下载地址与 SHA256 校验值：

build:urma --repo_env=URMA_PKG_URL=https://example.com/urma_package.zip
build:urma --repo_env=URMA_PKG_SHA256=<sha256-of-the-zip>

注释掉这两行则回退到系统路径方式（默认行为）。设置后执行：

bazel build //bazel:datasystem_wheel --config=urma --config=release

安装¶

pip install output/openyuanrong_datasystem-*.whl

部署指南¶

部署前，请确保满足以下必要条件：

节点准备：须至少在 2 个已配备 UB 硬件并安装相应软件的节点上部署服务端组件。
集群依赖：openYuanrong datasystem 的集群管理功能依赖于 ETCD，因此需预先搭建并确保一个稳定可用的 ETCD 集群。

ETCD部署命令：

etcd --listen-client-urls http://0.0.0.0:2379 \
     --advertise-client-urls http://0.0.0.0:2379 &

进程部署

openYuanrong datasystem 进程部署主要通过dscli工具，在使用前请确保在两个节点中已安装 openYuanrong datasystem wheel 包。

容器内进程部署注意事项

🔔 重要提示：在拉起容器前，请挂载如下宿主机目录，确保容器内的URMA二进制文件与宿主机版本一致：

宿主机路径

容器挂载路径

/usr/bin/urma_admin

/usr/bin/urma_admin

/usr/bin/urma_perftest

/usr/bin/urma_perftest

/usr/bin/urma_sample

/usr/bin/urma_sample

/lib64/urma/

/lib64/urma/

宿主机路径	容器挂载路径
/usr/bin/urma_admin	/usr/bin/urma_admin
/usr/bin/urma_perftest	/usr/bin/urma_perftest
/usr/bin/urma_sample	/usr/bin/urma_sample
/lib64/urma/	/lib64/urma/

分别在两个节点执行如下命令：

dscli start -w --worker_address "${node_address}" --etcd_address "${etcd_address}" --enable_urma true

参数说明：

node_address：当前节点的通信地址与端口。格式为 IP:Port，例如：192.168.0.1:31501。
etcd_address：ETCD集群的访问地址列表。格式为多个 IP:Port 的逗号分隔字符串，例如：192.168.1.100:2379,192.168.1.101:2379,192.168.1.102:2379。

K8S部署

# 通过dscli获取helm chart包
dscli generate_helm_chart -o /tmp

# 通过源码获取helm chart包
git clone -b ${version} https://gitcode.com/openeuler/yuanrong-datasystem.git
cp -r yuanrong-datasystem/k8s/helm_chart/datasystem /tmp

命令运行成功后会在”/tmp”目录下生成helm chart目录。

编辑 /tmp/datasystem/values.yaml 对集群启动项进行配置：

global:
  # 其他配置项...

  imageRegistry: ""
  images:
    datasystem: "openyuanrong-datasystem:0.6.0"
  
  etcd:
    # ETCD集群地址
    etcdAddress: "192.168.1.100:2379,192.168.1.101:2379,192.168.1.102:2379"
  
  performance:
    # 开启UB能力
    enableUrma: true
  
  # 挂载URMA二进制文件，确保Pod容器内的URMA二进制文件与宿主机版本一致：
  mount:
    - hostPath: "/usr/bin/urma_admin"
      mountPath: "/usr/bin/urma_admin"
      type: FileOrCreate
    - hostPath: "/usr/bin/urma_perftest"
      mountPath: "/usr/bin/urma_perftest"
      type: FileOrCreate
    - hostPath: "/usr/bin/urma_sample"
      mountPath: "/usr/bin/urma_sample"
      type: FileOrCreate
    - hostPath: "/lib64/urma/"
      mountPath: "/lib64/urma/"

部署集群：

helm install datasystem /tmp/datasystem

部署后可以通过 kubectl 命令查看集群状态：

kubectl get pods -o wide
# NAME                   READY   STATUS       RESTARTS      AGE    IP           NODE 
# ...
# ds-worker-5cw42        1/1     Running      1 (2s ago)    13s   127.0.0.1   node1
# ds-worker-4wv63        1/1     Running      1 (10s ago)   23s   127.0.0.2   node2

快速验证¶

通过跨节点拉取数据的样例可快速验证UB的能力。

在节点1执行以下Python脚本：

from yr.datasystem import KVClient

client = KVClient("192.168.0.1:31501", 31501)
client.init()
key = "key"
expected_val = b"value"
client.set(key, expected_val)
print("[OK] Set value")

在节点2执行以下Python脚本：

from yr.datasystem import KVClient

client = KVClient("192.168.0.2:31501", 31501)
client.init()
key = "key"
expected_val = b"value"
val = client.get([key])
assert val[0] == expected_val
print("[OK] Get value")

注意：

脚本中初始化KVClient的入参需要替换为节点1/节点2服务端组件的IP和端口号。

当脚本执行完均打印OK时说明验证成功。

UB最佳实践¶

源码编译安装¶

下载源码¶

编译¶

通过下载包编译（可选）¶

安装¶

部署指南¶

快速验证¶

推荐配置¶

关闭LPI¶

开启大页内存¶

绑定NUMA节点¶