跳到主要内容

环境变量参考

PlantPulse 的所有配置都始于一个环境变量。本页面是安装与运行期间所涉及变量的分类别参考指南。

本页面涵盖基础设施/部署环境变量(PP_* · DOCKER_PP_*)。关于应用程序运行属性(engine.*, websocket.* 等)，请参考 属性参考。

1. 配置文件在哪里？​

Platform 以 Docker Compose 栈形式运行，其值的定义处有两个。

定义处包含内容读取者
plantpulse-platform-docker/bin/env.sh在主机上确定的值 — 凭据默认值、docker 运行时、网络、在主机上计算出的资源值主机的运行脚本
plantpulse-platform-docker/compose/docker-compose.yml容器实际看到的值容器
应用容器不读取 env.sh

六个应用(plantpulse-server-web · plantpulse-batch-web · plantpulse-warehouse-web · plantpulse-plugin-opcua · plantpulse-plugin-aasx · plantpulse-ha)不 source env.sh。应用看到的定义处只有 compose 一个。

也就是说，仅存在于 env.sh 而不在 compose 中的名称无法触达应用，应用将使用 jar/WAR 内置默认值运行。实际上，曾发生过在仅在数据湖中更改标识符的站点上，五个应用持续使用旧名称而导致事故的情况(2026-08-29)。

每个层级决定值的方式不同。

层级值由什么决定
plantpulse-datalakecompose 传递的值 → 容器的 pd 以 ${VAR:-기본값} 形式接收。传递的值优先
六个应用compose 传递的环境变量覆盖 jar/WAR 内置默认值
plantpulse-certs仅查看 compose 的 PP_TLS_*。不 source 文件

优先级 — 谁覆盖谁​

在主机端，bin/env.sh 从上到下的运行顺序即为优先级。

优先级来源胜出原因
1 (最高)/etc/kopens/plantpulse-platform.env (Secret Sidecar)export VAR=값 无条件赋值，即使是 Shell export 也会被覆盖
2/etc/kopens/platform.node.env (单节点)在 Sidecar 之后 source，同样为无条件赋值
3调用 Shell 的 export胜过默认值的 :- — 但仅在 1·2 未定义该名称时
4 (最低)bin/env.sh 的 ${VAR:-기본값}仅在 unset 时有效
最容易出错的点在于 1 号优先级最高

在安装完成的节点上，PP_PG_PASSWORD=새값 bin/up.sh 将被静默忽略。因为 Sidecar 已经持有该名称。更改值的唯一方法是 bin/passwd.sh / bin/rotate-secret.sh。

🔑 机密值的正本在 /etc/kopens/ 之下​

DB · 消息密码与 API 密钥不在上述两个文件中，而是在 Sidecar 中

服务账号密码(PP_PG_PASSWORD · PP_CASSANDRA_PASSWORD · PP_MQ_PASSWORD 等)与 API 密钥的实际值位于 repo 树之外的 Sidecar 文件中。

文件状态
/etc/kopens/plantpulse-platform.env当前正本 — platform · ai · studio 三款产品通用协议(plantpulse-<product>.env)，权限 0600
/opt/kopens/plantpulse-platform.env旧路径 (仅在 2026-08-25 ~ 08-29 存在) — 不读也不写。若仍然存在，安装脚本将其还原为正本

请先通过 ls -l /etc/kopens/ 确认正本是否存在。

Sidecar 覆盖 bin/env.sh。 因为 env.sh 在最上方先 source Sidecar，且其下方所有值均为 ${VAR:-기본값} 形式。因此，仅修改 env.sh 的密码不会产生任何影响 — Sidecar 的旧值将继续胜出。

安装时不生成随机数

install.sh 将 bin/env.sh 的默认值原样加载到 Sidecar。因此，在委任(Commissioning)时必须更换 → 初始密码

由于 compose 要求密码为 ${PP_X:?}，若值为空，栈将无法启动，而非以«半配置状态启动»。

请勿通过编辑文件更改密码·API 密钥

仅修改 Sidecar 无法完成同步。对于 PostgreSQL · Aster TSDB 等服务器账号为正本的值，必须同步更改服务器端，且若顺序错误，Platform 将无法启动。

请使用专用流程 — 更改密码 (凭据轮转)。此操作在委任时执行一次即可。

🔑 标记为机密值。请勿将原文输入至 git · Issue · 聊天工具。

1.5 容器运行时 · 主机资源 (DOCKER_*)​

