密码更改（凭据轮换）

概述

PlantPulse 使用服务账户来连接内部基础设施组件（PostgreSQL · Aster TSDB · Valkey · RustFS · Kafka · MQTT · Hive/Kyuubi · Temporal）。所有安装中的初始值都是相同的，因此建议在调试阶段更改一次。

重要： 密码更改如果不按顺序执行，平台将无法启动。 通常，下面的自动轮换（bin/passwd.sh）会代替您执行该顺序。仅在工具未涵盖的值或存在工作节点的环境中，才使用手动步骤。务必在检修窗口内执行，并在操作前确保已备份。

已在数据湖部分整理

如何更改哪个密钥，以及失败时如何处理，已在 数据湖 — 更改密码 · API 密钥 中更新到最新状态。此页面是为该工具未处理的值的手动步骤而保留的。

自动轮换 — `passwd.sh` · `rotate-secret.sh`

安装包中的 bin/passwd.sh（前置界面）和 bin/rotate-secret.sh（轮换引擎）会一次性执行服务器端账户更改 · 保管库（边车）更新 · 配置重新渲染 · 顺序重启。手动步骤中的第 1~3 步由其完全替代。容器端的轮换机制是数据湖镜像中的 pd secret rotate，主机脚本会调用它。

操作员的入口点是主机。因为如果从容器内启动，当容器停止时，进度记录也会随之消失，导致无法恢复。

cd /opt/kopens/plantpulse-platform-docker

# 하나만 변경
bin/rotate-secret.sh PP_PG_PASSWORD='새비밀번호'

# 여러 개 — 재시작 1회로 묶인다
bin/rotate-secret.sh PP_PG_PASSWORD='...' PP_CASSANDRA_PASSWORD='...'

# 커미셔닝 시 전체 생성
bin/rotate-secret.sh --all --generate

# 계획만 출력 — 아무것도 바꾸지 않는다
bin/rotate-secret.sh --dry-run --all --generate

参数必须是 변수=값 格式。如果像 PP_PG_PASSWORD '새값' 那样用空格分隔，将被拒绝并报错 알 수 없는 인자。

--all 只能与 --generate 一起使用。--generate 会为每个变量生成一个 20 位随机值。首先用 --dry-run 确认目标 — 它只输出哪些变量会受到影响，不会改动边车或服务器端。

可轮换的变量

只有注册表中注册的变量才能轮换。如果提供未注册的变量，不会默默跳过，而是拒绝。

环境变量	轮换器	目标账户
`PP_PG_PASSWORD`	postgres	`plantpulse`
`PP_TEMPORAL_PASSWORD`	postgres	`temporal`
`PP_HIVE_PASSWORD`	postgres	`hive`
`PP_CASSANDRA_PASSWORD`	cassandra	—
`PP_REDIS_PASSWORD`	valkey	—
`PP_S3_PASSWORD`	rustfs	—
`PP_MQ_PASSWORD`	mq	— （Kafka · HiveMQ 一起 — 见下方节）
`PP_CEP_API_KEY`	apikey	—
`PP_DATA_GATEWAY_API_KEY`	apikey	—
`PP_DATALAKE_ADMIN_PASSWORD`	console	`admin` （管理控制台登录，2026-09-05 新增）
`PP_DATALAKE_ADMIN_API_KEY`	apikey	— （管理控制台日志端点，2026-09-05 新增）

--all --generate 也只针对这个列表。在 2026-09-05 之前的安装包中没有最后两项 — --list 是权威版本。

尚未注册的变量 — PP_API_KEY、PP_FLOW_WEBHOOK_API_KEY（供外部调用者使用，待验证端点确定后另行处理）、PP_SPARK_PASSWORD · PP_TSE_PASSWORD · PP_GRAVITINO_PASSWORD · PP_KESTRA_DB_PASSWORD · PP_KESTRA_ADMIN_PASSWORD，以及 TLS keystore/truststore 密码（与证书更换相关，另行处理）。这些会被脚本拒绝，因此请使用手动步骤进行更改。查询控制台的两个登录项（PP_DATA_GATEWAY_WEB_PASSWORD · PP_CEP_WEB_PASSWORD）已决定不纳入轮换目标，而是通过更新边车 + 重启来更改 → Web 界面登录账户。

