跳到主要内容

常见问题 (FAQ)

按症状或问题找答案。我们简明回答，详细步骤用链接指向。

配置​

我改了挎斗，但没有生效​

容器内没有挎斗文件。值在 compose 重新创建容器时以环境变量形式注入。docker restart 只是用同样的环境变量重新启动。

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

还是不行的话，①用 bin/env.sh --print 看哪个文件在优先 ②检查 compose 是否把那个名字传给了数据湖 → 未应用时的排查

我在容器内改了配置文件，但它又被改回来了​

这是正常的。PP_HOME 下面的 conf/ 都是生成物，pd start 每次都会从模板重新写入。正确的修改位置是主机上的 /etc/kopens/conf/<파일>.template → 编辑模板

export PP_PG_PASSWORD=… bin/up.sh 被静默忽略了​

如果挎斗已经有了这个名字，挎斗会优先。在已安装的节点上改值的唯一方法是 bin/passwd.sh → 更改密码·API 密钥

上传了镜像，但新配置默认值没有进来​

/etc/kopens/conf 是主机文件，不会自动变化。部署工具在每次部署时进行三方合并，保留运维人员修改过的文件，并用 [WARN] operator edit kept, but THE IMAGE DEFAULT CHANGED 通知。该文件需要手工合并。

docker exec plantpulse-datalake pd config diff --templates     # differs / missing 인 파일
TEMPLATE_FORCE_SEED=1 ./restart-datalake.sh                    # 통째로 이미지 기본값으로 (백업은 도구가 남긴다)

另一个盒子（Edge·AI·Worker）连不上这个数据湖​

检查节点文件中是否填了这台主机的 LAN 地址。留空的话，compose 网络内的地址（10.99.0.100）只能在同一盒子内集成。

sudo vi /etc/kopens/platform.node.env      # PP_MASTER_IP=<이 호스트의 LAN IP>
./restart-datalake.sh

如果只有 Kafka 连不上，那是广告地址的问题 → 节点文件

渲染器用 exit 8 拒绝连接​

广告地址是 127.0.0.1。在节点文件的 PP_HOST_IP·PP_MASTER_IP·PP_KAFKA_ADVERTISED_HOST 中填入实际地址。错误消息会告诉你要改哪个名字。

渲染器卡在 exit 3 或 exit 4​

  • exit 3 — 必需的密钥是空的。消息中会列出所有名字。放入挎斗并重新生成。
  • exit 4 — 模板中的 ${PP_*} 没有值。消息中会用 이름@템플릿:줄 形式显示。在节点文件中提供值或编辑模板。

能关闭一个组件吗（比如 Hive）​

pd 中有 PD_OPTIONS='{"enable-hive": false}' 开关，但当前 compose 栈不会把这个变量传给容器。即使写在挎斗或节点文件中，也到不了容器，所以什么都关不掉。这是已知需要产品端补全的事项。旧名字 PP_OPTIONS 在任何地方都读不到。

要改成韩语界面​

在挎斗中写 PP_LANG=ko，然后 restart.sh（这个值会影响应用，要全栈重启）。管理控制台单独在地址末尾加 ?lang=ko。

密码·账户​

改了密码，平台打不开了​

服务器端账户和挎斗之间有一方没改。先确认哪个值是有效的。

docker exec plantpulse-datalake bash -c 'PGPASSWORD="<구값>" psql -U plantpulse -h 127.0.0.1 -c "SELECT 1;"'
docker exec plantpulse-datalake bash -c 'PGPASSWORD="<신값>" psql -U plantpulse -h 127.0.0.1 -c "SELECT 1;"'

如果用旧值能连上，那是服务器端没改；用新值能连上，那就只用改挎斗。以后都用 passwd.sh → 更改密码·API 密钥

passwd.sh 用「variable not in the registry」拒绝了​

这个键不在轮转对象内。只有 --list 中出现的 11 个可以。其他的用手工步骤。如果是打字错了，它会提议类似的键。

轮转中途失败了​

原样重新执行同一命令。它知道日志进行到哪里，会继续。没有回滚。如果是 probe=NEITHER 或 verify 실패，需要人工直接登入那个组件检查状态。

有 Worker 节点，passwd.sh 拒绝了​

这是有意的行为。只在主节点轮转会导致 Worker 保留旧值，集群就半瘫了。用手工步骤改，然后对每个 Worker 重复挎斗更新 + 重启。

管理控制台登录屏幕说「未配置」​

PP_DATALAKE_ADMIN_PASSWORD 是空的。这不是故障。

bin/passwd.sh PP_DATALAKE_ADMIN_PASSWORD     # --list 에 이 키가 있으면
# 없으면 (2026-09-05 이전 패키지) 사이드카에 줄을 적고 ./restart-datalake.sh

→ Web 界面登录账户

数据网关·CEP 控制台登录失败​

PP_DATA_GATEWAY_WEB_PASSWORD·PP_CEP_WEB_PASSWORD 没有默认值，空着的话那个控制台就关闭。写在挎斗中，然后 restart-datalake.sh → 查询控制台

