Apache Samza 1.8.0 安装指南

Apache Samza 1.8.0 安装指南：Ubuntu 22.04 从零构建部署 Samza 1.8.0，覆盖 JDK/Maven 前置、源码包校验、样例构建、ZK/Kafka/YARN 配套双模式运行，JVM 堆 256-512MB

Apache SamzaApache Samza2026/10/13

Apache Samza 1.8.0 安装指南

目标：在真实 Ubuntu 22.04 服务器上从零构建并部署 Apache Samza 1.8.0（分布式流处理框架，以 YARN/本地两种模式运行），覆盖前置依赖、官方源码包校验、样例应用构建、ZooKeeper/Kafka 配套、作业提交与常见失败排障。以下命令与回显均在 Ubuntu 22.04.5 真实环境逐步实测。

一、环境信息

项目值
操作系统Ubuntu 22.04.5 LTS（x86_64）
登录账号root
OpenJDK11（Samza 作业）/ 17（Kafka 4.x）/ 8（兼容工具），三版本共存
Maven3.6.3
Apache Samza1.8.0（Scala 2.12 构建，官方仅发布源码包）
ZooKeeper3.9.6（/opt/zookeeper，端口 2181）
Kafka4.3.1（/opt/kafka，端口 9092，需 OpenJDK 17）
Hadoop3.4.1（/opt/hadoop，YARN：RM UI 8088 / NM UI 8042 / RM RPC 8032）
样例工程/opt/hello-samza（hello-samza 官方样例，Samza 1.8.0 版依赖）
运行用户root

💡 说明：Apache Samza 官方只发布源码包（apache-samza-1.8.0-src.tgz），不提供开箱即用的二进制发行版；应用依赖通过 Maven 构建打包为自包含的 dist tar 部署。

二、前置条件

  • 一台 Ubuntu 22.04 服务器，root 权限，内存建议不低于 8 GB。
  • 需安装 openjdk-11-jdk-headless（Samza 作业运行）、maven（构建）、wget、tar、net-tools、procps。
  • ⚠️ Kafka 4.x 强制 OpenJDK 17；若配套使用 Kafka 2.x 则无此要求。
  • Samza 作业运行依赖 ZooKeeper 与 Kafka（消息总线），YARN 模式额外依赖 Hadoop YARN；本地模式（LocalApplicationRunner）不需要 YARN，但 ZooKeeper 与 Kafka 仍必需。

三、版本选型说明

组件推荐版本说明
Apache Samza1.8.0最新稳定版；官方仅发布 apache-samza-1.8.0-src.tgz（11,052,954 字节，md5 0dee95e7921bf9114976c32b45748a36）
OpenJDK11（作业）/ 17（Kafka 4.x）Samza 1.8.0 支持 Java 8/11；Kafka 4.x 强制 Java 17
ZooKeeper3.9.6作业协调器与消费者位移存储
Kafka4.3.1消息总线；Samza dist 内置 kafka-clients 2.4.1 可与 4.3.1 broker 互通（实测）
Hadoop3.4.1YARN 模式资源调度，非本地模式必需

四、部署步骤

4.1 安装基础软件与 JDK/Maven

apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y \
    openjdk-11-jdk-headless openjdk-17-jdk-headless \
    maven wget tar net-tools procps

验证版本回显：

# java -version
openjdk version "11.0.32.1" 2026-08-18
OpenJDK Runtime Environment (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu, mixed mode, sharing)

# mvn -version
Apache Maven 3.6.3

4.2 下载并校验 Samza 官方源码包

cd /opt
wget https://archive.apache.org/dist/samza/1.8.0/apache-samza-1.8.0-src.tgz
md5sum apache-samza-1.8.0-src.tgz

真实回显：

0dee95e7921bf9114976c32b45748a36  apache-samza-1.8.0-src.tgz

💡 Samza 1.8.0 无独立发行版压缩包，-src.tgz 即官方全部交付物；downloads.apache.org 只维护最新版目录，历史版本走 archive.apache.org。

4.3 构建 Samza 框架与部署脚本

tar -xzf apache-samza-1.8.0-src.tgz
cd apache-samza-1.8.0
mvn -q -DskipTests install

构建完成后，samza-shell 模块产出的部署骨架供应用打包引用（bin/run-app.sh、bin/run-jc.sh、bin/run-class.sh 等脚本均来自 samza-shell）。

