跳到主要内容

密码 · API 密钥变更

PlantPulse AI 使用几个 API 密钥来连接图形存储(Neo4j)账户和内部服务。 初始值在所有安装中都相同,因此在调试时变更一次即可。此后不需要再改动。

变更工具只有 bin/passwd.sh 一个。Platform · AI · Studio 三个产品使用相同的名称、相同的用法。

配置的唯一来源是 /etc/kopens/plantpulse-ai.env

本产品的机密存储在**/etc/kopens/plantpulse-ai.env。它不在安装目录内,而是在repo 树之外**,权限为 0600。

compose/.env 是旧路径。现在没有任何东西会读取它 — 修改这里不会改变堆栈。

在 2026-08-16 之前,passwd.sh 写入 /etc/kopens/plantpulse-ai.env,但启动堆栈的 10 个脚本都在读取 compose/.env。因此轮转悄然失效,passwd.sh 报告成功,但服务仍然使用旧密钥运行。现在读取和写入使用同一个文件。不要再写入旧路径。

与应用账户是两回事​

不要混淆这两种情况。

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

本文档仅涉及下文的基础设施凭证。

可以变更什么​

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

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

密钥、标识符、当前值(仅前 3 个字符)、目标以及该值存储在何处一起显示。 如需查看完整值,请使用 --list --show。

密钥说明如何变更
DOCKER_NEO4J_PASSWORDNeo4j(图形存储)服务器账户是主副本 — ALTER USER (cypher-shell)
RAG_API_KEYRAG API 密钥 — copliot-web · lightrag · rag-api 共用文件
VLLM_API_KEYvLLM API 密钥 — lightrag · insight-api 共用文件
LITELLM_MASTER_KEYLiteLLM 主密钥文件
LITELLM_SALT_KEYLiteLLM 盐值密钥文件
PP_INBOUND_API_KEY后端入站密钥 — rag · insight · parser · vision 共用文件

密钥名称就是环境变量的名称。 没有 neo4j 或 rag 这样的别名 — 如果使用别名,就需要单独维护名称和变量的映射表,这样的映射表必然会与实际不符。

不要将 PP_INBOUND_API_KEY 留空

后端的四个服务(rag · insight · parser · vision)如果此密钥为空,会跳过认证。 删除值相当于解锁。变更时必须输入新值,并使用 --list 验证值已生效。

DOCKER_PLATFORM_* 此处不可用

它是平台仓库凭证的副本,无法在本产品中变更(您没有权限更改服务器端)。不在列表中,并且如果传入会像拼写错误一样被拒绝。请先用平台的 bin/passwd.sh 变更,然后更新本产品的值以匹配。

变更步骤​

推荐的做法是省略值并通过提示符输入。 密码不会ps出现或保留在 shell 历史中。系统会提示两次输入,以验证两次输入一致。

bin/passwd.sh PP_INBOUND_API_KEY

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

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

一次传递多个时,重启会合并为一次。 调试时使用此形式。

bin/passwd.sh VLLM_API_KEY=<new-value> LITELLM_MASTER_KEY=<new-value>

仅查看要变更的内容而不进行任何更改,请使用 --dry-run。

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

执行后会先显示要变更的项目和影响,然后通过 [y/N] 请求确认。在自动化中要跳过确认,请使用 --yes。

非交互模式下不能省略值

在没有终端的环境(如脚本、cron)中,如果省略值,将无法显示提示符,会导致错误。此时使用 KEY=<value> 格式传递。

执行时发生什么​

执行顺序是固定的。

顺序操作
1从服务器账户是主副本开始 — 如果DOCKER_NEO4J_PASSWORD,首先在 Neo4j 内变更账户
2使用新值更新 /etc/kopens/plantpulse-ai.env(保持权限 0600)
3docker compose up -d --wait — 重新创建服务以应用新值

先变更服务器端,再同步文件的顺序。反过来做会导致服务器使用旧值,文件使用新值,直到重启前认证处于断裂状态。

此期间 AI 路径会断开。 请在巡检时段执行。

中途失败时​

阶段状态处理方法
第 1 阶段(Neo4j 账户变更)不修改文件,中止用 bin/status.sh 检查 neo4j 是否在运行,然后重新执行
第 3 阶段(重启)文件已是新值用 bin/status.sh 检查状态并处理启动失败的原因

验证​

bin/passwd.sh --list

如果当前值的前 3 个字符已变更,说明已生效。保留前 3 个字符是为了一眼看出默认值是否仍在使用。

相关文档​