如何更改设置

根据您要更改的内容不同，需要修改的文件和生效方法也不同。 请首先在下面的表格中找到您的情况。

直接修改组件的配置文件会在下次启动时丢失

数据湖在每次启动时都会重新渲染配置。 它会读取 plantpulse-datalake-cli/config/templates/ 中的模板，填充 ${PP_*} 后， 覆盖写入到每个组件的配置位置（例如 plantpulse-storage/db/cassandra/conf/cassandra.yaml 这样的位置）。哪个模板去向哪里，在 config/render.map 这一页上有说明。

因此，即使打开并修改 cassandra.yaml · postgresql.conf · kafka.properties， 在下一次 pd start 时也会恢复原状。 需要修改的地方是模板。

# ❌ 이렇게 고치면 다음 기동에 사라진다
vi /opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/conf/cassandra.yaml

# ✅ 템플릿을 고친다 — 호스트의 /etc/kopens/conf 가 템플릿 자리로 마운트돼 있다
vi /etc/kopens/conf/cassandra.yaml.template
docker exec plantpulse-datalake pd config render     # 렌더해 보고
docker exec plantpulse-datalake pd config diff       # 「지금 도는 설정」과의 차이 (0 = 같다)
docker exec plantpulse-datalake pd restart storage   # 해당 서비스만 재시작

如果 pd config diff 不为 0，则表示运行时文件与模板不同——这意味着有人直接修改过，或者渲染尚未完成。

想要更改的内容	示例	修改位置	生效方式
密码 · API 密钥	PostgreSQL 密码，CEP API 密钥	`bin/passwd.sh`	工具会执行到重启为止
此主机箱的地址 · 身份	其他主机箱连接的地址，Kafka 通告地址，NAT 公网 IP	`/etc/kopens/platform.node.env`	`bin/restart-datalake.sh`
所有节点共有的非机密值	语言 · 时区，备份计划开关，控制台日志端点	`/etc/kopens/plantpulse-platform.env`	`bin/restart-datalake.sh`
容器资源	数据湖内存限制	`/etc/kopens/platform.node.env` (`DOCKER_DATALAKE_MEMORY`)	`bin/restart-datalake.sh`
引擎配置的«行»	`postgresql.conf` 参数，Kafka 保留期，Aster TSDB 堆内存	`/etc/kopens/conf/<파일>.template`	`bin/restart-datalake.sh` 或容器内 `pd config render` + `pd restart <서비스>`
备份计划	夜间备份时间	容器内 `pd backup schedule set`	立即生效
公开端口	在主机上开放的端口	`compose/docker-compose.yml`	`bin/restart-datalake.sh` — 注意

更改后的确认方法始终相同

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh                                       # 0 = 정상
docker exec plantpulse-datalake pd config diff    # 런타임 파일 = 렌더 결과인가 (0 = 같다)
docker exec plantpulse-datalake pd doctor         # FAIL 0

1. 密码 · API 密钥

不要打开文件。passwd.sh 会以一条命令完成服务器端账户变更 → 边车更新 → 配置重新渲染 → 重启。

cd /opt/kopens/plantpulse-platform-docker
bin/passwd.sh --list                 # 바꿀 수 있는 키
bin/passwd.sh PP_PG_PASSWORD         # 값은 프롬프트로 (권장)

详细信息请参阅更改密码 · API 密钥。

2. 本机箱的地址与身份 — 节点文件

/etc/kopens/platform.node.env 是记录仅对本机箱为真的值的文件。不能复制到其他机箱——实际上曾经发生过，复制了一个机箱文件到另一机箱，导致后者被静默地以错误角色重新安装。

变量	何时填写	留空时
`PP_MASTER_IP`	当其他机箱（边缘，AI，工作节点）需要连接到此数据湖时——本主机的 LAN 地址	compose 网络内的地址（`10.99.0.100`）— 仅在同一机箱内部通信
`PP_KAFKA_ADVERTISED_HOST`	仅在 NAT 之后或通过第二接口连接到 Kafka 时	启动时工具会推导（操作员值 > `PP_MASTER_IP` > 主机默认 IP）。通常留空
`DOCKER_PP_EXTERNAL_IP`	NAT 环境中的公网 IP。会写入 TLS 证书 SAN	留空——如果填了错误的 IP，将不会生成任何证书
`PP_NODE_ID`	当机箱超过一个时，本机箱的短且唯一的名称	从容器主机名派生——如果有两个机箱，会互相冲突。在连接第二个机箱之前确定

sudo vi /etc/kopens/platform.node.env
#   PP_MASTER_IP=192.168.10.20

cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh        # 데이터레이크만 재생성 + 준비 대기 + 의존 앱 판정

如果通告地址是 127.0.0.1，渲染将被拒绝（exit 8）

如果服务器告知客户端“请重新连接到这里”的地址（Kafka advertised.listeners，Aster TSDB broadcast_rpc_address，Temporal broadcastAddress）是回环地址，那么该服务器在自身位置看起来正常，但其他所有容器都会连接到自己。 端口检查全部显示 UP，但客户端一个也连不上。错误消息会告诉您需要修改的名称——即节点文件中的 PP_HOST_IP · PP_MASTER_IP · PP_KAFKA_ADVERTISED_HOST。

3. 所有节点共有的非机密值 — 边车

边车 /etc/kopens/plantpulse-platform.env 并非仅用于机密的文件。非机密的共有值也可以通过 VAR=값 的一行写入，bin/env.sh 会读取并传递给 compose。哪些变量可用，在 compose/platform.env.example 中连同注释完整列出——从中选择一行抄写即可。

常用项：

变量	默认值	含义
`PP_LANG`	`en`	如果是韩语运营，则为 `ko`
`PP_TZ`	`Asia/Seoul`	时序数据会以该时区的 epoch 存储，因此韩国运营时建议保持
`PP_BACKUP_SCHEDULE_ENABLED`	`true`	如果为 `false`，则五个备份定时器只会记录为“skipped”并结束
`PP_DATALAKE_ADMIN_LOGS_ENABLED`	`true`	如果为 `false`，则仅控制台的日志画面（端点）会不提供
`PP_KEYSPACE` · `PP_DB_NAME` · `PP_TOPIC_PREFIX`	`pp`	数据湖“生成”而应用“读取”的标识符。安装后请勿更改

sudo vi /etc/kopens/plantpulse-platform.env
#   PP_LANG=ko

cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh                 # 언어 · 타임존은 앱에도 닿으므로 전체 재시작

请勿改动边车的头部两行

# generated: 和 # last rotation: 由工具管理。其余行只要是 VAR=값 即可。旧的 export VAR=값 行也能被读取，但在下次更新时会重新写入新格式。

4. 容器内存

数据湖容器的内存限制是 DOCKER_DATALAKE_MEMORY。默认 96G，这也是 最低值 — 64G 不是受支持的规格。它会被截断为不超过主机 RAM 的 90%，因此主机小于 107G 时无法分配 96G，该主机低于规格（系统要求）。需要调高时，请记录在节点文件中。

sudo vi /etc/kopens/platform.node.env
#   DOCKER_DATALAKE_MEMORY=128g

cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh

设置过小会导致“看似 UP 实则已死”的状态

容器内 PID 1 是 systemd，因此只有 Java 进程会被 cgroup OOM-kill，而 docker ps 会继续显示 Up。杀死记录仅保留在主机的 dmesg 中。在 2026-09-04 于 64G 限制下实际发生过（实测峰值 63.9G），因此默认值已提高到 80G。2026-10-04 又提高到 96G。2026-10-29 容器触及 96G 上限，Kafka 因内存分配失败（ENOMEM）而停止 — 请勿降到 96G 以下。

dmesg -T | grep -i "memory cgroup"
docker inspect plantpulse-datalake --format '{{.State.OOMKilled}}'

5. 引擎配置的«行» — 模板

当需要像在 postgresql.conf 中添加参数或更改 Kafka 保留期那样，更改的不是值而是行时，请修改主机上的模板。哪个模板成为哪个文件，请参阅模板列表。

# 1. 호스트에서 템플릿 편집
sudo vi /etc/kopens/conf/postgresql.conf.template

# 2-a. 데이터레이크 전체 재시작 — 기동 때 자동 렌더
cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh

# 2-b. 또는 서비스 하나만 — 컨테이너 안에서
docker exec plantpulse-datalake pd config diff        # 무엇이 바뀔지 먼저 본다
docker exec plantpulse-datalake pd config render      # 생성물을 실제로 쓴다
docker exec plantpulse-datalake pd restart storage    # 그 서비스만 재기동

# 3. 확인
docker exec plantpulse-datalake pd config diff        # 0 = 런타임이 렌더 결과와 같다

只输入 pd config render 而不重启，并不算“已生效”。那只是文件变了。pd restart <서비스> 才算完整的一套。

当镜像携带新的默认值时 — 3-way 播种

/etc/kopens/conf 是主机文件，因此即使镜像携带新的默认值，它不会自动改变。 因此，启动工具会在每次部署时按文件比较三套：本次镜像的默认值，上一次部署的默认值（/etc/kopens/conf.dist），以及主机文件。

