跳到主要内容

改变配置的方法

根据改变的内容不同，修改的文件和生效的方法也不同。 首先在下表中找到你的情况。

改变的内容例子修改位置生效
密码 · API 密钥PostgreSQL 密码、CEP API 密钥bin/passwd.sh工具会自动重启
本节点的地址 · 身份其他节点连接的地址、Kafka 广播地址、NAT 公网 IP/etc/kopens/platform.node.envbin/restart-datalake.sh
所有节点的非机密值语言 · 时区、备份计划开关、控制台日志端点/etc/kopens/plantpulse-platform.envbin/restart-datalake.sh
容器资源数据湖内存限制/etc/kopens/platform.node.env (DOCKER_DATALAKE_MEMORY)bin/restart-datalake.sh
引擎配置的«行»postgresql.conf 参数、Kafka 保留期、Cassandra 堆/etc/kopens/conf/<파일>.templatebin/restart-datalake.sh 或容器内 pd config render + pd restart <서비스>
备份计划夜间备份时间容器内 pd backup schedule set立即生效
公开端口主机开放的端口compose/docker-compose.ymlbin/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_IPNAT 环境的公网 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、Cassandra 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_LANGen韩国运维则设为 ko
PP_TZAsia/Seoul时序数据按此时区 epoch 加载，韩国运维应保持不变
PP_BACKUP_SCHEDULE_ENABLEDtrue若为 false，备份计时器五个只记录«已跳过»并结束
PP_DATALAKE_ADMIN_LOGS_ENABLEDtrue若为 false，仅关闭控制台日志画面(端点)
PP_KEYSPACE · PP_DB_NAME · PP_TOPIC_PREFIXpp数据湖«创建»应用«读取»的标识符。安装后不要改变
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 中设置。默认 80G，如果主机内存更小则自动计算为 RAM 的 90%。因为每个节点的值不同，在节点文件中设置。

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

cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh
设置过小会导致«运行中却已死»的状态

容器内 PID 1 是 systemd，只有 Java 进程会在 cgroup 中被 OOM-kill，而 docker ps 仍然显示 Up。杀死记录仅保存在主机的 dmesg 中。2026-09-04 时在 64g 限制下实际发生过(实测峰值 63.9G)，因此默认值提升至 80G。

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 <서비스> 才是完整的一套。

当镜像带来新的默认值时 — 三方合并​

/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
2026-09-03 之前批次的 /etc/kopens/conf 会自动重新播种

如果存在旧 plantpulse-startup 批次(文件名不带 .template 后缀)，pd 将无法渲染。启动工具会检测到此情况，备份后从镜像重新播种，并以 [WARN] stale template layout 通知。旧的编辑仅保留在备份中，不会自动迁移。

6. 备份计划​

不要编辑文件。容器内 pd backup schedule set 会验证和写入 systemd 计时器。管理控制台的备份界面«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: 列。节点文件 > 旁路容器 > Shell > 默认值
② 是否是容器能识别的名称compose 没有记录的名称不会进入 → 变量参考
③ 是否重建了容器旁路容器 · 节点文件的值仅在容器重建时生效。docker restart 不行 — 需要用 restart-datalake.sh
④ 是否已渲染pd config diff 是 0 吗？如果是 1，则 pd config render 后重启
⑤ 是否是密码文件编辑无法改变 → passwd.sh
⑥ 是否是旧模板pd config diff --templates 中有 differs · missing → 查看上面的 三方合并

不要做的事​

  • 不要编辑容器内的 PP_HOME/…/conf/*。 下次启动时会消失，消失前没有人知道哪个是真的。
  • 不要尝试用 docker restart plantpulse-datalake 反映值的变更。 环境变量仅在重建容器时确定。restart-datalake.sh 负责那项工作。
  • 不要用 FORCE=1 pd start。 这会在活运行的进程上以相同端口再启动一个。
  • 安装后不要改变 PP_KEYSPACE · PP_DB_NAME · PP_TOPIC_PREFIX。 会创建新名称的空仓库，旧数据保留在旧名称下。

相关文档​