Apache StreamPipes 0.98.0 配置参数详解

目标：详解 Apache StreamPipes 0.98.0 的配置体系——以 SP_* 环境变量为核心的参数全集（核心服务网络、CouchDB 元数据存储、时序存储、消息代理、安全账号与 JWT、初始化安装、健康检查、日志），给出默认值、示例与可直接套用的生产模板，并覆盖 JVM 堆 256-512MB 的设置与验证。参数默认值基于 0.98.0 源码（Envs.java）与实测环境核对。

一、环境信息

Apache StreamPipes：0.98.0（2025-11-28 发布，官方最新稳定版）
配置方式：环境变量（SP_* 前缀体系）——平台各服务启动时由 Envs 枚举读取并绑定
配置来源：源码 streampipes-commons/src/main/java/org/apache/streampipes/commons/constants/Envs.java（0.98.0，权威默认值）
涉及服务：backend（核心后端，8030）、extensions-all-iiot（流水线元素扩展，8090）、couchdb（元数据存储，5984）、influxdb（时序存储，8086）、nats（消息代理，4222）
默认管理员账号：admin@streampipes.apache.org / admin（登录用户名为邮箱）
内部服务账号：sp-service-client / my-apache-streampipes-secret-key-change-me

二、参数查看与修改方式

StreamPipes 的配置以环境变量注入（官方发行形态无独立配置文件；不推荐改动部署内部的应用配置文件，改动易被重建覆盖）。修改方式：

在官方部署编排文件（installer/compose 目录）对应服务的 environment 区追加或覆盖 SP_* 变量；
重新执行编排启动命令使配置生效；
核对生效值：backend 日志（启动时打印关键配置）与 REST API（/api/v2/info/system、/api/v2/info/versions 等）。

示例（backend 服务注入消息协议与 JWT 签名模式两个变量）：

  backend:
    environment:
      - SP_PRIORITIZED_PROTOCOL=nats
      - SP_JWT_SIGNING_MODE=HMAC

约定：未显式设置时使用 Envs.java 定义的默认值；下表「默认值」列即 0.98.0 源码默认。

三、参数总览

参数	默认值	说明
`SP_CORE_SCHEME`	`http`	核心服务访问协议
`SP_CORE_HOST`	`backend`	核心服务主机名（部署网络内服务名）
`SP_CORE_PORT`	`8030`	核心服务端口
`SP_PRIORITIZED_PROTOCOL`	`kafka`	消息协议优先级（官方编排设为 `nats`）
`SP_KAFKA_RETENTION_MS`	`600000`	Kafka 消息保留时长（毫秒）
`SP_COUCHDB_HOST`	`couchdb`	元数据库主机
`SP_COUCHDB_PORT`	`5984`	元数据库端口
`SP_COUCHDB_USER`	`admin`	元数据库管理员
`SP_COUCHDB_PASSWORD`	`admin`	元数据库密码
`SP_TS_STORAGE`	`influxdb`	时序存储类型
`SP_TS_STORAGE_HOST`	`influxdb`	时序存储主机
`SP_TS_STORAGE_PORT`	`8086`	时序存储端口
`SP_TS_STORAGE_TOKEN`	`sp-admin`	时序存储访问 token
`SP_TS_STORAGE_ORG`	`sp`	时序存储组织
`SP_TS_STORAGE_BUCKET`	`sp`	时序存储 bucket
`SP_INITIAL_ADMIN_EMAIL`	`admin@streampipes.apache.org`	首次安装管理员邮箱（登录用户名）
`SP_INITIAL_ADMIN_PASSWORD`	`admin`	首次安装管理员密码
`SP_INITIAL_SERVICE_USER`	`sp-service-client`	内部服务账号
`SP_INITIAL_SERVICE_USER_SECRET`	`my-apache-streampipes-secret-key-change-me`	内部服务账号密钥
`SP_JWT_SIGNING_MODE`	空（默认 HMAC）	JWT 签名模式（HMAC / RSA）
`SP_JWT_SECRET`	空	JWT HMAC 签名密钥（生产必改）
`SP_ENCRYPTION_PASSCODE`	`eGgemyGBoILAu3xckoIp`	敏感配置加密口令（生产必改）
`SP_INITIAL_WAIT_BEFORE_INSTALLATION_MS`	`5000`	首次安装延迟（毫秒）
`SP_HEALTH_CHECK_INTERVAL_MS`	`30000`	健康检查间隔（毫秒）
`SP_LOGGING_CONSOLE_ENABLED`	`true`	控制台日志开关
`SP_LOGGING_FILE_ENABLED`	`false`	文件日志开关
`SP_LOGGING_FILE_DIR`	`logs`	文件日志目录
`JAVA_TOOL_OPTIONS`	空	JVM 参数注入（堆 256-512MB 见 4.9）

