安装

PlantPulse Studio 在客户服务器上的安装步骤。 由 4 种 Docker 容器（Web·Server·Builder Sidecar·PostgreSQL）组成，安装脚本自动处理从 Docker 安装到启动的全部流程。

如果是无互联网的隔离网络，请改看 气隙安装。

---

1. 前置要求

服务器配置

项目	最低	推荐	备注
CPU	4 核	8 核以上	每个应用会话会运行构建
内存	8 GB	16 GB 以上	详见下表
磁盘	50 GB 余量	100 GB 以上	容器镜像约 6 GB
OS	Linux (x86_64)	RHEL 9 / Rocky 9 / Ubuntu 22.04 以上	systemd + Docker 即可

内存计算依据——堆栈固定预留的上限值。

容器	内存上限
studio-server（编排器）	2 GB
agent-server（Builder Sidecar）	2 GB
studio-web（nginx）	256 MB
postgres（捆绑模式）	无限制（实际用量数百 MB）
每个应用会话容器	2 GB

应用会话容器在用户打开项目时逐个启动，30 分钟未使用后自动回收。请根据并发工作人数每人加 2 GB。

并发 3~5 用户的目标

以 16 GB 内存·8 核·100 GB 磁盘为基准，配置会很宽松。

软件

• Docker Engine + Docker Compose v2（v2.22 以上） 如未安装，一键安装脚本会自动安装。
• curl、tar（大多数发行版已默认包含）

端口和防火墙

堆栈使用 host 网络运行。即容器端口直接开放在主机上，访问控制仅通过服务器防火墙进行。

端口	用途	防火墙
80	Studio UI（nginx）	开放
5171	应用监听器——预览·部署应用·二维码访问	开放（必需）
5170	Studio API	Web 内部代理——无需开放（诊断用）
5432	PostgreSQL（捆绑模式）	127.0.0.1 仅绑定——禁止开放
8000	Builder Sidecar（agent-server）	环回专用——绝对禁止开放
5172	MCP 工具网桥	环回专用——绝对禁止开放

屏蔽 5171 会导致预览和部署应用无法打开

预览（/preview/…）和部署应用（/apps/…）因安全边界需要，在与 Studio 不同的源 （默认 5171 端口）上提供。这样可以防止通过聊天生成的应用 JavaScript 访问 Studio 登录令牌。不开放 5171 会导致界面空白。

8000·5172 无认证

这两个端口仅供内部组件间通信，无认证机制。如果暴露，任何人都可以读写所有用户的工作区。堆栈默认仅绑定环回地址，但防火墙也务必禁止开放。

注册表访问

镜像从 KOPENS 注册表（docker.kopens.io）获取。安装前请先登录一次。 账户由 KOPENS 运营团队发放。

docker login docker.kopens.io

---

2. 数据库选择

安装前选择以下之一。之后也可更改，但需要数据迁移。

=== "（A）捆绑 PostgreSQL——默认"

堆栈同时启动 PostgreSQL 容器。这是无独立 DB 服务器的现场的默认做法。

COMPOSE_PROFILES=bundled-pg
PG_DB=ppstudio
PG_USER=ppstudio
PG_PASSWORD=`<long-random-string>`

数据存储在 DATA_ROOT/postgres 下。

=== "（B）外部/共用 PostgreSQL"

如果现场已有 PlantPulse 平台用的 PostgreSQL，可以消除重复的基础设施。 删除 COMPOSE_PROFILES 这一行，仅指定连接 URL，PostgreSQL 容器将不会启动。

# 删除 COMPOSE_PROFILES 这一行
DATABASE_URL=postgres://`<user>`:`<password>`@`<db-host>`:5432/`<db-name>`

仅需准备一个空数据库——表会在服务器首次启动时自动创建。

PG 密码初期请保持一致

在捆绑模式中，数据累积后若仅修改 PG_PASSWORD，会与现有数据目录的账户不匹配，导致堆栈无法启动。如需修改密码，应先在 PostgreSQL 内部更改账户密码。

---

3. 安装（一键·推荐）

以 root 身份登录服务器并执行一行命令。脚本会完成 Docker 检查·安装→下载包→ 生成 .env→启动堆栈。

curl -fsSL https://product.kopens.io/plantpulse-studio/install.sh | sudo bash

