env 环境配置 — env.sh / PPLANG / CERTPASS / -Dpe.conf.dir

默认密码在客户现场部署时必须修改

本文档中出现的密码(CERT_PASS 等)是公司内部 dev 机器的默认值,并非机密。在客户现场/量产部署中不得直接沿用:

install.sh 在未指定 CERT_PASS 时会生成 14 位随机值(bin/install.sh:298)。生成的值会记录到 /etc/kopens/credentials.txt(0600, root) 和 factory 标签中。
机器 OS 登录密码也在安装时修改。
因此文档中默认值的有效范围仅限公司内部的一台 dev 机器。

PlantPulse Edge 的配置分为两个层次。

层次	内容	位置
环境变量 (env) ← 本页	语言/时区、JDK 路径、TLS 密码、数据路径、安装时的站点值	`env.sh` / `/etc/kopens/*.env` / systemd / `docker -e`
应用配置 (properties)	`edge.id` / `cassandra.` / `mqtt.` / OPC-UA 等运行时键	`app.properties` → app.properties 指南

env 层确定语言 · 时区 · JVM 选项 · 密码 · 配置目录位置之后,app.properties 才在其之上运行。这些值以机器为单位设定一次后基本不再变动。

1. 核心 env 变量一览

变量	含义	默认值
`PP_LANG`	UI/OS/JVM 语言 (BCP 47) — 每台机器单一语言	`en`
`PP_TZ`	时区 (`java.util.TimeZone` ID)	`Asia/Seoul`
`JAVA_HOME`	JDK 路径 (class file 65 → JDK 21)	`/usr/lib/jvm/java-21-openjdk`
`PE_HOME`	网关根目录	`/opt/kopens/plantpulse-edge`
`PE_DATA_DIR`	数据目录 (Cassandra/Redis/HiveMQ/Node-RED)	`/data1`
`CERT_PASS`	TLS keystore 密码 (Tomcat/HiveMQ/OPC-UA 通用)	`kopens123!` (legacy) / 安装时随机生成
`CLEAN_ON_STARTUP`	启动时是否清理 work/temp	`false`
`JAVA_TOOL_OPTIONS`	所有 JVM 通用选项 (entrypoint/`setenv.sh` 注入语言/时区)	(自动配置)

请勿将机密值留在 argv/日志/历史记录中

CERT_PASS / SERVER_API_KEY / 各类 password 不得暴露在 shell history、ps argv 或日志中。请使用 *_FILE 注入(例如 EDGE_ADMIN_PASSWORD_HASH_FILE、CASSANDRA_PASSWORD_FILE),或将 root 0600 文件 source 后再执行安装。install.sh 生成的随机凭据会一次性保存到 /etc/kopens/credentials.txt (chmod 0600 root)。

2. 语言 / 时区 — `PP_LANG` / `PP_TZ`

PlantPulse 强制每台机器单一语言/时区。用户级 cookie / Accept-Language 会被忽略, webapp + 宿主 OS + 容器 OS + JVM 全部使用相同值。

PP_LANG=en  PP_TZ=Asia/Seoul   # 글로벌 default (영문 UI + 한국 시간)
PP_LANG=ko  PP_TZ=Asia/Seoul   # 완전 한국 박스
PP_LANG=en  PP_TZ=UTC          # 완전 영문 박스

2.1 传播链 (4 layer)

env.sh / i18n.env  ─→  install.sh  ─→  systemd EnvironmentFile + docker -e  ─→  container-entrypoint.sh  ─→  webapp PpFixedLocaleResolver
   (값 정의)            (host locale)     (PP_LANG / PP_TZ 주입)                 (OS LANG/TZ + JAVA_TOOL_OPTIONS)   (UI 언어 결정)

2.2 容器中 entrypoint 的处理

container-entrypoint.sh 将 PP_LANG 映射为 POSIX locale 并构建 JVM 选项:

PP_LANG="${PP_LANG:-en}"; PP_TZ="${PP_TZ:-Asia/Seoul}"

case "$PP_LANG" in
    ko|ko_*|ko-*) LANG=ko_KR.UTF-8 ; lang=ko country=KR ;;
    en|en_*|en-*) LANG=en_US.UTF-8 ; lang=en country=US ;;
esac
export LANG TZ="$PP_TZ"
ln -sf "/usr/share/zoneinfo/$PP_TZ" /etc/localtime

# 모든 JVM 프로세스 통일
export JAVA_TOOL_OPTIONS="$JAVA_TOOL_OPTIONS -Duser.language=$lang -Duser.country=$country -Duser.timezone=$PP_TZ"

同时写入 /etc/locale.conf、/etc/environment、/etc/timezone,因此重新登录/调用工具时依然保持。

PpFixedLocaleResolver 仅在启动时解析一次 — 运行中不可更改

