Apache Pekko 1.7.1 构建并运行示例应用指南

目标：从零构建并运行一个基于 Apache Pekko 1.7.1 的最小 Actor 应用（Classic API，Java）：创建 ActorSystem、创建 Greeter actor、tell 发送消息、优雅关闭系统。给出完整 pom.xml、示例源码、编译与运行命令及真实回显，并覆盖 JVM 堆内存限制与中文输出 locale 处理。所有命令与输出均在 Ubuntu 22.04.5 + JDK 17 环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
登录用户：root（演示账号）
Java：OpenJDK 17.0.20.1
构建工具：Apache Maven 3.6.3
Pekko 版本：1.7.1（依赖 org.apache.pekko:pekko-actor_2.13）
示例工程目录：/opt/pekko-demo/
ActorSystem 名称：hello-pekko
运行堆内存：-Xms256m -Xmx512m（经 MAVEN_OPTS 注入）

二、前置条件

JDK 17 与 Maven 已安装（安装过程见《Ubuntu 22.04 安装 Apache Pekko 1.7.1 指南》篇），核验：

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)

依赖可解析：在本工程目录内编译通过即认为依赖就绪（见第六节）。

三、工程结构

标准 Maven 布局，仅一个 pom 与一个主类（主类位于默认包）：

pekko-demo/
├── pom.xml
└── src/main/java/GreeterMain.java

mkdir -p /opt/pekko-demo/src/main/java

四、完整 pom.xml

pom 通过 <pekko.version> 属性统一 Pekko 版本，并用 exec-maven-plugin 执行主类：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>pekko-demo</artifactId>
  <version>1.0</version>
  <packaging>jar</packaging>
  <name>Apache Pekko Actor Demo (Java)</name>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <pekko.version>1.7.1</pekko.version>
  </properties>

  <dependencies>
    <!-- Pekko 核心 actor（Scala 2.13 构建） -->
    <dependency>
      <groupId>org.apache.pekko</groupId>
      <artifactId>pekko-actor_2.13</artifactId>
      <version>${pekko.version}</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.11.0</version>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.1.0</version>
        <configuration>
          <mainClass>GreeterMain</mainClass>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

💡 说明：示例主类 GreeterMain 位于默认包（源码无 package 声明），因此 <mainClass> 直接写 GreeterMain，无需包名前缀。Ubuntu 22.04 的 Maven 3.6.3 需显式声明 maven-compiler-plugin 3.11.0 才支持 maven.compiler.release 属性。

五、示例源码

创建 /opt/pekko-demo/src/main/java/GreeterMain.java，完成四步：创建 ActorSystem → 通过 Props 创建 Greeter actor → tell 发送消息 → 优雅关闭系统。

示例源码：

import org.apache.pekko.actor.AbstractActor;
import org.apache.pekko.actor.ActorRef;
import org.apache.pekko.actor.ActorSystem;
import org.apache.pekko.actor.Props;

/**
 * Apache Pekko 经典 actor（Classic API）最小示例：
 * 创建 ActorSystem -> 创建 Greeter actor -> tell 发送消息 -> 关闭系统。
 */
public class GreeterMain {

    /** 经典 Actor：继承 AbstractActor，定义消息处理逻辑 */
    public static class Greeter extends AbstractActor {
        @Override
        public Receive createReceive() {
            return receiveBuilder()
                .match(String.class, msg -> {
                    System.out.println("Greeter 收到消息: " + msg);
                })
                .build();
        }
    }

    public static void main(String[] args) throws Exception {
        // 1. 创建 ActorSystem（应用级 Actor 系统的根节点 / 调度器）
        ActorSystem system = ActorSystem.create("hello-pekko");

        // 2. 通过 Props 创建 Greeter actor，得到 ActorRef
        ActorRef greeter = system.actorOf(Props.create(Greeter.class), "greeter");

        // 3. tell = fire-and-forget 发消息（无需等待回复）
        greeter.tell("Hello Pekko!", ActorRef.noSender());

        // 4. 短暂等待消息被异步处理，然后优雅关闭 ActorSystem
        Thread.sleep(2000);
        system.terminate();
        System.out.println("ActorSystem terminated.");
    }
}