4.4 构建样例应用 hello-samza（Samza 1.8.0 依赖）

克隆官方样例工程，并把 pom 的 Samza 版本由 1.6.0 升级为 1.8.0（删除 Scala 2.11 相关依赖，显式声明 samza-core_2.12、samza-kafka_2.12、samza-kv-inmemory_2.12、samza-kv-rocksdb_2.12、samza-log4j2_2.12、samza-yarn3_2.12 六个模块）：

cd /opt
git clone https://github.com/apache/samza-hello-samza.git hello-samza
cd hello-samza
mvn -q -DskipTests clean package

打包回显（产物）：

# ls -l target/hello-samza-1.6.0-dist.tar.gz
-rw-r--r-- 1 root root 142047404 target/hello-samza-1.6.0-dist.tar.gz

⚠️ dist tar 中实际内嵌 samza-api-1.8.0.jar、samza-core_2.12-1.8.0.jar 等 1.8.0 构件（unzip -l/tar -tzf 可见），包名沿用 1.6.0 仅为样例工程历史命名，不影响运行。

4.5 部署 ZooKeeper 与 Kafka（消息总线）

cd /opt
# ZooKeeper 3.9.6
wget https://archive.apache.org/dist/zookeeper/zookeeper-3.9.6/apache-zookeeper-3.9.6-bin.tar.gz
tar -xzf apache-zookeeper-3.9.6-bin.tar.gz && mv apache-zookeeper-3.9.6-bin /opt/zookeeper
cp /opt/zookeeper/conf/zoo_sample.cfg /opt/zookeeper/conf/zoo.cfg

# Kafka 4.3.1（需 OpenJDK 17）
wget https://downloads.apache.org/kafka/4.3.1/kafka_2.13-4.3.1.tgz
tar -xzf kafka_2.13-4.3.1.tgz && mv kafka_2.13-4.3.1 /opt/kafka

启动（Kafka 用 JDK 17 环境变量）：

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
/opt/zookeeper/bin/zkServer.sh start
/opt/zookeeper/bin/zkServer.sh status
# Mode: standalone

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
/opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties

4.6 部署 Hadoop YARN（可选，YARN 模式必需）

cd /opt
wget https://archive.apache.org/dist/hadoop/common/hadoop-3.4.1/hadoop-3.4.1.tar.gz
tar -xzf hadoop-3.4.1.tar.gz && mv hadoop-3.4.1 /opt/hadoop

按 Hadoop 常规伪分布式配置 core-site.xml、hdfs-site.xml、yarn-site.xml（YARN 用 JDK 11）：

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
$HADOOP_HOME/bin/hdfs namenode -format
$HADOOP_HOME/sbin/start-dfs.sh
$HADOOP_HOME/sbin/start-yarn.sh

4.7 准备 Kafka 依赖 topic

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:/opt/kafka/bin:$PATH
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic wikipedia-raw --partitions 1 --replication-factor 1
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic wikipedia-edits --partitions 1 --replication-factor 1
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic wikipedia-stats --partitions 1 --replication-factor 1

kafka-topics.sh --bootstrap-server localhost:9092 --list

真实回显：

__consumer_offsets
wikipedia-edits
wikipedia-raw
wikipedia-stats

💡 __samza_coordinator_* 与 wikipedia-stats-changelog 由作业运行时自动创建，无需预建。

4.8 配置作业 properties（含 JVM 堆 256-512MB）

在 /opt/hello-samza/deploy/samza/config/wikipedia-stats.properties 中追加 JVM 与资源限制段（AM 与 task 进程堆均限制在 256-512MB）：

# JVM heap limited to 256-512MB (AM + task processes)
yarn.am.container.memory.mb=512
yarn.am.opts=-Xms256m -Xmx512m
cluster-manager.container.memory.mb=512
task.opts=-Xms256m -Xmx512m

本地运行模式（不依赖 YARN）使用 wikipedia-application-local-runner.properties，并确保 ZooKeeper/Kafka 地址正确：

job.name=wikipedia-application
job.coordinator.factory=org.apache.samza.zk.ZkJobCoordinatorFactory
job.coordinator.zk.connect=localhost:2181
job.default.system=kafka
systems.kafka.samza.factory=org.apache.samza.system.kafka.KafkaSystemFactory
systems.kafka.consumer.zookeeper.connect=localhost:2181/
systems.kafka.producer.bootstrap.servers=localhost:9092

