跳到主要内容

环境变量配置

PlantPulse AI 的配置从 /etc/kopens/plantpulse-ai.env 这一个文件开始。

sudo vi /etc/kopens/plantpulse-ai.env
配置正本位于 /etc/kopens/ 下

路径为 /etc/kopens/plantpulse-ai.env。它不在安装目录 (/opt/kopens/plantpulse-ai-docker) 内，而在 repo 树之外，权限为 0600。 platform · ai · studio 三个产品按同一约定使用 /etc/kopens/plantpulse-<product>.env。

🔴 请不要修改 compose/.env。 没有任何程序读取它 — 堆栈不会因此改变。

请勿直接编辑密码与 API 密钥

下表中的 *_PASSWORD · *_API_KEY 仅改文件并不算改完。像 Neo4j 这种 以服务器账户为正本的值，必须同时在服务器侧修改，顺序错了就会留下认证损坏的状态。 请使用专用工具 — 密码 · API 密钥变更。

值存放在三个位置 (2026.10)​

从 2026.10 起，主机 env 只放仅属于本次安装的值。其余随发行版一起进行版本管理。

位置内容修改方式
主机 env /etc/kopens/plantpulse-ai.env硬件形态(PP_HW_PROFILE) · 站点值(语言 · 时区 · 证书名) · 平台连接 · 机密修改该文件并重新创建服务
硬件配置档 compose/profiles/<모양>.env随硬件而异的值 — 三套 vLLM 的 GPU 份额及其总和上限由发行版决定
compose 默认值产品默认值 — 镜像 · 模型名称与路径 · 服务调优由发行版决定。若在主机 env 写入不同的值，则仅覆盖该安装

PP_HW_PROFILE 为 gb10(GB10 · aarch64) 或 g7e(AWS g7e · x86_64)。模板中已写好，若缺失或 与机器架构不符则不会启动。

下列表格中主机 env 模板里没有的变量(标注了默认值的)属于 compose 默认值。保持原样使用是 正常的，只有需要更改时才在主机 env 中以不同的值写入该行。

修改值之后必须重新创建服务(docker restart 不会重新读取 env)。

cd /opt/kopens/plantpulse-ai-docker
bin/restart.sh

启动脚本在启动前会用 bin/lint-env.sh 判定该文件每一行是否各在其位， 若出现下列任意一项则不会启动。

判定内容
release镜像引用 — DOCKER_REGISTRY · DOCKER_NAMESPACE · UPSTREAM_* · *_IMAGE · PI_IMAGE_TAG_* · 有值的 PP_IMAGE_TAG
profile硬件配置档键(如 LLM_GPU_UTIL 等)
redundant原样重复 compose 默认值的行
derivedPP_HOST — 由 PP_DATALAKE_ADMIN_URL 的主机计算得出
unknown任何地方都不会读取的键
renamed已改名的旧键(CH_* → CO_*) — 提示的是 «迁移» 而非 «删除»(见下文「Copilot 配置」)

此外，值位置残留 ${…} 替换符、缺少 PP_HW_PROFILE、GPU 份额超限也会阻止启动。与 compose 默认值不同的 值视为有意覆盖，仅给出提示([note])。判定会逐行打印原因，并一并打印可一次性删除待删行的 sed 命令(保留备份的形式)。renamed 行不会列入删除清单，而是单独打印仅改名的 sed。 不会打印值本身。

保持原样也不会有任何变化的行只以 [warn] 提示，不阻止启动 — 包括本次发行版期间仍按旧名 读取的别名(alias)、与新名同值残留的旧行(oldname)、与影音开关给出的值相同的行(media-same)。 判定会一并打印一条可一次性清理这些内容的 sed，且 bin/doctor.sh 会把这些行单独显示为 «old or redundant lines» 而非 «bad»。若影音开关的值超出 true · false 范围，或 PI_INBOUND_API_KEY 为空，则阻止启动(见下文「影音采集」 · 「后端入站密钥」)。

镜像与镜像仓库​

🔴 从 2026.10 起，镜像引用不写入主机 env。 使用哪个镜像 · 哪个标签由发行版的 compose 决定，若主机 env 中存在下列变量，启动前判定会以 release 阻止启动。原因是主机上残留的 固定项会遮蔽下一个发行版，且在制作离线包时曾出现过泄漏到那里的情况。

变量含义
DOCKER_REGISTRY · DOCKER_NAMESPACE拉取自有镜像的位置 (docker.kopens.io / pi)
UPSTREAM_DOCKERHUB · UPSTREAM_NVCR代为拉取外部镜像的企业内部代理
PP_IMAGE_TAG整套默认标签。模板中仅保留空行
PI_IMAGE_TAG_<component>仅将某一个组件绑定到其他快照时使用(热修复 · 回滚)。共十三个，后缀为镜像名的大写形式(plantpulse-timeseries-insight-api → PI_IMAGE_TAG_TIMESERIES_INSIGHT_API)

紧急情况下若只需以其他标签启动某一个组件，请通过 shell 环境只对该次执行提供，而不是写入文件。 下一次普通启动会回到发行版标签。

cd /opt/kopens/plantpulse-ai-docker
PI_IMAGE_TAG_RAG_API=<태그> bin/up.sh

2026.10 中自有镜像增至十二个 — 新增了数字主线(plantpulse-digital-thread-api)， 并且 LightRAG 与 LiteLLM 也不再直接使用原始镜像，而改为我方封装的镜像 (pi/plantpulse-lightrag · pi/plantpulse-litellm)。这两个封装镜像同样遵循月度标签(2026.10)， 单独固定时使用 PI_IMAGE_TAG_LIGHTRAG · PI_IMAGE_TAG_LITELLM。封装基底为 LightRAG v1.5.7 · LiteLLM v1.103.0。

在 2026.10 再发行 3 中又增加一个，共十三个 — 即录音服务所用的音频库镜像 pi/plantpulse-asr-audio(约 130 MB，固定时使用 PI_IMAGE_TAG_ASR_AUDIO)。它仅在启用影音的安装中启动，但 离线包中始终包含(见下文「影音采集」)。

