跳到主要内容

常见问题 (FAQ)

按症状或问题搜索。答案简述，详细步骤请通过链接查看。

配置​

修改了 Sidecar 但未生效​

容器内 没有 Sidecar 文件。 值是在 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 被静默忽略​

如果 Sidecar 已持有该名称，则以 Sidecar 为准。在安装完成的节点上更改值的方法只有 bin/passwd.sh → 更改密码 · API 密钥

上传了镜像但新的配置默认值未生效​

/etc/kopens/conf 是主机文件，不会自动更改。启动工具会在每次部署时进行 3-way 合并，但 保留操作员修改过的文件，并通过 [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                    # 통째로 이미지 기본값으로 (백업은 도구가 남긴다)

其他节点（边缘 · AI · 工作节点）无法连接到该数据湖​

请检查节点文件中是否写入了此主机的 LAN 地址。如果留空，则使用 compose 网络内的地址（10.99.0.100），仅在同一节点内通信。

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

如果仅 Kafka 无法连接，则是广播地址问题 → 节点文件

Renderer 以 exit 8 拒绝​

广播地址为 127.0.0.1。请在节点文件的 PP_HOST_IP · PP_MASTER_IP · PP_KAFKA_ADVERTISED_HOST 中写入实际地址。错误消息会指出需要修改的名称。

Renderer 因 exit 3 或 exit 4 停止​

  • exit 3 — 必需的密钥为空。消息中会列出全部名称。添加到 Sidecar 并重新创建。
  • exit 4 — 模板的 ${PP_*} 中没有值。消息中以 이름@템플릿:줄 显示。在节点文件中提供值或修改模板。

可以禁用某个组件（如 Hive）吗​

pd 中有 PD_OPTIONS='{"enable-hive": false}' 开关，但 当前 compose 堆栈不会将此变量传递给容器。 即使写入 Sidecar 或节点文件也无法接触到容器，因此不会关闭任何组件。该问题已作为需要产品改进的事项上报。旧名称 PP_OPTIONS 任何地方都不读取。

如何将语言设置为韩语​

在 Sidecar 中写入 PP_LANG=ko 并执行 restart.sh（该值也会影响应用，因此需完全重启）。管理控制台单独在地址末尾添加 ?lang=ko。

密码 · 账户​

更改密码后平台无法显示​

服务器端账户与 Sidecar 仅有一方被更改。首先确认哪个值有效。

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;"'

如果使用旧值能连接，则服务器端未更改；如果使用新值能连接，则只需修改 Sidecar。今后请使用 passwd.sh → 更改密码 · API 密钥

passwd.sh 以 «variable not in the registry» 拒绝​

该密钥不属于轮换范围。--list 中列出的 11 个才可轮换。其余请参考 手动过程。如果是拼写错误，会建议类似的密钥。

轮换中途失败​

请原样重新执行相同命令。 日志会记录进展并继续执行。没有回滚。如果是 probe=NEITHER 或 verify 실패，则需要人员直接连接到该组件检查状态。

存在工作节点但 passwd.sh 被拒绝​

这是预期行为。仅轮换主节点会导致工作节点保留旧值，使集群处于残缺状态。请按 手动过程 更改，并对每个工作节点重复 Sidecar 更新 + 重启。

管理控制台登录界面显示 «未设置»​

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 没有默认值，如果为空则 仅该控制台 关闭。写入 Sidecar 并执行 restart-datalake.sh → 查询控制台

PlantPulse Dashboard 的仪表板在容器重新创建后恢复原状​

自 2026-09-08 起已解决。 PlantPulse Dashboard 存储已从镜像内的 SQLite 迁移到 PostgreSQL，仪表板 · 数据源 · 用户 · 报警规则在容器重新创建后得以保留。

对于已部署的安装，🔴 内容不会自动跟随。 如果指向空的 PostgreSQL，则 PlantPulse Dashboard 也将为空 → 时序 · PlantPulse Dashboard

pd start 以 exit 3 停止（PlantPulse Dashboard）​

PP_GRAFANA_DB_PASSWORD 为空。这是 2026-09-08 新增的 启动必需 值 — 请添加到 Sidecar 并重新启动。

SQL 工具卡片消失了​

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 分钟​

首次启动时，由于 Aster TSDB 架构创建，仅存储就可能需要 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 进入后执行。

数据​

数据未进入​

通过 pd flow 查看 MQTT → Kafka → 消费者链路中的阻塞点。

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 · 토픽 보존 · 콜드 티어
  • 如果 Aster TSDB snapshots 较大，则执行 pd node cleanup（快照删除 — 破坏性操作）。
  • 如果显示 slot.orphan，则已移除工作节点的复制槽位占用了 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 发行版的 示例文件，看到后不必惊讶 — 代理读取的只有 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 --cron "0 45 2 * * ?"

即使重新创建容器也会保留 — 该值存储在数据湖数据库的 backup_schedule 行中。

--calendar 是旧标志

仍然接受，但会显示警告。更糟糕的是 它会原样传递值 — 此列用于存储 Quartz cron（초 분 시 일 월 요일，六位），如果使用 systemd 语法 （*-*-* 02:45:00），则会保存错误的表达式。请使用 --cron。

cassandra-full 始终为 fail (exit 120 (medusa))​

2026-09-04 之前的镜像中，未配置 Medusa，导致每天失败。现在 Aster TSDB 启动时由 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> 记录。在控制台更改的配置会记录在 审计 界面。

更多内容​