Apache StreamPark 2.1.7 配置参数详解

目标：详解 Apache StreamPark 2.1.7 管理台的配置文件——conf/config.yaml（server、datasource、workspace、yarn、project、安全各段）、bin/jvm_opts.sh（JVM 堆 256-512MB）与日志配置，并给出可直接套用的生产模板。所有参数取值均为 Ubuntu 22.04.5 真实环境实测。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Apache StreamPark：2.1.7
• 安装目录：/opt/streampark
• 配置文件：/opt/streampark/conf/config.yaml
• JVM 参数文件：/opt/streampark/bin/jvm_opts.sh
• 日志配置：/opt/streampark/conf/logback-spring.xml
• 管理台端口：10000
• 元数据库：MySQL 8.0.46（库名 streampark）

二、前置条件

• 已按《Apache StreamPark 2.1.7 安装指南》完成安装并初始化元数据库。
• 修改配置后需重启服务生效：systemctl restart streampark（或 bin/streampark.sh restart）。

三、参数查看与修改方式

3.1 配置文件位置

StreamPark 管理台的主配置为 YAML 格式，位于 conf/ 目录：

ls /opt/streampark/conf/

实测目录内容（节选）：

config.yaml        logback-spring.xml

• config.yaml：管理台全部运行时参数（端口、数据源、工作区、YARN、项目构建、安全等）。
• logback-spring.xml：日志级别与输出策略，通过启动参数 -Dlogging.config 指定。

3.2 修改方式与生效

vim /opt/streampark/conf/config.yaml
systemctl restart streampark

⚠️ config.yaml 中 streampark.workspace.local 若指向不存在或不可写的目录，streampark.sh start 会直接报 ERROR: streampark.workspace.local: "<path>" is an invalid path 退出（见常见问题）。

3.3 用 BashJavaUtils 读取当前生效值

管理台内置工具类 org.apache.streampark.console.base.util.BashJavaUtils 可读取 YAML 中任意键的生效值（脚本内部也用它取 server.port 做健康检查）：

/usr/lib/jvm/java-11-openjdk-amd64/bin/java -cp "/opt/streampark/lib/*" \
  org.apache.streampark.console.base.util.BashJavaUtils --get_yaml "server.port" /opt/streampark/conf/config.yaml

实测回显：

10000

四、参数总览

五、核心参数分类详解

5.1 server 段（服务监听与会话）

5.1.1 server.port

管理台 HTTP 端口，默认 10000。Undertow 启动日志会确认监听端口：

server:
  port: 10000

生效核对：

netstat -tlnp | grep 10000

实测回显：

tcp6       0      0 :::10000                :::*                    LISTEN      5923/java

5.1.2 server.session.ttl

登录会话有效期，支持 s/m/h/d 单位。超时后需重新登录：

  session:
    ttl: 2h

5.1.3 server.undertow

Undertow Web 服务器线程与缓冲区配置（实测值）：

  undertow:
    buffer-size: 1024
    direct-buffers: true
    threads:
      io: 16
      worker: 256

• threads.io：IO 线程，一般取 CPU 核数。
• threads.worker：工作线程，处理业务请求，256 可支撑中等并发。
• buffer-size：每块缓冲 1024 字节。
• direct-buffers：true 使用堆外直接缓冲，降低 GC 压力。

5.2 datasource 段（元数据库）

5.2.1 dialect / username / password / url

StreamPark 元数据支持 h2/mysql/pgsql，本环境使用 MySQL 8.0：

datasource:
  dialect: mysql
  username: root
  password: q1w2e3r4
  url: jdbc:mysql://localhost:3306/streampark?useUnicode=true&characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=GMT%2B8

要点：

• 官方包默认 dialect 为 h2（内置文件库），生产务必改为 mysql/pgsql。
• JDBC 串中 serverTimezone=GMT%2B8（URL 编码的 GMT+8）避免时区错误。
• 使用 MySQL 时必须把 MySQL Connector/J jar 放入 /opt/streampark/lib/，否则启动报驱动缺失（见常见问题）。

5.2.2 数据源密码修改

改密码需同步 config.yaml 与数据库账号，例如：

mysql -uroot -pq1w2e3r4 -e "ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '新密码'; FLUSH PRIVILEGES;"

5.3 streampark.workspace 段（工作区）

5.3.1 workspace.local / remote

streampark:
  workspace:
    local: /data/streampark/workspace
    remote: hdfs:///streampark/

• workspace.local：本地工作区，存放项目克隆、编译产物、jars、savepoints 等，禁止设置在 APP_HOME（/opt/streampark）下；目录需预先存在且 root 可读写。首次启动自动创建子目录（实测）：

# ls /data/streampark/workspace/
backups  client  dist  jars  savepoints  shims  uploads  workspace

• workspace.remote：远端依赖目录，使用 YARN 部署时对应 HDFS 路径，格式 hdfs:///streampark/。

5.4 yarn 与 hadoop 段（YARN 模式）

5.4.1 yarn.http-auth 与 hadoop-user-name

YARN 模式下轮询作业状态用：

  yarn:
    http-auth: simple
  hadoop-user-name: hdfs

• yarn.http-auth：YARN ResourceManager 的鉴权方式，simple 对应 Hadoop 简单认证。
• hadoop-user-name：连接 Hadoop 的用户名，需有 HDFS 对应目录读写权限。

纯 Flink 本地模式（无 YARN）可不配置这两项；启动时 HADOOP_HOME is undefined 仅为告警，不影响管理台启动。

5.5 project 段（项目构建）

5.5.1 project.max-build

并发构建 Flink 项目（编译打包）的上限：

  project:
    max-build: 16

超过上限的构建任务会排队等待，避免并发 Maven 编译耗尽 CPU/内存。

