跳到主要内容

密码 · API 密钥轮转

数据湖的服务账户(PostgreSQL · Cassandra · Valkey · MinIO · 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_MINIO_PASSWORD   # 여러 개를 한 번에 — 재시작 1회
bin/passwd.sh --dry-run PP_MQ_PASSWORD     # 계획만 — 아무것도 바꾸지 않는다
不要打开文件手动修改密码行

密码存在两个地方 — 服务器接受的值(PostgreSQL 账户、Cassandra role …)和客户端提交的值(配置文件 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 元存储的 PostgreSQL 账户 + Kyuubi 入站认证hive命令 — ALTER ROLE (psql) + 重新渲染
PP_CASSANDRA_PASSWORDCassandracassandra命令 — ALTER ROLE (cqlsh)
PP_REDIS_PASSWORDValkey—文件 — plantpulse-storage/cache/valkey/conf/valkey.conf
PP_MINIO_PASSWORDMinIOminio启动 env — MINIO_ROOT_PASSWORD
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 中。账户名变更需要单独的操作——服务器端 role 创建和权限转移。

如果在--list 中看不到两个管理控制台密钥

PP_DATALAKE_ADMIN_PASSWORD · PP_DATALAKE_ADMIN_API_KEY 在2026-09-05添加。之前的安装包只有 9 个密钥。此时控制台密码没有服务器端账户，只需直接修改 sidecar 并重启 → 网页控制台登录账户

程序 — 首次设置​

调试时轮转所有注册的密钥为随机值。--all 不是passwd.sh，而是轮转引擎rotate-secret.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 一起更改​

一个值既是两个代理的服务器端凭证存储，也是所有客户端的连接密码。不能单独更改，轮转工具的验证要求两者都用新值连接才算成功。

静态 JAAS 无法同时接受新旧值，在代理和消费者顺序重启期间MQ 路径会断开。不支持无中断轮转。

PP_HIVE_PASSWORD — 一个值双向使用​

Hive 元存储连接 PostgreSQL 时提交的值，同时也是客户端连接 Kyuubi 时的验证值。因此轮转工具同时进行 PostgreSQL 账户变更和配置重新渲染。手动操作时只做一个的话，元存储或 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 管理员网页控制台登录账户
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 更新 + 重启 → 网页控制台登录账户

禁止事项​

  • 不要在容器内直接修改pd secret rotate。轮转日志和 sidecar 必须在主机上，这样容器重建时才能保留。主机上的passwd.sh 会调用它。
  • 不要期望修改bin/env.sh 中的密码默认值会生效。sidecar 优先。
  • 不要把--list --show 的输出贴到工单·聊天。
  • 轮转中不要用Ctrl+C 中断，然后用不同的值重新开始。日志记住了第一个值。用相同值重新运行完成后，再进行下一次轮转。

相关文档​