环境变量设置

默认密码在交付客户时必须更改

本文件中出现的密码（如 CERT_PASS 等）为 公司内部 dev 盒子的默认值，并非机密。在客户现场或量产交付时不得直接使用：

若未指定 CERT_PASS，install.sh 将 随机生成 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 将在其上运行。这些值一旦按盒子单位设定，几乎不会更改。

值决定顺序

env.sh 是安装 · 升级 · 启动脚本 全部 source 的单一来源。若同一变量出现在多个位置，先定义的生效 — 因为 Shell 的 ${VAR:-기본값} 仅在变量 «不存在时» 才会触发。

顺序	位置	内容
1	`/etc/kopens/env.sh.generated`	`install.sh` 首次创建的 Sidecar。`API_KEY` · `ADMIN_PASS` · `MQTT_PASS` · `OPCUA_PASS` · `CERT_PASS`。`0600` root
2	`env.sh` 中的 `${VAR:-기본값}`	文件声明的默认值
3	`env.sh` 后方的运行人员 `export` 行	最后编写的生效

Sidecar 位于默认值与运行人员之间

安装时创建的机密即使 重新运行 install.sh 也会保留（因为 1 优先定义）。若运行人员仍想强制指定某个值，可在 env.sh 后方添加一行 export。

删除 Sidecar 后重新安装将生成新凭据

在删除 /etc/kopens/env.sh.generated 的状态下重新运行 install.sh，密码和 API 密钥将 重新生成。这将导致与注册在上位 Platform 的 API 密钥不一致，从而停止采集 — 在删除前请确认 /etc/kopens/credentials.txt。

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 共用)	安装时随机生成
`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 仅在启动时运行 1 次 — 运行时无法更改

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

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

在 native 模式下，server/bin/setenv.sh 的 LOCALE 必须是动态的 — 曾出现旧版 hardcode -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 中。若文件存在，则 override 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` (= 主机 `/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 是指向该文件的符号链接 (ln -sfn /etc/kopens/conf/app.properties /etc/kopens/app.properties)。
log4j2.xml 是 代码产物 — entrypoint 每次启动时从 webapp 默认配置复制（仅更改日志级别并 restart 即可生效，无需重新构建镜像）。

关于配置键本身（填写内容），请参阅 app.properties 参考和 Web UI 环境配置。本页讨论的是 如何/从何处读取 这些文件。

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` 预设	—
`EDGE_ID`	盒子唯一 ID (`^EDGE_[A-Z0-9_]{1,60}$`)	基于 MAC 自动生成
`SITE_ID`	站点 ID (必须注册至 Platform)	`SITE_00001`
`DEV_MODE`	`EDGE` (连接 Platform) / `STANDALONE` (不连接)	`EDGE`
`SERVER_HOST` / `SERVER_API_KEY`	Platform API 联动 (EDGE 模式必填)	—
`PP_LANG` / `PP_TZ`	语言 / 时区	`en` / `Asia/Seoul`
`ADMIN_PASS` / `API_KEY` / `MQTT_PASS` / `OPCUA_PASS`	初始凭据 override	每个盒子随机生成
`CERT_PASS`	TLS keystore 密码	安装时随机生成
`CERT_DOMAIN` / `CERT_SAN_DNS` / `CERT_SAN_IP`	证书 CN / SAN	`plantpulse.io` / 自动
`NET1_IFACE` / `NET2_IFACE` …, `NET2_IP` / `NET2_GATEWAY` / `NET2_DNS`	NIC 映射 / 静态 IP	自动检测 / DHCP
`IMAGE_TAG`	固定 Docker 镜像 tag	`latest`
`SKIP_PULL=1`	跳过 Docker pull (隔离网络/重新运行)	`0`
`SKIP_COSIGN_VERIFY=1`	安装时跳过镜像签名验证。不应用于 OTA 升级	`0` (staging/standalone `1`)

dev.mode 同时支持 EDGE 和 STANDALONE，但会 reject PLATFORM。在 STANDALONE 时，将跳过 SERVER_HOST / SERVER_API_KEY 提示 (server.host 为空 → DiagnosticSender 跳过初始化)。

7. JVM Heap env (容器)

env	组件	默认	override 示例
`HIVEMQ_HEAP`	HiveMQ	`-Xms2g -Xmx2g`	`1g`
`CASSANDRA_HEAP`	Cassandra	基于主机 /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-app.sh` (仅应用，30~90秒)

env 层 ≠ app.properties

即使将 PP_LANG 写入 app.properties 也不会生效 — 语言由 env 层 (env.sh / i18n.env) 决定。相反，像 cassandra.host 这样的运行时键不应写在 env 中，而应写在 app.properties 中。

9. 常见陷阱

症状	原因 / 解决
UI 语言未更改	写入了 `app.properties` 或未重启。修改 `i18n.env` (容器) / `env.sh` (native) 后重启
native 模式下 ko 语言持续生效	`setenv.sh` LOCALE 为 hardcode。改为 `${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` 或 root 0600 env 文件 source 代替 argv
设置更改未生效	未修改 `-Dpe.conf.dir` 所指向的标准文件 (容器=`/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. 相关文档​