跳到主要内容

安装概览

PlantPulse AI 以一套 docker compose 堆栈运行。正本是 compose/docker-compose.yml，所有运维脚本也都通过该文件来操作容器。

大多数情况下，这一行就够了
curl -fsSL https://product.kopens.io/plantpulse-ai/install.sh | sudo bash

详情请参阅一行命令安装。本页说明 什么装在哪里，以及安装脚本实际做了什么。

装在哪里​

/opt/kopens/
├── plantpulse-ai-docker/                  ← 설치 본체 (bin · compose)
├── plantpulse-ai-inference-server/        ← 형제 저장소
└── plantpulse-timeseries-insight-server/  ← 형제 저장소
两个同级仓库«必须»存在

compose/docker-compose.yml 会以相对路径 bind-mount 这两个仓库中的文件（例如网关 配置 litellm-config.yaml）。缺失时堆栈无法启动 —— 即使是 START=1，安装器也会拒绝启动并打印 缺失的仓库名。一行命令安装和隔离网络离线包会一并下载解压这三者，无需操心；但若 手动执行 git clone，就必须把三者放在同级目录下。

什么在哪里
安装主体/opt/kopens/plantpulse-ai-docker
配置·凭据正本/etc/kopens/plantpulse-ai.env (0600)
其原始模板<설치 본체>/compose/env.gb10.example（AWS g7e 为 env.g7e.example）
硬件配置文件<설치 본체>/compose/profiles/gb10.env · g7e.env —— GPU 相关部分。由主机 env 中的 PP_HW_PROFILE 选择
Docker 存储根目录/data1/docker-data（用 DOCKER_DATA_DIR 更改）

会启动什么 —— 二十五个容器​

分类容器作用
入口plantpulse-proxynginx（非 root）。接收主机的 80 · 443 和管理控制台 HTTPS（5960）并转发到内部
界面plantpulse-copilot-web · plantpulse-admin-web副驾界面 · 管理控制台（HTTP 5959）
推理plantpulse-llm · plantpulse-emb · plantpulse-rerankvLLM —— 生成 · 嵌入 · 重排序
网关plantpulse-litellm（4000）将模型调用汇聚到一处
文档plantpulse-rag-api · plantpulse-lightrag · plantpulse-docling-serve · plantpulse-document-understanding-api读取文档 · 切分 · 检索
知识plantpulse-neo4j（7474 · 7687） · plantpulse-qdrant知识图谱 · 向量索引
数字主线plantpulse-digital-thread-api（7140，不对主机开放） · plantpulse-digital-thread-neo4j工厂图谱镜像与连接器注册表 · 其专用 Neo4j（不对主机开放）
时序plantpulse-timeseries-insight-api（8970） · plantpulse-timeseries-insight-server（8980，不对主机开放）异常检测 · 预测
视觉plantpulse-vision-api图像理解
管理plantpulse-admin-api管理控制台后端
观测plantpulse-phoenix（6006，不对主机开放） · plantpulse-dcgm链路追踪 UI · GPU 指标
转录plantpulse-asr · plantpulse-asr-audio语音 → 文本（vLLM Whisper） · 将其音频库搬到卷后即结束的一次性服务。仅在启用视频 · 语音的安装（PI_MEDIA_ENABLED=true）中启动 → 视频 · 语音采集
镜像仓库plantpulse-registry · plantpulse-registry-ui隔离网络用的内部镜像存储 —— 默认启动时不会运行

默认启动的是除转录两个和镜像仓库两个之外的二十一个。启用视频 · 语音后加上转录两个，共二十三个 （plantpulse-asr-audio 完成任务后保持 «Exited (0)» 是正常的）。数字主线两个是 2026.10 新增的。

8970 和 7115 是 MCP 客户端直接连接的位置（Platform CEP 异常检测、 Claude Desktop 之类）。其余都在代理之后。

install.sh 做什么​

一行命令安装就是由 bootstrap.sh 下载仓库并执行该脚本。 判别 OS（RHEL 系 / Debian 系）后，按日志中打印的编号顺序处理。