PP_IMAGE_TAG 保持为空

留空则使用 compose 中内置的 calver 字面量。该字面量每个发行版由 bin/bump-version.sh 搬移，因此发行月份只有一个归属地。若填入值，启动前判定会 阻止启动。

YYYY.MM 是 «会移动的» 标签

同月内再次发行会被覆盖。若要锁定时间点，请按上文 shell 环境方式给出日期标签 (YYYY.MM-YYYYMMDD)，但需确认每个镜像是否存在该标签，只对存在的逐个固定 — 并非全部镜像都有，整体替换会导致不存在的镜像 pull 失败。

管理控制台有两个镜像 — 固定时使用的变量为 PI_IMAGE_TAG_ADMIN_API 与 PI_IMAGE_TAG_ADMIN_WEB(两者为空时 跟随 PP_IMAGE_TAG)。它们出自同一次提交，因此单独固定时也要始终成对绑定。 若版本不一致，控制台会与缺少其所调用 API 的后端配对。

语言与时区​

变量默认值含义
PP_LANGko安装的默认语言 —— 邮件 · 定时执行 · 保存的文稿这类没有请求的场合所用的语言。自动化的摘要 · 轮次原因 · PDF 章节名 · Excel 工作表名这类由服务器撰写的自动化文字也使用此语言 → 自动化 — 报告的标题。Copilot 界面优先采用用户自选的语言 → 浏览器语言，两者都不是韩语 · 英语时才使用此值 → 界面语言。管理控制台仅首页卡片名称跟随此值，其余界面由登录页的语言切换(English · 한국어)决定 · 取值只有 ko · en 两种。为空或为其他值时服务拒绝启动(安装模板默认 ko)
PP_TZAsia/Seoul单次安装的时区 — 全部服务与主机 OS 共用这一个值。由安装程序选择(安装时给出的值 → env 中已有的值 → 主机时区(非 UTC 时) → Asia/Seoul 顺序)
LIGHTRAG_SUMMARY_LANGUAGEKoreanRAG 总结知识所用的语言

将总结语言与界面语言分开设置的原因是：界面可以用英文，但语料(现场 SOP) 往往是韩语。

从平台借用的组件​

🔴 AI 堆栈不会启动 PostgreSQL · Aster TSDB · Redis · RustFS。 它们共用平台的安装实例。 这些值若有误，AI 虽能启动但无法保存任何数据。

平台凭据由容器在 «启动时» 获取​

从 2026.10 起，平台存储的账户 · 密码 · 端口(PG · Aster TSDB · Redis · RustFS)不再由 compose 传给容器。使用它们的六个服务(copilot-web · timeseries-insight-api · lightrag · rag-api · digital-thread-api · litellm)会在启动时从平台的凭据 API 获取，转换为自身的名称 后再启动应用。主机 env 中只需写入调用该 API 的地址和密钥这两项。

变量含义
PP_DATALAKE_ADMIN_URL平台数据湖管理 API — https://<플랫폼 호스트>:4950。该 URL 的主机即平台主机
PP_DATALAKE_ADMIN_API_KEY该 API 的密钥。从平台主机 /etc/kopens/plantpulse-platform.env 中原样复制同名行

模板中这两行填有占位值，交互式安装(INTERACTIVE=1)会询问这两个值。获取所需的准备工作见 安装概览(平台白名单 · 信任锚 root.crt)。

获取失败时该容器会 «停止»
  • 两个值中只填一个，容器会拒绝启动。
  • 获取失败会以 FATAL 停止(连接失败 · 5xx 会短暂重试，4xx 立即失败)。不存在用上次值启动的缓存。
  • 服务器证书仅通过 /etc/kopens/ca/root.crt 验证。文件缺失即 FATAL，且没有关闭验证的途径。

若在平台侧更改了密码，AI 侧无需修改任何文件 — 重启该容器即可获取新值。获取到的值在日志中 只留下键名和数量(docker logs <컨테이너> 2>&1 | grep credentials:)。

主机脚本也走同一条路径获取。 启动前的 DB 预置(provision-platform-db.sh)、手动执行的 DB 迁移脚本、install.sh START=1 的前置检查都以相同规则(用 root.crt 验证)调用同一 API。 因此主机 env 中也没有平台账户 · 密码。失败时会用 [FATAL] [platform-credentials] … 一行说明 原因(不可达 · 401/403 · 无密钥 · 缺少 URL/密钥/CA)后停止。仅在无法连通平台的场合进行测试时， 可通过该次执行的 shell 环境给出值，此时以其为准。

主机 env 中保留的平台相关值仅有以下几项。

变量含义
PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEY见上 — 获取凭据的位置
PP_API_URL · PP_API_TOKEN平台 V5 API — 凭据存储中没有的值，故保留在主机 env(见下文「平台集成 MCP」)
PP_PG_PORT · PP_CASSANDRA_PORT模板中仅以注释形式存在。只有主机脚本读取，若为平台默认端口则留空

平台主机(PP_HOST)不要填写 — PP_DATALAKE_ADMIN_URL 的主机即是它，容器与 主机脚本按相同规则计算。AI 使用的 PG 数据库名(PP_LIGHTRAG_PG_DB 默认 lightrag 等)属于 compose 默认值。

AI 应用自身的 PG 数据按应用分 schema 存放在平台 PG 的 DB pi 中(Copilot co · 数字主线 dt，账户为 PP_PG_USER)。旧安装的 DB ch 会在启动时以 pi.co 迁移。

升级到 2026.10 时 — 旧 env 无法原样启动

安装程序与 update.sh 不会重新生成已有的 env。2026.09 及以下版本的 env 中如今会残留大量 不在其位的行 — 镜像引用、GPU 份额、与 compose 默认值相同的值、PP_HOST、平台账户 · 密码 (PP_PG_USER · PP_PG_PASSWORD · PP_CASSANDRA_* · PP_REDIS_PASSWORD · PP_S3_* 等) — 启动前判定会阻止启动。升级前请先清理。

