Apache Pekko 1.7.1 配置参数详解

目标：系统讲解 Apache Pekko 1.7.1 的主要配置项。Pekko 是以 jar 引入的 Actor 工具库，配置分布在三层：构建层（pom.xml）、JVM 与环境变量层、框架层（classpath 上的 application.conf，经 com.typesafe:config 1.4.9 加载）。本文对每个参数给出含义、取值与设置方式，并给出 256–512MB 小内存场景的配置模板。构建层与 JVM 层参数均在 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（pekko-actor_2.13；传递依赖 com.typesafe:config 1.4.9）
• 示例工程：/opt/pekko-demo/（主类 GreeterMain，位于默认包）
• 配置载体：pom.xml、环境变量、classpath 上的 application.conf

二、前置条件

已按《Ubuntu 22.04 安装 Apache Pekko 1.7.1 指南》完成 JDK 17 + Maven 安装与依赖引入，工程可编译：

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

实测：无输出即编译成功（首次编译会下载 pekko-actor 1.7.1 / scala-library 2.13.18 / typesafe config 1.4.9）。

三、参数查看与修改方式

💡 说明：Pekko 的框架层配置基于 com.typesafe:config 1.4.9（依赖树实测携带），启动时按「系统属性 > application.conf > reference.conf（内置默认）」的优先级合并；pekko://hello-pekko 这类系统地址即由 ActorSystem 名称生成（实测日志可见 CoordinatedShutdown(pekko://hello-pekko)）。

四、参数总览

⚠️ 注意：标「内置默认」的取值来自 Pekko 1.7.1 发行包内的 reference.conf（经 com.typesafe:config 加载），本次实测未逐项改跑验证，落地调参前请以运行环境的 reference.conf 为准（核对生效值的方法见 5.4 节）。

五、核心参数详解

5.1 构建层参数（pom.xml）

• pekko.version = 1.7.1：版本号集中定义，所有 pekko-* 模块引用同一属性，避免模块间版本漂移：

<properties>
  <pekko.version>1.7.1</pekko.version>
</properties>

• maven.compiler.release = 17：按服务器 JDK 大版本设置；Ubuntu 22.04 的 Maven 3.6.3 自带 maven-compiler-plugin 3.1，不支持该属性，必须显式升级 compiler 插件到 3.11.0，否则编译报 Source option 5 is no longer supported：

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

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.11.0</version>
</plugin>

• mainClass = GreeterMain：exec-maven-plugin 3.1.0 的运行入口，主类位于默认包时直接写类名：

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <version>3.1.0</version>
  <configuration>
    <mainClass>GreeterMain</mainClass>
  </configuration>
</plugin>

5.2 JVM 层参数（堆内存）

Java 进程堆限制在 256–512MB，通过 MAVEN_OPTS 注入（exec:java 与 Maven 进程同 JVM 运行，该限制即示例进程的堆限制）：

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

复核实际生效堆（另开终端）：

jps -lv

输出中 exec 进程的 JVM 参数应含 -Xms256m -Xmx512m；ps -ef | grep [j]ava 同样可见该标记。若发现堆未按预期生效，优先检查 MAVEN_OPTS 是否在当前会话真实导出、有无后续 export 覆盖。

💡 说明：小堆场景（256–512MB）建议同步调低框架层 dispatcher 并行度（见 5.4 节），避免线程数超出可用内存承载。

5.3 JVM 层参数（编码与 locale）

locale 为 POSIX 的系统上，中文 println 会输出 ????。实测以下设置后中文正常：

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

5.4 框架层参数（application.conf）

Pekko 启动时经 com.typesafe:config 1.4.9 从 classpath 根读取 application.conf，与内置 reference.conf 合并；也可用 -Dpekko.loglevel=DEBUG 这类系统属性临时覆盖。在 src/main/resources/application.conf 放置覆盖键即可生效：

pekko {
  loglevel = "INFO"
  stdout-loglevel = "WARNING"
  log-dead-letters = 10

  actor {
    default-dispatcher {
      fork-join-executor {
        parallelism-min = 4
        parallelism-factor = 2.0
        parallelism-max = 8
      }
    }
  }
}

常用键含义（默认值取自 reference.conf）：

核对生效配置的方法：在代码中读取运行时设置，例如对 ActorSystem system 执行 system.settings().config().getString("pekko.loglevel") 并打印，即得实际生效值；系统属性 -Dpekko.loglevel=DEBUG 优先级高于 application.conf，可用于临时调试。

⚠️ 前置说明：上表「默认值」来自 Pekko 1.7.1 内置 reference.conf，本次实测未逐项改跑验证；示例 application.conf 中 parallelism-min 4 / factor 2.0 / max 8 是面向 256–512MB 小堆的调低示例值，生产请按核数与内存重新评估。

六、生产配置模板

适用场景：4GB 内存以内的演示/开发服务器或低配小规格实例，JVM 堆 256–512MB，单机运行 hello-pekko 类轻量 Actor 应用。

MAVEN_OPTS 与编码环境（写入会话导出或 /etc/environment）：

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

src/main/resources/application.conf：

pekko {
  loglevel = "INFO"
  stdout-loglevel = "WARNING"
  log-dead-letters = 10

  actor {
    default-dispatcher {
      fork-join-executor {
        # 小堆（256-512MB）场景调低并行度，避免线程栈挤占内存
        parallelism-min = 4
        parallelism-factor = 2.0
        parallelism-max = 8
      }
    }
  }
}

💡 说明：多核大内存机器可上调 parallelism-max（内置默认 64）；死信日志量大时把 log-dead-letters 设为 0 可减少噪音。

七、常见问题

Q1：编译报 Source option 5 is no longer supported？ Maven 3.6.3 默认 maven-compiler-plugin 3.1 不支持 maven.compiler.release 属性。按 5.1 节显式声明 compiler 插件 3.11.0。

Q2：运行示例中文输出为 ????？ locale 为 POSIX 所致，按 5.3 节导出 JAVA_TOOL_OPTIONS 与 LANG/LC_ALL 后重新运行。

Q3：如何确认 application.conf 里的键已生效？ 在代码中用 system.settings().config().getString("pekko.loglevel") 打印实际生效值；或用系统属性 -Dpekko.loglevel=DEBUG 对比日志详略变化验证优先级。

Q4：日志级别调 DEBUG 后仍看不到调试日志？ 直打 stdout 的日志受 pekko.stdout-loglevel（默认 WARNING）控制，与 pekko.loglevel 是两个键，需分别调整。

八、参考链接

• Pekko 官方配置文档：https://pekko.apache.org/docs/pekko/current/general/configuration.html
• typesafe config 项目：https://github.com/lightbend/config
• Apache Pekko 官网：https://pekko.apache.org/