跳到主要内容

更改密码 · API 密钥

PlantPulse AI 使用图存储(Neo4j)账户以及连接内部服务的若干 API 密钥。 自 2026.09 起，内部 API 密钥由安装器在每次安装时新建(仅当仍为占位符时)。2026.10 起，存储凭据加密密钥两个(PI_COPILOT_SECRET_KEY · PI_DT_SECRET_KEY)也会在首次安装时一并生成。Neo4j 密码不会自动生成，需在安装时手动填入(若留着占位符，START=1 会拒绝启动)。 此后，只要怀疑泄露或人员变更，就按本文档操作更改。

更改所用的工具只有一个：bin/passwd.sh。platform · ai · studio 三款产品都以同样的名称、 同样的用法提供该工具。

配置的唯一真本是 /etc/kopens/plantpulse-ai.env

该产品的机密保存在 /etc/kopens/plantpulse-ai.env 中。它不在安装目录内，而是 位于 repo 目录树之外，权限为 0600。

🔴 请勿修改 compose/.env。 没有人读取它——栈不会因此改变。

passwd.sh 写入的文件与启动栈的脚本读取的文件是同一个。 因此轮换后的值会直接生效。

这与应用账户是两回事​

请不要把两者混淆。

是什么在哪里更改
应用账户人员登录所用的账户在各应用的管理员界面中管理
基础设施 · API 密钥数据库账户、服务间认证密钥本文档 — bin/passwd.sh

本文档只讨论下文中的基础设施凭据。

可以更改哪些内容​

先看一下列表。不带任何参数运行也是一样的。

cd /opt/kopens/plantpulse-ai-docker
bin/passwd.sh --list

密钥 · ID · 当前值(仅前 3 个字符) · 对象 · 该值所在位置会一并显示。 若需查看完整值，使用 --list --show。

密钥内容如何改变
PI_NEO4J_PASSWORDNeo4j — LightRAG 知识图谱与工厂图镜像，两个实例服务器账户是真本 —— 需在两个实例上都执行 ALTER USER (cypher-shell)
PI_RAG_API_KEYRAG API 密钥 — copliot-web · lightrag · rag-api 共用文件
PI_VLLM_API_KEYvLLM API 密钥 — lightrag · insight-api 共用文件
PI_LLM_API_KEYLiteLLM 主密钥文件
PI_LITELLM_SALT_KEYLiteLLM 盐密钥 — 🔴 请勿轮换(见下文)文件
PI_INBOUND_API_KEY后端入站密钥 — rag · insight · parser · vision · 数字线程接收此密钥(为空时这五者将拒绝启动)，copilot · 管理控制台后端也以同一值调用文件

密钥名称与环境变量名称完全一致。 不存在 neo4j 或 rag 之类的别名——若设置别名， 就必须另外维护一张连接名称与变量的对照表，而那张表必然与实际情况产生偏差。

六个密钥均以 PI_ 开头

名称已统一整理过一次(2026-08-27)。没有回退机制，若传入旧名称会 被 unknown key 拒绝——与拼写错误同等对待(若存在相近名称会给出提示)。

旧名称新名称
DOCKER_NEO4J_PASSWORDPI_NEO4J_PASSWORD
RAG_API_KEYPI_RAG_API_KEY
VLLM_API_KEYPI_VLLM_API_KEY
LITELLM_MASTER_KEYPI_LLM_API_KEY
LITELLM_SALT_KEYPI_LITELLM_SALT_KEY
PP_INBOUND_API_KEYPI_INBOUND_API_KEY

在容器内部，每个服务看到的名称各不相同(CO_INBOUND_API_KEY · TS_INBOUND_API_KEY …)， 但运维人员需要操作的值只有上面六个。compose 会把一个值拆分成多个名称注入。

入站密钥 — 空值拒绝启动，占位符可通过

留空会有两重阻挡。启动前检查(bin/lint-env.sh)会因 PI_INBOUND_API_KEY is empty … 不启动整个栈， 而后端服务(rag · insight · parser · vision · 数字线程)也会在自身密钥为空时拒绝启动(以前的版本会在无认证的情况下放行)。 无认证启动的唯一途径是特意设置开发用开关 PI_INBOUND_AUTH_DISABLED=true，一旦存在密钥， 该开关会被忽略 → 环境变量设置