💡 说明：tell(msg, sender) 是 fire-and-forget 语义，消息进入目标 actor 的 mailbox 后由其串行处理；Thread.sleep(2000) 仅为等待异步消息处理完成，避免进程过早退出。

六、编译与运行

6.1 编译

cd /opt/pekko-demo && mvn -q clean compile

实测：首次编译会下载 pekko-actor 1.7.1 / scala-library 2.13.18 / typesafe config 等依赖；无输出 = 编译成功，生成 target/classes/GreeterMain*.class。

6.2 运行

系统 locale 非 UTF-8 时，先导出编码环境变量（否则中文输出为 ????）：

export JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8" LANG=C.UTF-8 LC_ALL=C.UTF-8

运行：

mvn -q exec:java

实测回显：

Greeter 收到消息: Hello Pekko!
[INFO] [10/11/2026 11:25:21.212] [GreeterMain.main()] [CoordinatedShutdown(pekko://hello-pekko)] Running CoordinatedShutdown with reason [ActorSystemTerminateReason]
ActorSystem terminated.

💡 说明：示例中的 stdout（println）与 stderr（Pekko 日志）交错顺序每次运行可能不同，属正常现象。

6.3 限制 JVM 堆内存（256–512MB）

示例进程建议限制堆内存，避免默认大堆挤占服务器资源：

export MAVEN_OPTS="-Xms256m -Xmx512m"
mvn -q exec:java

exec:java 与 Maven 进程同 JVM 运行，该限制即示例进程的堆限制。如需复核实际生效堆，可另开终端执行 jps -lv，在进程 JVM 参数中应能看到 -Xms256m -Xmx512m 标记；ps -ef | grep [j]ava 同样可以看到该参数。

七、运行结果解读

三行输出分别对应：

Greeter 收到消息: Hello Pekko! —— Greeter actor 的 receiveBuilder 匹配到 String 消息后由 println 打印，说明「创建 actor → tell 发消息 → 异步处理」整条链路已跑通。
[INFO] ... Running CoordinatedShutdown with reason [ActorSystemTerminateReason] —— system.terminate() 触发 CoordinatedShutdown 协调关闭流程，日志中的 pekko://hello-pekko 即本 ActorSystem 的地址（位置透明协议头，pekko://系统名）。
ActorSystem terminated. —— 关闭完成后主线程打印的收尾输出，进程正常退出。

八、注意事项

⚠️ 注意：

必须使用 JDK 8 及以上编译运行（本文实测 JDK 17.0.20.1；JDK 21 亦受支持）。

依赖版本统一：所有 pekko-* 模块版本统一 1.7.1，Scala 变体后缀 _2.13 保持一致。

Thread.sleep(2000) 不可省略：tell 是异步的，消息可能尚未处理完；若直接 terminate 可能丢失输出。

中文乱码：locale 为 POSIX 的系统上需按 6.2 节导出 UTF-8 环境变量。

输出交错：stdout 与 stderr 分别缓冲，行序每次可能不同，勿以行序做断言。

API 通路：本文走 Classic 通路（AbstractActor + tell）；新项目官方推荐 Typed 通路（pekko-actor-typed），概览见《Apache Pekko 1.7.1 常用工具与 API 详解》篇。

九、常见问题

Q1：编译报 Source option 5 is no longer supported？ Maven 3.6.3 默认的 compiler 插件过旧。在 pom 中显式声明 maven-compiler-plugin 3.11.0（见第四节）。

Q2：运行后没有打印 Greeter 收到消息 就退出了？ system.terminate() 在消息处理前执行所致：确认代码在 terminate 前保留了 Thread.sleep(2000)（tell 是异步投递，消息需短暂等待才会被处理并打印）。

Q3：mvn -q exec:java 报找不到主类 GreeterMain？ 确认 <mainClass> 为 GreeterMain，且源码位于 src/main/java/GreeterMain.java（默认包），并先执行 mvn -q clean compile。

Q4：堆内存如何确认生效？ export MAVEN_OPTS="-Xms256m -Xmx512m" 后运行，另开终端 jps -lv 查看进程 JVM 参数应含 -Xms256m -Xmx512m。

十、参考链接

Apache Pekko 官方文档：https://pekko.apache.org/docs/pekko/current/
Classic Actor 文档：https://pekko.apache.org/docs/pekko/current/general/actors.html
Apache Pekko 官网：https://pekko.apache.org/