PP_MQ_PASSWORD（Kafka · HiveMQ）是轮换目标，但它是唯一会导致连接中断的项目，因此在下面的 MQ 轮换中单独处理。

操作员用前置界面 — `passwd.sh`

这是用来替代直接调用 rotate-secret.sh 的前置界面。它只负责验证并调用一次轮换引擎，因此行为相同，不同之处在于它会以列表形式显示可以更改哪些内容。platform · ai · studio 三个产品具有相同的名称和相同的用法。

cd /opt/kopens/plantpulse-platform-docker

bin/passwd.sh --list                      # 키 + 아이디 + 현재값(마스킹) + 위치
bin/passwd.sh --list --show               # 현재값 전체

bin/passwd.sh PP_MQ_PASSWORD              # 값 생략 → 프롬프트 (권장)
bin/passwd.sh PP_PG_PASSWORD=<new-password>
bin/passwd.sh PP_CASSANDRA_PASSWORD=<new-password> PP_S3_PASSWORD=<new-password>   # 묶으면 재시작 1회
bin/passwd.sh --dry-run PP_MQ_PASSWORD=<new-password>

没有别名 — 键就是环境变量名本身

不能用 mq、cassandra、postgres 这样的组件名称来调用。如果设置别名，就必须维护一个与注册表不同的名称-变量映射表，并且每当两个别名指向同一个变量时（例如“kafka 和 hivemq 是同一个值”），都需要附加特殊规则。如果键本身就是变量，就没有这个问题。

哪些变量对应哪些组件，由 --list 告知 — 所以才有这个列表。

以下是可更改的键，以及其值的权威来源。

键	组件	更改方式
`PP_PG_PASSWORD`	PostgreSQL	命令 — `ALTER ROLE` (psql)
`PP_TEMPORAL_PASSWORD`	Temporal 的后端 PostgreSQL 账户	命令 — `ALTER ROLE` (psql)
`PP_HIVE_PASSWORD`	Hive 元存储的 PostgreSQL 账户	命令 — `ALTER ROLE` (psql)
`PP_CASSANDRA_PASSWORD`	Aster TSDB	命令 — `ALTER ROLE` (cqlsh)
`PP_REDIS_PASSWORD`	Valkey	文件 — `plantpulse-storage/cache/valkey/conf/valkey.conf`
`PP_S3_PASSWORD`	RustFS	启动环境变量 — `RUSTFS_SECRET_KEY`
`PP_MQ_PASSWORD`	Kafka + HiveMQ (共享一个值)	文件 — `kafka/config/jaas.conf` + `mqtt/conf/auth.properties`
`PP_CEP_API_KEY`	CEP API 密钥	文件 — `plantpulse-cep/config/plantpulse-cep.properties`
`PP_DATA_GATEWAY_API_KEY`	Data Gateway API 密钥	文件 — `plantpulse-data-gateway/config/plantpulse-jdbc.properties`

这三种方式的含义如下：

命令 — 服务器端账户是权威来源。通过 SQL/CQL 更改，配置文件只是连接用的副本
文件 — 该文件本身就是权威来源。只能通过重新渲染 + 重启来更改
启动环境变量 — 在进程启动时注入。没有运行时更改 API，因此重启是唯一的生效方式

ID（PP_*_USER）不更改。 仅作显示 — 更改账户名是另一项需要服务器端角色创建和权限移交的任务。

建议路径是省略值并通过提示符输入 — 这样密码不会出现在 ps 输出或 shell 历史记录中。

如果传递注册表中不存在的键，不会默默跳过，而是拒绝。拼写错误时会建议相似的键。