由 bin/env.sh 决定。以下资源值非固定默认值，而是根据主机计算得出 — 若使用常量，可能会导致在低配主机上无法启动(若 --cpus 大于实际核心数，docker 将拒绝启动)或在启动过程中被 OOM-kill。针对每个盒子指定的值始终优先。

| 变量 | 决定方式 | |---|---|---| | DOCKER_CMD | docker (podman 同样可用) | | DOCKER_REGISTRY | docker.kopens.io/pp — 栈镜像八个仓库的前缀 | | PP_IMAGE_TAG | latest。发布时建议使用 2026.08 等固定标签 | | DOCKER_PP_CPUS | nproc (读取失败时为 8) | | DOCKER_PP_CLUSTER_CORES | DOCKER_PP_CPUS - 2, 最少 4 · 最多 30。以 PP_CLUSTER_CORES 形式传递给容器 | | DOCKER_PP_MEMORY | 主机 RAM 的 90%, 最少 8G | | DOCKER_DATALAKE_MEMORY | 96G — 数据湖 Master 的最小值。该值被截断至不超过主机 RAM 的 90%，因此若主机 RAM 低于 107G，则无法提供 96G，该主机即为规格不足。64G 并非支持规格 (系统要求) | | DOCKER_PW_MEMORY | 60G, 若主机较小则为 RAM 的 90% — Worker 与 Master 使用相同镜像，但运行服务较少，故单独设置 | | DOCKER_PP_DATA_DISK_NAME | 将承载 / 的实际磁盘通过 findmnt + lsblk 反向追踪 (LVM/dm 追踪至物理磁盘)。失败时为 sda | | DOCKER_PP_EXTERNAL_IP | 默认空值。仅在 NAT 环境下填写实际公网 IP |

请勿在 DOCKER_PP_EXTERNAL_IP 中输入无效 IP

该值经由 PP_SERVICE_IP 进入 TLS 证书的 SAN。只要混入一个格式不符的 IP，openssl 将拒绝整个扩展文件，导致无法生成任何证书。

网络​

变量默认值说明
DOCKER_PP_NETWORKpp-netdocker network 名称
DOCKER_SUBNET10.99.0.0/24子网 (避免与其他容器网络重叠)
DOCKER_GATEWAY10.99.0.1网关
DOCKER_PP_IP10.99.0.100数据湖固定 IP

各应用内存上限 — 由 compose 决定​

为每个应用单独设置 mem_limit 是容器隔离的第一目的(OOM 隔离)。即使某个应用达到上限，其他应用及基础设施仍能保持运行。

变量默认值服务
DOCKER_SERVER_MEMORY / DOCKER_SERVER_HEAP14g / 8gplantpulse-server-web
DOCKER_BATCH_MEMORY / DOCKER_BATCH_HEAP4g / 3gplantpulse-batch-web
DOCKER_WAREHOUSE_MEMORY8gplantpulse-warehouse-web
DOCKER_OPCUA_MEMORY3gplantpulse-plugin-opcua
DOCKER_AASX_MEMORY3gplantpulse-plugin-aasx
DOCKER_HA_MEMORY2gplantpulse-ha
DOCKER_DATALAKE_MEMORY96gplantpulse-datalake

卷​

变量默认值用途
DOCKER_PP_DATA_VOLUMEpp-data数据持久存储
DOCKER_PP_TEMP_VOLUMEpp-temp临时数据
DOCKER_PP_BACKUP_VOLUMEpp-backup备份存储
DOCKER_PP_SECURITY_VOLUMEpp-securityTLS 材质
DOCKER_PP_PROXY_CERTS_VOLUME—不存在该变量。代理证书卷 pp-proxy-certs 已在 compose 中以名称形式固定

install.sh 一次性选项​

变量效果
SKIP_OS=1省略 OS 设置
SKIP_LOGIN=1省略仓库登录
SKIP_FW=1省略防火墙设置
DOCKER_DATA_DIRDocker data-root 路径 (默认 /data1/docker-data)

2. 至少请确认以下内容​

在新单机服务器安装中，实际需要操作的内容很少，因为资源值由安装脚本根据主机自动计算。

项目位置备注
🔑 各类 *_PASSWORD · API 密钥bin/passwd.sh / bin/rotate-secret.sh委任时必须更换。通过编辑文件无法更改
PP_LANGbin/env.sh若为韩语运行则设为 ko (默认 en)
PP_TZbin/env.sh韩语运行保持 Asia/Seoul
DOCKER_PP_EXTERNAL_IPbin/env.sh仅在 NAT 之后时填写。否则保持空值
DOCKER_DATALAKE_MEMORYbin/env.sh默认 96G。主机规格较小时会自动降低
下文 §3 之后的 PP_* 为 «容器看到的名称»

