密码变更（凭证轮换）
概述
PlantPulse 使用服务账户来访问内部基础设施组件（PostgreSQL · Cassandra · Valkey · MinIO · Kafka · MQTT · Hive/Kyuubi · Temporal）。初始值在所有安装中相同，建议在委交时变更一次。
重要： 密码变更必须按顺序进行，否则平台无法启动。通常下面的自动轮换(
bin/passwd.sh)会代替手工流程。只在工具无法处理的值或有工作节点的环境中才使用手工步骤。必须在维护窗口进行，变更前做好备份。
具体如何更改各个键、失败后如何处理，已在**数据湖 — 密码·API 密钥变更中保持最新。本页面仅保留工具无法处理的值的手工步骤**。
自动轮换 — passwd.sh · rotate-secret.sh
安装包中的bin/passwd.sh（前端）和bin/rotate-secret.sh（轮换引擎）一次性执行服务器端账户变更、保管库（sidecar）更新、配置重新渲染、顺序重启。它代替了手工步骤的第 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确认目标 — 只输出涉及哪些变量，不涉及 sidecar 或服务器端。
可轮换的变量
只有注册到注册表的变量才可轮换。若给出未注册的变量，不会悄悄跳过而是拒绝。
| 环境变量 | rotator | 目标账户 |
|---|---|---|
PP_PG_PASSWORD | postgres | plantpulse |
PP_TEMPORAL_PASSWORD | postgres | temporal |
PP_HIVE_PASSWORD | postgres | hive |
PP_CASSANDRA_PASSWORD | cassandra | — |
PP_REDIS_PASSWORD | valkey | — |
PP_MINIO_PASSWORD | minio | — |
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)不是轮换目标，而是决定改为 sidecar 更新 + 重启 → 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_MINIO_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 | Cassandra | 命令 — ALTER ROLE（cqlsh） |
PP_REDIS_PASSWORD | Valkey | 文件 — plantpulse-storage/cache/valkey/conf/valkey.conf |
PP_MINIO_PASSWORD | MinIO | 启动 env — MINIO_ROOT_PASSWORD |
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 变更，配置文件只是访问副本
- 文件 — 该文件本身是真实位置。只能通过重新渲染 + 重启反映
- 启动 env — 进程启动时注入。无运行时变更 API，重启是唯一的反映手段
不变更用户名(PP_*_USER)。只展示 — 账户名变更需要服务器端 role 创建和权限转移，这是另一项工作。
省略值并通过提示输入是推荐的做法 — 密码不会出现在ps输出或 shell 历史中。
给出注册表中没有的键会被拒绝，不会悄悄跳过。打字错误会建议类似的键。
MQ（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 · 两种插件 + cluster/变体）也在同一轮换中一起获得新值，所以不存在只有客户端仍用旧密码的漏洞。
静态 JAAS 无法同时接受新旧密码。在代理和消费者顺序重启期间MQ 路径会中断。不支持无中断轮换 — 必须在维护窗口进行。
BifroMQ 不是轮换对象。实际 MQTT 代理是 HiveMQ。
失败时 — 重新执行同一命令
不执行回滚。回滚需要重新连接，但失败时刻哪个凭证有效不确定，尝试回滚会进一步破坏状态。只支持前向恢复。
失败后原样重新执行同一命令。主机/etc/kopens/rotation.journal(0600)中新旧值已有先行记录，重新执行时会判断各组件当前状态并继续处理。已用新凭证变更的组件会被跳过。
| 消息 | 含义 | 处理 |
|---|---|---|
probe=NEITHER | 无法用新密码或旧密码连接 | 自动化无法判断。需要人工确认状态 |
apply 실패 | 服务器端变更失败，立即停止 | 修复原因后重新执行同一命令 |
verify 실패 | 服务器端已变更但无法用新值连接 | 最危险的情况。日志记录在APPLIED — 需要人工确认 |
configure 실패 | 停止而不重启 | 如果用旧配置启动，所有认证都会失败，这是预期行为 |
若设置了PP_WORKER_NODES，脚本会拒绝并停止。工作节点各有自己的 sidecar，只在主节点轮换会导致工作节点仍用旧密码，集群只有一半工作。部分成功是最坏的失败，所以不会悄悄只处理主节点。
多节点环境目前不支持。请按照集群（多节点）环境的手工步骤。
为什么顺序很重要
密码存在于两个地方。它们不会自动同步。
- 只改 ① 所有客户端认证失败。
- 只改 ② 服务器仍要求旧密码，认证失败。
- 遗漏 ③ 现在可以工作，但下次容器重建时旧密码会被重新注入，启动失败。最容易遗漏的步骤。
因此顺序总是 ① 服务器 → ③ 保管库 → ② 配置重新生成 → 重启。
可变更的账户
자동 회전列为"目标"的可用passwd.sh变更。手工步骤用于其他值和有工作节点的环境。
| 环境变量 | 目标 | 需要服务器端变更 | 自动轮换（计划中） |
|---|---|---|---|
PP_PG_PASSWORD | PostgreSQL 账户 plantpulse | 是 | 目标 |
PP_TEMPORAL_PASSWORD | PostgreSQL 账户 temporal（Temporal 后端） | 是 | 目标 |
PP_HIVE_PASSWORD | PostgreSQL 账户 hive（Hive metastore）+ Hive/Kyuubi 连接认证 | 是 | 目标 |
PP_CASSANDRA_PASSWORD | Cassandra role | 是 | 目标 |
PP_REDIS_PASSWORD | Valkey requirepass | 否（配置文件） | 目标 |
PP_MINIO_PASSWORD | MinIO 根凭证 | 否（启动时注入） | 目标 |
PP_MQ_PASSWORD | Kafka SASL · MQTT 代理 | 否（配置文件） | 目标（MQ 轮换） |
PP_TEMPORAL_PASSWORD不是 Temporal 自身账户。它是 Temporal 连接后端 PostgreSQL 时使用的数据库账户。
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 '새비밀번호';"
Cassandra：
cqlsh -u cassandra -p 구비밀번호 \
-e "ALTER ROLE cassandra WITH PASSWORD = '새비밀번호';"
Cassandra 变更直后约 2 秒钟新旧密码都无法连接。这是因为
cassandra.yaml中credentials_validity（默认 2000ms）凭证缓存。变更后立即看到连接失败，不要判断为失败，3~5 秒后重新确认。
Valkey · MinIO · 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 步 — 保管库（Sidecar）更新
遗漏此步骤会在下次重启时重新注入旧密码。
/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) — 同一秘密有两份副本，但轮换引擎不更新该文件，导致密码变更后仍显示旧值。查看值时也只看 sidecar 一个。
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 步（sidecar 更新）和第 3 步（重启），完全相同。第 1 步（服务器端变更）是共享资源，只需做一次。
失败时恢复
| 现象 | 原因 | 处理 |
|---|---|---|
| 变更直后所有组件认证失败 | 仅做第 1 步，未做第 3 步 | 在主机上执行bin/restart.sh |
| 重启后恢复为旧密码 | 遗漏第 2 步（sidecar） | 修改/etc/kopens/plantpulse-platform.env后重启。Sidecar 优先于bin/env.sh和 shell export |
| 仅 Cassandra 连接失败 | 凭证缓存(2 秒) | 3~5 秒后重新确认 |
| Hive/Kyuubi 可以但 metastore 报错 | PostgreSQL hive账户未变更 | 执行第 1 步中的ALTER USER hive |
ALTER ROLE成功但连接失败 | 引号错误导致存入意外值 | 参考第 1 步验证程序 — 成功返回不保证值正确 |
| 某条路径单独失败 | 某些配置文件未更新 | 在数据湖容器内重新运行./configure.sh后用下面的命令检查残留 |
检查是否有替换失败的占位符留在已部署的配置中：
# 데이터레이크 컨테이너 안에서
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 端口的独立网络界面，有自己的登录账户。此账户既不是平台网络控制台账户，也不是上述基础设施服务账户。
控制中心是以 root 权限启动·停止·控制整个平台的界面。不设置环境变量则所有安装都用相同的开发默认账户(用户名admin)登录。必须在委交时变更。
变更方法
由两个环境变量确定。给出值则使用该值而不是默认值。
| 环境变量 | 用途 |
|---|---|
PP_CONTROL_USER | 控制中心登录用户名 |
PP_CONTROL_PASSWORD | 控制中心登录密码 |
-
在运行控制中心的环境（
plantpulse-startup的环境文件或 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中新旧值以编码形式记录。敏感度同 sidecar，必须维护权限0600。