跳到主要内容

环境变量参考

PlantPulse 的所有配置都从环境变量这一处出发。本页是安装、运维时会遇到的变量按类别整理的参考。

本页涉及的是基础设施/部署环境变量（PP_* · DOCKER_PP_*）。应用行为相关的属性（engine.*、websocket.* 等）请参考属性参考。

1. 配置文件在哪里？​

平台以 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 · plantpulse-plugin-opcua-server · plantpulse-plugin-aasx-server · plantpulse-ha）不会 source env.sh。应用能看到的定义处只有 compose 这一个。

也就是说，只存在于 env.sh 而不在 compose 中的名称不会传达给应用，应用会以 jar/WAR 内置的默认值运行。实际上就发生过在数据湖（datalake）单独更改标识符的站点，导致五个应用继续沿用旧名称的事故（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（密钥 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/ 之下​

数据库·消息中间件密码及 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 · Cassandra 这类以服务器端账户为权威来源的值，服务器端也需要一并修改，顺序出错平台将无法启动。

请使用专用流程 —— 修改密码（凭证轮换）。这是在调试阶段做一次即可完成的工作。

🔑 标记表示秘密值。请勿将原文放入 git·issue·聊天中。

1.5 容器运行时·主机资源（DOCKER_*）​

这是由 bin/env.sh 确定的值。下面的资源值不是固定的默认值，而是根据主机计算得出的——因为若使用常量，可能导致小型主机根本无法启动（若 --cpus 大于实际核心数，docker 会拒绝），或在启动过程中被 OOM-kill。按主机单独指定的值始终优先。

变量如何决定
DOCKER_CMDdocker（也可用 podman）
DOCKER_REGISTRYdocker.kopens.io/pp —— 技术栈八个镜像的仓库前缀
PP_IMAGE_TAGlatest。发布版本建议使用如 2026.08 这样的固定标签
DOCKER_PP_CPUSnproc（读取失败时为 8）
DOCKER_PP_CLUSTER_CORESDOCKER_PP_CPUS - 2，最小 4 · 最大 30。以 PP_CLUSTER_CORES 形式传给容器
DOCKER_PP_MEMORY主机 RAM 的 90%，最小 8G
DOCKER_DATALAKE_MEMORY80G。若主机小于该值则为 RAM 的 90%（2026-09-04 从 64G 上调——归档器的 spark-submit 开始在该容器内运行后，在 64g 上限下发生了 OOM，实测峰值 63.9G）
DOCKER_PW_MEMORY与 DOCKER_DATALAKE_MEMORY 相同的值——由于 worker 使用与数据湖相同的镜像，因此分配相同的预算
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_HEAP16g / 12gplantpulse-server-web
DOCKER_BATCH_MEMORY / DOCKER_BATCH_HEAP4g / 3gplantpulse-batch-web
DOCKER_WAREHOUSE_MEMORY8gplantpulse-warehouse
DOCKER_OPCUA_MEMORY4gplantpulse-plugin-opcua-server
DOCKER_AASX_MEMORY4gplantpulse-plugin-aasx-server
DOCKER_HA_MEMORY2gplantpulse-ha
DOCKER_DATALAKE_MEMORY80gplantpulse-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_VOLUMEpp-proxy-certs代理证书

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默认 80G。主机较小时会自动降低
下方第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 就期待生效——若不传入，16 vCPU 的主机会误以为存在其实并不存在的 30 个核心，导致 Kyuubi 永远无法启动。

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

变量默认值说明
PP_HOME/opt/kopens/plantpulse-platform安装根目录（容器内部相同）
PP_SCHEMEPP部署标识方案
PP_MODEMASTER节点角色（MASTER / worker）—— 集群化（水平扩展）轴
PP_TIERFULL该节点要启动的层级门控（FULL / DATALAKE / APP）——与 PP_MODE 正交。FULL=基础设施+应用一体化，DATALAKE=仅基础设施，APP=仅应用（接入远程数据湖）。详情参见双节点分离安装
PP_OPTIONS{}专用于逐个服务开关的 JSON。层级门控已迁移至 PP_TIER（参见下方 §3.3）
PP_HOST_IP127.0.0.1该节点的 IP
PP_SERVICE_IP127.0.0.1服务绑定 IP
PP_MASTER_IP127.0.0.1worker/APP 层所指向的主（数据湖）IP。同时也是 Kafka advertised.listeners 的来源。安装 DATALAKE 层时若未指定，会自动检测为主机 IP
PP_DATALAKE_ANCHOR（派生）5 种数据存储 HOST 的默认 IP 锚点。APP 层=PP_MASTER_IP（远程数据湖），其他（FULL/DATALAKE）=PP_HOST_IP（自身 IP）。不直接设置，为派生值（参见下方 §3.2）
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_TIER —— 层级启动门控​