cd /opt/kopens/plantpulse-ai-docker
sudo bash bin/lint-env.sh                 # 무엇이 남았나 — 바꾸지 않습니다
sudo cp -p /etc/kopens/plantpulse-ai.env ~/plantpulse-ai.env.bak-$(date +%Y%m%d-%H%M)
# lint-env 가 찍은 sed 한 줄을 그대로 실행한 뒤, 하드웨어 모양을 더합니다(GB10 = gb10 · g7e = g7e)
grep -q '^PP_HW_PROFILE=' /etc/kopens/plantpulse-ai.env || echo 'PP_HW_PROFILE=gb10' | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null
sudo bash bin/lint-env.sh && bin/restart.sh
  • 删除前先添加 — 新增 PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEY 并放置信任锚。 对旧的平台账户行，判定只会提示 «删除»，因此请先添加这两项。
  • 旧的 CH_* 行会被判定识别为 renamed，并单独打印仅改名的 sed — 执行后值会原样 迁移到 CO_*(见下文「Copilot 配置」)。
  • 有意设置为与默认值不同的值(例如模型路径)会以 override 提示保留，不会被删除。
设备报警通过 MQTT 接收

Copilot 通过 MQTT 订阅平台的设备报警(2026.09 起，此前为 Kafka)。Broker 地址 跟随 PP_API_URL 的主机，端口默认 1884(TLS)，因此无需单独填写任何值。 以前的 PP_KAFKA_PORT 已取消 — 即使残留也无人读取。

平台集成 MCP​

这是 Copilot 聊天拉取平台实时数据的通道。

变量含义
PP_API_URL平台 server-web 基础 URL
PP_API_TOKEN平台签发的 API 令牌
令牌 «错误» 也能启动

这两个值由 compose 强制要求 — 为空则堆栈无法启动。若残留占位符，bin/up.sh 不会启动。 但如果是错误的令牌，堆栈会正常启动，而仅聊天中的平台 MCP 工具静默变为 0 个。出现「看不到工具」的症状时，请先从这里排查。

模型与网关​

模型 · 网关的值全部为 compose 默认值(密钥中只有安装程序生成的机密位于主机 env)，vLLM 为 v0.31.0，docling-serve 为 v1.36.0。镜像(VLLM_IMAGE · DOCLING_IMAGE)遵循上文「镜像与镜像仓库」的 规则，因此不写入主机 env。模型位置为 LLM_MODEL_PATH · EMB_MODEL_PATH · RERANK_MODEL_PATH (默认在 /opt/kopens/models 下的 Aura-* 目录)。

变量默认值含义
LLM_NAMEaura-lite调用生成模型的名称。兼作视觉模型
EMB_NAMEaura-embedding-4b嵌入模型名称
RERANK_NAMEaura-reranker-0.6b重排序模型名称
LLM_MODEL_PATH/opt/kopens/models/Aura-Lite-NVFP4生成模型权重文件夹。以最后一级文件夹名作为 Aura-Lite-NVFP4.tar.zst
LLM_MODEL_ARGS--tool-call-parser gemma4 --reasoning-parser gemma4 --async-scheduling --enable-chunked-prefillvLLM 启动参数。解析器与权重(Gemma 4 系列)匹配，因此只能与权重一起更改
VISION_LLM_MODEL(空)仅在视觉请求使用其他模型时填写。留空则使用 LLM_NAME
PI_VLLM_API_KEY安装程序生成vLLM 前端密钥
PI_LLM_API_KEY安装程序生成LiteLLM 主密钥
PI_LITELLM_SALT_KEY安装程序生成LiteLLM 加密存储值所用的盐
PI_LITELLM_UI_USERNAME · PI_LITELLM_UI_PASSWORDadmin · admin123!LiteLLM 管理界面(:4000/ui)登录。密码为必填 → 初始密码变更
PI_LITELLM_PORT4000在主机上开放 LiteLLM 的端口。仅当本主机上已有其他 LiteLLM 占用 4000 时才更改。堆栈内的消费方通过容器网络调用 plantpulse-litellm:4000，与此值无关。更改后需以 bin/restart.sh plantpulse-litellm 重新创建
LITELLM_IMAGE 已取消

从 2026.10 起网关镜像属于自有镜像(pi/plantpulse-litellm)，遵循上文的镜像标签规则。 旧 env 中残留的 LITELLM_IMAGE 行会被启动前判定识别为镜像引用(release)并阻止启动 — 请删除。

模型名称为 aura-* — 不提供旧名别名

注册到网关的名称为 aura-lite · aura-vision(视觉别名) · aura-embedding-4b · aura-reranker-0.6b。LLM 的服务名称在 2026.09 由 gpt-4o → aura-35b， 在 2026.10 再发行 9 由 aura-35b → aura-lite，且不提供旧名兼容别名 — 用旧名调用会返回 404，因此必须把外部集成的 model 值改为新名。VLM_NAME 也已 取消(视觉别名由网关配置持有)。

服务名称(LLM_NAME)与权重文件夹(LLM_MODEL_PATH，默认 /opt/kopens/models/Aura-Lite-NVFP4)是彼此独立的配置。 再发行 9 中两者都已变更 — 权重文件夹由 Aura-35B-A3B-NVFP4 → Aura-Lite-NVFP4(打包模型文件 Aura-Lite-NVFP4.tar.zst)。 若把这三项(LLM_NAME · LLM_MODEL_PATH · LLM_MODEL_ARGS)以与默认值相同的值写入主机 env，启动前判定(lint-env)会以 redundant 阻止启动 — 只有试用其他模型时才以 «不同的值» 写入。

请勿更改 PI_LITELLM_SALT_KEY

它是加密在管理控制台模型注册界面填入的外部提供商 API 密钥的钥匙。更改后将无法解密 已保存的内容 — 容器会以 healthy 启动、模型列表也照常显示，但仅调用会静默失败。 请保持最初设定的值不变，并纳入备份对象。

