跳到主要内容

更改密码与 API 密钥

数据湖的服务账户（PostgreSQL · Aster TSDB · Valkey · RustFS · Kafka/MQTT …）和 API 密钥都从所有安装版本相同的默认值开始。在调试阶段必须更改它们，此后按照策略轮换。

更改工具是主机上的 bin/passwd.sh 一个工具。

cd /opt/kopens/plantpulse-platform-docker

bin/passwd.sh --list                       # 바꿀 수 있는 키 + 계정명 + 현재값(마스킹) + 정본 위치
bin/passwd.sh PP_PG_PASSWORD               # 값을 생략하면 프롬프트 — 권장 (히스토리 · ps 에 안 남는다)
bin/passwd.sh PP_PG_PASSWORD=<새비밀번호>   # 인라인
bin/passwd.sh PP_CASSANDRA_PASSWORD PP_S3_PASSWORD   # 여러 개를 한 번에 — 재시작 1회
bin/passwd.sh --dry-run PP_MQ_PASSWORD     # 계획만 — 아무것도 바꾸지 않는다
不要打开文件直接修改密码行

密码存储在两个位置 —— 服务器接受的值（PostgreSQL 账户，Aster TSDB 角色 …）和客户端提供的值（约 20 个配置文件）。这两者不会自动同步。只修改 sidecar 会导致所有客户端在下次重启时认证失败；只修改服务器端则会导致当前立即失败。

passwd.sh 会按顺序在一条命令内完成：① 更改服务器端账户 → ② 更新 sidecar → ③ 重新渲染配置 → ④ 重启。

可更改的密钥​

密钥就是环境变量的原名。没有像 postgres · mq 这样的别名 —— 哪个密钥对应哪个组件由 --list 告知。

密钥组件账户值的正源在哪里
PP_PG_PASSWORDPostgreSQLplantpulse命令 —— ALTER ROLE (psql)
PP_TEMPORAL_PASSWORDTemporal 后端 PostgreSQL 账户temporal命令 —— ALTER ROLE (psql)
PP_HIVE_PASSWORDHive metastore 的 PostgreSQL 账户 + Kyuubi 入站认证hive命令 —— ALTER ROLE (psql) + 重新渲染
PP_CASSANDRA_PASSWORDAster TSDBcassandra命令 —— ALTER ROLE (cqlsh)
PP_REDIS_PASSWORDValkey—文件 —— plantpulse-storage/cache/valkey/conf/valkey.conf
PP_S3_PASSWORDRustFSrustfs启动 env —— RUSTFS_SECRET_KEY
PP_MQ_PASSWORDKafka + HiveMQ —— 共享同一个值mq文件 —— kafka/config/jaas.conf + mqtt/conf/auth.properties
PP_CEP_API_KEYCEP API 密钥 (X-API-Key)—文件 —— plantpulse-cep/config/plantpulse-cep.properties
PP_DATA_GATEWAY_API_KEY数据网关 API 密钥—文件 —— plantpulse-data-gateway/config/plantpulse-jdbc.properties
PP_DATALAKE_ADMIN_PASSWORD管理控制台登录admin启动 env —— admin-api 从其环境变量中读取
PP_DATALAKE_ADMIN_API_KEY管理控制台日志端点 X-API-Key—启动 env

三个类别的含义：

  • 命令 —— 服务器账户是正源。通过 SQL/CQL 更改，配置文件只是连接用的副本。
  • 文件 —— 渲染后的那个文件本身就是正源。只能通过重新渲染 + 重启来更改。
  • 启动 env —— 在进程启动时注入。没有运行时更改 API，重启是唯一的生效方式。

账户名（PP_*_USER）不会更改。 仅在 --list 中显示。更改账户名是另一项需要同时进行服务器端角色创建和权限迁移的工作。

如果 --list 中没有显示两个控制台密钥

PP_DATALAKE_ADMIN_PASSWORD · PP_DATALAKE_ADMIN_API_KEY 于 2026-09-05 添加。在那之前的安装包只有 9 个密钥。此种情况下，控制台密码没有对应的服务器端账户，可直接修改 sidecar 并重启即可 → Web 界面登录账户

流程 —— 首次一次性​

在调试阶段，将已注册的密钥全部轮换为随机值。--all 是轮换引擎 rotate-secret.sh 的选项，而非 passwd.sh。

cd /opt/kopens/plantpulse-platform-docker

bin/rotate-secret.sh --dry-run --all --generate   # 어떤 키가 걸리는지 확인 — 아무것도 안 바꾼다
bin/rotate-secret.sh --all --generate             # 실행. 키마다 20자 무작위 값
bin/passwd.sh --list --show                       # 결과 확인 — 값이 그대로 찍히니 화면 공유 중에는 치지 마세요
  • 必须在巡检窗口内执行。轮换期间有一次重启，Kafka/MQTT 路径会在此间断开。
  • 操作前请先确保 备份。
  • 更改后的值仅存在于 sidecar /etc/kopens/plantpulse-platform.env 中。在交接文档中，不要写值本身，而应写“由谁保管”。