阶段做什么主机全局
1区域设置（ko_KR.UTF-8） · 时区 —— 将 PP_TZ 的值统一确定，并把主机 OS 也调整为该时区（安装时给定的值 → env 中已有的值 → 主机时区（非 UTC 时） → Asia/Seoul）✅
2关闭 swap（同时反映到 /etc/fstab）✅
3安装 Docker CE + buildx + compose v2 插件 —— 已存在则跳过
3b安装 NVIDIA 驱动 + container toolkit，在 Docker 中注册 nvidia 运行时（为 SKIP_GPU=1 时跳过）
4/etc/docker/daemon.json 与数据目录（见下）
5OS 调优 —— chrony · limits · sysctl · tmpfiles✅
6开放防火墙 —— 仅开放 compose 实际发布的端口（SSH 22 会预先开放）。其中已被本堆栈之外的进程占用的端口会以警告打印，并提示可用于迁移的键✅
7确认内部镜像仓库登录（为 SKIP_LOGIN=1 时跳过）
8准备配置 sidecar —— 将模板复制为 /etc/kopens/plantpulse-ai.env 并填值 → 仅当 START=1 时才接收模型 · pull 镜像 · 启动

标有«主机全局»的阶段改变的不是本产品，而是整台主机的设置。 HOST_TUNING 控制这四个阶段（见下表）。

在已有其他容器运行的主机上«只打印»

未给定 HOST_TUNING 而本 compose 项目之外的容器处于 Up 状态时，默认变为 plan —— 只打印将要变更的内容，不写入任何东西。查看输出后若可以应用， 请用 HOST_TUNING=apply 重新运行。专用设备（没有其他容器）时默认为 apply。 若主机上 sysctl 已有更高的值，不会被调低。

第 4 阶段 —— 不触碰已存在的 Docker​

本主机的 Docker做什么
本次执行新安装以默认值（overlay2，DOCKER_DATA_DIR=/data1/docker-data）写入 daemon.json
原本就有存储（data-root · storage-driver）以运行中守护进程的 docker info 为正本，不重新写入。 变更内容仅打印，不重启

若要修改原有 Docker 的配置并允许重启，请给定 ALLOW_DOCKER_RECONFIGURE=1。 想使用其他 DOCKER_DATA_DIR 时同样需要它。

更改存储会让现有容器·镜像«消失»

以前当现有 daemon.json 中缺少键时会填入默认值，结果曾导致使用其他存储根目录的 主机上的容器和镜像变得不可见。因此现在默认是«不触碰»。 ALLOW_DOCKER_RECONFIGURE=1 请仅在理解其后果时使用。

默认是«准备到位为止»

未给定 START=1 时，会创建好配置文件后停止。这是为确认取值后希望自行启动的 运维人员准备的默认行为。

常用环境变量​

变量含义
START=1不在 .env 准备阶段停止，而是一直到启动 —— 此时也会自动接收模型并执行安装验证
INTERACTIVE=1对空值进行询问（默认为非交互式）
ENV_TEMPLATEsidecar 的原始模板。默认 env.gb10.example（GB10 · arm64），AWS g7e 为 env.g7e.example（amd64）。不会自动选择
ENV_TEMPLATE_SKIP_ARCH_CHECK=1模板与本机架构不一致时安装器会停止。仅在测试新硬件等有意为之的情况下跳过该检查
HOST_TUNINGskip · plan · apply —— 主机全局设置（区域设置 · 时区 · swap · chrony · limits · sysctl · tmpfiles · 防火墙）与软件包安装（Docker CE · NVIDIA 驱动/toolkit · jq）。为 skip · plan 时不安装软件包，也不注册 nvidia 运行时（不重启 Docker）—— 只打印将要做的事，并在缺之不可的阶段停止。默认为 apply；若主机上有其他容器运行则为 plan
DOCKER_DATA_DIR本次执行新安装的 Docker 的存储根目录（默认 /data1/docker-data）。原有 Docker 仍使用自己的根目录
ALLOW_DOCKER_RECONFIGURE=1允许更改并重启原有（运行中）Docker 的 daemon.json
SKIP_GPU=1跳过第 3b 阶段（NVIDIA 驱动 · toolkit 安装）—— 适用于驱动由运维团队另行管理的主机
SKIP_WAIT=1跳过 START=1 之后的«等待响应»与安装验证
WAIT_READY_MIN上述等待的上限（分钟）。默认 15
SKIP_LOGIN=1跳过内部镜像仓库登录 —— 用于隔离网络。同时跳过镜像 pull
SKIP_PULL=1在有互联网的设备上用已下载的镜像启动
INSECURE_REGISTRY将客户内部镜像仓库（HTTP）加入 daemon.json 允许列表
SKIP_PULL=1 可能«用旧构建启动»

镜像标签为 YYYY.MM，且以相同名称更新。 本地缓存的同名标签 可能是上个月的构建。若必须确保版本一致，请勿使用该选项。

会询问什么、会«生成»什么​