GPU 内存份额​

三套 vLLM(生成 · 嵌入 · 重排序)、语音录音 vLLM(plantpulse-asr)与时序推理服务器共用同一块 GPU。 各自的份额及其总和上限全部由硬件配置档(compose/profiles/<PP_HW_PROFILE>.env)承载 — 若写入主机 env，启动前判定会以 profile 阻止启动。

变量gb10 / g7e含义
LLM_GPU_UTIL · EMB_GPU_UTIL · RERANK_GPU_UTIL0.4 · 0.10 · 0.08 / 0.53 · 0.13 · 0.10三套 vLLM 的 GPU 内存份额
TS_GPU_UTIL0.13 / 0.15时序推理服务器的份额
ASR_GPU_UTIL0.03 / 0.04语音录音 vLLM 的份额 — 仅在启用影音的安装(PI_MEDIA_ENABLED=true)中启动，但即使关闭也计入总和(以免启用当天超出上限)
PP_GPU_BUDGET_CEILING0.75 / 0.95五项份额之和的上限。超出则在启动前停止

GB10 为统一内存，上限为 0.75(合计 0.74)；独立显存设备(AWS g7e)为 0.95(合计 0.95)。

总和超限会让 vLLM 每 24 秒崩溃并重启

vLLM 启动时会确认 «剩余内存 ≥ 自身份额»，不足则退出。总和超限时会变成先启动者胜出的竞争， 失败方反复重启、聊天随之中断 — 日志中任何地方都不会出现「配置过量」的提示。因此在启动前 用算术拦截。需要缩减时请从最大的份额开始缩减。

GB10 的 GPU 内存与系统 RAM 属于同一池，提高上限会让 OS · DB 无内存可用。 模板与机器架构不符时安装程序会停止，也正是出于这个原因。

Copilot 配置 — 前缀为 CO_​

从 2026.10 起，传给 Copilot(copilot-web)的环境变量以 CO_ 开头(此前为 CH_)。 CO_LLM_* · CO_TOOL_RESULT_MAX_CHARS · CO_API_V1_KEY · CO_JAVA_OPTS · CO_NAVIGATOR_CRON · CO_ANOMALY_CRON · CO_INCIDENT_DIAG_CONCURRENCY · CO_OTEL_* 全部如此。

升级到 2026.10 时 — CH_* 行不要删除，请 «迁移»

不会回退到旧名称。 安装程序不会重新生成已有的 env，因此旧 env 中 CH_API_V1_KEY · CH_LLM_MAX_COMPLETION_TOKENS · CH_OTEL_GENAI_CONTENT 这类行会原样保留，但 Copilot 不会读取这些名称。若只是删除这些行，对应值会回到默认值 — 例如曾用 CH_API_V1_KEY 开放的 公开 API 将无法再用该密钥进入。

启动前判定(bin/lint-env.sh)会把这些行识别为 renamed 并阻止启动，同时逐行说明该做什么。

判定打印的内容含义 · 处理方式
only the old name is set — rename it只有旧名称。一并打印的 sed 单行命令(保留备份)只改名、保留原值
both set with the same value新名称已存在且值相同。删除旧行
both set and DIFFERENT两者都存在且值不同。以新名称为准 — 确认哪个值正确后删除旧行
sudo grep -n '^CH_' /etc/kopens/plantpulse-ai.env     # 남은 옛 줄

迁移后以 bin/restart.sh plantpulse-copilot-web 重新创建。

自动化的输出目的地 — 邮件 · 即时通讯 · PDF​

把自动化结果输出到邮件 · 即时通讯的通道默认关闭，必须具备下列值才会开启。PDF 仅在能连通转换服务时才会生成。

内容在哪里设置为空时
PDF 转换服务(Gotenberg)环境变量 CO_GOTENBERG_URL — compose 默认值 http://plantpulse-gotenberg:3000(随堆栈一起启动的转换容器)若值为空或该地址的转换容器无响应，则仅 PDF 关闭。 报表的 PDF 下载与自动化邮件的 PDF 附件按钮会置灰，界面会说明原因。Excel · CSV 与此值无关
邮件允许域名管理控制台 › 通知渠道的 «邮件允许域名»(配置键 automation.mail.allowed-domains，逗号分隔 · 最多 20 个)🔴 自动化邮件处于关闭状态。 必须填写企业域名才会开启
邮件服务器管理控制台 › 系统设置的 smtp.host · smtp.port · smtp.username · smtp.password · smtp.starttls，发件人 navigator.report.email.from邮件无法发出(执行记录中显示「邮件服务器未配置」)
即时通讯渠道(Teams · Slack)在管理控制台 › 通知渠道注册 Webhook 地址 — 不是环境变量自动化的 «发送» 中无法选择即时通讯渠道
邮件 · 即时通讯正文中的链接管理控制台 › 系统设置的 app.base.url(本安装的外部地址)正文中不插入链接

CO_GOTENBERG_URL 必须是 http:// · https:// 地址。其他值会记录警告并关闭 PDF。界面上的 PDF 按钮 · 附件标签并不取决于是否填写了地址，而取决于 转换器此刻是否响应(/health，每 30 秒重新确认) — 在只有地址而没有容器的安装中会显示为关闭。无法连通转换器时，邮件会仅去掉 PDF后发出 (执行记录中显示「附件失败」)，报表下载会返回「当前无法生成 PDF。」。转换器状态会在 /actuator/health/deps 的 gotenberg 中以 off · unreachable · up 显示， 且转换器宕机不会计入 Copilot 的启动判定。

每日发送上限是系统设置中的值(无需重启即可生效)。即使从未修改过，也会与默认值一起显示在管理控制台 › 系统设置中，可在那里修改或恢复为默认值。 自动化的周期 · 令牌上限(agentdef.*)与双人审批工具(access.two_person.tools)也在同一列表中 → Copilot 管理控制台 — 系统设置