5.6 安全段（kerberos / ldap / openapi）

security:
  kerberos:
    login:
      enable: false

ldap:
  enable: false

• security.kerberos.login.enable：接入 Kerberos 认证集群时置 true 并补全 keytab 等配置；本环境 false。
• ldap.enable：对接企业 LDAP 目录时置 true；本环境 false。
• 另有 openapi.white-list 段控制免鉴权白名单接口，默认保持官方值即可。

5.7 JVM 堆参数（jvm_opts.sh）

5.7.1 堆内存限制（256-512MB）

管理台是 Spring Boot Java 进程，默认堆 -Xms512m -Xmx1024m，运维规范要求限制到 256-512MB。修改 /opt/streampark/bin/jvm_opts.sh：

vim /opt/streampark/bin/jvm_opts.sh

实测生效值（文件头部）：

-server
-Xms256m
-Xmx512m
-Xmn128m

生效核对（jps -v，JDK 自带）：

# jps -v | grep StreamParkConsoleBootstrap
5923 StreamParkConsoleBootstrap -Xms256m -Xmx512m -Xmn128m -XX:+ExitOnOutOfMemoryError -XX:+HeapDumpOnOutOfMemoryError -XX:+IgnoreUnrecognizedVMOptions -XX:+UseGCLogFileRotation -Xloggc:/opt/streampark/logs/gc.log

jps -v 会打印完整 classpath，此处摘录核对 -Xms256m -Xmx512m -Xmn128m。

💡 脚本逻辑：streampark.sh 中 JAVA_OPTS=${JAVA_OPTS:-"${JVM_ARGS}"}——设置了环境变量 JAVA_OPTS 时优先使用环境变量（systemd Environment= 注入同样生效），否则读取 jvm_opts.sh。管理台只做作业编排，堆无需过大；计算内存由 Flink/Spark 作业承担。

5.8 日志配置（logback-spring.xml）

conf/logback-spring.xml 控制日志级别与输出，启动参数 -Dlogging.config=/opt/streampark/conf/logback-spring.xml 指定。默认 root 级别 info，日志落盘 logs/streampark.out：

<configuration>
  <springProfile name="dev">
    <logger name="org.apache.streampark" level="DEBUG"/>
  </springProfile>
  <springProfile name="prod">
    <logger name="org.apache.streampark" level="INFO"/>
  </springProfile>
</configuration>

排查问题时临时把 org.apache.streampark 调为 DEBUG 可看到更多细节，排查后恢复。

六、生产配置模板

适用场景：16GB 内存、SSD 磁盘、单管理台对外提供 Flink 作业开发/发布/运维，元数据库 MySQL 独立实例（或同机）。

server:
  port: 10000
  session:
    ttl: 2h
  undertow:
    buffer-size: 1024
    direct-buffers: true
    threads:
      io: 16
      worker: 256

datasource:
  dialect: mysql
  username: root
  password: q1w2e3r4
  url: jdbc:mysql://localhost:3306/streampark?useUnicode=true&characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=GMT%2B8

streampark:
  workspace:
    local: /data/streampark/workspace
    remote: hdfs:///streampark/
  yarn:
    http-auth: simple
  hadoop-user-name: hdfs
  project:
    max-build: 16

security:
  kerberos:
    login:
      enable: false

ldap:
  enable: false

配合 JVM 堆参数（bin/jvm_opts.sh）：

-server
-Xms256m
-Xmx512m
-Xmn128m

内存说明：管理台为作业编排进程，-Xms256m -Xmx512m 足够；若并发构建任务多（project.max-build 大），Maven 子进程内存另计，需给系统预留余量。磁盘上保证 /data/streampark/workspace 有足够空间存放项目源码与打包产物。

七、常见问题

7.1 启动报 MySQL 驱动缺失

错误回显：

Exception in thread "main" java.lang.ExceptionInInitializerError: The datasource.dialect is MySQL, but the classes "com.mysql.cj.jdbc.Driver" and "com.mysql.jdbc.Driver" not found. Please ensure that the MySQL Connector/J is located under $streampark/lib.

原因：datasource.dialect=mysql 但 lib/ 下无 MySQL 驱动（官方包因 Apache 2.0 许可不内置）。 解决：下载 mysql-connector-j-8.0.33.jar 放入 /opt/streampark/lib/ 后重启。

7.2 启动报 workspace 路径无效

错误回显：

ERROR: streampark.workspace.local: "<path>" is an invalid path, please reconfigure in $CONFIG
NOTE: "streampark.workspace.local" should not be set under APP_HOME($APP_HOME) directory. Set it to a secure directory outside of APP_HOME.

解决：在 config.yaml 把 streampark.workspace.local 指向 APP_HOME 之外、已存在且 root 可读写的目录（如 /data/streampark/workspace），mkdir -p 后再启动。

7.3 改了 server.port 不生效

解决：systemctl restart streampark 后以 netstat -tlnp | grep <端口> 核对；若 status 因 pid 残留误报 running，先查 logs/streampark.out 真实异常。

7.4 时区/时间相关错误

解决：JDBC 串必须带 serverTimezone=GMT%2B8（URL 编码的 GMT+8）；同时确认系统时区（timedatectl），否则登录会话与作业时间可能偏移。

7.5 JVM 参数未生效

解决：确认 JAVA_OPTS 环境变量未被设置（它优先于 jvm_opts.sh）；修改 jvm_opts.sh 后务必重启进程，用 jps -v | grep StreamParkConsoleBootstrap 核对实际生效的 -Xms/-Xmx/-Xmn 值。

八、参考链接

• Apache StreamPark 官网：https://streampark.apache.org/
• 官方文档：https://streampark.apache.org/docs/
• GitHub：https://github.com/apache/streampark