语言在启动时确定一次,无法通过 cookie / Accept-Language 更改。 ko↔en 切换需要修改 PP_LANG + 重启容器/Tomcat。

2.3 native 模式的 LOCALE (`setenv.sh`)

在 native 模式下,server/bin/setenv.sh 中的 LOCALE 必须是动态的 —— 曾出现旧的硬编码 -Duser.language=ko -Duser.country=KR 优先于 JAVA_TOOL_OPTIONS,导致 ko 胜出的情况。

# server/bin/setenv.sh
LOCALE="-Duser.language=${PP_LANG:-en} -Duser.country=${PP_COUNTRY:-US} -Duser.timezone=${PP_TZ:-Asia/Seoul}"

并在 conf/env.sh 中加入 export PP_LANG / export PP_TZ / export JAVA_HOME=/usr/lib/jvm/java-21-openjdk。

3. native `conf/env.sh`

native 机器的环境文件。bin/start.sh 在启动前 source 它。

# $PE_HOME/conf/env.sh
export PE_HOME=/opt/kopens/plantpulse-edge
export PE_DATA_DIR=/data1
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk      # JDK 21 — class file 65 호환 (필수)
export PP_LANG="${PP_LANG:-en}"
export PP_TZ="${PP_TZ:-Asia/Seoul}"
export CLEAN_ON_STARTUP=false

键	含义
`PE_HOME`	网关根目录 (脚本的基准路径)
`PE_DATA_DIR`	数据分离目录 (通常为独立分区 `/data1`)
`JAVA_HOME`	未指定 JDK 21 时使用 `UnsupportedClassVersionError`
`PP_LANG` / `PP_TZ`	语言 / 时区 (见第 2 章)
`CLEAN_ON_STARTUP`	启动时清理 work/temp

native 安装的完整结构参见原生安装。

4. 容器 `/etc/kopens/*.env` (systemd EnvironmentFile)

在容器机器上,systemd unit 以 EnvironmentFile 方式读取以下文件并注入为 docker -e。若文件存在,则覆盖 unit 内置默认值。

文件	键	生成者	用途
`/etc/kopens/version.env`	`PE_VERSION=<tag>`	OTA `upgrade.sh`	固定镜像 tag — OTA/rollback 只修改这一行
`/etc/kopens/i18n.env`	`PP_LANG` / `PP_TZ`	`install.sh`	语言 / 时区
`/etc/kopens/cert.env`	`CERT_PASS`	TLS 签发脚本	keystore 密码

# plantpulse-edge.service (발췌)
EnvironmentFile=-/etc/kopens/version.env
EnvironmentFile=-/etc/kopens/i18n.env
EnvironmentFile=-/etc/kopens/cert.env
Environment=PE_VERSION=latest
Environment=KOPENS_IMAGE=docker.kopens.io/pe/plantpulse-edge
Environment=PP_LANG=en
Environment=PP_TZ=Asia/Seoul
Environment=CERT_PASS=kopens123!

更改语言:

sudo tee /etc/kopens/i18n.env <<'EOF'
PP_LANG=ko
PP_TZ=Asia/Seoul
EOF
sudo systemctl restart plantpulse-edge.service

systemd unit 的完整解析参见 Docker 安装 §4。

5. 配置目录位置 — `-Dpe.conf.dir`

这是决定从哪里读取 app.properties 和 log4j2.xml 的核心 env/系统属性。在 WAR 模式(2026-06-13 起),配置直接从宿主 /etc/kopens 读取 —— 无需重建镜像/批处理。

模式	`-Dpe.conf.dir`	canonical 文件
容器	`/opt/kopens/plantpulse-edge/conf` (= host `/etc/kopens/conf` bind-mount)	`/etc/kopens/app.properties`
native	`$PE_HOME/conf`	`$PE_HOME/conf/app.properties`

容器:宿主的 /etc/kopens/conf/app.properties 是实体文件,也是 source-of-truth。 /etc/kopens/app.properties 只是指向它的 legacy 兼容符号链接 (ln -sfn /etc/kopens/conf/app.properties /etc/kopens/app.properties)。
log4j2.xml 是代码产物 —— entrypoint 每次启动都会从 webapp default 复制(仅修改日志级别后 restart 即可生效,无需重建镜像)。

配置键本身(写什么)参见 app.properties 指南与环境配置界面。本页讨论的是从哪里、如何读取这些文件。

6. install.sh 安装时的 env override

安装时通过 env 注入机器的站点值/网络/凭据(install.sh 会反映到 app.properties)。

sudo PROFILE=production \
     EDGE_ID=EDGE_00303 \
     SITE_ID=SITE_00001 \
     SERVER_HOST=192.168.0.41 \
     SERVER_API_KEY='<platform-api-key>' \
     PP_LANG=en PP_TZ=Asia/Seoul \
     CERT_PASS='<keystore-pass>' \
     bash install.sh