配置键默认值含义
automation.deliver.mail.daily-max6单个自动化每天发给一个人的邮件数
automation.deliver.webhook.daily-max12单个自动化每天发往一个渠道的即时通讯条数
automation.deliver.role.max-members50按角色选择收件人时展开的人数

界面上的操作见 Copilot 管理控制台 — 通知渠道。

Copilot 聊天 — 思考模式与三项上限​

这是决定对话式 Copilot(copilot-web)如何调用网关的三个值。三者都以不同的手柄处理同一个失败——即模型在回答前会 «思考»，而思考同样消耗生成令牌。

变量默认值含义
CO_LLM_THINKING_ENABLEDtrue (compose，自 2026.10 再发行 9 起。应用单独运行时默认为空)思考模式开关 → chat_template_kwargs.enable_thinking。留空则不发送(遵循模型默认值 — AURA-Lite 的模板默认值为 «关»)
CO_LLM_MAX_COMPLETION_TOKENS4096 (自有堆栈部署为 16384)单次调用的生成令牌上限。必须大到足以容纳思考与回答。为 0 则不发送上限
CO_TOOL_RESULT_MAX_CHARS24000单个工具结果载入模型的最大字符数。超出时从最深层数组开始削减并留下 _truncated 标记。为 0 则不截断
关闭思考会变快但会 «编造»

在 Qwen3.5 系列中以 CO_LLM_THINKING_ENABLED=false 关闭后，响应会缩短到数秒，但模型会不调用工具而编造不存在的资产与报警(2026-09-18 预发布环境实测)。这不是在速度与质量之间权衡的问题，而是答案正确与否的问题。

关闭这一选项只对不思考也会调用工具的模型有意义。

思考程度 — 各路径默认值​

从 2026.10 再发行 9 起，除了开关思考之外，还可以选择思考多少(reasoning_effort)。它不是 env，而是 Copilot 管理 › 系统设置(/admin/config)中的键，保存后无需重启即可从下一次调用生效。

键界面名称
llm.reasoning.chat聊天思考程度默认值
llm.reasoning.automation自动化思考程度
llm.reasoning.diagnosis异常诊断思考程度
llm.reasoning.proposal执行建议思考程度
llm.reasoning.other其他生成的思考程度
  • 取值为 none(关) · low · medium · high，或留空(«遵循服务器默认值»)。none 关闭思考，其余在开启思考的前提下按该程度发送。
  • 决定顺序为 用户在提问时选择的值 → 上述各路径键 → CO_LLM_THINKING_ENABLED。
  • 提问界面的 思考程度 按钮仅在设定了全局值或 llm.reasoning.chat 时才显示。
若回答 «空白» 结束，请检查上限

若思考未能在上限内结束，生成会以 length 被截断，正文为 0 字。由于流是正常结束的，界面上只表现为「出不来答案」，看起来像网关故障。

以下是在预发布环境对同一问题并行测量的结果。

配置结果
思考开 + 4096空回答 — 思考耗尽了上限
思考关快但跳过工具并编造
思考开 + 16384调用工具且答案正确 (视问题 20 秒~4 分钟)

若提高上限仍无法完成，则应考虑缩减提示词或工具结果大小(CO_TOOL_RESULT_MAX_CHARS)。

文档索引(LightRAG)时间预算​

保持默认值即为正常。只有在实测确认「本设备需要更多/更少」时才调整。

变量默认值含义
LIGHTRAG_LLM_TIMEOUT3600实体抽取 LLM 调用的超时(秒)。worker 超时为此值的两倍
LIGHTRAG_LLM_MAX_TOKENS32768单次抽取调用可产出的最大令牌数 — 失控上限
LIGHTRAG_MAX_ASYNC4并发 LLM 调用数。🔴 减小反而更慢
若因 Worker execution timeout 导致索引失败

会思考的模型单次调用消耗大量令牌。在以前的默认值(240 秒，worker 480 秒)下，大型 PDF 会在 索引过程中整体失败。若看到该错误，请提高 LIGHTRAG_LLM_TIMEOUT，同时 一并关注 LIGHTRAG_LLM_MAX_TOKENS — 没有上限时，一次失控就会长时间占用相应的 GPU 槽位。

公开 API 机器认证​

这是外部系统调用 Copilot 公开 API(/api/v1)时使用的密钥 → API 集成指南

变量默认值含义
CO_API_V1_KEY(空)通过请求头 X-API-Key: <value> 接收的密钥。截至 2026.09 的名称为 CH_API_V1_KEY — 请迁移
留空表示用此密钥 «无法进入» — 不是放行

