跳到主要内容

环境变量参考

以下是 Studio 服务器读取的全部环境变量。与在界面（环境设置）中修改的值不同， 这里的值需要修改文件并重启后才能生效。

权威文件是 /etc/kopens/plantpulse-studio.env​

/etc/kopens/plantpulse-studio.env
不再读取存储库根目录下的 .env

即使将值设置在旧路径（安装目录下的 .env）中，也不会生效。如果旧文件仍然存在， 脚本会提示这一情况。修改值时请使用上述权威文件路径。

请将权限设置为 chmod 600 ——此文件包含 API 密钥。

镜像与版本​

变量默认值说明
REGISTRYdocker.kopens.io/ps拉取镜像的注册表。留空则仅使用本地标签（适用于自行构建的情况）
PP_IMAGE_TAG(空值)我们镜像集（server · web）的日历标签
PS_IMAGE_TAG_SERVER(无)仅当希望 plantpulse-studio-server 使用不同标签时
PS_IMAGE_TAG_WEB(无)仅当希望 plantpulse-studio-web 使用不同标签时
PS_IMAGE_TAG_AGENT_SERVER0c5ac7fb代理边车。由于是摘要指纹而非日历标签（OpenHands SDK v1.43.1），因此不跟随 PP_IMAGE_TAG
建议将 PP_IMAGE_TAG 留空

留空则 bin/start.sh 会读取 VERSION 文件中的日历标签，随每次发布自动更新。 如果在此手动指定月份，该值会被固定——实际上，确实曾经因此出现了一个月前的镜像。

如果必须固定到某个时间点，请使用快照标签（2026.09-20260911），而不是月份（2026.09）。 不要用 date +%Y.%m 进行计算——在每月1日 00:00~04:00 KST 期间，它指向的会是尚不存在的标签（该月发布在 04:00 上线）。

没有名为 TAG · AGENT_SERVER_TAG 的变量

compose 只读取上表所列的名称。如果写成了 TAG=2026.08 这样的形式，将不会有任何作用，堆栈会以 VERSION 的日历标签启动——你会在以为已固定的情况下，实际在跟随更新。

若需固定在特定发布版本，请使用快照标签——例如：TAG=2026.08-20260810。 :::

区域设置与时区​

使用与 Platform·Edge 相同的变量名。

变量默认值说明
PP_LANGenWeb 默认语言（ko / en）。浏览器中存储的值优先
PP_TZAsia/SeoulIANA 时区 ID。用于解析“今天/昨天”等相对时间时

如果是韩语环境，请设置为 PP_LANG=ko。

数据存储位置​

变量默认值说明
DATA_ROOT/var/lib/pp-studio工作区 · 构建产物 · 状态均保存在此路径下

备份对象即此路径 → 备份与恢复。

数据库 — 外部 PostgreSQL​

Studio 使用外部 PostgreSQL。 可以共用 Platform 所使用的同一个 PG。

变量示例
DATABASE_URLpostgres://<user>:<password>@<db-host>:5432/ppstudio

🔴 不存在名为 PG_PASSWORD 的变量。 数据库密码包含在 DATABASE_URL 同一行内——如果为密码单独设置变量，可能和 URL 不一致，因此将其合并为一行。

DATABASE_URL 是必需的

如果为空，安装会立即停止，并提示具体缺失项——不会捏造一个看似合理的默认值。

必须先创建数据库和角色

服务器只对已存在的数据库执行迁移。它不会创建数据库和角色——这项工作由 bin/provision-platform-db.sh 负责。 请参见安装中的“数据库准备”部分。

平台集成​

变量说明
PP_API_URL委托实际数据查询和登录认证的平台地址
PP_API_TOKEN该平台的 api_key
容器内名称不同

在日志或容器内部，会显示为 PLATFORM_API_TARGET · PLATFORM_API_KEY。 写入 .env 时的名称是 PP_API_URL · PP_API_TOKEN ——请参见下方“两层名称”。

监听端口​