MQ（Kafka · HiveMQ）轮换

Kafka 和 HiveMQ 不能单独更改

PP_MQ_PASSWORD 一个值既是两个代理的服务器端凭据存储，又是 8 个客户端的连接密码。无论是通过 kafka 调用还是 hivemq 调用，两者会一起更改。

如果在一条命令中给 kafka 和 hivemq 提供不同的值，将被拒绝 — 不会悄悄决定哪一方生效。

Kafka 从静态 JAAS（kafka-jaas.conf）读取值，HiveMQ 从安全扩展（plantpulse-mq-auth.properties）读取值。8 个客户端（plantpulse-mq · plantpulse-mqtt · plantpulse-batch · 2 种插件 + cluster/ 变体）也会在同一轮轮换中获得新值，因此不会留下只使用旧密码的客户端漏洞。

轮换期间 MQ 路径会中断

静态 JAAS 无法同时接受新旧密码。在顺序重启代理和消费者的过程中，MQ 路径会出现中断。 无中断轮换不在支持范围内 — 务必在检修窗口内执行。

BifroMQ 不是目标。 实际的 MQTT 代理是 HiveMQ。

失败时 — 重新执行相同命令

不进行回滚。 要回滚需要重新连接，而失败时无法确定哪份凭据有效，尝试回滚可能会使状态更糟。只支持向前恢复。

如果失败，请原样重新执行相同命令。 在新旧值被预先记录在主机 /etc/kopens/rotation.journal（0600）中的情况下，重新执行时会判断每个组件的当前状态并继续执行。已经改用新凭据的组件会被跳过。

消息	含义	操作
`probe=NEITHER`	新旧任一种方式都无法连接	自动化没有判断依据。需要人工检查状态
`apply 실패`	服务器端更改失败，立即停止	修复原因后重新执行相同命令
`verify 실패`	服务器端已更改，但新值无法连接	最危险。日志会以 `APPLIED` 的形式保留 — 需要人工检查
`configure 실패`	未重启就停止	如果以旧配置启动，所有认证都会失败，因此这是预期行为

存在工作节点时无法使用

如果配置了 PP_WORKER_NODES，脚本将拒绝并停止。因为每个工作节点都有单独的边车，如果只轮换主节点，工作节点会保留旧密码，导致集群只有一半工作。部分成功是最糟糕的失败，所以不会默默只处理主节点。

目前不支持多节点。请遵循集群（多节点）环境中的手动步骤。

为什么顺序很重要

密码独立存在于两处。两者不会自动同步。

只更改①会导致所有客户端认证失败。
只更改②会导致服务器仍然要求旧密码，认证失败。
遗漏③会导致当前可以工作，但下次容器重建时会重新注入旧密码，导致启动失败。这是最容易被遗漏的步骤。

因此，顺序始终是 ① 服务器 → ③ 保管库 → ② 配置重新生成 → 重启。

可更改的账户

자동 회전 列中《目标》为 passwd.sh 的说法不正确，应改为 passwd.sh 可轮换。手动步骤是为其他值和存在工作节点的环境准备的。

下面是基础设施账户七个。四个 API 密钥（PP_CEP_API_KEY · PP_DATA_GATEWAY_API_KEY · PP_DATALAKE_ADMIN_PASSWORD · PP_DATALAKE_ADMIN_API_KEY）也是同一工具的目标，全部十一个罗列在上面的可轮换变量中。

环境变量	目标	需要服务器端更改	自动轮换
`PP_PG_PASSWORD`	PostgreSQL 账户 `plantpulse`	需要	目标
`PP_TEMPORAL_PASSWORD`	PostgreSQL 账户 `temporal` (Temporal 后端)	需要	目标
`PP_HIVE_PASSWORD`	PostgreSQL 账户 `hive` (Hive metastore) + Hive/Kyuubi 连接认证	需要	目标
`PP_CASSANDRA_PASSWORD`	Aster TSDB role	需要	目标
`PP_REDIS_PASSWORD`	Valkey `requirepass`	不需要 (配置文件)	目标
`PP_S3_PASSWORD`	RustFS 根凭据	不需要 (启动时注入)	目标
`PP_MQ_PASSWORD`	Kafka SASL · MQTT 代理	不需要 (配置文件)	目标 (MQ 轮换)

