CentOS 8 安装 Apache SystemDS 3.4.0 指南
CentOS 8 实机实测的 Apache SystemDS 3.4.0 部署指南，覆盖 dnf 安装 OpenJDK 17、官方包下载校验、环境变量配置与单机模式线性回归验证，含 jps 工具补装、堆内存限制、常见报错处理与卸载步骤。
CentOS 8 安装 Apache SystemDS 3.4.0 指南
一、环境信息
本文所有命令与回显均在以下环境中实测采集，读者可按相同版本对照：
| 项目 | 值 |
|---|---|
| 操作系统 | CentOS Linux 8（root 用户） |
| SystemDS 版本 | 3.4.0（Apache 官方当前最新稳定版，2026-07-24 发布） |
| JDK | OpenJDK 17.0.1（java-17-openjdk-headless，el8_5） |
| 包管理器 | dnf 4.4.2 |
| 安装路径 | /opt/systemds-3.4.0 |
| 运行模式 | singlenode 单机模式（本地 Java 进程执行，不依赖集群） |
| 包大小 | systemds-3.4.0-bin.tgz 约 123 MB |
二、前置条件
- 一台 CentOS 8 服务器，具备 root 权限；
- 服务器可访问公网（用于访问 downloads.apache.org），本文实测直连正常；
- 磁盘剩余空间不低于 2 GB（安装包 123 MB，解压后约 500 MB，另需工作目录存放数据）；
- 内存不低于 2 GB。本文将 JVM 堆限制在 256-512 MB，以适配小规格机器与演示场景；
- wget、curl 等基础工具随部署步骤安装。
SystemDS 3.4.0 官方要求 Java 8 及以上，实测采用系统源中的 OpenJDK 17 全流程验证通过；JDK 11 亦为常见选择。
三、版本选型说明
访问 Apache 官方下载页 https://downloads.apache.org/systemds/，当前提供的版本包括 1.2.0 至 3.4.0 多个发布线，其中 3.4.0 为最新发布版本（downloads.apache.org 仅保留当前发布线，历史版本会移至 archive.apache.org）。
3.4.0 提供两类二进制包：
| 包名 | 说明 |
|---|---|
| systemds-3.4.0-bin.tgz | Linux 下推荐使用的 tar.gz 包（本文采用） |
| systemds-3.4.0-bin.zip | Windows 常用的 zip 包 |
| systemds-3.4.0-javadoc.jar | API 文档包 |
每个包均附带 .sha512、.sha1、.md5 校验文件与 .asc 签名文件，生产环境建议至少完成 sha512 校验。
需要注意两点：其一，3.4.0 解压后的顶层目录名为 systemds-3.4.0-bin，与旧版本惯例不同，需统一重命名（见 4.4 节）；其二，CentOS 8 的 java-17-openjdk-headless 包不含 jps 工具，若需按本文 4.8 节验证 JVM 进程参数，需另行安装 java-17-openjdk-devel（见 4.2 节）。
四、部署步骤
4.1 安装基础工具
以 root 执行：
dnf install -y curl wget
实测回显（节选）：
Dependencies resolved.
Complete!
4.2 安装 OpenJDK 17
dnf install -y java-17-openjdk-headless
实测回显（节选，列出部分关键依赖包）：
Installing:
java-17-openjdk-headless x86_64 1:17.0.1.0.12-2.el8_5
Complete!
验证版本：
java -version
实测回显：
openjdk version "17.0.1" 2021-10-19 LTS
OpenJDK Runtime Environment 21.9 (build 17.0.1+12-LTS)
OpenJDK 64-Bit Server VM 21.9 (build 17.0.1+12-LTS, mixed mode, sharing)
确认 JDK 安装路径：
ls -d /usr/lib/jvm/java-17*
实测回显：
/usr/lib/jvm/java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64
补装 jps 工具（CentOS 8 的 headless 包不含 jps，位于 devel 包中）：
dnf install -y java-17-openjdk-devel
实测回显（节选）：
Complete!
jps -V
实测回显：
1164 systemds-3.4.0.jar
1288 Jps
4.3 下载官方二进制包并校验
cd /tmp
wget https://downloads.apache.org/systemds/3.4.0/systemds-3.4.0-bin.tgz
实测回显（节选）：
--2026-10-12 05:38:00-- https://downloads.apache.org/systemds/3.4.0/systemds-3.4.0-bin.tgz
HTTP request sent, awaiting response: 200 OK
Length: 129291520 (123M) [application/x-gzip]
Saving to: 'systemds-3.4.0-bin.tgz'
systemds-3.4.0-bin.tgz 100%[===============================>] 123.32M 10.9MB/s in 25s
'/tmp/systemds-3.4.0-bin.tgz' saved [129291520/129291520]
校验 sha512（与官方 .sha512 文件逐字比对）：
sha512sum /tmp/systemds-3.4.0-bin.tgz
实测回显：
f6dd2fed83d5480558a6a778dbbff1c5034c77399d39f5f5e24a49416e78fb47fe4bd850f067b3ae8b5f3bf90fa244d29b419f70e197e77e77c6172c1e865868 /tmp/systemds-3.4.0-bin.tgz
curl -s https://downloads.apache.org/systemds/3.4.0/systemds-3.4.0-bin.tgz.sha512
实测回显（两者一致即校验通过）：
f6dd2fed83d5480558a6a778dbbff1c5034c77399d39f5f5e24a49416e78fb47fe4bd850f067b3ae8b5f3bf90fa244d29b419f70e197e77e77c6172c1e865868 /tmp/systemds-3.4.0-bin.tgz
4.4 解压到 /opt 并统一目录名
tar -xzf /tmp/systemds-3.4.0-bin.tgz -C /opt/
3.4.0 解压后的顶层目录为 systemds-3.4.0-bin，重命名为标准目录：
mv /opt/systemds-3.4.0-bin /opt/systemds-3.4.0
查看目录结构：
ls /opt/systemds-3.4.0/
实测回显：
LICENSE
NOTICE
README.md
bin
conf
lib
scripts
systemds-3.4.0.jar
各子目录用途：
| 路径 | 用途 |
|---|---|
| bin/systemds | 命令行启动脚本（唯一可执行入口） |
| conf/SystemDS-config.xml | 默认配置文件 |
| conf/log4j.properties | 日志配置 |
| lib/ | 依赖库（含内置的 hadoop 相关库） |
| scripts/ | 官方 DML 算法与工具脚本（builtin 线性回归、utils 数据生成等） |
| systemds-3.4.0.jar | 主程序 jar 包 |
4.5 配置环境变量
创建 profile 片段（root 登录后自动加载）：
cat > /etc/profile.d/systemds.sh << 'EOF'
export SYSTEMDS_ROOT=/opt/systemds-3.4.0
export SYSTEMDS_JAR_FILE=/opt/systemds-3.4.0/systemds-3.4.0.jar
export SYSTEMDS_STANDALONE_OPTS="-Xms256m -Xmx512m"
export PATH=$SYSTEMDS_ROOT/bin:$PATH
EOF
三个变量的作用：
| 变量 | 作用 |
|---|---|
| SYSTEMDS_ROOT | 安装根目录，systemds 脚本据此定位 jar、conf、scripts |
| SYSTEMDS_JAR_FILE | 显式指定主 jar 路径，可规避 3.4.0 启动脚本查找 jar 的缺陷（见 4.6） |
| SYSTEMDS_STANDALONE_OPTS | 传给 JVM 的参数，此处将堆内存限定为初始 256 MB、最大 512 MB |
使配置生效并验证：
source /etc/profile.d/systemds.sh
echo $SYSTEMDS_ROOT
which systemds
实测回显：
/opt/systemds-3.4.0
/opt/systemds-3.4.0/bin/systemds
4.6 首次运行验证
编写一个最简 DML 脚本（DML 是 SystemDS 的类 R 语言脚本）：
echo 'print("hello systemds on centos");' > /tmp/hello.dml
systemds -f /tmp/hello.dml
实测回显（节选）：
# SYSTEMDS_ROOT= /opt/systemds-3.4.0
# SYSTEMDS_JAR_FILE= /opt/systemds-3.4.0/systemds-3.4.0.jar
# SYSDS_EXEC_MODE= singlenode
# CONFIG_FILE= -config /opt/systemds-3.4.0/conf/SystemDS-config.xml
# LOG4JPROP= -Dlog4j.configuration=file:/opt/systemds-3.4.0/conf/log4j.properties
# HADOOP_HOME= /opt/systemds-3.4.0/lib/hadoop
#
WARNING: Using incubator modules: jdk.incubator.vector
26/10/12 05:38:08 WARN util.NativeCodeLoader: Unable to load native-hadoop library for your platform, using builtin-java classes where applicable
hello systemds on centos
SystemDS Statistics:
Total execution time: 0.013 sec.
输出中出现 hello systemds on centos 即安装成功。两条 WARN 属正常现象：incubator 提示来自 Java 17 向量模块；NativeCodeLoader 警告表示使用内置 Java 类代替本地 hadoop 库，不影响单机模式。
若此处出现 Error: Unable to access jarfile org.apache.sysds.api.DMLScript，说明未设置 SYSTEMDS_JAR_FILE，这是 3.4.0 启动脚本在已安装目录下查找 jar 时的一个缺陷，按 4.5 节补上该变量并重新 source 即可。
4.7 运行官方脚本完成线性回归验证
创建工作目录，先使用官方 scripts/utils/generateData.dml 生成 1000 行 x 10 列的模拟数据：
mkdir -p /opt/systemds-work
systemds -f $SYSTEMDS_ROOT/scripts/utils/generateData.dml -nvargs R=1000 C=10 S=1.0 Min=0.0 Max=10.0 Pdf=normal Path=/opt/systemds-work/X.csv Fmt=csv
实测回显（节选）：
SystemDS Statistics:
Total execution time: 0.163 sec.
wc -l /opt/systemds-work/X.csv
实测回显：
1000 /opt/systemds-work/X.csv
编写脚本生成带真值系数的标签 y（真实权重为 2.5、1.5、3.0、0.0、1.0、2.0、0.5、1.2、0.8、1.1，截距 5.0，附加噪声）：
cat > /opt/systemds-work/genY.dml << 'EOF'
X = read("/opt/systemds-work/X.csv");
w = matrix("2.5 1.5 3.0 0.0 1.0 2.0 0.5 1.2 0.8 1.1", rows=10, cols=1);
y = X %*% w + 5.0 + rand(rows=nrow(X), cols=1, min=-1, max=1, pdf="uniform");
write(y, "/opt/systemds-work/y.csv", format="csv");
print("y generated, rows=" + nrow(y));
EOF
systemds -f /opt/systemds-work/genY.dml
实测回显（节选）：
y generated, rows=1000
Total execution time: 0.234 sec.
编写训练脚本，调用官方内置的 lm（线性回归）函数：
cat > /opt/systemds-work/train.dml << 'EOF'
X = read("/opt/systemds-work/X.csv");
y = read("/opt/systemds-work/y.csv");
B = lm(X=X, y=y, icpt=1);
write(B, "/opt/systemds-work/B.csv", format="csv");
print("=== learned coefficients ===");
print(toString(B));
EOF
systemds -f /opt/systemds-work/train.dml
实测回显（节选）：
Calling the Direct Solver
=== learned coefficients ===
2.513
1.508
3.001
0.001
0.993
1.974
0.509
1.204
0.810
1.103
4.927
SystemDS Statistics:
Total execution time: 0.313 sec.
学到的 10 个系数与截距 4.927 与真值高度吻合（数据含噪声存在小偏差属正常），说明 SystemDS 在 256-512 MB 堆限制下可完整完成训练流程。
4.8 验证 JVM 堆内存限制
SYSTEMDS_STANDALONE_OPTS 是修改堆内存的唯一入口（脚本内默认值为 -Xmx4g -Xms4g -Xmn400m，被环境变量覆盖）。运行一个耗时较长的数据生成任务，同时在另一终端采集进程参数：
systemds -f $SYSTEMDS_ROOT/scripts/utils/generateData.dml -nvargs R=800000 C=20 S=1.0 Min=0.0 Max=10.0 Pdf=normal Path=/opt/systemds-work/bigX.csv Fmt=csv
任务运行期间执行：
jps -v | grep -i systemds
实测回显（节选）：
1370 systemds-3.4.0.jar -Xms256m -Xmx512m --add-modules=jdk.incubator.vector --add-opens=java.base/java.nio=ALL-UNNAMED -Dlog4j.configuration=file:/opt/systemds-3.4.0/conf/log4j.properties
ps -ef | grep "[j]ava -Xms256m"
实测回显（节选，仅保留一行）：
root 1370 1 99 05:40 ? 00:00:06 java -Xms256m -Xmx512m --add-modules=jdk.incubator.vector --add-opens=java.base/java.nio=ALL-UNNAMED -Dlog4j.configuration=file:/opt/systemds-3.4.0/conf/log4j.properties -jar /opt/systemds-3.4.0/systemds-3.4.0.jar -w 9090 -config /opt/systemds-3.4.0/conf/SystemDS-config.xml
-Xms256m -Xmx512m 明确出现在命令行中，堆限制生效。同时每次运行日志都会打印内存预算调整提示：
26/10/12 05:38:20 WARN utils.SettingsChecker: Low memory budget of total: 31 GB set to: 512 MB
五、配置说明
5.1 环境变量配置
全部环境变量集中在 /etc/profile.d/systemds.sh，逐项说明：
| 变量 | 实测值 | 说明 |
|---|---|---|
| SYSTEMDS_ROOT | /opt/systemds-3.4.0 | 安装根目录 |
| SYSTEMDS_JAR_FILE | /opt/systemds-3.4.0/systemds-3.4.0.jar | 显式指定主 jar，规避脚本缺陷 |
| SYSTEMDS_STANDALONE_OPTS | -Xms256m -Xmx512m | JVM 堆参数，256-512 MB 适配小内存机器 |
| PATH | 前置 $SYSTEMDS_ROOT/bin | 免去每次输入完整路径 |
若需调整堆内存，直接编辑 /etc/profile.d/systemds.sh 中 SYSTEMDS_STANDALONE_OPTS 一行，重新 source 后用 4.8 节方法验证。
5.2 配置文件位置
| 文件 | 路径 | 用途 |
|---|---|---|
| SystemDS 配置 | /opt/systemds-3.4.0/conf/SystemDS-config.xml | 临时目录、并行度、codegen、压缩线性代数等参数 |
| 日志配置 | /opt/systemds-3.4.0/conf/log4j.properties | 日志级别与输出格式 |
运行时可通过 -config <文件路径> 参数指定自定义配置文件，例如：
systemds -f /opt/systemds-work/train.dml -config /opt/systemds-work/my-config.xml
六、注意事项
- 3.4.0 的
bin/systemds脚本在已安装目录下查找 jar 时存在引号处理缺陷，务必设置SYSTEMDS_JAR_FILE环境变量，或在脚本第一参数位置显式传入 jar 完整路径（如systemds /opt/systemds-3.4.0/systemds-3.4.0.jar -f x.dml）； - 解压目录默认带
-bin后缀，建议按 4.4 节重命名，否则SYSTEMDS_ROOT相关配置与本文不一致； - CentOS 8 的 java-17-openjdk-headless 不含 jps，需按 4.2 节安装 java-17-openjdk-devel 后才能用 jps 验证进程参数；
- SystemDS 单机模式每条命令都是前台进程，运行结束即退出，无常驻服务，因此无需注册 systemd 服务；
- 默认堆配置为 4 GB，小内存机器务必覆盖
SYSTEMDS_STANDALONE_OPTS，否则 JVM 启动即申请 4 GB 虚拟内存； - 官方 algorithms 目录下的 Univar-Stats.dml 需要配套的 2xN 类型矩阵与 .mtd 元数据文件，直接仅传 X 参数会报错。
七、常见问题
Q1：运行报 Error: Unable to access jarfile org.apache.sysds.api.DMLScript，如何解决？
这是 3.4.0 启动脚本在查找 jar 文件时的缺陷导致 jar 路径为空。解决办法：在 /etc/profile.d/systemds.sh 中增加一行 export SYSTEMDS_JAR_FILE=/opt/systemds-3.4.0/systemds-3.4.0.jar，重新 source 后即可；也可每次运行时显式传入 jar 路径。
Q2：命令行输入 jps 提示 command not found 怎么办？
CentOS 8 的 java-17-openjdk-headless 包不含 jps 工具，执行 dnf install -y java-17-openjdk-devel 补装即可，装完 jps 位于 /usr/lib/jvm/java-17-openjdk/bin/ 下并已在 PATH 中。
Q3：日志中的 WARN utils.SettingsChecker: Low memory budget 提示是什么意思？
SystemDS 启动时按堆大小计算内部内存预算，检测到堆较小（如 512 MB）时会打印该提示并自动收缩预算，属于正常行为，说明堆限制已生效。
Q4：运行官方 Univar-Stats.dml 报 The parameter $STATS either needs to be passed 是什么原因？
该脚本除输入矩阵 X 外还需命名参数 TYPES（2xN 类型矩阵，第一行是类型码、第二行是列 ID，需配套 .mtd 元数据文件）与 STATS（输出路径），三者缺一不可。
Q5：直接运行 java -jar systemds-3.4.0.jar 报 NoClassDefFoundError: jdk/incubator/vector/DoubleVector 怎么办？
绕过启动脚本直连 java 时必须手动带上模块参数：java -Xms256m -Xmx512m --add-modules=jdk.incubator.vector -jar /opt/systemds-3.4.0/systemds-3.4.0.jar -f your.dml -exec singlenode。启动脚本已内置该参数，优先使用 systemds 命令。
八、卸载方式
按以下顺序清理（SystemDS 无服务进程，先确认无运行中的 java 任务）：
ps -ef | grep "[s]ystemds"
无输出即无运行任务。随后执行工作目录清理、删除安装目录、删除环境变量与安装包：
java -jar /opt/systemds-3.4.0/systemds-3.4.0.jar -clean
rm -rf /opt/systemds-3.4.0 /opt/systemds-work /opt/systemds-tmp
rm -f /etc/profile.d/systemds.sh /tmp/systemds-3.4.0-bin.tgz
-clean 会清理 SystemDS 的工作目录（本地临时缓存，默认 /tmp/systemds）。验证卸载干净：
ls /opt/ | grep -i systemds
无输出即卸载完成。
九、参考链接
- Apache SystemDS 官方下载页：https://downloads.apache.org/systemds/
- Apache SystemDS 官网：https://systemds.apache.org/
- 官方文档（DML 语言参考）：https://systemds.apache.org/docs/
- 官方 GitHub 仓库：https://github.com/apache/systemds
- 历史版本归档：https://archive.apache.org/dist/systemds/