留空时不接受该环境变量密钥。此时能通过 X-API-Key 进入的，只有在 Copilot 管理 控制台的 API 密钥界面(/admin/api-keys)命名签发的密钥；若连那也没有，则只接受会话登录。 这样设计是为了避免漏配的部署变成无认证的公开 API。无论哪种密钥，权限都只触及公开 API， 不会触及管理界面(/admin/**)和 API 文档。

单个环境变量密钥无法区分发给了谁，一旦泄漏，所有使用方会同时中断。若要为每个外部系统 分别签发，请使用 Copilot 管理控制台的签发方式 → Copilot 管理控制台 — API 密钥

管理控制台与 API 密钥​

变量含义
PI_ADMIN_USER · PI_ADMIN_PASSWORD管理控制台登录。账号默认 admin，密码由安装时的人员设定
PI_ADMIN_SESSION_SECRET管理控制台会话签名密钥 — 由安装程序生成
ADMIN_SESSION_MAX_AGE会话有效时长(分钟)。默认 480
PI_ADMIN_WEB_PORT管理控制台 HTTP 端口。默认 5959
PI_ADMIN_WEB_TLS_PORT管理控制台 HTTPS 端口。默认 5960 — 由代理接收并转发到同一控制台(证书与 :443 为同一套)
PI_NEO4J_USER · PI_NEO4J_PASSWORD图数据库账户 — 两个 Neo4j 实例(LightRAG 知识图谱 plantpulse-neo4j · 工厂图谱镜像 plantpulse-digital-thread-neo4j)使用同一账户
PI_RAG_API_KEYRAG API 调用密钥
PI_INBOUND_API_KEY进入后端服务(RAG · 时序洞察 · 文档理解 · 视觉 · 数字主线)的请求密钥。为空则启动前判定会阻止整个堆栈(见下文「后端入站密钥」)

这些值仅改文件并不算改完 — 像 Neo4j 这种以服务器账户为正本的，必须同时在服务器侧 修改。bin/passwd.sh 会按正确顺序完成 → 密码 · API 密钥变更。

管理控制台端口已从 9080 迁移到 5959 · 5960 (2026.10)

两个入口调用同一个控制台，且都会开放(不会把明文重定向到 HTTPS)。留空则采用上述 默认值，修改后安装程序会按该值开放防火墙。修改后请以 bin/restart.sh plantpulse-admin-web plantpulse-proxy 重新创建这两个容器。

存储凭据加密密钥 — PI_COPILOT_SECRET_KEY · PI_DT_SECRET_KEY​

这是把界面中录入的凭据以 AES-256-GCM 封存到 DB 的钥匙。值为 base64 表示的 32 字节， 首次安装时由安装程序生成。

变量封存什么为空时
PI_COPILOT_SECRET_KEYCopilot 保存的凭据 — 外部 MCP 连接器认证值、LLM 密钥、SMTP 密码、Slack Webhook、Web Push 私钥🔴 仅 Copilot 拒绝启动，并在日志中打印需要添加的那一行。其余堆栈正常启动
PI_DT_SECRET_KEY数字主线连接器注册表中的连接器凭据仅连接器注册表返回 config_error(503)。图谱镜像正常运行
更改或丢失将无法解密已保存的凭据

  • /etc/kopens/plantpulse-ai.env 备份中必须一并包含这两个值。 只恢复 DB 而没有密钥时， 连接器 · 通知凭据需要重新录入。

  • 从 2026.09 及以下升级的主机上没有这两行。 安装程序不会向已有 env 追加行， 启动前判定会提示 «缺少存储凭据加密密钥»。请自行添加(采用不在屏幕上回显值的方式)。

    echo "PI_COPILOT_SECRET_KEY=$(openssl rand -base64 32)" | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null
    echo "PI_DT_SECRET_KEY=$(openssl rand -base64 32)" | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null

  • bin/passwd.sh 不会轮换这两个密钥。更换只能通过把旧值放到 _PREVIOUS 的流程进行 → 密码 · API 密钥变更

数字主线​

从 2026.10 起 plantpulse-digital-thread-api 默认包含在堆栈中(不在主机上开放端口， 在堆栈内通过 7140 调用)。工厂图谱镜像放在专用 Neo4j(plantpulse-digital-thread-neo4j)中， 连接器注册表放在 PG DB pi 的 schema dt 中。平台事件读取器出厂即为开启状态。

以下是主机上可调整的手柄。保持默认值即为正常。

变量默认值含义
PI_DT_SECRET_KEY安装程序生成连接器凭据加密密钥(见上)
DT_INSIGHT_EVENTS_PUSHfalse是否把数字主线读取的平台事件推送给时序洞察
TS_EVENTS_SOURCEdirect时序洞察从何处接收平台事件 — direct(直接读取) · shadow(直接读取并与推送内容比对) · digital_thread(仅使用推送内容 — 需上面的开关处于开启)
DT_PLATFORM_READ · CO_PLATFORM_READ · TS_PLATFORM_READdb读取平台原始账本的路径 — db(直接读平台表) · shadow(两边都读、以 db 作答并统计差异) · api(平台 V5 REST，使用既有的 PP_API_URL · PP_API_TOKEN)

连接器周期同步与新鲜度 (2026.10 再发行 3)​

对已启用的连接器周期性重新同步。同步不会删除消失的连接，而是将其 «关闭»(写入结束时间)， 因此按历史时点查询的结果仍然正确。保持默认值即为正常。

变量默认值含义
DT_CONNECTOR_SYNC_ENABLEDtrue周期同步。为 false 则停止，仅保留管理控制台的 «立即同步»
DT_CONNECTOR_SYNC_INTERVAL_S0同步间隔(秒)。为 0 则按族别 — 取该族新鲜度上限的一半，最小 300 秒
DT_CONNECTOR_MAX_AGE(空)连接器数据的新鲜度上限。가족=기간 列表(例如 mes=2h,erp=1d，单位 s · m · h · d)。留空则按族别默认 — ehs 1h，mes · sched · wms 2h，cmms 4h，lims 12h，其余 1d。若存在比上限更陈旧的连接器，则不输出恢复 · 影响数值
DT_LINK_HISTORY_DAYS(空 — 180)已关闭连接的保留期限(天，1~3650)

当前生效的值与同步状态可在数字主线的 /api/v1/config(如 dt_connector_max_age_effective 等)和 /health 的 connector_sync 中查看。connector_sync 仅为信息，不会使服务变为 degraded。

后端入站密钥 — 为空则不启动​

RAG(rag-api) · 时序洞察 API · 文档理解 · 视觉 · 数字主线使用同一个密钥(PI_INBOUND_API_KEY)校验 入站请求。compose 会把该值按各服务自己的名称(RAG_INBOUND_API_KEY · TS_INBOUND_API_KEY · INBOUND_API_KEY …)分发，Copilot 与管理控制台后端也用同一值调用这些服务。

密钥为空时，不存在 «偶然» 以无认证状态开放启动的路径。

位置密钥为空时
启动前判定(bin/lint-env.sh)以 [fail] PI_INBOUND_API_KEY is empty and PI_INBOUND_AUTH_DISABLED is not true 不创建任何容器并停止
各服务自身密钥为空则拒绝启动，并留下 FATAL: … is empty — refusing to start … 之类的一行日志

以无认证方式启动的途径只有一个显式开关，且仅供开发 · 测试使用。

变量默认值含义
PI_INBOUND_AUTH_DISABLEDfalse仅当为 true 且密钥为空时，这五个服务才会以无认证方式启动。compose 会按服务分别传为 RAG_INBOUND_AUTH_DISABLED · TS_INBOUND_AUTH_DISABLED · DT_INBOUND_AUTH_DISABLED · INBOUND_AUTH_DISABLED(文档理解 · 视觉)

启动前判定针对该开关的输出如下。

输出含义
[fail] PI_INBOUND_AUTH_DISABLED=<value> — write true or false超出 true · false 的值
[note] PI_INBOUND_AUTH_DISABLED=true is ignored — PI_INBOUND_API_KEY is set and the key wins若存在密钥则密钥优先 — 认证仍处于开启状态

以无认证方式启动的服务会在 /health 中体现该事实(文档理解 inbound_auth: "disabled"、数字主线 auth.inbound=disabled 等)。生产安装中正确做法是填入密钥。

无认证开放的只有健康检查路径 /ping · /health 两个(且仅限这两个路径)。指标 /metrics 同样位于密钥之后 → 日志与监控

占位符会通过这项检查

CHANGE_ME_… 不是空值，因此 compose 与服务都不会拦截，而该字符串在所有安装中都相同。安装程序在首次 安装时会替换为新值，但若是手工创建的 env，请用 bin/passwd.sh --generate PI_INBOUND_API_KEY 填入新值 → 密码 · API 密钥变更

让文档 · 图片工具可访问企业内部 URL​

文档理解 · 视觉工具接收的不是文件而是 URL，并自行下载。若该地址解析为回环 · 私有网段 · 链路本地， 则会拒绝 → MCP 工具地图

像企业内部文件服务器这类有意放行的位置请写入允许列表。compose 会把该值同时传给文档理解与视觉 两个服务。

变量默认值含义
FETCH_ALLOWED_HOSTS(空)即便是内部地址也允许获取的主机。多个以逗号分隔。必须与 URL 中的主机名完全一致(忽略大小写) — 像 files.example.local 或 files.example.local:8080 这样连端口一起写则只放行该端口；若服务器以 IP 调用，就直接写 IP
echo 'FETCH_ALLOWED_HOSTS=files.example.local,10.0.0.15' | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null
cd /opt/kopens/plantpulse-ai-docker
bin/restart.sh plantpulse-document-understanding-api plantpulse-vision-api
  • 不支持通配符 · 网段(CIDR)。子域名也要逐个写。
  • 即便是被允许的主机，也只接受 http · https，大小上限(文档 200 MiB · 图片 32 MiB)保持不变。重定向每跳转 一次都会重新检查，因此若被允许的主机跳转到未允许的内部地址，会在那一步被拒绝。
  • 该行覆盖的是 compose 默认值(空值)，因此启动前判定会给出 override 提示 — 属于正常现象。

RAG 对象存储桶​

rag-api 会把手动上传的文档原件 · 图纸结构与预览 · 视频播放副本与录音转写放在平台 RustFS 的一个桶中。

变量默认值含义
RAG_S3_BUCKETplantpulse-rag该桶名称。只有当两个 AI 安装共用同一平台时，才给第二个安装不同的名称

→ 数据库

图纸采集 — 默认关闭​

该功能把图纸(DXF · 带文本层的矢量 PDF)按标题栏 · 尺寸 · 公差 · BOM 行读取并索引。出厂为关闭 状态，关闭时 rag-api 的图纸 API 与相关表根本不会创建(与没有该功能时相同)。

变量默认值含义
DRAWING_INGEST_ENABLEDfalse为 true 时 rag-api 启用图纸采集。.dxf 始终按图纸处理；PDF 只有在上传时将类型指定为 «图纸»(document_kind=drawing)才按图纸读取。超出 true · false 的值会记录警告并按关闭处理
echo 'DRAWING_INGEST_ENABLED=true' | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null
cd /opt/kopens/plantpulse-ai-docker
bin/restart.sh plantpulse-rag-api
  • 不接受 DWG — 请导出为 DXF 或 PDF 后上传。单文件上限为 50 MB。
  • 平台资产文档也会作为图纸进入(2026.10 再发行 3)。导入平台资产所附文档的同步会把 .dxf 文件以及«文档类型»为 DRAWING 的 PDF 送入图纸路径。这样进入的图纸以平台为正本，因此在管理 控制台覆盖上传或删除会返回 409(「drawing is platform-managed …」) — 修改或删除请在平台进行； 若只想从检索中排除，可在管理控制台文档表中执行 «从语料中排除»(自 2026.10 再发行 4 起，控制台按钮对账本图纸开放。 自行上传的图纸仍然无法排除)。关闭时 .dxf 只计数(drawing_disabled)而不写入，PDF 会作为 普通文档进入。
  • 图纸的版次(修订)是否为当前作业版本，会向数字主线查询(PLM 的发图版次 · 未关闭的设计变更)。若标题栏中没有 品号 · 版次，或数字主线无法应答，则版次状态为 unknown，不会显示为 «最新»。
  • 启用后 rag-api 会在启动时于 rag_ingest DB 中创建图纸用表(rag_drawing_*) — 无需手工迁移。

影音采集 — 默认关闭，一行即可开启​

把影音转写(语音 → 带时间戳的文本)并索引的功能，以及 Copilot 聊天输入中的语音提问，使用同一个转写 服务(plantpulse-asr)。出厂为关闭状态，开启只需主机 env 的一行 PI_MEDIA_ENABLED=true (模板中以注释 #PI_MEDIA_ENABLED=true 形式存在)。使用方法见 视频 · 语音检索。

这一行同时决定的内容说明
启动的服务plantpulse-asr-audio — 把音频库复制到卷 pi-asr-audio 后即结束的一次性服务 · plantpulse-asr — vLLM Whisper large-v3-turbo，服务名称 aura-asr，内部 8000(不在主机开放)。运维脚本会附加 compose 配置档 media 来启动
容器值rag-api MEDIA_INGEST_ENABLED=true · 文档理解 ASR_URL=http://plantpulse-asr:8000(安装实例的 compose/media/true.env)
模型bin/fetch-models.sh 会下载转写模型 Aura-ASR-Turbo(下载约 1.5 GB，解压后约 1.6 GB)。关闭的安装不会下载
GPUASR_GPU_UTIL 即使在关闭时也计入硬件配置档的总和，因此开启后也不会超出上限
cd /opt/kopens/plantpulse-ai-docker
sudo cp -p /etc/kopens/plantpulse-ai.env /etc/kopens/plantpulse-ai.env.bak-media-$(date +%Y%m%d-%H%M)
sudo sed -i '/^#\?PI_MEDIA_ENABLED=/d' /etc/kopens/plantpulse-ai.env && echo PI_MEDIA_ENABLED=true | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null
sudo bash bin/fetch-models.sh                    # Aura-ASR-Turbo — 이미 있으면 건너뜁니다
sudo bash bin/lint-env.sh && bin/restart.sh      # rag-api · 문서 이해가 새 값으로 다시 만들어집니다
bin/status.sh                                    # 켠 설치는 23/23 — plantpulse-asr-audio 는 «Exited (0)» 이 정상입니다

是否已开启可从三处查看。

# rag-api — "media_ingest_enabled":true
curl -s -H "X-API-Key: <PI_INBOUND_API_KEY>" http://127.0.0.1:7115/api/v1/config | grep -o '"media_ingest_enabled":[a-z]*'
# 문서 이해 — components.asr.status 가 "up"
docker exec plantpulse-document-understanding-api python3 -c \
  "import urllib.request;print(urllib.request.urlopen('http://localhost:7120/health').read().decode())"

bin/status.sh 会把以 «退出码 0» 结束的一次性服务(plantpulse-asr-audio)计为正常。若不为 0， plantpulse-asr 也不会启动 — 请先查看其日志。

  • 关闭 — 删除该行或设为 PI_MEDIA_ENABLED=false 后执行 bin/restart.sh，再以 docker rm -f plantpulse-asr plantpulse-asr-audio 删除剩余的两个容器(配置档关闭后，运维脚本不再处理这两个容器)。
  • 隔离网络 — 镜像始终随离线包提供。只需单独导入模型 → 隔离网络安装
  • 若值超出 true · false 范围，启动前判定会以 [fail] PI_MEDIA_ENABLED=<value> — true 또는 false 만 받는다 停止。
旧名称 MEDIA_INGEST_ENABLED — 仅在本次发行版期间作为别名

若在 2026.10 之前的版本中曾手工在主机 env 写入 MEDIA_INGEST_ENABLED · ASR_URL，升级不会中断，会继续以该值 运行(若没有 PI_MEDIA_ENABLED 行，则把旧名称当作开关读取)。运维脚本首次运行时会把旧名称迁移为 PI_MEDIA_ENABLED，并删除与开关给出的值相同的 ASR_URL 行。

启动前判定含义
alias [warn]只有旧名称 — 可以启动。用一并打印的 sed 单行命令迁移。2026.11 移除别名后，未迁移的行将变为 renamed [fail]
media-same [warn]主机 env 的 ASR_URL 与开关给出的值相同 — 可以删除
media [fail]主机 env 的 ASR_URL 与开关给出的值不同 — 确定本意后删除。开启只需 PI_MEDIA_ENABLED=true 一行
两个名称为不同的值[fail] — 由人确定本意为哪一个

若以无权写入 env 文件的账户运行，则无法自行迁移，会打印 [paths] [warn] cannot write … 以及需人工执行的 sudo sh -c '…' 命令。容器(rag-api)内部读取的名称仍是 MEDIA_INGEST_ENABLED — 该值由开关决定，因此不要写入 主机 env。

以下手柄为 compose 默认值。保持默认值即为正常。

变量服务默认值含义
PI_MEDIA_ENABLED(主机开关)false见上 — 同时开启影音采集与语音提问
MEDIA_MAX_FILE_MBrag-api2048单个视频文件的上限(MB)。与文档上限分开
MEDIA_MAX_DURATION_MINrag-api120单个视频的时长上限(分钟)
MEDIA_TEXT_TRACKSrag-apisubtitles视频中的文字 — off · subtitles(内嵌字幕轨 · 外挂字幕 srt/vtt) · all(+ 由 LLM 读取硬字幕 · 画面文字)
MEDIA_SPAN_TARGET_SECrag-api0索引片段长度(秒，20~300)。为 0 时一个转写片段(约 120 秒)为一段。超出范围的值会记录警告并按 0 读取。更改后从重新索引的内容起生效
MEDIA_PROCESSING_WINDOWrag-api(空 — 20:00-06:00)允许开始视频处理的时间段(以 PP_TZ 为准的 HH:MM-HH:MM，若开始晚于结束则跨零点)。若要始终处理请设为 always。留空或格式错误则采用 rag-api 默认值 20:00-06:00。该窗口只约束处理的开始 — 已开始的处理即使窗口关闭也会跑完。处理与聊天共用同一个 LLM
ASR_URL文档理解(由开关决定)转写服务地址。开启时为 http://plantpulse-asr:8000，关闭时为空值(转写入口为 503)。🔴 请勿写入主机 env — 见上表的 media · media-same
ASR_NAME · ASR_BACKEND文档理解 · asraura-asr · vllm服务名称 · 引擎(只接受 vllm)
ASR_MODEL_PATHasr/opt/kopens/models/Aura-ASR-Turbo转写模型位置
OCR_URL · OCR_BACKEND文档理解http://plantpulse-llm:8000 · vlm读取视频中文字的服务 LLM。仅在开启转写时使用

视觉文字识别引擎​

变量默认值含义
VISION_OCR_ENGINE(空 — 视觉默认 vlm)vision_ocr 的引擎。vlm 由正在服务的 LLM 读取，且三次中有两次字符串一致才作答(可读韩语)。docling 交给文档理解的 OCR(不能读韩语)

相关文档​