PP_TEMPORAL_PASSWORD 不是 Temporal 自身的账户。 它是 Temporal 连接后端 PostgreSQL 时使用的 DB 账户。

PP_HIVE_PASSWORD 是一个值，双向使用。 它既是 Hive metastore 连接 PostgreSQL 时提交的值，同时又是客户端连接 HiveServer2/Kyuubi 时验证的值。因此既要更改 PostgreSQL 账户，也要重新生成配置。 如果只做一个，metastore 或 HiveServer2 中会有一个无法工作。

手动步骤

在以下情况下使用此步骤 — 自动轮换未处理的变量（TLS keystore/truststore、Spark · TSE · Gravitino · Kestra 账户等），以及存在工作节点导致脚本拒绝的环境。其他情况由 bin/passwd.sh 代替此步骤。

第 1 步 — 服务器端账户更改

使用旧密码连接后进行更改。如果跳过此步骤，其余步骤都毫无意义。

PostgreSQL（3 个账户 — 仅更改需要更改的）：

psql -U plantpulse -c "ALTER USER plantpulse PASSWORD '새비밀번호';"
psql -U temporal   -d temporal -c "ALTER USER temporal PASSWORD '새비밀번호';"
psql -U hive       -d hive     -c "ALTER USER hive     PASSWORD '새비밀번호';"

Aster TSDB:

cqlsh -u cassandra -p 구비밀번호 \
  -e "ALTER ROLE cassandra WITH PASSWORD = '새비밀번호';"

Aster TSDB 在更改后约 2 秒内，新旧任一种方式都无法连接。 这是由于 cassandra.yaml 中的 credentials_validity（默认 2000ms）凭据缓存所致。更改后立即看到连接失败时，不要判定为失败，请在 3~5 秒后再次确认。

Valkey · RustFS · Kafka · MQTT 没有存储在服务器端的账户 — 配置文件和启动环境变量是权威来源，因此不需要此步骤。

⚠ 更改后必须立即使用新密码尝试连接

ALTER USER 即使输入错误的值也会返回成功（ALTER ROLE）。 成功消息仅表示“命令已执行”，不保证“已输入预期值”。

最常见的事故是引号处理错误。如果将 shell 变量放在单引号内，它不会被展开，而是按字面值存储。

# ✗ 위험 — 변수가 확장되지 않아 '$NEW_PW' 라는 문자열이 비밀번호가 된다.
#          그런데도 ALTER ROLE 은 성공을 반환한다.
psql -U hive -c 'ALTER USER hive PASSWORD "$NEW_PW";'

# ✓ 안전 — 값을 직접 적거나, 확장되는 문맥인지 확인한다
psql -U hive -c "ALTER USER hive PASSWORD '실제새비밀번호';"

因此，更改每个账户后，立即在该处验证连接。如果等到进入下一步后才发现问题，则很难找到原因。

PGPASSWORD='새비밀번호' psql -U hive -h 127.0.0.1 -d postgres -w -tAc "SELECT 1"
# 1 이 나오면 정상. 인증 실패면 값이 의도와 다르게 들어간 것이다.

如果无法连接，请首先确认旧密码是否仍然有效。如果有效，说明更改尚未生效；如果新旧都无效，则说明输入了意外值，需要找到该值并重新连接以纠正。

如果密码包含单引号（'），在 SQL/CQL 语句中必须转义为两个（a'b → 'a''b'）。

第 2 步 — 更新保管库（边车）

如果遗漏此步骤，下次重启时会重新注入旧密码。