安装器会询问只有人或 Platform 才知道的值，而仅在堆栈内部使用的密钥由它自己生成。

值
询问TLS 证书 SAN（PP_PROXY_CERT_SAN） · 接收 Platform 凭据的地址与密钥（PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEY）—— 之后逐个询问剩余的占位符（Platform API 令牌 · 管理员密码 · Neo4j 密码等）
生成网关主密钥 · 盐 · 推理服务器密钥 · 入站密钥 · RAG 密钥 · 管理会话密钥 · 两个存储凭据加密密钥（PI_COPILOT_SECRET_KEY · PI_DT_SECRET_KEY）

询问发生在 INTERACTIVE=1 时。所询问的值都可以用同名环境变量传入 —— 按 PP_DATALAKE_ADMIN_URL=… PP_DATALAKE_ADMIN_API_KEY=… PP_API_TOKEN=… PI_ADMIN_PASSWORD=… bash 的方式给定时，安装器 只会把仍为占位符的键填成该值（2026.10 重新发布 —— 以前只接收 TLS SAN 和 Platform 凭据两个值）。 仍然剩余的部分可通过交互填入，或直接修改 /etc/kopens/plantpulse-ai.env。生成的值也 仅在为占位符时填入，不会覆盖人已填写的值。env 文件中已写入的 TLS SAN 在重新安装时也保持不变 —— 若要更改， 请显式指定 PP_PROXY_CERT_SAN=… 后运行。

不再询问 Platform 账号 · 密码（2026.10）

Platform 主机（PP_HOST）以及 Platform PG · Aster TSDB · Redis 的账号 · 密码不再询问，也不写入 env。 Platform 主机由 PP_DATALAKE_ADMIN_URL 的主机推算，账号 · 密码由容器和主机脚本 在启动时从 Platform 获取。 若本次执行传入 PP_PG_USER 之类的值，只会打印不写入 env 的警告。 信任锚 root.crt 不由安装器放置，需自行准备 → 见下文「获取 Platform 凭据 —— 启动前需准备的内容」

TLS SAN —— 把访问地址写入证书

代理的自签名证书中必须包含人实际访问时使用的地址·名称，浏览器才不会拦截。 安装器会把本主机的地址设为默认值，但 NAT 外的公网 IP · 负载均衡 VIP · 域名 在这台机器上是看不到的。交互式安装一定会询问；非交互式时只按主机地址设定并 给出警告。若通过外部名称访问，请用逗号传入多个。

curl -fsSL https://product.kopens.io/plantpulse-ai/install.sh \
  | sudo PP_PROXY_CERT_SAN=ai.example.com,203.0.113.10 bash
不会让人手敲八个密钥

让人照抄会导致出现又短又重复的值 —— 实际发生过两台主机一起照用文档中示例密钥 的情况。现在由安装器生成，运维人员只需轮换即可。

入站密钥为空则什么都起不来

安装器生成的入站密钥（PI_INBOUND_API_KEY）是 RAG · 时序洞察 · 文档理解 · 视觉 · 数字主线共同 使用的入口密钥。为空时启动前判定（bin/lint-env.sh）不会拉起堆栈，各服务也会各自拒绝启动 —— 唯一能在无密钥状态下开放启动的途径，是刻意给定开发用开关 PI_INBOUND_AUTH_DISABLED=true。若手动创建了 env， 务必填好这一行 → 环境变量配置

START=1 时发生的事 —— 还多了三件​

自 2026.09 起，启动路径会«获取 · 填充 · 验证»这些值。

阶段做什么
占位符检查🔴 若仍残留 CHANGE_ME_* 或 <PLACEHOLDER> 则停止。以前只是警告并以「安装完成」结束
Platform 凭据预检在拉取镜像前先从 Platform 获取一次凭据。若密钥错误或没有 root.crt，则以 [FATAL] [platform-credentials] … 不启动任何东西并停止。两个值为空时同样停止
模型自动接收从 model.kopens.ai 下载缺失的模型并校验 SHA256 后解包。以前这是由人工照做的步骤
等待响应等待管理控制台（:5959/health）和 RAG 入口（:7115/ping）响应，最多 WAIT_READY_MIN（15）分钟。超时则以安装失败结束。也会打印控制台 HTTPS（:5960）是否响应，但不计入失败判定
安装验证检查的不是堆栈«是否起来了»，而是«是否能工作»（见下）
值为空却一片绿的堆栈更糟