变量	含义	默认值
`PROFILE`	`production` / `staging` / `standalone` / `airgap` preset	—
`EDGE_ID`	机器唯一 ID (`^EDGE_[A-Z0-9_]{1,60}$`)	基于 MAC 自动生成
`SITE_ID`	站点 ID (平台注册必填)	`SITE_00001`
`DEV_MODE`	`EDGE` (连接平台) / `STANDALONE` (未连接)	`EDGE`
`SERVER_HOST` / `SERVER_API_KEY`	平台 API 对接 (EDGE 模式必填)	—
`PP_LANG` / `PP_TZ`	语言 / 时区	`en` / `Asia/Seoul`
`ADMIN_PASS` / `API_KEY` / `MQTT_PASS` / `OPCUA_PASS`	初始凭据 override	每台机器随机
`CERT_PASS`	TLS keystore 密码	`kopens123!`(legacy) / random
`CERT_DOMAIN` / `CERT_SAN_DNS` / `CERT_SAN_IP`	证书 CN / SAN	`plantpulse.io` / 自动
`NET1_IFACE` / `NET2_IFACE` …, `NET2_IP` / `NET2_GATEWAY` / `NET2_DNS`	NIC 映射 / static IP	自动检测 / DHCP
`IMAGE_TAG`	固定 docker 镜像 tag	`latest`
`SKIP_PULL=1`	跳过 docker pull (airgap/重复执行)	`0`
`SKIP_COSIGN_VERIFY=1`	跳过镜像签名验证	`0` (staging/standalone `1`)

dev.mode 同时支持 EDGE 与 STANDALONE,仅 PLATFORM 会被 reject。指定 STANDALONE 时 SERVER_HOST / SERVER_API_KEY 提示会被跳过(server.host blank → DiagnosticSender init skip)。

7. JVM heap env (容器)

env	组件	默认	override 示例
`HIVEMQ_HEAP`	HiveMQ	`-Xms2g -Xmx2g`	`1g`
`CASSANDRA_HEAP`	Cassandra	基于 host /proc/meminfo 自动计算 (~1/4)	`1g`
`TOMCAT_HEAP`	Tomcat	`-Xms2g -Xmx2g`	`1g`

8GB 机器的 drop-in override(override.conf)见容器模式 §资源限额。

8. 修改后的生效方式

修改项	生效方法
`PP_LANG` / `PP_TZ` (i18n.env / env.sh)	重启容器/Tomcat (locale 仅在启动时解析一次)
`CERT_PASS` (cert.env)	重启容器 (entrypoint 重新打补丁写入 keystore 密码)
`PE_VERSION` (version.env)	`systemctl restart plantpulse-edge.service`
`app.properties` (容器)	`config.sh --set … && config.sh --restart`
`app.properties` (native)	`vi conf/app.properties` → `bin/restart.sh` (约 6 秒)

env 层 ≠ app.properties

将 PP_LANG 写入 app.properties 并不会生效 —— 语言由 env 层(env.sh / i18n.env)决定。反之,像 cassandra.host 这样的运行时键应写入 app.properties 而非 env。

9. 常见陷阱

现象	原因 / 解决
UI 语言不变	写到了 `app.properties` 中,或未重启。修改 `i18n.env`(容器)/`env.sh`(native) 后重启
native 下 ko 始终胜出	`setenv.sh` 的 LOCALE 为硬编码。将 `${PP_LANG}` 改为动态 (见 2.3)
`UnsupportedClassVersionError`	`JAVA_HOME` 不是 JDK 21
OPC-UA keystore password 错误	`cert.env` 的 `CERT_PASS` 与 `opc.ua.server.keystore.password=${ENV:CERT_PASS:}` 镜像值不一致
密码暴露在 `ps`/日志中	使用 `*_FILE` 或 source root 0600 env 文件,而非 argv
配置修改不生效	未修改 `-Dpe.conf.dir` 指向的 canonical 文件 (容器=`/etc/kopens`,native=`$PE_HOME/conf`)

10. 后续文档

app.properties 指南 — 全部运行时配置键
环境配置界面 (/ui/system/config) — 在 Web 上编辑 app.properties
原生安装 / Docker(容器)安装详解
快速安装 (install.sh) — 安装时的 env 注入流程
容器模式运维指南 — config.sh / 资源限额 / OTA

1. 核心 env 变量一览​

2. 语言 / 时区 — PP_LANG / PP_TZ​

2.1 传播链 (4 layer)​

2.2 容器中 entrypoint 的处理​

2.3 native 模式的 LOCALE (setenv.sh)​

3. native conf/env.sh​

4. 容器 /etc/kopens/*.env (systemd EnvironmentFile)​

5. 配置目录位置 — -Dpe.conf.dir​

6. install.sh 安装时的 env override​

7. JVM heap env (容器)​

8. 修改后的生效方式​

9. 常见陷阱​

10. 后续文档​