四、核心参数分类详解

4.1 核心服务网络（backend）

参数	默认值	说明
`SP_CORE_SCHEME`	`http`	核心服务对外协议，启用 TLS 时改 `https`
`SP_CORE_HOST`	`backend`	核心服务主机名；单机裸测环境回退 `localhost`（源码 dev 默认）
`SP_CORE_PORT`	`8030`	核心服务 REST 端口
`SP_HOST` / `SP_PORT`	空	服务监听地址/端口（未设置时随应用默认）

示例（core 服务地址显式指定）：

  backend:
    environment:
      - SP_CORE_HOST=backend
      - SP_CORE_PORT=8030

⚠️ 修改 SP_CORE_* 需与其他服务（ui、extensions-all-iiot）的指向保持一致，否则管理台无法连通后端。

4.2 CouchDB 元数据存储

参数	默认值	说明
`SP_COUCHDB_PROTOCOL`	`http`	元数据库访问协议
`SP_COUCHDB_HOST`	`couchdb`	元数据库主机（部署网络内服务名）
`SP_COUCHDB_PORT`	`5984`	元数据库端口
`SP_COUCHDB_USER`	`admin`	元数据库管理员账号
`SP_COUCHDB_PASSWORD`	`admin`	元数据库密码（生产必改）

实测核对：couchdb 服务响应 {"couchdb":"Welcome","version":"3.3.1",...}；后端建库后元数据落在 adapterdescription、pipeline、users 等 14 个业务库。

4.3 时序存储（InfluxDB / Data Lake）

参数	默认值	说明
`SP_TS_STORAGE`	`influxdb`	时序存储类型
`SP_TS_STORAGE_PROTOCOL`	`http`	时序存储访问协议
`SP_TS_STORAGE_HOST`	`influxdb`	时序存储主机（部署网络内服务名）
`SP_TS_STORAGE_PORT`	`8086`	时序存储端口
`SP_TS_STORAGE_TOKEN`	`sp-admin`	时序存储访问 token（与编排内 `DOCKER_INFLUXDB_INIT_ADMIN_TOKEN` 一致）
`SP_TS_STORAGE_ORG`	`sp`	时序存储组织
`SP_TS_STORAGE_BUCKET`	`sp`	时序存储 bucket（Data Lake 写入目标）
`SP_TS_STORAGE_IOT_DB_SESSION_POOL_SIZE`	`10`	连接池大小
`SP_TS_STORAGE_IOT_DB_USER` / `_PASSWORD`	`root` / `root`	兼容 IOTDB 驱动的账号（默认形态不使用）

实测核对：influxdb 服务响应 InfluxDB v2.6.1 (git: 9dcf880fe0)；SP_TS_STORAGE_TOKEN 必须与 InfluxDB 初始化 token 一致，否则数据写入报 401。

4.4 消息代理（NATS / Kafka / MQTT / Pulsar）

参数	默认值	说明
`SP_PRIORITIZED_PROTOCOL`	`kafka`	消息协议优先级；官方编排设为 `nats`
`SP_NATS_HOST`	`nats`	NATS 主机
`SP_NATS_PORT`	`4222`	NATS 端口
`SP_KAFKA_HOST`	`kafka`	Kafka 主机
`SP_KAFKA_PORT`	`9092`	Kafka 端口
`SP_KAFKA_RETENTION_MS`	`600000`	Kafka 消息保留时长（毫秒，默认 10 分钟）
`SP_MQTT_HOST`	`mosquitto`	MQTT 代理主机
`SP_MQTT_PORT`	`1883`	MQTT 代理端口
`SP_PULSAR_URL`	`pulsar://localhost:6650`	Pulsar 连接串