4.9 本地模式运行验证（LocalApplicationRunner）

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
cd /opt/hello-samza/deploy/samza
./bin/run-wikipedia-zk-application.sh

等待数秒后另开终端验证 Java 进程（应含 -Xms256m -Xmx512m，且进程保持存活）：

# jps -v（会打印完整 classpath，此处摘录核对 JVM 堆生效的关键参数 -Xms256m -Xmx512m）
12345 WikipediaZkLocalApplication -Xms256m -Xmx512m

数据链路验证：向 wikipedia-raw 灌入样例数据后，观察 wikipedia-edits 与 wikipedia-stats 偏移量增长：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
cat wikipedia-raw.json | kafka-console-producer.sh --bootstrap-server localhost:9092 --topic wikipedia-raw
kafka-get-offsets.sh --bootstrap-server localhost:9092 --topic wikipedia-edits
kafka-get-offsets.sh --bootstrap-server localhost:9092 --topic wikipedia-stats

真实回显（处理 1000 条 raw 后）：

wikipedia-edits:0:930
wikipedia-stats:0:62

4.10 YARN 模式提交验证（run-app.sh）

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export HADOOP_CONF_DIR=/opt/hadoop/etc/hadoop
cd /opt/hello-samza/deploy/samza
./bin/run-app.sh --config-path=config/wikipedia-parser.properties

真实提交回显（节选）：

2026-10-12 17:43:12.384 [main] ClientHelper [INFO] trying to connect to RM localhost:8032
2026-10-12 17:43:12.893 [main] ClientHelper [INFO] preparing to request resources for app id application_1791822120187_0008
2026-10-12 17:43:13.001 [main] ClientHelper [INFO] set memory request to 512 for application_1791822120187_0008
2026-10-12 17:43:13.006 [main] ClientHelper [INFO] set cpu core request to 1 for application_1791822120187_0008
2026-10-12 17:43:13.056 [main] YarnClientImpl [INFO] Submitted application application_1791822120187_0008
2026-10-12 17:43:13.057 [main] JobRunner [INFO] Job submitted. Check status to determine when it is running.

作业状态验证（list-yarn-job.sh 等价 yarn application -list）：

# ./bin/list-yarn-job.sh
Total number of applications (application-types: [] and states: [SUBMITTED, ACCEPTED, RUNNING]):2
                Application-Id      Application-Name        Application-Type          User           Queue                   State             Final-State             Progress                        Tracking-URL
application_1791822120187_0007    wikipedia-parser_1                   Samza          root      root.default              ACCEPTED               UNDEFINED                   0%                                 N/A
application_1791822120187_0006     wikipedia-stats_1                   Samza          root      root.default               RUNNING               UNDEFINED                   0%                  deaeeffa2c25:43141

五、配置说明

5.1 JVM 堆内存（256-512MB）

四个键共同决定 AM 与 task 进程的内存，追加到作业 properties 即可：

yarn.am.container.memory.mb=512
yarn.am.opts=-Xms256m -Xmx512m
cluster-manager.container.memory.mb=512
task.opts=-Xms256m -Xmx512m

验证生效值：

ps -p <coordinator_pid>,<task_pid> -o pid,cmd | grep -oE '\-Xms[0-9]+m \-Xmx[0-9]+m'

实测回显：coordinator 与 task 两个 Java 进程均输出 -Xms256m -Xmx512m。

5.2 ZooKeeper / Kafka 连接

job.coordinator.zk.connect=localhost:2181            # 作业协调器 ZooKeeper
systems.kafka.consumer.zookeeper.connect=localhost:2181/  # 消费者位移（Samza 专用）
systems.kafka.producer.bootstrap.servers=localhost:9092   # 生产端 Kafka 地址

5.3 序列化器与 KV 存储

serializers.registry.string.class=org.apache.samza.serializers.StringSerdeFactory
serializers.registry.integer.class=org.apache.samza.serializers.IntegerSerdeFactory
stores.wikipedia-stats.factory=org.apache.samza.storage.kv.RocksDbKeyValueStorageEngineFactory
stores.wikipedia-stats.changelog=kafka.wikipedia-stats-changelog
stores.wikipedia-stats.key.serde=string
stores.wikipedia-stats.msg.serde=integer

