跳到主要内容

密钥管理

API 密钥和令牌仅存放在环境变量文件中。因为配置文件(settings.json)是明文， 一旦文件泄露，密钥也会直接暴露。

此原则自 2026.07 版本起生效，现有安装也照常运行（请参阅下文“现有安装迁移”）。

配置正本只有 /etc/kopens/plantpulse-studio.env 一个

环境变量文件的路径是 /etc/kopens/plantpulse-studio.env 。它不在安装目录 (/opt/kopens/plantpulse-studio-docker)内，而是在 repo 树之外，权限为 0600 。platform · ai · studio 三个产品遵循相同约定，使用 /etc/kopens/plantpulse-<product>.env 。

安装目录根目录下的 .env 是旧路径。现在谁也不会读取它，所以即使修改那里， 堆栈也不会改变。即使旧文件残留，迁移后也仅用于对照。

六个密钥 — 是什么，何时需要​

这些是放入 .env 的值。不使用某项功能的密钥，可以留空。

环境变量用途何时需要若无
PP_API_TOKENPlantPulse 平台服务密钥一般用于查询实际数据（站点·设备·标签·报警）🔴 若为空，则拒绝启动
PI_LLM_API_KEYOpenAI 兼容网关密钥使用内部 AI 网关时（默认路径）🔴 若为空，则拒绝启动
PS_ANTHROPIC_API_KEYAnthropic 密钥当 AI 提供方为 anthropic 时代理程序实际不工作（返回桩响应）
OPENAI_API_KEYOpenAI 密钥当 AI 提供方为 openai 时同上
GIT_TOKEN远程 Git 访问令牌（PAT）将应用源码推送到客户 GitLab/GitHub 时仅 Git 推送功能不可用
APP_REGISTRY_TOKEN应用镜像仓库令牌将已部署的应用推送为 Docker 镜像时仅镜像推送功能不可用
与容器内部看到的名字不同

在日志和源代码中显示为 PLATFORM_API_KEY · AI_API_KEY · ANTHROPIC_API_KEY， 但写入 .env 的名称是上述这些。对照表见 环境变量参考 中的“两层名称”。

AI 密钥仅需三个中的一个

只需在环境设置 → AI 选项卡中选择的提供方相对应的一个密钥即可。 如果使用内部网关（OpenAI 兼容）的现场，则为 PI_LLM_API_KEY 。

配置密钥​

sudo vi /etc/kopens/plantpulse-studio.env
# ── 비밀(키·토큰) — 환경변수 전용 ─────────────────────────
PP_API_TOKEN=...
PI_LLM_API_KEY=...
# PS_ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=
# GIT_TOKEN=
# APP_REGISTRY_TOKEN=
sudo chmod 600 /etc/kopens/plantpulse-studio.env
cd /opt/kopens/plantpulse-studio-docker && bash bin/restart.sh
通过 docker restart 无法更改密钥

docker restart plantpulse-studio-server 不会重新读取 .env。 它只会保留创建容器时 注入的旧环境变量并重启。这是更改密钥后，花费很长时间排查“为什么没变”的典型案例。

必须重新创建容器。

bash bin/restart.sh
# 또는
docker compose up -d --force-recreate
放入 .env 并不代表会进入容器

传递给容器的仅是 docker-compose.yml 的 environment: 列表中注明的变量。 上述 6 种已经预先配置好，但如果新增了表中没有的变量，则需要在 compose 中一同 添加。（确实发生过因传递遗漏导致 AI 显示为禁用状态的实际案例。）

确认生效​

# 서버가 인식한 키 출처 확인 — 부팅 로그
docker logs plantpulse-studio-server 2>&1 | head -40

在界面上，环境设置 → AI / 平台 选项卡的密钥输入框中会出现 환경변수 기본값 徽章， 并且空白框中显示 “正在使用环境变量值 — 输入后覆盖” 即为正常。 输入框本身不会被锁定 — 环境变量是默认值，可在界面上覆盖。

优先级与现有安装迁移​