PP_HOST_IP · PP_DATA_DIR · PP_CLUSTER_CORES 等值是容器内部使用的名称，而在主机上确定该值的是 compose 和 bin/env.sh 的 DOCKER_* (见 §1.5)。例如，核心数由 DOCKER_PP_CLUSTER_CORES 计算并以 PP_CLUSTER_CORES 形式传递给容器。

请勿期望仅在主机上修改 PP_CLUSTER_CORES 即可生效 — 若不传递，Kyuubi 将信任一个不存在的 30 核配置（即便盒子只有 16 vCPU），导致永远无法启动。

3. 平台基础 / 网络 / 资源​

变量默认值说明
PP_HOME/opt/kopens/plantpulse-platform安装根目录 (容器内部相同)
PP_SCHEMEPP部署标识方案
PP_MODEMASTER节点角色 (MASTER / Worker) — 集群化(水平扩展)轴
PP_OPTIONS{}单个服务 on/off 专用 JSON (参考下文 §3.1)
PP_HOST_IP127.0.0.1本节点的 IP
PP_SERVICE_IP127.0.0.1服务绑定 IP
PP_MASTER_IP127.0.0.1Worker/APP 层级面向的Master(数据湖) IP。同时也是 Kafka advertised.listeners 的来源。安装 DATALAKE 层级时若未指定，则自动检测为主机 IP
PP_PUBLIC_IP127.0.0.1外部公开 IP (NAT 环境)
PP_DATA_DIR/data1/pp-data数据根目录
PP_TEMP_DIR/data1/pp-temp临时文件根目录
PP_BACKUP_DIR/data1/pp-backup备份根目录
PP_DATA_DISK_NAMEsdb数据磁盘设备名
PP_CLUSTER_CORES30使用核心数
PP_CLUSTER_MEMORY_BY_CORE2G每核内存分配
PP_LANGen默认语言
PP_TZAsia/Seoul时区 (自动应用于所有 java 进程)

3.1 PP_OPTIONS — 单个服务 on/off​

PP_OPTIONS 是用于开启或关闭单个组件的 JSON。默认值为 {}，未指定的键全部视为 true(激活)。

例) 若使用外部托管 Redis 并关闭内置 Valkey：

export PP_OPTIONS='{"enable-valkey":false}'

可用的 enable-* 键 (全部默认为 true):

enable-messaging · enable-valkey · enable-postgres · enable-cassandra · enable-spark · enable-rustfs · enable-tse · enable-cep · enable-workflow · enable-data-gateway · enable-sql · enable-hive · enable-gravitino · enable-kyuubi · enable-grafana · enable-monitor

4. 数据存储​

变量默认值说明
PP_REDIS_HOST / PP_REDIS_PORTplantpulse-datalake / 6379Valkey/Redis (TLS 监听 6380)
PP_REDIS_USER / 🔑 PP_REDIS_PASSWORDredis / —Redis 账号
PP_POSTGRES_HOST / PP_POSTGRES_PORTplantpulse-datalake / 5432PostgreSQL 18 (Percona)
PP_PG_USER / 🔑 PP_PG_PASSWORDplantpulse / —PostgreSQL 账号
PP_CASSANDRA_HOST / PP_CASSANDRA_PORTplantpulse-datalake / 9042Aster TSDB
PP_CASSANDRA_USER / 🔑 PP_CASSANDRA_PASSWORDcassandra / —Aster TSDB 账号
PP_CASSANDRA_PORT9042存储层客户端复用的 Aster TSDB 端口。不存在名为 PP_STORAGE_PORT 的变量
PP_S3_HOST / PP_S3_PORTplantpulse-datalake / 9000RustFS 对象存储
PP_S3_USER / 🔑 PP_S3_PASSWORDrustfs / —RustFS 账号
PP_S3_BUCKETplantpulse默认 Bucket — Iceberg 数据 · 备份
PP_S3_UPLOAD_BUCKETupload上传物 Bucket。仅加载至 plantpulse-server-web(刻意不传至 Worker)。区分 Bucket 是为了防止一方的保留规则影响另一方
PP_DB_NAMEppPostgreSQL 数据库名
PP_KEYSPACEppAster TSDB Keyspace 名
PP_HIVE_DBhive-metastore-230Hive Metastore DB

5. 消息传递​

