Apache SystemDS 3.4.0 Docker Compose 部署指南

一、环境信息

本文所有命令与回显均在以下环境中实测采集：

项目	值
宿主系统	Linux x86_64（Docker Engine 29.8.0，含 compose v2 插件）
SystemDS 版本	3.4.0（官方二进制包 systemds-3.4.0-bin.tgz，约 123 MB）
基础镜像	eclipse-temurin:17-jre-jammy（内置 JRE 17）
自建镜像	systemds:3.4.0（构建后约 904 MB）
工作目录	/work（部署目录）与 /work/jobs（作业数据卷）
JVM 堆	-Xms256m -Xmx512m

二、镜像选型说明

Apache 官方不发布 SystemDS 镜像，需要基于二进制包自建。基础镜像选择依据：

候选镜像	结论
eclipse-temurin:17-jre-jammy	本文采用，Ubuntu 22.04 底座，仅含 JRE 17，体积与启动速度均衡
eclipse-temurin:17-jdk-jammy	含完整 JDK（jps 等工具），需在容器内做进程诊断时选用
openjdk:17	官方镜像已停止维护，不推荐新部署

SystemDS 3.4.0 官方要求 Java 8 以上，实测 JRE 17 可完整运行训练流程。镜像内不修改 SystemDS 启动脚本，JVM 堆通过镜像环境变量 SYSTEMDS_STANDALONE_OPTS 控制为 256-512 MB。

三、前置条件

宿主机已安装 Docker Engine 20.10 以上并包含 compose 插件（docker compose version 可输出版本）；
磁盘剩余空间不低于 3 GB（基础镜像 97 MB、构建后镜像 904 MB、安装包 123 MB、数据卷空间）；
已取得官方安装包 systemds-3.4.0-bin.tgz（下载地址 https://downloads.apache.org/systemds/3.4.0/systemds-3.4.0-bin.tgz ，下载后用 .sha512 文件校验，实测值为 f6dd2fed 开头的 128 位十六进制串）；
建议准备部署目录 /work 并将安装包放入其中。

四、部署步骤

4.1 组织目录结构

mkdir -p /work/jobs
cp /tmp/systemds-3.4.0-bin.tgz /work/
cd /work

最终目录结构（实测）：

/work
  Dockerfile
  compose.yaml
  systemds-3.4.0-bin.tgz
  jobs/
    job.dml
    makeData.dml

4.2 编写 Dockerfile

cat > /work/Dockerfile << 'EOF'
FROM eclipse-temurin:17-jre-jammy

ENV SYSTEMDS_ROOT=/opt/systemds-3.4.0
ENV SYSTEMDS_JAR_FILE=/opt/systemds-3.4.0/systemds-3.4.0.jar
ENV SYSTEMDS_STANDALONE_OPTS="-Xms256m -Xmx512m"
ENV PATH=/opt/systemds-3.4.0/bin:$PATH

COPY systemds-3.4.0-bin.tgz /tmp/systemds-3.4.0-bin.tgz
RUN tar -xzf /tmp/systemds-3.4.0-bin.tgz -C /opt/ \
    && mv /opt/systemds-3.4.0-bin /opt/systemds-3.4.0 \
    && rm -f /tmp/systemds-3.4.0-bin.tgz

WORKDIR /data
ENTRYPOINT ["systemds"]
CMD ["-f", "/data/job.dml"]
EOF

要点说明：

3.4.0 解压目录自带 -bin 后缀，构建时统一重命名为 /opt/systemds-3.4.0；
SYSTEMDS_STANDALONE_OPTS 的值必须用引号包裹，写成 ENV SYSTEMDS_STANDALONE_OPTS=-Xms256m -Xmx512m 会触发构建报错 Syntax error - can't find = in "-Xmx512m"（实测踩坑）；
设置 SYSTEMDS_JAR_FILE 规避 3.4.0 启动脚本查找 jar 的缺陷；
ENTRYPOINT 固定为 systemds 脚本，CMD 提供默认脚本路径，二者配合让 compose 命令只需关心 DML 文件。

4.3 编写 compose.yaml

cat > /work/compose.yaml << 'EOF'
services:
  systemds:
    build: .
    image: systemds:3.4.0
    container_name: systemds-job
    volumes:
      - ./jobs:/data
    command: ["-f", "/data/job.dml"]
EOF

服务定义说明：build 使用当前目录 Dockerfile 构建；image 指定产物镜像名；jobs 目录挂载为 /data 作为作业工作区；command 覆盖 CMD 指定要执行的 DML 文件。

4.4 准备作业脚本

数据生成脚本：