不过 CHANGE_ME_… 占位符本身并非空值，能通过该检查，且该字符串在所有安装中都相同。更改时 务必填入新值(建议使用 --generate)，并用 --list 确认值是否已写入。passwd.sh 在修改文件后会重新启动 整个栈，因此接收该密钥的一方与调用方会同时换成新值。

PP_* 不在本文档范围内

PP_PG_PASSWORD · PP_CASSANDRA_PASSWORD · PP_REDIS_PASSWORD 之类的 PP_* 属于平台凭据， 无法在本产品中更改(没有修改服务器端的权限)。它们不在列表中，若传入会像拼写错误一样 被拒绝。前缀表明所属方 —— PP_ = 平台，PI_ = AI。

自 2026.10 起，容器会在启动时从平台获取平台账户 · 密码 → 环境变量 设置。因此在平台侧更改 bin/passwd.sh 后， 只需重启 AI 的对应容器(bin/restart.sh)即可获取新值。启动前数据库预配置等主机脚本 也会在每次执行时从平台获取，因此 AI 侧没有需要修改的地方 —— 主机 env 中不存在平台账户 · 密码这一行。 若旧版安装中仍残留 PP_PG_* · PP_CASSANDRA_* · PP_REDIS_PASSWORD 这几行，系统不会读取它们， 启动前检查会提示应将其删除。

在主机 env 中仍保留的平台机密只有两项：PP_DATALAKE_ADMIN_API_KEY(用于获取凭据的密钥)与 PP_API_TOKEN(平台 V5 API)。 若该值在平台侧发生变更，请手动同步 /etc/kopens/plantpulse-ai.env 中的对应行，并用 bin/restart.sh 重新创建。

人员登录账户同样不在本文档范围内

管理控制台(PI_ADMIN_USER · PI_ADMIN_PASSWORD)与 LiteLLM 管理界面(PI_LITELLM_UI_USERNAME · PI_LITELLM_UI_PASSWORD)不在 passwd.sh 列表中。请修改环境文件后用 bin/up.sh 重新 创建 → 更改初始密码

更改方法​

省略值、改用提示输入是推荐路径。 密码不会留在 ps 输出或 shell 历史记录中。系统会要求输入两次以确认一致。

bin/passwd.sh PI_INBOUND_API_KEY

也可以将值直接作为参数传入。

bin/passwd.sh PI_RAG_API_KEY=<new-value>

一次性传入多个密钥时，重启只会发生一次。 调试(commissioning)阶段建议使用这种形式。

bin/passwd.sh PI_VLLM_API_KEY=<new-value> PI_LLM_API_KEY=<new-value>

让工具自动生成值 — --generate​

对于无需人工指定值的密钥，最安全的做法是让工具自动生成。由于无需手动输入， 不会留在 shell 历史记录或 ps 中，且生成规则与安装器完全相同(长度 · 系列前缀)。

bin/passwd.sh --generate PI_INBOUND_API_KEY PI_RAG_API_KEY

生成的值会表明自己属于哪个系列的密钥。即便日志或配置界面只显示片段， 也能一眼看出是什么，也能及时发现粘贴到了错误的位置。前缀本身不是机密， 其后的随机部分长度不会因此缩短。

密钥前缀
PI_INBOUND_API_KEYppin_
PI_VLLM_API_KEYppvl_
PI_RAG_API_KEYpprg_
PI_LLM_API_KEYsk-pplm_
PI_ADMIN_SESSION_SECRETppss_ (仅安装器会生成 —— 不在 passwd.sh 列表中)

有些密钥 --generate 会拒绝生成。

  • PI_LITELLM_SALT_KEY — 这不是密钥而是盐值(见下文)
  • PI_NEO4J_PASSWORD 等没有生成规则的密钥 —— 需直接给定值或通过提示输入
  • PI_ADMIN_PASSWORD · PP_* —— 必须与人员实际登录使用的值，或平台指定的值一致
  • PI_COPILOT_SECRET_KEY · PI_DT_SECRET_KEY —— 不在列表中。随机替换等同于丢弃已存储的值 (详见下文「存储凭据加密密钥」)