安装位置为 /opt/kopens/plantpulse-studio-docker，之后所有运维命令都在该目录执行。

预先设定值进行无人值守安装

环境变量必须 附加在 bash 前面，才能通过管道传递。

curl -fsSL https://product.kopens.io/plantpulse-studio/install.sh \
  | sudo PLATFORM_API_TARGET=https://192.168.0.41 \
         DATA_ROOT=/data1/pp-studio \
         ANTHROPIC_API_KEY=sk-ant-... \
         bash

让系统询问各项值

curl -fsSL https://product.kopens.io/plantpulse-studio/install.sh | sudo INTERACTIVE=1 bash

每个空字段都会出现提示符（数据根路径·PG 密码·平台地址·管理员账户等）。

重新运行也是安全的

在同一服务器上重新运行安装脚本，仅会更新代码，.env 和本地备份（dist/）会保留。可直接用于升级。

若安装脚本返回 404 或旧版本

可能是 CDN 缓存残留。在 URL 末尾加上 ?v=$(date +%s) 重新下载。

---

4. 安装（手动）

已预先下载包或想直接编写 .env 的情况。

cd /opt/kopens/plantpulse-studio-docker
sudo cp .env.example /etc/kopens/plantpulse-studio.env
sudo vi /etc/kopens/plantpulse-studio.env   # 아래 표를 보고 값 채우기
sudo chmod 600 /etc/kopens/plantpulse-studio.env
bash bin/start.sh

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

环境变量文件不在安装目录内，而在 repo 树外的 /etc/kopens/plantpulse-studio.env。权限为 0600。platform、ai、studio 三个产品都遵循同一约定使用 /etc/kopens/plantpulse-<product>.env。

安装目录根下的 .env 是 旧路径。compose 和其他脚本现在都不再读取该文件，修改它不会改变堆栈。现有安装的 .env 会被 bin/install.sh 移动到新路径（不是新建——新建的话数据库用旧密码但 env 用新默认值，下次重启就会崩溃）。

环境变量主要项

项	说明	默认值
REGISTRY	镜像注册表。留空则仅使用本地镜像，不拉取（气隙）	docker.kopens.io/ps
TAG	镜像标签。固定特定版本时指定如 2026.08	latest
DATA_ROOT	所有数据（工作区·构建·状态·DB）的存储路径	/var/lib/pp-studio
PLATFORM_API_TARGET	PlantPulse 平台地址，用于授权和实时数据	https://192.168.0.41
APPS_PORT	应用监听器端口（预览·部署应用）	5171
PP_LANG	Web 默认语言 ko / en	en
PP_TZ	时区（IANA ID）。用于解释"今天·昨天·上周"	Asia/Seoul
STUDIO_CORS_ORIGINS	仅当从其他域名调用 API 时才指定。默认为禁用	留空
COMPOSE_PROFILES / DATABASE_URL	数据库选择——参见上面第 2 节	bundled-pg
ANTHROPIC_API_KEY 等	AI·平台密钥——详见 密钥管理	留空

账户和角色不通过环境变量传递

STUDIO_LOCAL_USERS·STUDIO_ADMINS·STUDIO_VIEWERS 已移除（2026-08-18）。 当服务器不存在任何账户时，会在 DB 中植入引导管理员，之后通过应用的 环境设置→用户管理添加·删除账户，并分配角色（管理员/构建者/查看者）。 参见下面的 7. 首次登录。

韩国现场请直接加入 PP_LANG=ko

一键安装生成的 .env 中没有 PP_LANG·PP_TZ 这两行，会使用默认值（en / Asia/Seoul）。 要用韩文启动，需要在 .env 中添加 PP_LANG=ko，然后 bash bin/restart.sh。

修改 .env 后必须执行 bin/restart.sh

docker restart 不会重新读取 .env。值不会生效，你可能会花很长时间找"为什么没变"。详见 密钥管理。

---

5. 堆栈组成检查

安装完成后应有 4 个容器运行。

容器	角色
pp-studio-web	Studio UI（nginx :80）——静态页面 + API 代理
pp-studio-server	编排器（:5170）——代理·会话·部署·应用监听器(:5171)
pp-studio-agent-server	Builder Sidecar——应用代码编写引擎
pp-studio-postgres	捆绑 PostgreSQL（若使用外部 DB 则不启动）