说明：官方默认编排部署 NATS 并以 SP_PRIORITIZED_PROTOCOL=nats 启用；若改用官方 Kafka 消息形态编排，则把该变量设回默认值 kafka 并保证 SP_KAFKA_HOST/PORT 指向可达的 Kafka。

4.5 安全账号与 JWT

参数	默认值	说明
`SP_INITIAL_ADMIN_EMAIL`	`admin@streampipes.apache.org`	首次安装创建的管理员邮箱（登录用户名）
`SP_INITIAL_ADMIN_PASSWORD`	`admin`	首次安装创建的管理员密码（生产必改）
`SP_INITIAL_SERVICE_USER`	`sp-service-client`	内部服务账号（扩展服务调用后端 API 用）
`SP_INITIAL_SERVICE_USER_SECRET`	`my-apache-streampipes-secret-key-change-me`	内部服务账号密钥（生产必改）
`SP_JWT_SIGNING_MODE`	空（默认 HMAC）	JWT 签名模式：HMAC 或 RSA
`SP_JWT_SECRET`	空	HMAC 签名密钥（生产必改，建议 32 字节以上随机串）
`SP_JWT_PRIVATE_KEY_LOC` / `SP_JWT_PUBLIC_KEY_LOC`	空	RSA 模式私钥/公钥路径
`SP_ENCRYPTION_PASSCODE`	`eGgemyGBoILAu3xckoIp`	平台敏感配置（账号口令等）加密口令（生产必改）
`SP_OAUTH_ENABLED`	`false`	OAuth 登录开关
`SP_OAUTH_REDIRECT_URI`	空	OAuth 回调地址

实测核对：默认管理员登录（admin@streampipes.apache.org / admin）返回 HMAC 签名的 JWT（alg=HS256）；/api/v2/users 列出该账号 principalId。登录用户名是邮箱，不是 admin。

4.6 初始化安装

参数	默认值	说明
`SP_INITIAL_WAIT_BEFORE_INSTALLATION_MS`	`5000`	启动后延迟多久开始自动安装（毫秒）
`SP_SETUP_INSTALL_PIPELINE_ELEMENTS`	继承默认	安装流水线元素（true 时注册全部扩展元素）
`SP_INFLUX_INIT_MODE`（编排层变量）	`setup`	InfluxDB 初始化模式：`setup`（新装）/ `upgrade`（从 0.91.0 前版本迁移）

实测：backend 日志可见 Auto-setup will start in 5000 milliseconds → Creating admin user...；安装完成后 /api/v2/setup/configured 返回 {"configured":true}，期间登录接口可能返回 401，等待初始化完成即可。

4.7 健康检查与监控

参数	默认值	说明
`SP_HEALTH_CHECK_INTERVAL_MS`	`30000`	扩展服务健康检查间隔（毫秒）
`SP_HEALTH_CHECK_INITIAL_DELAY`	`10000`	健康检查初始延迟（毫秒）
`SP_HEALTH_SERVICE_MAX_UNHEALTHY_TIME_MS`	`60000`	允许不健康的最长时长（毫秒），超时判定失联
`SP_LOG_FETCH_INTERVAL_MS`	`60000`	日志拉取间隔（毫秒）
`SP_PROMETHEUS_ENDPOINT_INCLUDE`	`health,prometheus`	暴露的 actuator 端点
`SP_SETUP_PROMETHEUS_ENDPOINT`	`false`	是否启用 Prometheus 端点采集

4.8 日志

参数	默认值	说明
`SP_LOGGING_CONSOLE_ENABLED`	`true`	控制台日志开关
`SP_LOGGING_FILE_ENABLED`	`false`	文件日志开关（开启后落盘）
`SP_LOGGING_FILE_PREFIX`	`streampipes`	日志文件名前缀
`SP_LOGGING_FILE_DIR`	`logs`	日志文件目录
`SP_LOGGING_FILE_PATTERN`	`%d{yyyy-MM-dd HH:mm:ss} %-5level %logger{36} - %msg%n`	文件日志格式