配置权威是 /etc/kopens/plantpulse-platform.env 一个

平台的秘密位于 repo 树之外的 /etc/kopens/ 中，格式为 0600。权威只有一个文件。

ls -l /etc/kopens/

文件	状态
`/etc/kopens/plantpulse-platform.env`	权威 — platform · ai · studio 三个产品通用约定（`plantpulse-<product>.env`）
`/opt/kopens/plantpulse-platform.env`	仅在 2026-08-25 ~ 08-29 期间使用的路径。不读也不写 — 如果残留，安装脚本会将其恢复为权威版本

platform.env.generated 已不再存在（2026-08-22 删除）。同样，platform-credentials.txt 也已废弃（2026-08-16）— 它持有同一秘密的两份副本，但轮换引擎不会更新该文件，导致更改密码后仍告知旧值。查看值时也只查看一个边车。

sudo vi /etc/kopens/plantpulse-platform.env

将相应的 export PP_..._PASSWORD=... 行修改为新值。请保持文件权限为 0600。

sudo chmod 600 /etc/kopens/plantpulse-platform.env

第 3 步 — 重启

从主机重启栈。配置重新生成已包含在启动过程中。

cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh       # graceful drain → 재기동 → 준비될 때까지 대기 (0 = 쓸 수 있다)

数据湖容器启动时会重新渲染模板。因此，直接修改组件配置文件，重启后会恢复为模板值。 请在主机的 /etc/kopens/conf（绑定挂载到容器的 plantpulse-datalake-cli/config/templates）中更改配置。

六个应用不渲染模板 — 它们仅通过 compose 传递的环境变量接收值。

第 4 步 — 验证

# 플랫폼 전체 상태 (호스트에서) — 0 = 정상 / 2 = 비정상
cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh
./ops-check.sh

# 각 컴포넌트가 새 비밀번호로 실제 접속되는지 (데이터레이크 컨테이너 안에서)
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node psql -c "SELECT 1;"
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node cql -e "SELECT now() FROM system.local;"
exit

如果健康 API 返回 OK 或 WARN，则为正常。

curl -kfsS https://<server-ip>:4950/api/health | jq .status

集群（多节点）环境

在存在工作节点的环境中，不能只更改主节点。

工作节点也拥有自己的 /etc/kopens/plantpulse-platform.env 并注入到容器中。如果只更改主节点，工作节点会保留旧密码，导致集群只能一半工作。

在每个工作节点上，第 2 步（边车更新）和第 3 步（重启） 都要执行相同的操作。第 1 步（服务器端更改）是共享资源，只需执行一次。

失败时

症状	原因	操作
更改后所有组件认证失败	仅执行第 1 步，未执行第 3 步	从主机执行 `bin/restart.sh`
重启后恢复为旧密码	遗漏第 2 步（边车）	修改 `/etc/kopens/plantpulse-platform.env` 后重启。边车优先于 `bin/env.sh` 和 shell export
仅 Aster TSDB 连接失败	凭据缓存（2 秒）	3~5 秒后重新确认
Hive/Kyuubi 正常但 metastore 错误	PostgreSQL `hive` 账户未更改	执行第 1 步中的 `ALTER USER hive`
`ALTER ROLE` 成功但连接失败	引号错误导致存储了非预期值	参考第 1 步的验证步骤 — 成功返回不保证值的准确性
仅特定路径失败	部分配置文件未更新	在数据湖容器内重新执行 `pd config render` 后，使用以下命令确认残留

检查已部署的配置中是否留有未替换的占位符：

# 데이터레이크 컨테이너 안에서
grep -rn '\${PP_' /opt/kopens/plantpulse-platform/ \
  --include='*.conf' --include='*.properties' --include='*.xml' --include='*.yaml' \
  | grep -v '/plantpulse-datalake-cli/config/templates/'
# 아무것도 나오지 않아야 정상입니다

如果中途失败导致只有一侧更改，首先确认哪个密码有效。