变量默认值说明
PORT5170Studio 服务器（编排器）的 API 端口。由于 Web 在内部代理，无需对外暴露 ——用于诊断（curl localhost:5170/health）
APPS_PORT5171用于提供预览和已部署应用的独立监听端口
  • 通过端口直接访问的安装 — 必须在防火墙中开放此端口，预览、部署应用和 QR 访问才可用。
  • 位于反向代理后面 — 无需开放。代理会将同一域名下的 /container、/preview · /apps 转发到此监听器 → 域名与反向代理。
不指定应用 Origin

客户端仅使用相对路径。无需另行告知预览和部署应用的公开 URL，因此在仅开放 80/443 的配置下也能正常运行。

AI 提供商​

这里的值是初始值。在界面（环境设置 → AI）中设置的值会覆盖此值。

变量默认值说明
AI_PROVIDERopenai-compatible留空则始终为 openai-compatible
PI_LLM_URL(空值 — 必填)网关地址。不设默认值
AI_MODELgpt-4o模型名称
PI_LLM_API_KEY(空值 — 必填)OpenAI 兼容密钥
PS_ANTHROPIC_API_KEY(空值)仅在使用云端 Claude 时填写

⚠ 如果 PI_LLM_URL 和 PI_LLM_API_KEY 为空，堆栈将拒绝启动。

为何不给 PI_LLM_URL 设置看似合理的默认值

如果网关不存在于该主机，聊天会直接变成 fetch failed，而由于值看起来合理，排查原因的成本很高。 请填写实际地址。可以在保存前，通过“环境设置 → AI”选项卡中的连接测试来确认所填值是否正确 → 环境设置（管理员）。

不根据密钥推断提供商

提供商通过 AI_PROVIDER 明确指定。 如果根据密钥类型来推断，则会因 env 配置不同而无法预测实际使用哪个提供商。

CORS​

变量默认值说明
STUDIO_CORS_ORIGINS(空值 = same-origin)仅在从不同域访问时指定

安装·启动标志​

这些不是 .env，而是加在命令前面使用的参数（SKIP_DOCKER=1 bash bin/install.sh）。

变量默认值说明
SKIP_DOCKER0如果为 1，则跳过 Docker 安装步骤（当已安装时）
SKIP_WAIT0如果为 1，则不等待启动完成，脚本直接结束
WAIT_READY_MIN10等待启动完成的时间（分钟）。网络较慢或镜像较大时请增加此值

代理边车资源​

变量默认值说明
AGENT_SERVER_CPUS1分配给构建器边车的 CPU 数量
AGENT_SERVER_MEMORY2g构建器边车的内存上限

不通过 env 传递的内容​

用户账号和角色不由环境变量设定。 当服务器没有任何账号时，会在数据库中创建管理员账号，之后通过应用中的用户管理界面进行添加和删除，角色（admin / builder / viewer）也在该界面分配。

→ 更改初始密码

相关文档​

两层名称 — .env 与容器内不同​

🔴 这里是最容易出错的地方。 在日志·docker inspect·产品源码中看到的名称，和写入 .env 的名称不同。写入时使用左侧列。

写入 .env 时的名称容器内看到的名称
PP_API_URLPLATFORM_API_TARGET
PP_API_TOKENPLATFORM_API_KEY
PI_LLM_URLAI_BASE_URL
PI_LLM_API_KEYAI_API_KEY
PS_ANTHROPIC_API_KEYANTHROPIC_API_KEY

其余（DATABASE_URL · DATA_ROOT · APPS_PORT · AI_PROVIDER · AI_MODEL · STUDIO_CORS_ORIGINS）两侧名称相同。

为何要区分名称

一台服务器上会同时部署多个产品（Platform · AI · Studio）。在 .env 一侧名称中添加产品前缀（PP_ Platform · PI_ 公共基础设施 · PS_ Studio），即可仅凭名称辨识属于哪个产品的值，当两个产品共享一个值时也不会混淆。