编排层已统一限制日志驱动与轮转（max-size: 12m、max-file: 5），无需额外配置；如需排查请用编排日志命令查看 backend 日志（见《Apache StreamPipes 0.98.0 Docker Compose 部署指南》「常用运维命令」）。

4.9 JVM 堆内存（256-512MB）

backend 与 extensions-all-iiot 均为 Java 17 进程，默认无显式堆参数（实测 cmdline 仅 java org.springframework.boot.loader.launch.JarLauncher）。生产建议把堆限制在 256-512MB，通过 JAVA_TOOL_OPTIONS 环境变量注入（两个服务分别设置）：

  backend:
    environment:
      - JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m
  extensions-all-iiot:
    environment:
      - JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m

生效验证（实测回显）：

backend 日志出现 Picked up JAVA_TOOL_OPTIONS: -Xms256m -Xmx512m
GET /api/v2/info/system 返回 "totalMemory":268435456,"totalMemoryKB":262144（256MB，对应 -Xms256m；注入前默认约 148MB）

五、生产配置模板

把以下内容合并到官方编排文件的 services.backend 与 services.extensions-all-iiot 的 environment 区（或写成独立 override 文件），即生产安全基线：

  backend:
    environment:
      - SP_PRIORITIZED_PROTOCOL=nats
      - SP_JWT_SIGNING_MODE=HMAC
      - SP_JWT_SECRET=q1w2e3r4StreampipesJwtSecret2026
      - SP_ENCRYPTION_PASSCODE=q1w2e3r4StreampipesPasscode
      - SP_INITIAL_ADMIN_PASSWORD=q1w2e3r4
      - JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m

  extensions-all-iiot:
    environment:
      - JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m

配套修改元数据库与时序存储口令（保持 SP_COUCHDB_PASSWORD、SP_TS_STORAGE_TOKEN 与编排内对应初始化变量一致），并同步修改官方编排中 couchdb 的 COUCHDB_PASSWORD 与 influxdb 的 DOCKER_INFLUXDB_INIT_ADMIN_TOKEN。

⚠️ 模板中 SP_JWT_SECRET、SP_ENCRYPTION_PASSCODE 与管理员口令为演示值，生产必须替换为强随机值，并在修改后立即测试登录；JWT 密钥变更会使既有登录态全部失效（重新登录即可）。

六、常见问题

Q1：改了 SP_* 变量不生效？ 定位：修改后未重建或改错了服务。解决：重新执行编排启动命令重建使配置生效；确认变量加在对应服务（backend 的变量不要加在 ui）。

Q2：SP_TS_STORAGE_TOKEN 与 InfluxDB 不一致导致 Data Lake 写入 401？ 定位：时序存储 token 不匹配。解决：把 SP_TS_STORAGE_TOKEN 与编排内 DOCKER_INFLUXDB_INIT_ADMIN_TOKEN 设为同一值（默认均为 sp-admin）。

Q3：登录返回 401，backend 日志提示 None or to many users with matching username？ 定位：初始化未完成或用户名写错。解决：等首次安装完成（/api/v2/setup/configured 返回 {"configured":true}）；登录用户名必须用邮箱 admin@streampipes.apache.org（如已改 SP_INITIAL_ADMIN_EMAIL 则用新邮箱）。

Q4：Picked up JAVA_TOOL_OPTIONS 未出现在日志？ 定位：JAVA_TOOL_OPTIONS 未注入到对应服务。解决：确认环境变量加在 backend / extensions-all-iiot 两个服务；重启后用编排日志命令查看 backend 日志核对。

Q5：JWT 密钥改了之后管理台全部登出？ 定位：正常现象，JWT 签名密钥变更导致旧 token 全部失效。解决：用新配置的管理员账号重新登录即可；这是验证密钥生效的正确信号。

七、参考链接

Apache StreamPipes 官网：https://streampipes.apache.org/
源码（Envs.java 参数定义）：https://github.com/apache/streampipes/blob/rel/0.98.0/streampipes-commons/src/main/java/org/apache/streampipes/commons/constants/Envs.java
官方文档：https://streampipes.apache.org/docs/
下载页：https://downloads.apache.org/streampipes/