占位符未填就启动，界面看起来正常，只有功能是死的。因此 START=1 时 拒绝启动。 若只想准备，不给 START 即可（隔离网络安装仍沿用稍后填值的流程）。自 2026.10 起， 之后用 bin/up.sh 启动时也会执行相同检查 —— 若残留占位符，会打印剩余键名并拒绝启动。

「21/21 running」不等于「能工作」

曾发生过在全新安装中状态全部 running · HTTP 200，却有三处是死的 —— 这三者都能通过容器健康检查。

  • 没人下载模型，导致推理服务器不断重启
  • 网关密钥为空值，导致所有对话都是 401
  • Platform 令牌是占位符，导致 MCP 工具静默为 0 个

安装验证（bin/verify-install.sh）会检查这三项。每项检查以 OK · FAIL · 「无法测量」 作答，而无法测量的项不计为通过。

判断安装是否«正常»的四个步骤​

  1. bin/status.sh —— 21/21 running · HTTP=200（默认启动的二十一个）
  2. bin/verify-install.sh —— OK 4 · FAIL 0。只要有一项 FAIL，安装即以失败结束
  3. AI 管理控制台 › MCP 网关 › 服务器 —— Platform · 时序洞察 · 数字主线 · 工程计算等内置服务器应为正常，且工具数不为 0。 若为 0，请检查 Platform 令牌 → MCP 工具地图
  4. 用提问实际问一次 —— 曾出现 1~3 全绿但只有对话返回 401 的情况
两个已知陷阱
  • 首次启动的主机上可能需要启动两次。 如果文档解析器未在依赖等待时间内 变为健康状态，流程就会停在那里。重新拉起即可达到 21/21。
  • 🔴 直接运行 docker compose up 会回退到已部署之前的镜像。 部署只把标签绑定到那次调用， 不写入 .env（这是设计行为）。拉起时请使用提供的脚本。

获取 Platform 凭据 —— 启动前需准备的内容​

自 2026.10 起，Platform PG · Aster TSDB · Redis · RustFS 的账号 · 密码 · 端口由容器在启动时 从 Platform 获取（副驾 · 时序洞察 API · LightRAG · RAG API · 数字主线 · LiteLLM）。 compose 不传递这些值，因此若下面四项未备齐，这些容器会以 FATAL 停止。

需准备的内容来源
PP_DATALAKE_ADMIN_URLhttps://<플랫폼 호스트>:4950 —— 本主机即为 PP_HOST
PP_DATALAKE_ADMIN_API_KEYPlatform 主机 /etc/kopens/plantpulse-platform.env 中同名的那一行
Platform 允许列表🔴 AI 主机的 IP 必须在 Platform 侧的允许列表中才能获取
/etc/kopens/ca/root.crtPlatform 信任锚 —— Platform GET /api/credentials/tls 响应中的 root_pem。与同一响应中的 root_fingerprint_sha256 及指纹核对后放置
/etc/kopens/ca/CA.crt与 root.crt 内容相同。应用按此名称读取

前两个值写入 /etc/kopens/plantpulse-ai.env —— 模板中以占位符形式存在，由交互式安装询问或 通过环境变量传入。compose 会把 /etc/kopens/ca 目录整体挂载到容器中。

  • 这两个值是必填项。为空时 compose 拒绝启动；只有其中一个时容器会拒绝。
  • 主机脚本（启动前的 DB 预配置等）也用相同的两个值和 root.crt 从 Platform 获取。主机 env 中 没有 Platform 账号 · 密码。
  • 服务器证书仅用 root.crt 验证 —— 文件不存在即为 FATAL，且没有关闭验证的途径。
  • 是否获取成功通过日志查看 —— 只会打印键名和数量。
docker logs plantpulse-copilot-web 2>&1 | grep credentials:

→ 环境变量配置 · 故障排查

要使用视频 · 语音 —— 安装后加一行​

视频 · 语音采集与对话中的语音提问默认关闭。要使用时，在主机 env 中加入 PI_MEDIA_ENABLED=true 一行，用 bin/fetch-models.sh 下载转录模型（Aura-ASR-Turbo，约 1.5 GB）后执行 bin/restart.sh。 步骤与确认方法见视频 · 语音采集。

安装之后​

顺序做什么命令 · 文档
1更改默认密码修改初始密码
2查看堆栈是否存活bin/status.sh · bin/health.sh
3定位卡在哪里bin/doctor.sh

常用运维命令见 bin/ —— up.sh · down.sh · restart.sh · logs.sh · backup.sh · update.sh · passwd.sh。详情请参阅 服务运维。

相关文档​