情况	工具的操作
操作员未修改的文件，默认值变更	替换为新默认值
操作员修改的文件，默认值也变更	保留操作员文件 + 输出 `[WARN] operator edit kept, but THE IMAGE DEFAULT CHANGED` 及默认值变更的 diff
操作员修改的文件，默认值不变	保留（静默）
镜像中出现新模板	安装
镜像移除模板	保留主机文件并警告

在 restart.sh · update.sh 的输出中看到 [WARN] operator edit kept 行时，您需要手动合并您的编辑和新默认值。同一行会告知新默认值文件的位置。

我的模板与镜像默认值差异在哪，可以在容器内查看。

docker exec plantpulse-datalake pd config diff --templates
#   same     — 같다
#   differs  — 호스트 사본이 다르다 (렌더는 이쪽을 쓴다)
#   local    — 운영자가 추가한 파일
#   missing  — 이미지엔 있는데 호스트엔 없다

若要将主机目录整体恢复为镜像默认值（工具会将备份保存在 /etc/kopens/conf.backup/<시각>/）：

cd /opt/kopens/plantpulse-platform-docker/bin
TEMPLATE_FORCE_SEED=1 ./restart-datalake.sh

6. 备份计划

不要修改文件。容器内的 pd backup schedule set 会向 datalake 数据库的 backup_schedule 表写入 Quartz cron——读取并执行该表的是 plantpulse-datalake-admin-api 内的调度器。管理控制台的备份界面“Schedule editor”会调用相同的命令。

docker exec plantpulse-datalake pd backup schedule                                   # 지금 일정
docker exec plantpulse-datalake pd backup schedule set --job postgres-diff --calendar "*-*-* 02:45:00"
docker exec plantpulse-datalake pd backup schedule set --job purge --enabled false
docker exec plantpulse-datalake pd backup schedule reset --job postgres-diff         # 기본값으로

任务名称有五个——postgres-diff · postgres-full · cassandra-diff · cassandra-full · purge。日历使用 systemd 语法（*-*-* 02:45:00 每天，Sun *-*-* 01:00:00 星期日）。错误的表达式不会被写入任何内容，而是直接拒绝。选择会保留在 /data1/pp-data/backup/schedule.json 中，即使重新创建容器也会保留 → 备份 · 恢复

7. 公开端口

在主机上开放的端口由 compose/docker-compose.yml 的 plantpulse-datalake 服务 ports: 决定。更改时请注意两点。

容器内监听的端口由 defaults.env（PP_*_PORT）和模板决定。如果只更改发布端口，会造成“容器绑定 6379，但 compose 发布 6399”这样的错位。必须同时查看两者。
1883 / 1884（MQTT）不是数据湖，而是代理容器发布的。如果在数据湖上添加相同端口，会因绑定冲突导致启动失败。

完整的端口列表和防火墙，请参阅端口及服务管理。

未生效时 — 请按顺序检查

检查项	内容
① 哪个文件生效	`bin/env.sh --print` 的 `# source:` 列。节点文件 > 边车 > 外壳 > 默认值
② 是否为容器可访问的名称	compose 未写入的名称不会传入 → 变量参考
③ 是否重新创建了容器	边车 · 节点文件的值仅在容器重新创建时传入。`docker restart` 不行——请使用 `restart-datalake.sh`
④ 是否已渲染	`pd config diff` 是否为 0。如果为 1，则在 `pd config render` 后重启
⑤ 是否是密码	通过文件编辑无法更改 → `passwd.sh`
⑥ 模板是否过时	在 `pd config diff --templates` 中执行 `differs` · `missing` → 参见上方 3-way 播种

请勿操作

不要编辑容器内的 PP_HOME/…/conf/*。 它会在下次启动时消失，并且在消失之前，没有人知道哪边才是真实的。
不要试图通过 docker restart plantpulse-datalake 来反映值更改。 环境变量在重新创建容器时确定。restart-datalake.sh 负责完成这件事。
不要使用 FORCE=1 pd start。 它会在已存活进程上方，以相同端口再启动一个。
不要在安装后更改 PP_KEYSPACE · PP_DB_NAME · PP_TOPIC_PREFIX。 将会创建新名称的空存储，旧数据会留在旧名称下。

1. 密码 · API 密钥​

2. 本机箱的地址与身份 — 节点文件​

3. 所有节点共有的非机密值 — 边车​

4. 容器内存​

5. 引擎配置的«行» — 模板​

当镜像携带新的默认值时 — 3-way 播种​

6. 备份计划​

7. 公开端口​

未生效时 — 请按顺序检查​

请勿操作​

相关文档​