改了 Grafana 密码，重新创建容器后又变回去了​

这是已知缺陷。Grafana 的数据目录不是卷，而是在镜像树内 → Grafana

SQL 工具卡消失了​

plantpulse-sql 在 2026-09-07 被弃用。SQL 现在在数据网关控制台中运行（https://<server-ip>:5501/）。管理控制台的工具屏幕有 Data Gateway 卡。

启动·状态​

pd status 里有一个 STOPPED，我刚启动过​

这是启动窗口。analytics 的 Kyuubi 最后启动，从 spark-master 开始大约需要 54 秒。1 分钟后再看。还是这样的话看 pd logs --lines 100 <서비스>。

docker ps 是 Up，但所有服务都死了​

怀疑内存 OOM。PID 1 是 systemd，所以只有 Java 死，容器还活着。

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

→ 提高内存限制

pd stop 以 STILL RUNNING(exit 7) 结束了​

别急着 pd start。用 pd kill --dry-run 看剩余的，然后 pd kill → 用 pd status 确认是空的 → pd start。

pd start 用「already running」拒绝了​

已经启动了。要重新启动，从 pd stop 开始。FORCE=1 会在活进程上用同一端口再启一个，别用。

首次启动超过 10 分钟​

首次启动 Cassandra 模式生成在 storage 上就能花到 500 秒。容器启动宽限是 900 秒的原因就是这个。用 bin/logs.sh -f plantpulse-datalake 看进度。

控制台里出现「Another job is already running on this node」​

这是 2026-09-04 之前 admin-api 镜像的症状。看 pd env 中的 IMAGE_BUILT_AT，如果是旧的就 update.sh。新镜像中「运行检查」按钮也是一次只受理一个，稍后再按。

从主机运行 pd 得到「command not found」​

pd 只在容器内。用 docker exec plantpulse-datalake pd … 或 bin/shell.sh 进去再运行。

数据​

数据进不来​

MQTT → Kafka → 消费者这条链的某处堵了。用 pd flow 看。

docker exec plantpulse-datalake pd flow

LAG 很大的话，说明消费者（服务器·CEP·批处理）很慢或卡了；NA 是「从未读过」→ 如果 MEMB 是 0，消费者没启；如果大于 0 但主题空了，那是正常的。管理控制台的拓扑屏幕用图形展示同样的东西。

磁盘满了 / 不缩小​

docker exec plantpulse-datalake pd storage        # 얼마나 있나 — 볼륨 · WAL · 슬롯 · 스냅샷
docker exec plantpulse-datalake pd retention      # 언제 사라지나 — TTL · 토픽 보존 · 콜드 티어
  • Cassandra 的 snapshots 很大的话，用 pd node cleanup（删除快照 — 有破坏性）。
  • 看到 slot.orphan 说明已删除 Worker 的复制槽在锁定 WAL — 主机 ops-check.sh --reclaim。
  • 卡住的模块日志就是 pd clean。
  • pd retention 中的 TTL none 不是「无过期」而是「表无默认值」。行级有 TTL 的表（ts_data_points）能正常过期。
  • cold_tier 中的 last advance 超过 48 小时没动，说明存档作业卡了 — 这常常是热磁盘不缩小的真实原因。

Kafka 用「advertises 127.0.0.1」显示 DOWN​

节点文件的地址空了 → 节点文件。容器内的 broker.properties·server.properties 是 Kafka 发行版的示例文件，别吃惊 — broker 只读一个文件：kafka.properties。

时序数据几天后消失了​

时序单点的寿命是 PP_TSE_DATAPOINT_TTL（默认 365 天）。2026-09-05 之前是 31 天字面量。值在写入时被戳，所以即使提高也不会救活已写行 → 变量参考

备份​

备份有没有在打？怎么看​

docker exec plantpulse-datalake pd backup schedule      # 잡 다섯의 일정 · 마지막 결과
docker exec plantpulse-datalake pd backup list          # 세트 목록

管理控制台的备份屏幕会显示同样的东西 → 备份·恢复

要改夜间备份时间​

docker exec plantpulse-datalake pd backup schedule set --job postgres-diff --calendar "*-*-* 02:45:00"

即使重新创建容器也会保留。

cassandra-full 一直是 fail (exit 120 (medusa))​

2026-09-04 之前的镜像因为没人用 Medusa 配置，每天都失败。现在 Cassandra 启动时 pd 会重新写 — pd restart storage 后用 pd backup run --engine cassandra --type full 检查。

日志​

日志在哪看​

主机上用 bin/logs.sh plantpulse-datalake（最后 200 行，-f 跟踪），容器内用 pd logs [서비스]。应用容器日志不在 pd logs，用 logs.sh <서비스> 看 → 日志与健康

想知道谁什么时候关的服务​

事件日志 plantpulse-datalake-admin-api/logs/pd-events.jsonl，或管理控制台的事件屏幕。在控制台执行的命令记在 operator:<name>。在控制台改的配置记在审计屏幕。

了解更多​