此外，当用户打开项目时，会逐个启动 应用会话容器，每个项目一个。 这些不属于堆栈容器，而是服务器按需创建，闲置 30 分钟后回收。

---

6. 启动验证

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh          # 컨테이너 상태 + 헬스 + 세션 컨테이너 수
curl -s localhost:5170/health

安装直后建议运行一次综合检查脚本。它会检查健康状态·Web 响应·实际登录·会话运行时镜像·容器状态，任何一项失败都会以错误结束。

bash bin/smoke-install.sh

✓ health
✓ client-config → {"lang":"ko",...}
✓ web 200
✓ 로그인(부트스트랩 계정)
✓ 세션 런타임 이미지
✓ 컨테이너 running(...)
✅ 설치 스모크 통과

会话运行时镜像

应用会话容器使用 plantpulse-studio-runtime 镜像。bin/start.sh 会自动 下载并标记，失败时会出现 ⚠️ 세션 런타임 이미지 없음 警告，项目打开会失败。 此时请检查注册表登录状态并重新运行 bash bin/start.sh。

---

7. 首次登录

在浏览器中访问 http://<server-ip>/。

当服务器首次启动且无任何账户时，会在 DB 中植入 引导管理员。

项	值
用户名	admin
密码	admin123!

启动日志中也会记录——부트스트랩 관리자 생성: admin — 로그인 후 비밀번호를 바꿀 것。

首先要更改此密码

所有安装的默认值都相同。登录后立即进入 环境设置→用户管理更改密码 （密码重置，6 字符以上）。修改环境变量文件不会生效——服务器登录时按 ①DB→②环境变量 顺序查询，DB 中有记录就停止。

登录后要做的事：

1. 环境设置→用户管理——修改引导管理员密码，创建现场用户账户， 分配角色（管理员/构建者/查看者）
2. 修改密码·API 密钥——通过 bin/passwd.sh 一次性轮换 DB 账户和 AI 密钥。仅在试运行时需一次
3. 环境设置→AI——确认 AI 提供商和密钥的连接状态
4. 环境设置→平台——确认平台地址·密钥连接状态（实时数据查询所需）

详细的界面说明见 快速开始 和 环境设置（管理员）。

8. 日常运维命令

所有命令都在安装目录（/opt/kopens/plantpulse-studio-docker）中执行。

bash bin/start.sh            # 시작(레지스트리에서 최신 이미지 pull 포함)
bash bin/stop.sh             # 중지 — 데이터는 그대로 보존, 세션 컨테이너도 정리
bash bin/restart.sh          # 재기동(.env 변경 반영)
bash bin/status.sh           # 상태 요약
bash bin/logs.sh             # 서버 로그 팔로우(기본 studio-server)
bash bin/logs.sh studio-web  # 특정 서비스 로그

仅查看会话容器，用：

docker ps --filter label=plantpulse-studio=1

---

9. 更新

bin/start.sh 会从注册表重新拉取镜像并更新。重新运行安装脚本会一并更新运维脚本（.env·备份保留）。

=== "仅更新镜像"

cd /opt/kopens/plantpulse-studio-docker
bash bin/start.sh

=== "包括脚本一起更新"

curl -fsSL https://product.kopens.io/plantpulse-studio/install.sh | sudo bash

版本固定

版本号格式为 YYYY.MM（例：2026.08）。不想自动更新的生产环境，可在 .env 中固定标签。

TAG=2026.08

更新前先备份

先运行 bash bin/backup.sh。步骤见 备份与恢复。

镜像签名验证（可选）

可验证发布的镜像是否由 KOPENS 签名。需安装 cosign。

cd /opt/kopens/plantpulse-studio-docker
bash bin/verify-images.sh

[verify] ✅ docker.kopens.io/ps/plantpulse-studio-server:2026.08
[verify] ✅ docker.kopens.io/ps/plantpulse-studio-web:2026.08
[verify] ✅ docker.kopens.io/ps/plantpulse-studio-runtime:2026.08

---

下一步

• 密钥管理——安全放置 AI 和平台密钥的方法
• 域名和反向代理——用域名·HTTPS 而非 IP 服务
• 备份与恢复——自动备份安装和恢复演练
• 故障排除——症状索引表和解决方案