cat > /work/jobs/makeData.dml << 'EOF'
X = rand(rows=1000, cols=10, sparsity=1.0, min=0.0, max=10.0, pdf="normal");
write(X, "/data/X.csv", format="csv");
print("X generated rows=" + nrow(X));
EOF

训练脚本（调用官方内置 lm 线性回归，标签由 makeData 生成的数据加权求和得到）：

cat > /work/jobs/job.dml << 'EOF'
X = read("/data/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");
B = lm(X=X, y=y, icpt=1);
print("=== coefficients from compose run ===");
print(toString(B));
EOF

4.5 构建镜像

cd /work
docker compose build

实测回显（节选）：

Image systemds:3.4.0 Built

docker images | head -3

实测回显：

IMAGE                          ID             DISK USAGE   CONTENT SIZE
eclipse-temurin:17-jre-jammy   8993f1aed8b2        378MB         97.3MB
systemds:3.4.0                 7984902b9ca2        904MB          350MB

4.6 运行数据生成作业

docker compose run --rm systemds -f /data/makeData.dml

实测回显（节选）：

X generated rows=1000
Total execution time:           0.145 sec.

4.7 运行训练作业

docker compose up

实测回显（节选）：

systemds-job  | WARNING: Using incubator modules: jdk.incubator.vector
systemds-job  | 26/10/12 05:44:10 WARN utils.SettingsChecker: Low memory budget of total:     31 GB set to:    512 MB
systemds-job  | Calling the Direct Solver
systemds-job  | === coefficients from compose run ===
systemds-job  | 2.476
systemds-job  | 1.487
systemds-job  | 3.000
systemds-job  | -0.001
systemds-job  | 1.044
systemds-job  | 2.008
systemds-job  | 0.519
systemds-job  | 1.208
systemds-job  | 0.801
systemds-job  | 1.097
systemds-job  | 4.983
systemds-job  |
systemds-job  | SystemDS Statistics:
systemds-job  | Total execution time:           0.265 sec.
systemds-job exited with code 0

学到的系数与脚本中真实权重（2.5、1.5、3.0、0.0、1.0、2.0、0.5、1.2、0.8、1.1、截距 5.0）高度吻合，且日志确认 JVM 堆为 512 MB，部署验证通过。作业结束后容器状态：

NAME           IMAGE            COMMAND                  SERVICE    STATUS
systemds-job   systemds:3.4.0   "systemds -f /data/j…"   systemds   Exited (0)

五、数据持久化说明

所有作业输入输出统一放在宿主机 /work/jobs 目录（挂载到容器 /data）。实测一次完整运行后目录内容：

/work/jobs
  job.dml
  makeData.dml
  X.csv          191.9K
  X.csv.mtd
  scratch_space/

说明：

X.csv 与 X.csv.mtd 是作业写入的数据与元数据，宿主机直接可见，删除 compose 服务不影响数据；
scratch_space/ 是 SystemDS 按配置项 sysds.scratch 在工作目录自动创建的暂存目录；
一次性任务用 docker compose run --rm，任务结束自动删除临时容器；docker compose up 产物容器保留为 Exited 状态，便于回查日志；
多个作业建议共用同一数据卷，DML 脚本内以 /data 绝对路径读写。

六、常用环境变量表

环境变量	实测值	说明
SYSTEMDS_ROOT	/opt/systemds-3.4.0	安装根目录，脚本定位 jar 与配置
SYSTEMDS_JAR_FILE	/opt/systemds-3.4.0/systemds-3.4.0.jar	显式指定主 jar，规避 3.4.0 启动脚本缺陷
SYSTEMDS_STANDALONE_OPTS	"-Xms256m -Xmx512m"	JVM 堆参数，值必须带引号
SYSDS_QUIET	未设置（可选 1）	设为 1 可关闭启动横幅输出
SYSDS_DISTRIBUTED	未设置（可选 1）	设为 1 走 spark-submit，需外部集群
PATH	前置 /opt/systemds-3.4.0/bin	直接使用 systemds 命令

七、常用配置参数说明

容器内默认配置文件为 /opt/systemds-3.4.0/conf/SystemDS-config.xml，与裸机部署一致。常用调整项：

参数	默认值	容器场景建议
sysds.localtmpdir	/tmp/systemds	改到数据卷内（如 /data/tmp），避免临时目录随容器销毁且受容器可写层大小限制
sysds.optlevel	2	保持 2；计算密集任务可试 3
sysds.cp.parallel.ops	true	保持开启，与 CPU 配额匹配
sysds.compressed.linalg	false	小堆场景可开启压缩线性代数降低内存
sysds.caching.bufferpoollimit	15	保持默认（占堆 15%）