PP_TIER 是决定该节点启动哪一层的门控。它与集群化轴 PP_MODE（MASTER/WORKER）完全独立。

PP_TIER启动的层级
FULL（默认）基础设施 + 应用层（单机一体化——未指定时与既有安装相同）
DATALAKE仅基础设施层（Cassandra/PG/Kafka/MQTT/Redis/MinIO/Spark/Hive/TSE/CEP/Data Gateway/Temporal/Kestra/Monitor）
APP仅应用层（Server/Batch/Warehouse/OPC-UA/AASX/HA —— 接入远程数据湖）

关于将数据湖/应用拆分为两台主机的流程，请参考双节点分离安装。

3.2 PP_DATALAKE_ANCHOR —— 数据存储锚点（派生值）​

概念：PP_REDIS_HOST·PP_POSTGRES_HOST·PP_CASSANDRA_HOST·PP_MINIO_HOST·PP_TSE_HOST·PP_TEMPORAL_HOST·PP_KESTRA_HOST·PP_DATA_GATEWAY_HOST·PP_CEP_HOST 的默认主机均解析为 ${PP_DATALAKE_ANCHOR}。

  • 在 APP 层，由于存储位于远程（数据湖节点），因此为 PP_DATALAKE_ANCHOR = PP_MASTER_IP。
  • 在其他层（FULL/DATALAKE）中，因绑定到自身 IP，因此为 PP_DATALAKE_ANCHOR = PP_HOST_IP。

该值由 PP_TIER 自动派生，因此无需直接设置。APP 节点只需指定 PP_MASTER_IP，所有数据存储主机就会自动指向数据湖。

3.3 PP_OPTIONS —— 逐个服务开关​

PP_OPTIONS 是逐个组件开关的 JSON。默认值为 {}，未指定的键均视为 true（启用）。层级级别的启用（旧 use-infra / use-app）已迁移至 PP_TIER。

例如，若要使用外部托管的 Redis 而关闭内置的 Valkey：

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

可用的 enable-* 键（全部默认为 true）：

enable-messaging · enable-valkey · enable-postgres · enable-cassandra · enable-spark · enable-minio · 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_PORT${PP_DATALAKE_ANCHOR} / 6379Valkey/Redis（TLS 监听端口 6380）
PP_REDIS_USER / 🔑 PP_REDIS_PASSWORDredis / —Redis 账户
PP_POSTGRES_HOST / PP_POSTGRES_PORT${PP_DATALAKE_ANCHOR} / 5432PostgreSQL 18（Percona）
PP_PG_USER / 🔑 PP_PG_PASSWORDplantpulse / —PostgreSQL 账户
PP_CASSANDRA_HOST / PP_CASSANDRA_PORT${PP_DATALAKE_ANCHOR} / 9042Cassandra
PP_CASSANDRA_USER / 🔑 PP_CASSANDRA_PASSWORDcassandra / —Cassandra 账户
PP_STORAGE_PORT9042存储层客户端重用的 Cassandra 端口
PP_MINIO_HOST / PP_MINIO_PORT${PP_DATALAKE_ANCHOR} / 9000MinIO 对象存储
PP_MINIO_USER / 🔑 PP_MINIO_PASSWORDminio / —MinIO 账户
PP_MINIO_BUCKETplantpulse默认存储桶
PP_DB_NAMEppPostgreSQL 数据库名
PP_KEYSPACEppCassandra keyspace 名称
PP_HIVE_DBhive-metastore-230Hive 元存储 DB

5. 消息传递​

变量默认值说明
PP_MQ_USER / 🔑 PP_MQ_PASSWORDmq / —Kafka·MQTT 公用账户（无 Kafka 专用账户）
PP_TOPIC_PREFIXppKafka 主题前缀（pp-tag-point 等）
PP_KAFKA_HOST / PP_KAFKA_PORTPP_MASTER_IP / 9092Kafka broker
PP_KAFKA_TLS_PORT9094Kafka 外部 TLS
PP_KAFKA_CONTROLLER_PORT9093Kafka KRaft 控制器
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_PORT${PP_DATALAKE_ANCHOR} / 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_PORT${PP_DATALAKE_ANCHOR} / 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_PORT${PP_DATALAKE_ANCHOR} / 7800 / 7801时序引擎（TSE）。服务器同时监听 http 7800·https 7801
PP_TSE_PROTOCOLhttpTSE 客户端连接协议。因是内部区段通信，默认为明文 http —— 与 TLS 主开关（PP_TLS_ENABLED）分离（2026-08）
PP_TSE_CONNECT_PORT（未设置）env.sh 不导出的运维人员显式覆盖钩子。模板将其作为 ${PP_TSE_CONNECT_PORT:7800} 的回退值消费
PP_TSE_JDBC_SCHEMEtsJDBC scheme。默认明文 ts（jdbc.tse.url 模板中硬编码为 ts）
PP_TSE_USER / 🔑 PP_TSE_PASSWORDtse / —TSE 账户
PP_ANALYTICS_USER / 🔑 PP_ANALYTICS_PASSWORDspark / —分析（Spark/Kyuubi 客户端）账户。与 Kyuubi 内部元存储（PP_HIVE_*）分离的独立凭证
PP_HIVE_HOST / PP_HIVE_PORTPP_MASTER_IP / 9083Hive 元存储
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 目录
PP_TEMPORAL_HOST / PP_TEMPORAL_PORT${PP_DATALAKE_ANCHOR} / 7233Temporal 引擎（Web UI 8233）
PP_TEMPORAL_USER / 🔑 PP_TEMPORAL_PASSWORDtemporal / —Temporal 账户
PP_KESTRA_HOST / PP_KESTRA_PORT${PP_DATALAKE_ANCHOR} / 8380Kestra 调度器
PP_KESTRA_ADMIN_EMAIL / 🔑 PP_KESTRA_ADMIN_PASSWORDadmin@plantpulse.io / —Kestra 管理员
PP_KESTRA_DB_USER / 🔑 PP_KESTRA_DB_PASSWORDkestra / —Kestra 元数据 DB