变量默认值说明
PP_MQ_USER / 🔑 PP_MQ_PASSWORDmq / —Kafka·MQTT 共用账号 (无 Kafka 专用账号)
PP_TOPIC_PREFIXppKafka Topic 前缀 (pp-tag-point 等)
PP_KAFKA_HOST / PP_KAFKA_PORTPP_MASTER_IP / 9092Kafka Broker
PP_KAFKA_TLS_PORT9094Kafka 外部 TLS
PP_KAFKA_CONTROLLER_PORT9093Kafka KRaft Controller
PP_MQTT_HOST / PP_MQTT_PORTPP_MASTER_IP / 1883MQTT (HiveMQ)
PP_MQTT_TLS_PORT1884MQTT TLS
STOMP(ActiveMQ) 已停用

随着浏览器实时推送改为 SSE，STOMP Broker 已从数据湖镜像中移除。PP_STOMP_* 变量及 61000/61004 端口不再提供服务。若仍保留在旧防火墙规则中，请予以清理。

6. 处理 · 时序 · 分析 · 工作流​

变量默认值说明
PP_CEP_HOST / PP_CEP_PORT / PP_CEP_TLS_PORTplantpulse-datalake / 7400 / 7401CEP 服务器
PP_CEP_PROTOCOLhttpCEP 访问协议。分布式/容器建议使用 https
PP_CEP_CONNECT_PORT(派生)server-web → CEP 访问端口。根据协议自动对齐 (http → 7400, https → 7401)。若显式指定则优先
PP_DATA_GATEWAY_HOST / PP_DATA_GATEWAY_PORT / PP_DATA_GATEWAY_TLS_PORTplantpulse-datalake / 5500 / 5501Data Gateway
PP_DATA_GATEWAY_PROTOCOLhttpDGW 访问协议 (内部 loopback 默认为 http)
PP_DATA_GATEWAY_CONNECT_PORT(派生)DGW 访问端口。根据协议自动对齐 (http → 5500, https → 5501)。若显式指定则优先
PP_TSE_HOST / PP_TSE_PORT / PP_TSE_TLS_PORTplantpulse-datalake / 7800 / 7801时序引擎(TSE)。服务器同时监听 http 7800 和 https 7801
PP_TSE_PROTOCOLhttpTSE 客户端访问协议。由于是内部段通信，默认为明文 http — 与 TLS 主开关(PP_TLS_ENABLED)分离(2026-08)
PP_TSE_CONNECT_PORT(未设置)env.sh 不 export 的运算符显式覆盖钩子。模板将以 ${PP_TSE_CONNECT_PORT:7800} 为后备(fallback)消费
PP_TSE_JDBC_SCHEME—不存在该变量。jdbc.tse.url 模板硬编码了 ts，无法更改方案
PP_TSE_USER / 🔑 PP_TSE_PASSWORDtse / —TSE 账号
PP_ANALYTICS_USER / 🔑 PP_ANALYTICS_PASSWORDspark / —分析(Spark/Kyuubi 客户端)账号。与 Kyuubi 内部 Metastore(PP_HIVE_*)分离的独立凭据
PP_HIVE_HOST / PP_HIVE_PORTPP_MASTER_IP / 9083Hive Metastore
PP_HIVE_USER / 🔑 PP_HIVE_PASSWORDhive / —Hive 账号
PP_SPARK_HOST / PP_SPARK_PORTPP_MASTER_IP / 7077Spark Master
PP_KYUUBI_PORT10000Kyuubi SQL 网关
PP_GRAVITINO_USER / 🔑 PP_GRAVITINO_PASSWORDgravitino / —Gravitino Catalog
PP_TEMPORAL_HOST / PP_TEMPORAL_PORTplantpulse-datalake / 7233Temporal 引擎 (Web UI 8233)
PP_TEMPORAL_USER / 🔑 PP_TEMPORAL_PASSWORDtemporal / —Temporal 账号
PP_KESTRA_HOST / PP_KESTRA_PORTplantpulse-datalake / 8380Kestra 调度器
PP_KESTRA_ADMIN_EMAIL / 🔑 PP_KESTRA_ADMIN_PASSWORDadmin@plantpulse.io / —Kestra 管理员
PP_KESTRA_DB_USER / 🔑 PP_KESTRA_DB_PASSWORDkestra / —Kestra 元数据库

7. 插件 · 观测 · Web 层​

变量默认值说明
PP_OPCUA_TCP_PORT11004OPC-UA opc.tcp 协议端口
PP_OPCUA_TLS_PORT11005OPC-UA TLS
PP_AAS_SERVER_PORT8090AAS(BaSyx V3) API。UI 为 8091, Registry/AAS 端口(4800/4801)在代码中固定，无法通过 env 更改
PP_GRAFANA_DB_USER / 🔑 PP_GRAFANA_DB_PASSWORDgrafana / —PlantPulse Dashboard 存储(PostgreSQL)访问。若为空则 pd start exit 3。不存在指定管理员账号的变量
部分端口不存在对应的更改变量

