打包指南

本指南介绍如何为鹤思构建和安装 RPM 和 DEB 软件包。

概述

鹤思提供预构建软件包，便于在生产系统上轻松部署。软件包分为后端（控制和计算守护进程）和前端（CLI 工具和插件）组件，每个组件使用针对其技术栈优化的不同构建系统。

软件包概览

鹤思提供四个主要软件包：

软件包	组件	描述	构建系统
cranectld	后端	管理节点的控制守护进程	CPack (CMake)
craned	后端	计算节点的执行守护进程	CPack (CMake)
cranesched-frontend	前端	CLI 工具和 cfored 守护进程	GoReleaser
cranesched-plugin	前端	插件守护进程和插件库	GoReleaser

安装路径

所有软件包遵循 FHS（文件系统层次结构标准）约定：

• 二进制文件：/usr/bin/
• 库/插件：/usr/lib/ 或 /usr/lib64/
• Systemd 服务：/usr/lib/systemd/system/
• 配置文件：/etc/crane/
• 运行时数据：/var/crane/

后端软件包

后端软件包主要为使用 C++ 编写的核心组件。

构建

前置条件

在构建后端软件包之前，请确保您具备：

1. 已构建鹤思后端 - 按照部署指南中描述的构建过程完成
2. CMake 3.24+ - 软件包生成所需
3. RPM 工具（用于 RPM 软件包）：

   # Rocky/CentOS/Fedora
   dnf install -y rpm-build
   

4. DEB 工具（用于 DEB 软件包）：

   # Debian/Ubuntu
   apt-get install -y dpkg-dev
   

构建过程

导航到您的构建目录并确保项目已正确配置：

cd CraneSched/build

# 对于 CGroup v1（默认）
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ..

# 对于 CGroup v2
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCRANE_ENABLE_CGROUP_V2=true ..

# 构建项目
cmake --build .

# 生成软件包
cpack -G "RPM;DEB"

成功构建后，软件包将位于您的构建目录中：

ls -lh *.rpm *.deb

预期输出：

CraneSched-1.1.2-Linux-x86_64-cranectld.rpm
CraneSched-1.1.2-Linux-x86_64-craned.rpm
CraneSched-1.1.2-Linux-x86_64-cranectld.deb
CraneSched-1.1.2-Linux-x86_64-craned.deb

安装

cranectld 软件包

在控制/管理节点上安装：

基于 RPM 的系统：

sudo rpm -ivh CraneSched-*-cranectld.rpm
# 或更新
sudo rpm -Uvh CraneSched-*-cranectld.rpm

基于 DEB 的系统：

sudo dpkg -i CraneSched-*-cranectld.deb

软件包内容：

• /usr/bin/cranectld - 控制守护进程二进制文件
• /usr/lib/systemd/system/cranectld.service - Systemd 服务
• /etc/crane/config.yaml.sample - 配置模板
• /etc/crane/database.yaml.sample - 数据库配置模板

craned 软件包

在计算节点上安装：

基于 RPM 的系统：

sudo rpm -ivh CraneSched-*-craned.rpm
# 或更新
sudo rpm -Uvh CraneSched-*-craned.rpm

基于 DEB 的系统：

sudo dpkg -i CraneSched-*-craned.deb

软件包内容：

• /usr/bin/craned - 执行守护进程二进制文件
• /usr/libexec/csupervisor - 作业步骤执行守护进程
• /usr/lib/systemd/system/craned.service - Systemd 服务
• /etc/crane/config.yaml.sample - 配置模板
• /usr/lib64/security/pam_crane.so - PAM 身份验证模块

安装后操作

两个软件包都会自动：

1. 创建 crane 系统用户（如果不存在）
2. 创建具有适当权限的 /var/crane 目录
3. 创建 /etc/crane 目录
4. 复制示例配置文件（如果不存在）
5. 设置适当的文件所有权和权限

安装后，配置 /etc/crane/config.yaml 和 /etc/crane/database.yaml（用于 cranectld），然后启动服务：

