秘密管理

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 中的值。不使用的功能的密钥可以留空。

环境变量	用途	何时需要	缺失时
`PLATFORM_API_KEY`	PlantPulse 平台服务密钥	查询实际数据（站点·设备·标签·报警）的全部场景	聊天查询·已部署应用中无法查询到实际数据
`ANTHROPIC_API_KEY`	Anthropic 密钥	AI 提供商为 anthropic 时	智能体无法实际运行（返回桩响应）
`OPENAI_API_KEY`	OpenAI 密钥	AI 提供商为 openai 时	〃
`AI_API_KEY`	OpenAI 兼容网关密钥	使用企业内部 AI 网关时	〃
`GIT_TOKEN`	远程 Git 访问令牌（PAT）	将应用源码推送到客户方 GitLab/GitHub 时	仅无法使用 Git 推送功能
`APP_REGISTRY_TOKEN`	应用镜像仓库令牌	将已部署应用推送为 Docker 镜像时	仅无法使用镜像推送功能

AI 密钥三选一

只需在环境设置 → AI 标签页中选定的提供商对应的一个密钥即可。如果现场使用企业内部网关（OpenAI 兼容），则为 AI_API_KEY。

填入密钥

sudo vi /etc/kopens/plantpulse-studio.env

# ── 비밀(키·토큰) — 환경변수 전용 ─────────────────────────
PLATFORM_API_KEY=...
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=
# AI_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 pp-studio-server 不会重新读取 .env。 它只会带着容器创建时注入的旧环境变量原样重启。这是修改密钥后反复排查"为什么还是没变"的典型陷阱。

必须重新创建容器。

bash bin/restart.sh
# 또는
docker compose up -d --force-recreate

放入 .env 并不意味着会进入容器

传递给容器的仅是 docker-compose.yml 中 environment: 列表所列的变量。上述 6 种已经预先接好线，但如果新增了表中没有的变量，也需要一并添加到 compose 中。（曾发生因遗漏传递导致 AI 处于未激活状态的实际案例。）

确认是否生效

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

在界面上，如果环境设置 → AI / 平台标签页中的密钥输入框变为禁用，并显示**"由环境变量管理中"**，则说明正常。

优先级与现有安装迁移

优先级	来源	备注
1	环境变量（`/etc/kopens/plantpulse-studio.env`）	只要有值，这里必定优先
2	`settings.json`	旧版回退——用于兼容旧安装

即使升级，现有安装也不会突然崩溃。但如果文件中仍留有秘密，启动日志会告知需要迁移的对象（日志中绝不会留下值本身，只会显示应将哪个项目迁移到哪个环境变量）。

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

迁移步骤共分三步。

将对应值迁移到 /etc/kopens/plantpulse-studio.env 中相应的环境变量
bash bin/restart.sh
在环境设置界面确认该项目已变为"由环境变量管理中"后，在 settings.json 中删除旧值 → 启动警告随之消失

settings.json 位置

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

密钥更换（轮换）

ANTHROPIC_API_KEY · AI_API_KEY 有专用工具。 可以一次性完成文件更新与容器重建，且值不会残留在 shell 历史记录中。

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

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

其余密钥（PLATFORM_API_KEY · 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 · 镜像仓库）吊销该密钥并重新申请新密钥，然后执行上述"密钥更换"流程。在服务器重启之前，旧密钥仍会残留在内存中。

六种秘密——什么、何时​

填入密钥​

确认是否生效​

优先级与现有安装迁移​

密钥更换（轮换）​

自动应用的保护措施​

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

应遵守的事项​

相关文档​