八、配置文件持久化

将自定义配置放入宿主机并挂载到容器内 conf 目录，替换默认配置：

services:
  systemds:
    image: systemds:3.4.0
    container_name: systemds-job
    volumes:
      - ./jobs:/data
      - ./conf/SystemDS-config.xml:/opt/systemds-3.4.0/conf/SystemDS-config.xml
    command: ["-f", "/data/job.dml"]

操作步骤（实测可行）：

mkdir -p /work/conf
docker run --rm systemds:3.4.0 -help > /dev/null
docker cp systemds-job:/opt/systemds-3.4.0/conf/SystemDS-config.xml /work/conf/

修改 /work/conf/SystemDS-config.xml 后重新 docker compose up，启动横幅中的 CONFIG_FILE 一行仍显示同一文件路径，内容已替换为自定义版本。也可直接在 command 中追加 -config /data/my-config.xml 使用数据卷中的配置文件。

九、等价 docker run 运行方式

不使用 compose 时，构建与运行等价命令如下。

构建（与 compose build 等价）：

cd /work
docker build -t systemds:3.4.0 .

运行数据生成（一次性任务）：

docker run --rm -v /work/jobs:/data systemds:3.4.0 -f /data/makeData.dml

运行训练作业：

docker run --rm -v /work/jobs:/data systemds:3.4.0 -f /data/job.dml

交互式排查（进入容器执行任意命令）：

docker run --rm -it -v /work/jobs:/data --entrypoint bash systemds:3.4.0

进入后可用 jps -v、ps -ef 查看进程参数（jre 基础镜像无 jps，需 jdk 基础镜像或改用 ps），实测 ps -ef | grep "[j]ava" 可见 -Xms256m -Xmx512m。

十、常用运维命令

命令	用途
docker compose build	构建或重建 systemds:3.4.0 镜像
docker compose up	按默认 command 运行一次训练作业
docker compose run --rm systemds -f /data/makeData.dml	临时运行指定作业脚本
docker compose ps -a	查看作业容器状态
docker compose logs systemds	回看最近一次作业日志
docker compose down	删除服务容器与网络（数据卷不受影响）
docker images	查看镜像体积
docker history systemds:3.4.0	查看镜像构建层

长时间任务后台化运行：

docker compose up -d
docker compose logs -f systemds

十一、常见问题

Q1：构建时报 Syntax error - can't find = in "-Xmx512m" 怎么解决？

Dockerfile 中 ENV 变量值含空格时必须加引号。将 ENV SYSTEMDS_STANDALONE_OPTS=-Xms256m -Xmx512m 改为 ENV SYSTEMDS_STANDALONE_OPTS="-Xms256m -Xmx512m" 后重新构建。

Q2：容器内运行报 Error: Unable to access jarfile org.apache.sysds.api.DMLScript 是什么原因？

与裸机部署相同的 3.4.0 启动脚本 jar 查找缺陷。确认镜像 ENV 中已设置 SYSTEMDS_JAR_FILE=/opt/systemds-3.4.0/systemds-3.4.0.jar；自建镜像时按本文 Dockerfile 即可避免。

Q3：作业数据写进去了但容器删除后数据丢失？

检查 compose.yaml 是否正确挂载了数据卷（volumes: ./jobs:/data）。SystemDS 脚本内所有读写路径必须落在 /data 下才会持久化到宿主机；写到容器内其他路径（如默认 sysds.localtmpdir=/tmp/systemds）的数据随容器删除而消失。

Q4：如何在容器内调整 JVM 堆大小？

修改 Dockerfile 中 SYSTEMDS_STANDALONE_OPTS 后重建镜像；或运行时注入：docker run --rm -e SYSTEMDS_STANDALONE_OPTS="-Xms512m -Xmx512m" -v /work/jobs:/data systemds:3.4.0 -f /data/job.dml，运行时环境变量优先于镜像内置值，可用 docker exec 执行 jps -v 或 ps -ef 验证。

Q5：compose up 卡在拉取基础镜像或拉取超时？

eclipse-temurin:17-jre-jammy 需要从镜像仓库拉取。离线环境可先在有外网的机器执行 docker pull 与 docker save 导出 tar 包，拷贝到部署机后 docker load 导入，再执行 compose build。

十二、参考链接

Apache SystemDS 官方下载页：https://downloads.apache.org/systemds/
Apache SystemDS 官网与文档：https://systemds.apache.org/docs/
Eclipse Temurin 镜像页：https://hub.docker.com/_/eclipse-temurin
Docker Compose 官方文档：https://docs.docker.com/compose/
官方 GitHub 仓库：https://github.com/apache/systemds