若只想查看将发生哪些更改而不做任何实际修改，请使用 --dry-run。

bin/passwd.sh --dry-run PI_RAG_API_KEY=<new-value>

执行后会先显示将要更改的项目及其影响，再通过 [y/N] 请求确认。若要在自动化流程中 跳过确认，请使用 --yes。

非交互环境下不能省略值

在脚本 · cron 等没有终端的环境中若省略值，就无法弹出提示，会以错误结束。 此时请以 KEY=<value> 的形式传入。

PI_LITELLM_SALT_KEY 一旦轮换会«悄无声息地»损坏

该值是用于在网关数据库中加密管理控制台模型注册界面所填入的外部提供商 API 密钥的密钥。 即使更改它，也不会重新加密已存储的内容——容器仍会显示为 healthy，模型 列表也照常存在，但这些模型的调用会失败。 passwd.sh 在尝试更改此密钥时，会在确认前 弹出警告。请在安装时一次性确定，并将其纳入备份对象。

执行后会发生什么​

顺序是固定的。

顺序执行内容
1先处理以服务器账户为真本的部分 —— 若为 PI_NEO4J_PASSWORD，需先在 Neo4j 两个实例上都更改账户。更改前会先确认两边都能用当前值登录，若有一方无法登录，则不做任何更改并停止
2将 /etc/kopens/plantpulse-ai.env 更新为新值(保持权限 0600)
3docker compose up -d --wait —— 重新创建服务以应用新值(由于明确指定了 compose 文件与环境文件，无论在哪个目录下执行结果都相同)

顺序是先改服务器端，再同步文件。若反过来做，则服务器端仍为旧值而文件已是新值， 在重启之前认证会一直处于损坏状态。

在此期间 AI 的调用路径会中断。 请在维护窗口内执行。

若中途失败​

位置状态处理方式
第1步 (Neo4j 账户更改)不会修改文件，直接中止。若第一个实例已更改而第二个失败，会打印已更改的实例名称用 bin/status.sh 确认 plantpulse-neo4j · plantpulse-digital-thread-neo4j 是否正常运行。若只有一侧已更改，先将其恢复为旧值(ALTER CURRENT USER)后再重新执行
第3步 (重启)文件已经是新值用 bin/status.sh 确认状态，并处理启动失败的原因

存储凭据加密密钥 —— 通过 _PREVIOUS 进行替换​

PI_COPILOT_SECRET_KEY(copilot) · PI_DT_SECRET_KEY(数字线程连接器注册表)是用于将界面中填入的 凭据(外部连接器认证值 · LLM 密钥 · SMTP 密码 · Slack webhook · Web Push 私钥、连接器凭据) 封存到数据库中的密钥。不在 passwd.sh 列表中 —— 因为仅填入新值，无法解开用旧值封存的内容。 替换需通过同时提供旧值，使其«重新封存»的流程完成。

顺序执行内容
1将旧值放入 PI_COPILOT_SECRET_KEY_PREVIOUS(可用逗号分隔多个)，新值(openssl rand -base64 32)放入 PI_COPILOT_SECRET_KEY
2bin/restart.sh plantpulse-copilot-web —— 启动时会用新密钥重新封存已存储的值。可通过日志中的 [SECRETS] sealed at rest … 查看数量
3清空 PI_COPILOT_SECRET_KEY_PREVIOUS 后再重新创建一次

PI_DT_SECRET_KEY 也是同样处理 —— 将旧值放入 PI_DT_SECRET_KEY_PREVIOUS，重新创建 plantpulse-digital-thread-api 后再清空。

不带旧值更改会导致 copilot 无法启动

密钥已更改却没有旧值时，copilot 会以 Stored secrets cannot be decrypted 为由拒绝启动， 并在日志中打印被封存的行及清空它们所需的 SQL —— 不会悄无声息地以无认证方式调用。若密钥已丢失， 唯一的办法就是在界面中重新填入那些凭据。请确认 env 文件备份中是否包含这两个值。

确认​

bin/passwd.sh --list

若当前值前 3 个字符发生了变化，说明已生效。之所以保留前 3 个字符， 是为了一眼看出默认值是否仍未改变。

相关文档​