以下内容无法通过 env 更改 — 即使填写值也不会产生任何影响。

项目端口原因
PlantPulse Dashboard3000在 compose 的 ports: 中以数字形式固定(不存在 PP_GRAFANA_PORT)
WebSocket 推送—PP_WEBSOCKET_PORT · PP_WEBSOCKET_PORT_SSL · PP_WEBSOCKET_USER · PP_WEBSOCKET_SERVER_PASSWORD 在任何存储库中均不存在
AAS Registry/AAS4800 · 4801代码固定

PP_OPCUA_PORT 同样不存在 — OPC-UA 仅有 PP_OPCUA_TCP_PORT 一个端口。

邮件服务器与控制台 · 现场应用地址并非环境变量。PP_MAIL_SMTP_* 即使填写也不会被读取，值应填入 pp.mm_config — 邮件设置 · 地址设置。

8. TLS / SSL​

变量默认值说明
PP_TLS_ENABLEDtrueTLS 主开关 — 决定服务客户端的默认协议
PP_TLS_CERT_DIR/var/security/plantpulse证书目录
PP_TLS_DOMAINplantpulse.io证书域名
🔑 PP_TLS_KEYSTORE_PASSWORD / 🔑 PP_TLS_TRUSTSTORE_PASSWORD—keystore/truststore 密码 (所有节点必须相同)
PP_TLS_VALID_DAYS3650证书有效期(日)
PP_TLS_SAN_IPSPP_HOST_IP,…,127.0.0.1证书 SAN IP。运行环境下必须包含外部访问 IP(如：公网 IP)
PP_TLS_SAN_DNSlocalhost,<hostname>,<domain>证书 SAN DNS
PP_TLS_NODE_NAMESmaster worker-1 … worker-5集群节点名称
PP_TLS_FORCE_REGENERATEfalsetrue 时强制重新生成证书

9. API 密钥 / AI 网关​

所有项均有开发用默认值(fallback)。在运行/客户交付时，必须通过 Docker -e 或 export 进行更换。

变量说明
🔑 PP_API_KEY平台内部 API 密钥 (服务器 ↔ 边缘代理认证)
🔑 PP_DATA_GATEWAY_API_KEYserver-web → data-gateway JDBC 认证
🔑 PP_CEP_API_KEYserver-web → CEP 服务器 X-API-Key (需与 CEP 服务器 cep.api.key 一致)
🔑 PP_FLOW_WEBHOOK_API_KEYFlow Engine 外部 Webhook 认证
🔴 AI 不再通过环境变量进行设置

PP_AI_OPENAI_ENABLED · PP_AI_OPENAI_BASE_URL · PP_AI_OPENAI_API_KEY · PP_AI_OPENAI_MODEL 在 2026-09-18 起不再起作用。即使填写也不会报错或警告，而是被静默忽略， 且服务器看起来像已配置一样。

AI 设置的正本位于 PostgreSQL pp.mm_config 表中，键名称也从 ai.openai.* 变更为 ai.llm.*。填写值的途径为控制台的设置界面(/env)或该表 — 属性参考 — AI 设置。

10. 更改后应用流程​

vi /etc/kopens/plantpulse-platform.env       # 사이드카 — 여기를 고칩니다
cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh                                  # 준비될 때까지 대기 (종료 코드 0 = 쓸 수 있다)
请勿修改安装树内部文件

填写在 bin/env.sh 中的值在重新安装或升级时会消失。因为安装脚本会删除整个安装树并重新接收。Sidecar 位于该树之外，因此得以保留。

若需要更改容器看到的值，请修改 compose/docker-compose.yml 后以相同方式重启。设置模板通过绑定挂载(Bind Mount)至主机的 /etc/kopens/conf，可直接在主机编辑，且在重新安装后依然保留。

若更改变量后未生效，请按以下顺序确认。

确认项内容
① Sidecar 是否胜出若 /etc/kopens/plantpulse-platform.env 中存在同名变量，则 env.sh 和 Shell export 均失效 → 优先级
② 名称是否可触达应用六个应用不读取 env.sh。若不在 compose 中，则无法触达应用
③ 是否已重启包括区域(Locale)·时区在内，大部分值仅在启动时点生效
④ 是否为密码密码无法通过编辑文件更改 → 密码轮转

详细步骤请参考 启动指南。