# 在控制节点上
systemctl enable --now cranectld

# 在计算节点上
systemctl enable --now craned

对于需要锁定大量内存的作业，建议在所有计算节点为 craned.service 配置无限制的 memlock。启动 craned 前创建 systemd drop-in：

sudo mkdir -p /etc/systemd/system/craned.service.d
sudo tee /etc/systemd/system/craned.service.d/override.conf >/dev/null <<'EOF'
[Service]
LimitMEMLOCK=infinity
EOF
sudo systemctl daemon-reload

前端软件包

前端软件包主要为 Golang 编写的 CLI 工具和插件。

构建

前置条件

构建前端软件包需要 Golang 1.24+、Protoc 30.2+ 和 GoReleaser v2。以下命令以 x86-64 环境为例；ARM64 环境需要将下载文件名中的架构改为 arm64 或 aarch_64。

安装 Golang 和 Protocol Buffers 的 Go 代码生成插件：

GOLANG_TARBALL=go1.25.4.linux-amd64.tar.gz
curl -L https://go.dev/dl/${GOLANG_TARBALL} -o /tmp/go.tar.gz
rm -rf /usr/local/go
tar -C /usr/local -xzf /tmp/go.tar.gz
rm /tmp/go.tar.gz

cat > /etc/profile.d/go.sh <<'EOF'
export GOPATH=/root/go
export PATH=$GOPATH/bin:/usr/local/go/bin:$PATH
EOF
source /etc/profile.d/go.sh

go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.cn,direct
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

安装 Protoc：

PROTOC_ZIP=protoc-33.1-linux-x86_64.zip
curl -L https://github.com/protocolbuffers/protobuf/releases/download/v33.1/${PROTOC_ZIP} -o /tmp/protoc.zip
unzip /tmp/protoc.zip -d /usr/local
rm /tmp/protoc.zip /usr/local/readme.txt

安装 GoReleaser：

go install github.com/goreleaser/goreleaser/v2@latest

确认工具均可用：

go version
protoc --version
goreleaser --version

构建过程

# 克隆前端仓库
git clone https://github.com/PKUHPC/CraneSched-FrontEnd.git
cd CraneSched-FrontEnd

# 构建软件包
make package

软件包将在 build/dist/ 中生成：

ls build/dist/*.rpm build/dist/*.deb

预期输出：

cranesched-frontend_1.1.2_amd64.rpm
cranesched-plugin_1.1.2_amd64.rpm
cranesched-frontend_1.1.2_amd64.deb
cranesched-plugin_1.1.2_amd64.deb

软件包版本由仓库根目录中的 VERSION 文件确定。

软件包内容

cranesched-frontend 软件包

• /usr/bin/ 中的 CLI 工具：

  • cacct、cacctmgr、calloc、cbatch、ccancel、ccon、ccontrol
  • ceff、cfored、cinfo、cqueue、crun、cwrapper

• /usr/lib/systemd/system/cfored.service - 前端守护进程服务

cranesched-plugin 软件包

• /usr/bin/cplugind - 插件守护进程

• /usr/lib/crane/plugin/ 中的插件共享对象：

  • dummy.so - 测试插件
  • mail.so - 作业电子邮件通知
  • monitor.so - 资源使用指标收集
  • trace.so - TraceHook 接收与 trace span 写入
  • powerControl.so - 电源管理

• /usr/lib/systemd/system/cplugind.service - 插件守护进程服务

生成软件包后，请按照前端组件部署指南将软件包安装到相应节点，并启用 cfored 和 cplugind 服务。

下载预构建软件包

您可以从 GitHub Action Artifacts 中下载预构建的软件包。但是，CI 预构建的软件包仅作为测试目的，我们建议在生产环境中自行构建以确保兼容性。

后续步骤

• 后端软件包：按照多节点部署分发并安装到控制节点和计算节点。
• 前端软件包：按照前端组件部署指南安装到登录节点和需要插件功能的节点。