7. 插件·可观测性·Web 层​

变量默认值说明
PP_OPCUA_PORT / PP_OPCUA_TCP_PORT11004OPC-UA opc.tcp 协议端口
PP_OPCUA_TLS_PORT11005OPC-UA TLS
PP_AAS_V3_PORT8090AAS（BaSyx V3）API。UI 为 8091，Registry/AAS 端口（4800/4801）在代码中固定，不能通过 env 修改
PP_GRAFANA_PORT3000Grafana 仪表盘
PP_GRAFANA_ADMIN_USER / 🔑 PP_GRAFANA_ADMIN_PASSWORDadmin / —Grafana 管理员
PP_WEBSOCKET_PORT / PP_WEBSOCKET_PORT_SSL8000 / 8004实时推送 WebSocket
PP_WEBSOCKET_USER / 🔑 PP_WEBSOCKET_SERVER_PASSWORDws / —WebSocket 服务器账户
PP_MAIL_SMTP_PORT25报警/报告邮件发送 SMTP
PP_MAIL_SMTP_USER / 🔑 PP_MAIL_SMTP_PASSWORDwebmaster@kopens.com / —SMTP 账户
PP_MAIL_SMTP_AUTH / PP_MAIL_SMTP_STARTTLSfalse / falseSMTP 认证·STARTTLS

8. TLS / SSL​

变量默认值说明
PP_TLS_ENABLEDtrueTLS 主开关 —— 决定服务客户端的默认协议
PP_DEFAULT_PROTOCOL（派生：PP_TLS_ENABLED）服务客户端默认协议。PP_TLS_ENABLED=true→https，false→http。TSE 等继承此值，使协议/端口不与主开关矛盾
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 密钥（服务器 ↔ Edge 代理认证）
🔑 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 认证
PP_AI_OPENAI_ENABLED启用 AI 网关（默认 false）
PP_AI_OPENAI_BASE_URL兼容 OpenAI 的 LLM 代理 URL（默认 https://api.openai.com）
🔑 PP_AI_OPENAI_API_KEYLLM API 密钥（在 PP_AI_OPENAI_ENABLED=true 时需要）
PP_AI_OPENAI_MODEL要使用的模型（默认 gpt-5-mini）

10. 修改后应用生效的流程​

cd /opt/kopens/plantpulse-platform-docker/bin
vi env.sh          # 호스트 쪽 값 (DOCKER_* · PP_LANG · PP_TZ 등)
./restart.sh       # 스택 재시작 — 준비될 때까지 대기 (종료 코드 0 = 쓸 수 있다)

若需要修改容器所看到的值，请在修改 compose/docker-compose.yml 后按同样的方法重启。配置模板绑定挂载在主机的 /etc/kopens/conf 上，因此可以直接在主机端编辑，即使重新安装也会被保留。

若修改了变量却未生效，请按顺序检查以下事项。

检查项内容
① sidecar 是否正在生效若 /etc/kopens/plantpulse-platform.env 中存在相同名称，env.sh 及 shell export 都会被其压制 → 优先级
② 该名称是否能传达给应用六个应用不会读取 env.sh。若不在 compose 中，则不会传达给应用
③ 是否重启过包括语言/时区在内的大多数值仅在启动时生效
④ 是否为密码密码不能通过编辑文件修改 → 密码轮换

详细流程请参考启动指南。

请勿在容器内运行 env-reset.sh

数据湖容器内的 env-reset.sh 是一个仅供开发使用的工具，它会 unset 所有 PP_* 后重新读取 env.sh。若在此处运行，连 compose 注入的值也会消失，恢复为镜像内置的默认值。