PGPASSWORD='구비밀번호' psql -U plantpulse -h 127.0.0.1 -c "SELECT 1;"   # 구 값으로 접속되는가
PGPASSWORD='새비밀번호' psql -U plantpulse -h 127.0.0.1 -c "SELECT 1;"   # 신 값으로 접속되는가

旧值可以连接 → 第 1 步未生效。从第 1 步开始重新执行。
新值可以连接 → 第 1 步已完成。只需执行第 2·3 步即可。

控制中心（ppctl）操作员账户

在当前的容器出厂版本中无法访问此界面

compose 栈中没有容器将 9700 端口发布到主机。 systemctl restart ppctl 也不适用于在容器内运行的栈。

以下内容是为单独运营控制中心的环境保留的。在容器环境中启动、停止、控制平台的方法，请参见系统启动与停止中的通用动词（up.sh · down.sh · restart.sh · status.sh）。

除了前面的步骤之外，还有完全独立的一个密码。控制中心（ppctl）是在端口 9700 上运行的独立 Web 界面，使用自己的登录账户。该账户既不是平台 Web 控制台账户，也不是上面的基础设施服务账户。

不要保留默认值

控制中心是以 root 权限启动、停止、控制整个平台的界面。如果未设置环境变量，将使用所有安装都相同的开发用默认账户（用户名 admin）登录。请在调试阶段务必更改。

更改方法

由两个环境变量决定。如果提供值，则使用该值代替默认值。

环境变量	用途
`PP_CONTROL_USER`	控制中心登录用户名
`PP_CONTROL_PASSWORD`	控制中心登录密码

在启动控制中心的环境中（边车 /etc/kopens/plantpulse-platform.env 或 systemd 单元 ppctl.service 的 Environment=）设置上述两个值。
重启控制中心。
```
systemctl restart ppctl
```
确认在 https://[HOST]:9700 上可以使用新值登录。

此账户没有从界面更改的功能。修改环境变量并重启是唯一的更改方法。

不要在生产环境中开启 `PP_CONTROL_NOAUTH`

如果提供 PP_CONTROL_NOAUTH=1（或 JVM 选项 -Dppctl.noauth=1），控制中心的 登录将被整体禁用。这是一个用于可信网络演示的开关，默认值为关闭。

任何能访问到端口 9700 的人都可以在没有认证的情况下控制整个平台，因此请勿在生产环境中开启，并在防火墙中将 9700 端口的访问限制在操作员网段内。

注意事项

如果密码中使用单引号（'），在 SQL/CQL 语句中必须转义为两个（a'b → 'a''b'）。
请将更改历史和新密码保存在安全的地方。虽然当前值会记录在 /etc/kopens/platform-credentials.txt 中，但此文件是明文，因此必须保持其权限（0600）。
CEP · Data Gateway 的 API 密钥（PP_CEP_API_KEY · PP_DATA_GATEWAY_API_KEY）是服务器和消费者各自读取相同值并进行比较的方式。如果只更改一侧，会立即引发 401，因此必须同时更改两侧。这两个密钥都是自动轮换的目标。
自动轮换留下的 /etc/kopens/rotation.journal 中编码记录了新旧值。其敏感性与边车相同，因此请保持权限 0600。

概述​

自动轮换 — passwd.sh · rotate-secret.sh​

可轮换的变量​

操作员用前置界面 — passwd.sh​

MQ（Kafka · HiveMQ）轮换​

失败时 — 重新执行相同命令​

为什么顺序很重要​

可更改的账户​

手动步骤​

第 1 步 — 服务器端账户更改​

⚠ 更改后必须立即使用新密码尝试连接​

第 2 步 — 更新保管库（边车）​

第 3 步 — 重启​

第 4 步 — 验证​

集群（多节点）环境​

失败时​

控制中心（ppctl）操作员账户​

更改方法​

不要在生产环境中开启 PP_CONTROL_NOAUTH​

注意事项​

相关文档​

概述