流程 —— 运行中逐个轮换​

cd /opt/kopens/plantpulse-platform-docker
bin/passwd.sh --dry-run PP_PG_PASSWORD    # 계획 확인
bin/passwd.sh PP_PG_PASSWORD              # 프롬프트에 새 값 입력

完成后进行确认。

bin/status.sh                                                           # 0 = 정상
docker exec plantpulse-datalake pd node psql -c "SELECT 1;"             # 새 비밀번호로 실제 접속되나
docker exec plantpulse-datalake pd node cql -e "SELECT now() FROM system.local;"
curl -kfsS https://<server-ip>:4950/api/health | jq .status               # OK 또는 WARN

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

轮换不进行回滚。在失败时刻，哪个值有效是不确定的，尝试回退会使状态更加混乱。相反，我们进行前向恢复。

主机的 /etc/kopens/rotation.journal(0600) 中预先记录了新旧值。原样重新执行同一命令，各组件将探测（probe）当前接受的是哪个值并继续。已经更改的将被跳过。

消息含义操作
probe=NEITHER使用新旧值均无法连接自动化没有任何判断依据。需要人工直接连接该组件检查状态
apply 失败服务器端更改失败，立即中止修复原因后重新执行同一命令
verify 失败服务器已更改，但无法用新值连接最危险。日志将保留为 APPLIED —— 需要人工确认
configure 失败未重启即中止这是预期行为（如果以旧配置启动，所有认证都会失败）。修复原因后重新执行
variable not in the registry未注册的密钥参见下面的 不轮换的值 —— 手动处理
存在工作节点时将被拒绝

如果已配置集群工作节点，轮换工具将拒绝并中止。因为每个工作节点都有自己的 sidecar，仅轮换主节点会导致工作节点保留旧值，使集群变得残缺。存在工作节点的环境请遵循 手动流程，并对每个工作节点重复执行 sidecar 更新和重启。

PP_MQ_PASSWORD —— Kafka 和 HiveMQ 一起轮换​

一个值既是两个 broker 的服务器端凭据存储，也是所有客户端的连接密码。不能分开更改，轮换工具的验证必须两者都以新值连接成功才算成功。

静态 JAAS 无法同时接受新旧值，因此在 broker 和消费者按顺序重启期间，MQ 路径会断开。 无中断轮换不在支持范围内。

PP_HIVE_PASSWORD —— 一个值被双向使用​

这是 Hive metastore 连接 PostgreSQL 时提供的值，同时又是客户端连接 Kyuubi 时验证的值。因此轮换工具会同时执行 PostgreSQL 账户更改和配置重新渲染。手动操作时若只做其中一项，会导致 metastore 或 Kyuubi 其中之一挂掉。

不轮换的值 —— 手动处理​

如果给出不在注册表中的密钥，不会静默跳过，而是拒绝。以下是尚未注册的值，请通过 手动流程 更改。

变量用途手动更改要点
PP_SPARK_PASSWORDSpark/Kyuubi 客户端账户没有服务器端账户。hive-auth.properties 将使用此值创建账户 —— 更新 sidecar + 重启
PP_TSE_PASSWORD时序引擎账户更新 sidecar + 重启
PP_GRAVITINO_PASSWORD · PP_KESTRA_DB_PASSWORD各自的 PostgreSQL 后端账户数据湖在每次启动时，会将 PostgreSQL 角色密码调整为 sidecar 中的值 —— 更新 sidecar + 重启
PP_KESTRA_ADMIN_PASSWORDKestra 管理员Web 界面登录账户
PP_TLS_KEYSTORE_PASSWORD （+ truststore 派生集）证书整体与证书重新签发相关 → 安全设置
PP_OPCUA_PASSWORDOPC-UA 服务器（应用容器）数据湖外部
PP_API_KEY · PP_FLOW_WEBHOOK_API_KEY供外部调用者使用（应用容器）数据湖外部
PP_DATA_GATEWAY_WEB_PASSWORD · PP_CEP_WEB_PASSWORD查询控制台浏览器登录已决定不进行轮换（2026-09-07）。更新 sidecar + 重启 → Web 界面登录账户

不要这样做​

  • 不要在容器内部直接执行 pd secret rotate。 轮换日志和 sidecar 必须位于主机上才能在容器重建后存活。主机上的 passwd.sh 是调用它的工具。
  • 不要期望修改 bin/env.sh 中的密码默认值后会生效。 sidecar 会覆盖它。
  • 不要将 --list --show 输出粘贴到工单或聊天中。
  • 不要在轮换过程中通过 Ctrl+C 中断并用其他值重新开始。 日志会记录第一个值。请使用相同的值重新执行以完成，然后再进行后续更改。

相关文档​