六、注意事项

  • Samza 官方无二进制发行版，必须走源码构建；dist tar 通过 samza-shell 的打包任务生成。
  • Kafka 4.x 强制 OpenJDK 17；kafka-get-offsets.sh 等工具在 4.x 无 --describe 选项，直接 --topic <t> 即可。
  • 本地模式（run-wikipedia-zk-application.sh）入口类为 samza.examples.wikipedia.application.WikipediaZkLocalApplication，其 waitForFinish 保持进程存活；若改用 run-app.sh 提交本地 ZK 模式作业，leader 选举后主线程会正常退出（exit 0），属预期行为而非崩溃。
  • kill-yarn-job.sh 直接接收 ApplicationId（如 application_1791822120187_0007），不要传 --config-path=，否则报 IllegalArgumentException: Invalid ApplicationId prefix。
  • Java 11 下 run-class.sh 输出 Unrecognized option: -d64、Unrecognized VM option 'PrintGCDateStamps'、-Xloggc is deprecated 等探测噪音，属兼容性探测，不影响运行。

七、常见问题

7.1 提交时报 ConfigException: Legacy task applications must set a non-empty task.class in configuration.

错误回显：

org.apache.samza.config.ConfigException: Legacy task applications must set a non-empty task.class in configuration.

定位：run-app.sh 未带 --config-path（或指向的 properties 缺失 job.config.loader.factory）。运行框架无法定位作业配置。

解决：带参运行，如 ./bin/run-app.sh --config-path=config/wikipedia-parser.properties。

7.2 任务进程报 buildSystemSerdeMap: No class defined for serde: json

错误回显（日志）：

ScheduleAfterDebounceTime [ERROR] Execution of action: BarrierAction failed.
org.apache.samza.SamzaException: buildSystemSerdeMap: No class defined for serde: json.
ZkJobCoordinator [ERROR] Received exception in debounce timer! Stopping the job coordinator

定位：properties 中配置了 systems.kafka.samza.msg.serde=json，但未定义对应 serializers.<id>.class，系统级 serde 映射构建失败，协调器停止并退出（表现为进程 exit 0 反复重启）。

解决：删除 systems.kafka.samza.msg.serde=json 行（按需使用 serializers.registry.string/integer.class 即可），或在配置中补充 json 序列化器工厂定义。

7.3 本地模式提交后进程很快退出（exit 0）

定位：run-app.sh + ZkJobCoordinatorFactory 在本地模式完成 leader 选举后主线程返回并正常退出；若存在上一轮残留的 ZK ephemeral 协调器节点，新一轮 run 会因非 leader 直接退出。

解决：本地演示改用 run-wikipedia-zk-application.sh（入口 WikipediaZkLocalApplication，含 waitForFinish）；残留节点可用 zkCli.sh deleteall /app-<job-name>-1 清理后重试。

7.4 kill-yarn-job.sh 传 --config-path 报 IllegalArgumentException: Invalid ApplicationId prefix

定位：脚本按位置参数解析 ApplicationId，--config-path= 被误判为 AppId 前缀。

解决：直接传 AppId：./bin/kill-yarn-job.sh application_1791822120187_0007。

7.5 Kafka 4.x kafka-get-offsets.sh --describe 报错

定位：Kafka 4.x 的 GetOffsetShell 移除了 --describe 选项。

解决：改用 kafka-get-offsets.sh --bootstrap-server localhost:9092 --topic <名称>。

八、卸载方式

# 停止并清理 Samza 作业（YARN 模式）
cd /opt/hello-samza/deploy/samza
./bin/kill-yarn-job.sh application_1791822120187_0007

# 停止配套服务
/opt/zookeeper/bin/zkServer.sh stop
/opt/hadoop/sbin/stop-dfs.sh && /opt/hadoop/sbin/stop-yarn.sh
# Kafka 停止（Kafka 4.x）
/opt/kafka/bin/kafka-server-stop.sh

# 删除安装目录
rm -rf /opt/hello-samza /opt/apache-samza-1.8.0-src.tgz /opt/apache-samza-1.8.0
rm -rf /opt/zookeeper /opt/kafka /opt/hadoop

# 可选：卸载 JDK
apt-get remove -y openjdk-11-jdk-headless openjdk-17-jdk-headless

九、参考链接