Ubuntu 22.04 安装 Apache SystemDS 3.4.0 指南
Ubuntu 22.04 实机实测的 Apache SystemDS 3.4.0 部署指南，覆盖 OpenJDK 17 安装、官方包下载校验、环境变量配置与单机模式线性回归验证，含堆内存限制、常见报错处理与卸载步骤。
Ubuntu 22.04 安装 Apache SystemDS 3.4.0 指南
一、环境信息
本文所有命令与回显均在以下环境中实测采集，读者可按相同版本对照：
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS（root 用户） |
| SystemDS 版本 | 3.4.0（Apache 官方当前最新稳定版，2026-07-24 发布） |
| JDK | OpenJDK 17.0.20.1（openjdk-17-jdk-headless） |
| 安装路径 | /opt/systemds-3.4.0 |
| 运行模式 | singlenode 单机模式（本地 Java 进程执行，不依赖集群） |
| 包大小 | systemds-3.4.0-bin.tgz 约 123 MB |
二、前置条件
- 一台 Ubuntu 22.04 服务器，具备 root 权限；
- 服务器可访问公网（用于访问 downloads.apache.org），本文实测直连正常；
- 磁盘剩余空间不低于 2 GB（安装包 123 MB，解压后约 500 MB，另需工作目录存放数据与运行临时文件）；
- 内存不低于 2 GB。本文将 JVM 堆限制在 256-512 MB，以适配小规格机器与演示场景；
- 已安装 curl、wget、sha512sum 等基础工具（第二步会一并安装）。
SystemDS 3.4.0 官方要求 Java 8 及以上，实测采用 OpenJDK 17 全流程验证通过；JDK 11 亦为常见选择。
三、版本选型说明
访问 Apache 官方下载页 https://downloads.apache.org/systemds/，当前提供的历史版本包括 1.2.0、2.0.0、2.1.0、2.2.1、2.2.2、3.0.0、3.1.0、3.2.0、3.3.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，与旧版本惯例的 systemds-<版本号> 不同，解压后需统一重命名（见 5.3 节）。
四、部署步骤
4.1 更新系统并安装基础工具
以 root 执行：
apt-get update
回显（节选）：
Hit:1 http://archive.ubuntu.com/ubuntu jammy InRelease
Get:2 http://security.ubuntu.com/ubuntu jammy-security InRelease [129 kB]
apt-get install -y curl wget
回显（节选）：
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
4.2 安装 OpenJDK 17
apt-get install -y openjdk-17-jdk-headless
安装完成后验证：
java -version
实测回显：
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)
确认 JDK 安装路径（systemds 启动脚本会通过 java 命令自动定位，无需手动设置 JAVA_HOME）：
ls /usr/lib/jvm/
实测回显：
java-1.17.0-openjdk-amd64
java-17-openjdk-amd64
Ubuntu 的 openjdk-17-jdk-headless 包自带 jps 工具，后续验证 JVM 进程参数时会用到。
4.3 下载官方二进制包并校验
cd /tmp
wget https://downloads.apache.org/systemds/3.4.0/systemds-3.4.0-bin.tgz
实测回显（节选）：
--2026-10-12 05:33: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 -l /opt/systemds-3.4.0/
实测回显：
total 9620
-rw-rw-rw- 1 root root 19713 Jan 1 1970 LICENSE
-rw-rw-rw- 1 root root 171 Jan 1 1970 NOTICE
-rw-rw-rw- 1 root root 5925 Jan 1 1970 README.md
drwxr-xr-x 2 root root 4096 Oct 12 05:33 bin
drwxr-xr-x 2 root root 4096 Oct 12 05:33 conf
drwxr-xr-x 3 root root 4096 Oct 12 05:33 lib
drwxrwxrwx 3 root root 4096 Jan 1 1970 scripts
-rw-rw-rw- 1 root root 9797722 Jan 1 1970 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");' > /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
#
# Running script /tmp/hello.dml locally with opts:
# Executing command: 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 -f /tmp/hello.dml -exec singlenode -config /opt/systemds-3.4.0/conf/SystemDS-config.xml
###############################################################################
WARNING: Using incubator modules: jdk.incubator.vector
26/10/12 05:35:18 WARN util.NativeCodeLoader: Unable to load native-hadoop library for your platform, using builtin-java classes where applicable
hello systemds
SystemDS Statistics:
Total execution time: 0.014 sec.
输出中出现 hello systemds 即安装成功。两条 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
实测回显（节选）：
26/10/12 05:36:18 WARN utils.SettingsChecker: Low memory budget of total: 31 GB set to: 512 MB
SystemDS Statistics:
Total execution time: 0.162 sec.
head -1 /opt/systemds-work/X.csv
wc -l /opt/systemds-work/X.csv
实测回显：
2.5816994153466477,9.473793123709633,1.4748655385310439,5.9211272832782065,9.10840748081604,0.6476292220562074,1.0308530190497667,2.0912142963848934,4.205451102405558,3.2093001007511734
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.245 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.496
1.507
2.992
-0.009
1.006
1.991
0.499
1.204
0.798
1.082
5.152
SystemDS Statistics:
Total execution time: 0.278 sec.
学到的 10 个系数与截距 5.152 与真值高度吻合（数据含噪声存在小偏差属正常），说明 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
实测回显：
4435 systemds-3.4.0.jar -Xms256m -Xmx512m --add-modules=jdk.incubator.vector --add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.ref=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.base/sun.nio.ch=ALL-UNNAMED -Dlog4j.configuration=file:/opt/systemds-3.4.0/conf/log4j.properties
ps -ef | grep "[j]ava -Xms256m"
实测回显（节选，仅保留一行）：
root 4435 4395 99 05:36 ? 00:00:08 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 -f /opt/systemds-3.4.0/scripts/utils/generateData.dml -exec singlenode -config /opt/systemds-3.4.0/conf/SystemDS-config.xml -nvargs R=800000 C=20 S=1.0 Min=0.0 Max=10.0 Pdf=normal Path=/opt/systemds-work/bigX.csv Fmt=csv
-Xms256m -Xmx512m 明确出现在命令行中，堆限制生效。同时每次运行日志都会打印内存预算调整提示：
26/10/12 05:36:18 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相关配置与本文不一致； - SystemDS 单机模式每条命令都是前台进程，运行结束即退出，无常驻服务，因此无需注册 systemd 服务；
- 内联脚本参数
-s不被启动脚本支持，如需内联执行需直接调用 java 并带上--add-modules=jdk.incubator.vector，否则会报 NoClassDefFoundError； - 默认堆配置为 4 GB，小内存机器务必覆盖
SYSTEMDS_STANDALONE_OPTS，否则 JVM 启动即申请 4 GB 虚拟内存； - Ubuntu 的 openjdk-17-jdk-headless 自带 jps，可直接用于进程参数验证。
七、常见问题
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：日志中的 WARN utils.SettingsChecker: Low memory budget 提示是什么意思？
SystemDS 启动时按堆大小计算内部内存预算，检测到堆较小（如 512 MB）时会打印该提示并自动收缩预算，属于正常行为，说明堆限制已生效。若需消除，可增大堆参数。
Q3：出现 WARN util.NativeCodeLoader: Unable to load native-hadoop library 是否有影响？
没有影响。单机模式不依赖 Hadoop 集群，SystemDS 会自动回退到内置 Java 实现，仅本地文件读写，该警告可忽略。
Q4：直接运行 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 命令。
Q5：运行官方 Univar-Stats.dml 报 The parameter $STATS either needs to be passed 通过命令行？
该脚本除输入矩阵 X 外还需命名参数 TYPES（2xN 类型矩阵，第一行是类型码、第二行是列 ID，需配套 .mtd 元数据文件）与 STATS（输出路径），三者缺一不可。
八、卸载方式
按以下顺序清理（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/