优先级来源备注
1在界面上输入的值（settings.json）如果有值，则以此为准
2环境变量（/etc/kopens/plantpulse-studio.env）安装植入的默认值
2026-08-23 起此顺序被«反转»了

此前是环境变量优先。这导致 如果在 env 中残留一个失效密钥，无论环境设置界面 输入什么都会被忽略，并且无法通过界面解决。AI 提供方需要能够随时切换的要求 促成了此顺序的改变。

因此，当密钥失效时无需登录服务器 — 在环境设置界面输入新值 即可立即覆盖。如果您记得旧顺序，请在此处更改。

代价是 settings.json 为明文（服务器强制使用 0600 权限，备份 归档也使用 600/700）。如果您不想在文件中保存密钥，请将界面留空并仅使用环境变量 — 这样行为与以前完全相同。

即使升级，现有安装也不会突然崩溃。但如果文件中残留密钥，启动 日志会告知应该迁移的目标（值绝对不会出现在日志中，仅显示哪些项目需要迁移到哪个环境变量）。

settings.json 에 비밀이 남아 있습니다 — … platform.apiKey → PLATFORM_API_KEY

迁移步骤如下三步。

  1. 将该值移到 /etc/kopens/plantpulse-studio.env 对应的环境变量
  2. bash bin/restart.sh
  3. 在环境设置界面确认该项目的徽章变为 환경변수 기본값 后， 在 settings.json 中删除旧值 → 启动警告消失
settings.json 位置

<DATA_ROOT>/state/settings.json （默认 /var/lib/pp-studio/state/settings.json）。 建议编辑前备份，编辑后需要重启。

密钥更换（轮换）​

Anthropic 密钥和网关密钥有专用工具。 可一次性完成文件更新和容器 重建，且值不会保留在 shell 历史记录中。

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh                    # ① 되돌릴 지점 확보
bin/passwd.sh PS_ANTHROPIC_API_KEY    # ② 값 생략 → 프롬프트로 입력
bash bin/status.sh                    # ③ 헬스 확인

详细用法见 密码 · API 密钥更改。

其余密钥（PP_API_TOKEN · OPENAI_API_KEY · GIT_TOKEN · APP_REGISTRY_TOKEN） 不在工具范围内，需要直接修改文件。

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh                              # ① 되돌릴 지점 확보
sudo vi /etc/kopens/plantpulse-studio.env       # ② 새 키로 교체
bash bin/restart.sh                             # ③ 컨테이너 재생성
bash bin/status.sh                              # ④ 헬스 확인

更换后，通过一次聊天查询（确认平台密钥）和一次应用构建（确认 AI 密钥）来确认实际工作 是比较稳妥的方法。

自动应用的保护​

项目行为
文件权限服务器每次启动时强制设置 settings.json · 环境变量文件为 0600，状态目录为 0700
审计日志更改环境设置时记录被更改的字段 — 密钥只记录指纹（哈希前 8 位）而非值
界面由环境变量管理的密钥输入被禁用，防止误覆盖
密钥代理平台密钥只存在于服务器内部，仅附加到已登录用户的请求中（不附加到匿名请求）

例外 — MCP 外部服务器令牌​

在环境设置 → MCP 选项卡中由用户任意添加的外部 MCP 服务器的令牌，由于数量可变，无法用环境变量表达，因此存储在 settings.json 中。 （其敏感度低于平台/AI 密钥。）

必须遵守的事项​

禁止事项
  • 不要将环境变量文件 · settings.json 提交到版本控制（Git）。将正本放在 repo 树之外（/etc/kopens/）正是出于此原因。
  • 不要将密钥粘贴到聊天、电子邮件、工单正文中。
  • 不要未经授权共享备份归档 — 请参阅 备份与恢复 中的处理注意事项。
如果怀疑已泄露

请先在签发机构（平台 · AI 提供方 · Git · 仓库）作废并签发新密钥， 然后执行上述“密钥更换”流程。服务器重启前，旧密钥仍保留在内存中。

相关文档​