跳到主要内容

故障排除

AI 栈只有 docker compose 一个。因此故障排除的起点也只有一个 —— 找出哪个容器异常，然后查看该容器的日志。

cd /opt/kopens/plantpulse-ai-docker/bin
./doctor.sh      # 아무것도 바꾸지 않고 진찰만 합니다. 장애 중에 먼저 돌리십시오
./status.sh      # 무엇이 떠 있나
./health.sh      # 디스크 · 자원 · 서비스별 최근 로그까지

栈起不来​

先确认两个同级仓库是否存在​

ls /opt/kopens
# plantpulse-ai-docker
# plantpulse-ai-inference-server        ← 없으면 compose 가 뜨지 않습니다
# plantpulse-timeseries-insight-server  ← 없으면 compose 가 뜨지 않습니다

compose 会以相对路径 bind-mount 这两个仓库的文件（例如网关配置 litellm-config.yaml）。 缺少时安装器会拒绝启动并打印缺失的仓库名 → 安装概述。

确认配置文件是否存在​

sudo test -f /etc/kopens/plantpulse-ai.env && echo 있음 || echo 없음

没有的话重新运行 bin/install.sh，或将 compose/env.gb10.example 复制到该路径。

🔴 请不要修改 compose/.env。 没有任何程序会读取它 —— 正本是 /etc/kopens/plantpulse-ai.env。

确认启动前校验是否拦下​

bin/up.sh · restart.sh · update.sh 会在拉起 compose 之前校验 env 文件，不符合时一个容器也不创建便停止。2026.10 中最常见的有两种。

cd /opt/kopens/plantpulse-ai-docker
sudo bash bin/lint-env.sh     # 줄마다 제자리인지 — 바꾸지 않습니다
输出原因处理
lines that do not belong in … 以及逐行的 release · profile · redundant · derived · unknown直接沿用了 2026.09 及以下的 env —— 残留有镜像引用、GPU 份额、与默认值相同的值、PP_HOST、旧平台账号行用打印出的 sed 一行删除。删除前先填入两个平台凭据值 → 环境变量配置
renamed keys still use their old names残留旧名称 CH_*不要删除，执行打印出的 sed（仅改名） → 见下文「CH_ 前缀」
PP_HW_PROFILE is not set缺少硬件形态行GB10 填 PP_HW_PROFILE=gb10，AWS g7e 填 g7e
still has template placeholders残留 CHANGE_ME_*填入打印出的键。使用公开模板里写的值将无法启动
[FATAL] [platform-credentials] …启动前的 DB 预配置没能取得平台凭据与下文「容器以 FATAL 停止」同因
PI_INBOUND_API_KEY is empty and PI_INBOUND_AUTH_DISABLED is not true入站密钥为空见下文「后端服务拒绝启动」
PI_MEDIA_ENABLED=<value> — true 또는 false 만 받는다在视频 · 语音开关上写了别的值改为 true 或 false → 视频 · 语音采集
行列表中出现 ASR_URL … media主机 env 的 ASR_URL 与视频 · 语音开关给出的值不一致删除该行。开启转录只需 PI_MEDIA_ENABLED=true 一行

以 [warn] 打印的行（lines to tidy — the stack starts as is）不会阻止启动 —— 它们是旧名称 MEDIA_INGEST_ENABLED （本次发布期间作为别名，alias）、与开关取值相同的 ASR_URL（media-same）、与新名称取值相同而残留的旧行（oldname）。 用一并打印的 sed 一行整理即可。别名将在 2026.11 移除，请在此之前迁移。

compose 自身要求的值（PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEY · PP_HW_PROFILE 等）是否为空，这样查看。

docker compose --env-file /etc/kopens/plantpulse-ai.env -f compose/docker-compose.yml config >/dev/null

某一个容器不断重启​

docker compose ps                              # 어느 것이 Restarting 인가
docker compose logs --tail=200 <컨테이너>       # 왜 죽는가
常见原因确认
抓不到 GPUnvidia-smi · docker compose logs plantpulse-llm
连不上平台 DB见下文「平台 DB」
内存不足docker stats · dmesg -T | grep -i oom
端口冲突ss -ltnp | grep -E '80|443|4000|5959|5960|7115|8970' —— 安装器可能已以«端口被他人占用»发出警告 → 服务端口映射
取不到平台凭据见下文「容器以 FATAL 停止」
后端服务以 inbound · INBOUND_API_KEY is empty 停止见下文「后端服务拒绝启动」
仅副驾驶拒绝启动见下文「只有副驾驶起不来」

容器以 FATAL 停止 —— 平台凭据​

自 2026.10 起，副驾驶 · 时序洞察 API · LightRAG · RAG API · 数字主线 · LiteLLM 会在启动时从平台获取账号 · 密码。 获取不到时不会退回上次的值启动，而是以 FATAL 停止 —— 因此当这六个中的多个同时反复重启时，请先从这里查起。

docker logs --tail=50 plantpulse-copilot-web 2>&1 | grep -iE 'credentials|fatal'
sudo grep -E '^PP_DATALAKE_ADMIN_(URL|API_KEY)=' /etc/kopens/plantpulse-ai.env
ls -l /etc/kopens/ca/root.crt /etc/kopens/ca/CA.crt
原因处理
PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEY 中只有一个两个都填。只有一个时容器会拒绝
没有 /etc/kopens/ca/root.crt放置平台信任锚（同样内容也放一份到 CA.crt）。没有关闭证书校验的途径
密钥错误，或 AI 主机 IP 不在平台白名单中（4xx）把平台主机 /etc/kopens/plantpulse-platform.env 的 PP_DATALAKE_ADMIN_API_KEY 原样搬过来，并把 AI 主机 IP 加入白名单。4xx 不重试，直接停止
触不到平台 :4950 · 5xx会重试片刻后停止。先用 curl -sk https://<플랫폼 호스트>:4950 确认是否连得通

主机脚本（启动前的 DB 预配置 · install.sh START=1 的前置检查）也以同样的值获取。若在那里失败， 容器启动之前就会有 [FATAL] [platform-credentials] … 一行说明原因并停止 —— 处理方式与上表相同。

获取成功时，日志中会出现以 credentials: 开头的行，仅打印键的名称和个数。修改值之后 用 bin/restart.sh 重新创建 → 安装概述

后端服务拒绝启动 —— 入站密钥​

RAG · 时序洞察 API · 文档理解 · 视觉 · 数字主线 在入站密钥为空时不会启动（在 2026.10 重新发布之前， 它们会在无认证敞开的状态下以 healthy 启动）。

sudo grep -c '^PI_INBOUND_API_KEY=.' /etc/kopens/plantpulse-ai.env     # 1 이면 값이 있습니다
docker logs --tail=50 plantpulse-rag-api 2>&1 | grep -iE 'inbound|fatal'
症状原因处理
bin/up.sh 一个容器也不创建，并打印 [fail] PI_INBOUND_API_KEY is empty …env 中没有该行或值为空 —— 启动前校验拦下用 sudo bin/passwd.sh --generate PI_INBOUND_API_KEY 填入（改完文件后重新拉起栈）
[fail] PI_INBOUND_AUTH_DISABLED=<value> — write true or false在免认证开关上写了别的值改为 true · false 或删除该行
日志中出现 FATAL: RAG_INBOUND_API_KEY is empty — refusing to start … 这类行容器里进了空密钥 —— 绕过 compose 启动，或单独运行了镜像按上面填入密钥并用 bin/restart.sh 重新创建
栈起来了，但管理控制台 · 聊天的 RAG · 时序调用返回 401改完密钥后只重建了一部分用 bin/restart.sh 整体重建 —— 见下文「管理控制台报 502 · upstream_auth」

无认证启动的途径只有开发用开关 PI_INBOUND_AUTH_DISABLED=true 一个，而且只要有密钥，该开关就会被忽略 （[note] … is ignored — PI_INBOUND_API_KEY is set and the key wins）。生产安装的答案就是填入密钥 → 环境变量配置

只有副驾驶起不来 —— 存储凭据加密密钥​

若其余的栈都是绿色，只有 plantpulse-copilot-web 拒绝启动，就查看 PI_COPILOT_SECRET_KEY。

docker logs --tail=50 plantpulse-copilot-web 2>&1 | grep -iE 'SECRET_KEY|secrets'
日志原因处理
提示填入 PI_COPILOT_SECRET_KEY=… 一行密钥缺失或格式不对 —— 2026.09 及以下拉起的主机没有该行（安装器不会往既有 env 追加）用 openssl rand -base64 32 的值填入并重新创建 → 环境变量配置
Stored secrets cannot be decrypted密钥换了但没提供旧值把旧值放到 PI_COPILOT_SECRET_KEY_PREVIOUS → 轮换步骤。若旧值已丢失，用日志打印的 SQL 清空被封存的行，并在界面上重新填入该凭据

数字主线的 PI_DT_SECRET_KEY 为空时，栈会起来，但仅连接器注册表返回 config_error（503）。 启动前校验（bin/lint-env.sh）会以«缺少存储凭据加密密钥»提示这两个密钥是否缺失。

改了配置但副驾驶不生效 —— CH_ 前缀​

2026.10 中副驾驶环境变量的前缀由 CH_ → CO_，且没有回退。 旧 env 中 CH_API_V1_KEY · CH_LLM_MAX_COMPLETION_TOKENS · CH_OTEL_GENAI_CONTENT 这类行副驾驶不会读取。 只是删掉行的话，值会回到默认 —— 例如以 CH_API_V1_KEY 调用的外部集成将无法再用该密钥接入。

启动前校验会把这些行以 renamed 捕获并拦下启动，并对每一行打印仅改名的 sed 一行（值不变，保留备份）。 执行它并用 bin/restart.sh plantpulse-copilot-web 重新创建。

cd /opt/kopens/plantpulse-ai-docker
sudo bash bin/lint-env.sh 2>&1 | grep -A2 'renamed'

旧名与新名同时存在且取值不同时，新名称胜出 —— 确认哪个值正确后删除旧行 → 环境变量配置

拉起后没有日志，或写入失败 —— 卷属主​

自 2026.10 起，除 plantpulse-dcgm 一个之外，容器全部以非 root 运行（我们的镜像为 uid 10001、gid 0）。 旧安装中以 root 创建的可写卷（应用日志 · 时序微调权重 · LightRAG · Qdrant · Neo4j · Phoenix 存储、 vLLM 缓存、代理证书）将无法直接写入。这类失败通常是静默的（例如只留在控制台而不是日志文件）， Qdrant 会直接崩溃，代理会因读不到证书私钥而打印处置建议并停止。

bin/up.sh · restart.sh · update.sh 会在拉起之前用 bin/volumes-nonroot.sh 一次性校正属主。 若是裸调 docker compose up，就跳过了这一步。

cd /opt/kopens/plantpulse-ai-docker/bin
./volumes-nonroot.sh     # 이미 맞으면 아무것도 바꾸지 않습니다
./restart.sh

无法校正时会打印 볼륨 소유권을 <uid:gid> 로 맞추지 못했다 并停止启动 → 服务运维

连不上平台 DB​

🔴 AI 栈不启动 PostgreSQL · Aster TSDB · Redis · RustFS。 它共用平台的安装实例。这四个挂了，AI 也会一起停。

# 플랫폼 호스트는 이 URL 의 호스트입니다 (PP_HOST 는 따로 적지 않습니다)
sudo grep -E '^PP_DATALAKE_ADMIN_URL=' /etc/kopens/plantpulse-ai.env

# 실제로 닿는가
nc -zv <플랫폼 호스트> 5432    # PostgreSQL
nc -zv <플랫폼 호스트> 9042    # Cassandra

连不通就是平台侧的问题 → 服务端口映射。

平台账号不在 env 中（2026.10）

PG · Aster TSDB · Redis · RustFS 的账号 · 密码 · 端口，无论容器还是主机脚本都是在启动时从平台获取的。 若认证被拒，请看的不是 env，而是平台上的值以及上文「容器以 FATAL 停止」。 若在平台改过密码，必须重启 AI 容器才能取到新值。

管理控制台报 502 · upstream_auth​

若控制台界面的某个菜单以 … rejected the console's inbound API key (401) - check <변수> 失败，说明控制台背后的服务拒绝了控制台的入站密钥 —— 不是控制台会话过期。 旧版本把这个 401 读作会话过期，只会把你退回登录页（重新登录也一样）。

原因在于后端与控制台是否以相同的 PI_INBOUND_API_KEY 启动。多数是只重建了一侧，或改完密钥后只重启了一部分， 因此请重建整个栈。

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

管理控制台地址自 2026.10 起为 http://<AI 서버>:5959 · https://<AI 서버>:5960（原为 9080）。

LLM 界面报 502 · llm_upstream​

若控制台的 LLM 读取界面（API 密钥 · 日志 · 模型注册列表 · 上游状态等）以 502 和原因 llm_upstream 失败， 说明是网关（LiteLLM）或其 DB 返回了 5xx —— 并不是控制台后端崩了。响应中的 upstream_status 就是网关返回的状态码。旧版本会把它原样当作 500 流出，看起来像控制台故障。

docker compose logs --tail=100 plantpulse-litellm    # 게이트웨이가 왜 5xx 를 냈나 (DB 접속 등)

完全触不到网关时，同样是 502，原因为 llm_unreachable。4xx（输入错误）时网关给出的原因会原样显示在界面上。

出不来答案​

按顺序缩小范围 —— 网关 → 模型 → 界面。

docker compose logs --tail=100 plantpulse-litellm    # 게이트웨이가 요청을 받았나
docker compose logs --tail=100 plantpulse-llm        # 모델이 답했나
docker compose logs --tail=100 plantpulse-copilot-web
症状常见原因
网关日志里没有请求界面上的网关地址/密钥填错
网关返回 401PI_LLM_API_KEY 不一致
只有外部集成以模型名错误失败调用了旧名称（aura-35b · gpt-4o · text-embedding-3-large 等）—— 现在是 aura-lite · aura-embedding-4b → API 集成指南
模型耗时过长后断开GPU 内存不足 —— nvidia-smi
「未能生成答案 … 模型返回了空响应」重试后模型仍给出空答案（API 上为 502）。反复出现时检查思考模式与生成上限 → 环境变量配置
「⚠ 内容重复，已中止生成答复」模型反复输出相同内容，副驾驶中断了生成。请缩小问题范围后重问

「连接已断开。服务器仍在继续生成答案…」​

这是在提问途中仅连接断开（网络切换 · 代理中断等）。新界面的文案是「连接已断开。服务器正在继续生成答案， 完成后会在此处加载」。服务器会把答案生成完并保存，因此界面会在显示该提示的同时， 每 5 秒、最多 5 分钟重新查询该会话的答案，到达后加载。等待即可 —— 手机上同样如此。 5 分钟内仍未找到会转为错误提示，并保留重试按钮 —— 此时请先重新打开会话，确认答案是否已保存。

找不到文档（RAG）​

docker compose logs --tail=100 plantpulse-rag-api
docker compose logs --tail=100 plantpulse-lightrag
curl -s http://127.0.0.1:6333/healthz     # Qdrant(벡터 색인)
症状查看处
聊天不作答，而是回复「现在无法使用文档检索（MCP 网关无应答）…」聊天的文档检索只走 MCP 网关。确认网关是否在运行 —— docker compose logs --tail=100 plantpulse-mcp-gateway-api，以及 Copilot 日志中的 [MCP_GATEWAY] unreachable · [DOC_SEARCH_GUARD]。此时其他问题的答案开头会附上「无法连接到工具网关 …」
聊天不作答，而是回复「文档检索工具已关闭，或未授权给此账户 …」网关有应答，但 rag_search 没有传给模型。在 AI 管理控制台 › MCP 网关 中查看服务器中的 RAG Gateway 和工具中的 rag_search 是否已启用（两者默认都是启用的，关闭说明有人手动关了）。若已启用，请查看此人的聊天工具权限（tool:mcp）和网关的«权限»标签 → RAG — 聊天的文档检索
放入的文档搜不到索引作业是否结束 —— plantpulse-rag-api 日志 · Sync History 的跳过原因 → RAG
文档上传失败plantpulse-docling-serve · plantpulse-document-understanding-api
答案引用了无关文档索引过旧 —— 重新放入并建索引
AI 只说「在文档中没有找到」可能是正常行为 —— 检索为空时不会编造答案，而是以 retrieved: false 返回。先用 rag_list_documents 确认该文档是否已建索引
RAG /health 为 degraded响应的 ingest · neo4j · qdrant 中不为 ok 的那一项

大 PDF 在建索引途中失败​

LightRAG 对每个文档分片用 LLM 抽取实体。只要有一个分片未能在时限内完成，整篇文档就会标记为失败， 剩余分片也不会再尝试。

docker compose logs plantpulse-lightrag | grep -E 'Worker execution timeout|workers initialized'
日志含义
extract LLM func: Worker execution timeout after 480s该安装仍在用旧默认值（每次调用 240 秒）运行
(Timeouts: Func: 3600s, Worker: 7200s, …)当前默认值

时间预算为 /etc/kopens/plantpulse-ai.env 的 LIGHTRAG_LLM_TIMEOUT（默认 3600 秒）， 实际上限是其两倍。当聊天与查询拥挤、模型变慢的时段索引被截断时，请检查该值。 修改后需要的是重新创建（bin/restart.sh），而不是重启。

不要只调大超时

单个分片的输出上限（LIGHTRAG_LLM_MAX_TOKENS，默认 32768）同时生效，长预算才是安全的。 若去掉上限只调大预算，一个失控的请求会把 GPU 槽位占用一小时。

文档 · 图片工具以 refused to fetch 失败​

文档理解 · 视觉工具在收到的 URL 解析为**内网地址（环回 · 私网 · 链路本地）**时会拒绝。原因中 出现 resolves to a non-public address 即属此类。

若要特意放行内部文件服务器，把该主机名写入 FETCH_ALLOWED_HOSTS 并重建这两个服务。 必须与 URL 中使用的名称完全一致（带端口则只放行该端口）。

echo 'FETCH_ALLOWED_HOSTS=files.example.local' | 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

→ 环境变量配置 · MCP 工具地图

图纸被当作普通文档索引，或图纸界面不显示​

图纸采集默认关闭（DRAWING_INGEST_ENABLED=false）。关闭时 rag-api 中根本没有图纸 API， DXF · PDF 图纸不会按图纸解析。

docker exec plantpulse-rag-api printenv DRAWING_INGEST_ENABLED

若为 false，在主机 env 中写入 DRAWING_INGEST_ENABLED=true 并用 bin/restart.sh plantpulse-rag-api 重建，然后 重新上传图纸 —— 开启之前上传的文件不会被重新按图纸解析。PDF 需要在上传时把类型指定为«图纸»才会按图纸解析 → 环境变量配置

控制台给出的提示含义
drawing is platform-managed — update it in the platform, not here（409）试图在控制台覆盖上传来自平台资产文档的图纸（2026.10 重新发布 3）。修改应在平台侧进行
drawing is platform-managed — delete it in the platform ledger, or exclude it from RAG (POST …/exclude)（409）试图在控制台删除平台台账图纸。删除应在平台台账中进行；若只想从检索中剔除，请«从语料库排除»
manually uploaded drawings cannot be excluded — delete the drawing or re-index it instead (platform-ledger drawings can be excluded)（409）在控制台直接上传的图纸无法«排除检索»。请删除或重新索引。平台台账图纸可以排除
extension not allowed（400）这是 DWG。请导出为 DXF 或 PDF 再上传

无法读取插入聊天的文件​

通过提问输入框的插入文件放入的文件，由副驾驶接收并存放到对象存储，再交由文档理解服务（plantpulse-document-understanding-api） 读取 —— 文档用 docling，图纸用图纸识读，视频 · 音频用转写（/api/v1/transcribe → plantpulse-asr）。使用方法见 AI 聊天 — 插入文件。

docker logs --tail=200 plantpulse-copilot-web 2>&1 | grep -E '\[CHAT_ATTACH|\[attach\]|\[CHAT_MEDIA'   # 올림 · 판독 · 녹취 · 실패 사유
docker compose logs --tail=100 plantpulse-document-understanding-api
docker compose logs --tail=100 plantpulse-docling-serve
docker compose logs --tail=100 plantpulse-asr                       # 영상 · 음성 — PI_MEDIA_ENABLED=true 일 때만 뜹니다

上传时被拒绝的情况 —— 标签上会原样显示以下文字，该文件不会发送。

标签上显示的文字原因 · 处理
「无法上传此文件格式。请上传 Office（xlsx·xls·csv·docx·pptx）·PDF·图纸（DXF·PDF）·视频（mp4·mov·mkv·webm）·音频（m4a·mp3·wav）文件」不是可接受的格式。格式按内容判定，仅改扩展名无法放入
「视频·音频文件的名称与内容不符 …」扩展名是视频 · 音频，但文件头并非该格式。若是在转换工具中只改了扩展名的文件，请按原格式重新导出
「视频·音频文件过大（最大 1GB）」视频 · 音频最大 1GB。请拆分或降低分辨率后放入
「视频·音频过长（最长 60 分钟）。请剪切后上传」超过 60 分钟。不会只接收开头部分 —— 请剪切后分开放入
「当前等待转写的文件过多。请稍后重新上传」整个部署中等待转写或正在上传的视频 · 音频已有 4 个。待前面的处理完后重新放入
「无法读取 DWG。请导出为 DXF 或 PDF 后上传」在 CAD 中导出为 DXF 或 PDF 后放入
「照片请作为图片附加（放到输入框即可作为图片附加）」照片文件走了附件通道。重新放入输入框即可作为照片附加
「文件过大（最大 50MB）」单个文件最大 50MB。请拆分后放入
「一个对话最多可上传 20 个文件」该对话中已有 20 个。请在新对话中放入
「文件为空」0 字节的文件
「未能读取此文件：已损坏或未能完整接收」文件已损坏或上传中断。打开原件确认后重新放入
「文件结构过大，未予接收（解压后大小·条目数上限）」Office 文件内的条目超过 2 万个，或解压后大小超过 500MB
「未能保存文件。请稍后重新上传」未能写入对象存储。请查看副驾驶日志与对象存储状态

上传后识读失败的情况 —— 标签上显示「未能读取此文件：原因」。原因是服务器留下的英文句子。该文件仍可发送， AI 会将其视为«未能读取的文件»。

提示原因起因 · 处理
document reader unreachable · drawing reader unreachable无法连接文档理解服务。请确认 plantpulse-document-understanding-api 是否在运行
document reader is not configured副驾驶中没有文档理解服务的地址。默认 compose 下不会出现 —— 请确认是否手动改过配置
reading took longer than 10 min识读超过 10 分钟。多为大型 PDF，或与索引作业重叠。请移除文件后在空闲时重新放入，或只截取所需页面放入
too many files are being read — remove it and add it again同时读取的文件过多。移除标签，稍后重新放入
reading was interrupted — remove the file and add it again识读期间副驾驶重启了（超过 15 分钟没有进展也会这样中止）。移除后重新放入
document reader answered 503 等数字文档理解服务繁忙或密钥不匹配。请查看文档理解日志
其他句子为文档理解服务给出的原因原文（例：无法打开的旧版 Office 文件）。请将原件另存为 PDF 或新格式（xlsx · docx · pptx）后放入

视频 · 音频转写失败的情况 —— 标签上显示「未能转写：原因」或「未予接收：原因」。原因是文档理解服务给出的英文句子原文。 连接 · 繁忙之类的临时失败会在 1 · 5 · 30 秒后重试三次，之后才判定为失败；设置 · 输入问题则立即判定为失败。 失败的文件也可以发送，原件也能播放，但 AI 会将其视为«未能转写的文件»。

提示原因起因 · 处理
media transcription is disabled: ASR_URL is not set该部署关闭了视频 · 音频。管理员在主机 env 中加入 PI_MEDIA_ENABLED=true，下载转写模型后重新启动 → 影音采集
media transcription is misconfigured: …转写设置不正确（服务名称等）。请查看文档理解的 /health 与日志
transcription service unreachable · transcription service answered 503 等无法连接文档理解服务或转写服务（plantpulse-asr），或其繁忙。确认两者都在运行后，移除并重新放入
transcription service is not configured副驾驶中没有文档理解服务的地址。默认 compose 下不会出现
「未予接收：…」（时长超限）未能从文件头读出时长而接收的文件，在转写过程中超过了 60 分钟。请剪切后放入
其他症状原因
无法点击发送，「正在读取文件 —— 读完即可发送」一直显示识读尚未结束。读完或失败后即解除。移除正在读取的文件也会解除
「附件仍在读取中。请读完后再发送」发送的瞬间服务器上仍有正在读取的文件。待标签变为«已读»后重新发送
点击标签后显示「找不到此文件。文件已删除或无权查看」文件已被删除，或是他人对话中的文件。附件只有对话所有者能打开（管理员也一样）
点击标签后显示「未能加载文件。请稍后重新打开」未能从对象存储取得原件或读取的文字
文件显示«已读»，AI 却说不知道文件内容若该用户没有聊天工具权限 tool:builtin，AI 就拿不到读取附件的工具 → 权限
AI 不知道长文档的后半部分只读取前 100 页（工作表 · 幻灯片按一个算一页）。请截取所需部分放入
PDF 图纸的尺寸 · 零件表读得不对是被按文档读取了。点击标签上的图纸按钮按图纸重新读取后再发送
放入视频提问后，AI 说「仍在转写中」转写尚未结束。5 分钟 · 200MB 以下的文件，提问最多等待 20 秒；更长的文件在后台转写。待显示「转写就绪」后重新提问
标签长时间停留在「等待转写」转写在整个部署中按放入顺序一次处理一个（短文件优先）。请等待前面的文件完成。若一直不变，请查看 [CHAT_MEDIA 日志
「未找到语音·字幕」既没有语音也没有内嵌字幕。不读取画面文字 · 叠加在画面上的字幕
视频无法播放是浏览器无法打开的编解码器（例：H.265）。转写与回答照常进行
上传大视频时出现 HTML 413代理的聊天附件路径开放到 1040MB（不遵循主机的 MEDIA_MAX_FILE_MB）。请确认是否手动更换过代理镜像，或前面是否还有其他代理

语音提问以「当前无法使用语音输入」结束​

聊天的语音提问会把录音发往文档理解服务的转录入口，文档理解再调用转录服务（plantpulse-asr）。 该提示（「…转录服务已关闭或繁忙」）意味着这条链路某处是断的。副驾驶日志中 会留下文档理解返回的状态码。

docker logs --tail=100 plantpulse-copilot-web 2>&1 | grep '\[voice\]'      # 예: [voice] doc-und answered 503: …
docker exec plantpulse-document-understanding-api printenv ASR_URL          # 비었으면 영상 · 음성이 꺼진 설치
cd /opt/kopens/plantpulse-ai-docker && bin/status.sh                        # plantpulse-asr · plantpulse-asr-audio
原因可见现象处理
视频 · 语音处于关闭状态（默认）文档理解的 ASR_URL 为空，转录入口为 503（media transcription is disabled: ASR_URL is not set）在主机 env 中填入 PI_MEDIA_ENABLED=true，拉取转录模型后 bin/restart.sh → 视频 · 语音采集
已开启但文档理解仍以旧值运行ASR_URL 依然为空改完开关后不是 docker restart，而要用 bin/restart.sh 重新创建
plantpulse-asr 为 unhealthy · 反复重启文档理解 /health 的 components.asr.status 为 down，整体 status 为 degradeddocker logs plantpulse-asr —— 若没有模型（/opt/kopens/models/Aura-ASR-Turbo），用 bin/fetch-models.sh 拉取。首次启动会因编译而耗时较久
plantpulse-asr-audio 以非 0 码退出bin/status.sh 中不是«Exited (0)»。依赖它的 plantpulse-asr 也起不来查看 docker logs plantpulse-asr-audio，确认镜像是否已拉取，然后 bin/restart.sh
转录服务繁忙与视频处理重叠的时段稍后重试

plantpulse-asr-audio 停留在«Exited (0)»是正常的 —— 它是把音频库拷到卷里就结束的一次性服务， bin/status.sh 也会把它算作正常。

其他提示原因
「语音输入仅在 HTTPS 地址下可用」浏览器在明文地址下不授予麦克风权限。请用 https:// 访问
「麦克风权限被拒绝」地址栏的锁图标 → 麦克风«允许»
「录音过长（最长 60 秒）」 · 「录音过大（最大 4MB）」单次提问上限为 60 秒 · 4MB
「没有听清语音」转录结果为空。请靠近麦克风重新说

看不到 MCP 工具​

PP_API_URL · PP_API_TOKEN 为空时栈起不来，但令牌填错时栈会正常启动，只是聊天中的平台 MCP 工具变成 0 个。因此看起来并不像「故障」。

sudo grep -E '^PP_API_(URL|TOKEN)' /etc/kopens/plantpulse-ai.env

填入值之后需要的是重新创建而非重启 —— docker restart 不会重新读取 env。

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

时序分析不工作​

docker compose logs --tail=100 plantpulse-timeseries-insight-api    # :8970
docker compose logs --tail=100 plantpulse-timeseries-insight-server # :8980 (호스트에는 안 열립니다)

这两者从平台 Aster TSDB 读取数值。请先确认上文「平台 DB」。

预测返回 500，或全部以 NAIVE 返回​

配置错误不会让服务器挂掉 —— 同一进程也提供异常检测服务，因此不会连不相关的功能一起停。先看推理服务器的 /health。

# 이 이미지에는 curl 이 없습니다 — python 으로 찌릅니다
docker compose exec plantpulse-timeseries-insight-server \
  python -c "import urllib.request; print(urllib.request.urlopen('http://localhost:8980/health').read().decode())"

models.ttm.loaded: false 为 status: "degraded" 说明预测模型没能加载，原因在 error 中。 若根本没有 models 这一项，说明是旧版本，健康检查看不出来 —— 请用下面的日志来判别。

docker compose logs plantpulse-timeseries-insight-server | grep -E 'MODEL_LOAD|WARMUP|INFER_FORECAST|fallback naive'
日志含义要做的事
[MODEL_WARMUP_FAIL] TTM ch=… 설정이 체크포인트와 맞지 않는다检查点代次与加载器类不匹配。预测为 500把 TS_TTM_MODEL_CLASS 留空（由检查点决定）或对齐代次 → 说明
[MODEL_LOAD_FAIL] … 무작위 초기화 모델로 대체하지 «않는다»同一原因。这是拒绝加载的位置同上
[MODEL_WARMUP_SKIP] TTM ch=…2026-09-21 之前版本的同一原因。该版本中预测会以 200 加 model_used="NAIVE" 返回同上
TTM 을 돌릴 데이터가 모자라다 -> fallback naive. reason=…数据不足。为 200 加 NAIVE —— 当前版本只把这一种以简单外推吸收读取 reason
TTM failed -> fallback naive. reason='<태그>_prediction_q0.1'所有预测都以 NAIVE 返回。这是装入了 R3 权重但缺少分位数列名修正的镜像（例如 2026.09-20260924-1004）重新拉取包含该修正的镜像（./update.sh）
TTM failed -> fallback naive. reason=…（其他）这是旧版本的回退 —— 该版本把数据不足以外的失败也以 200 NAIVE 吞掉了读取 reason

以 NAIVE 作答时，响应的 fallback_reason 中也会带上同样的原因 —— 在进不了日志的场合请看那里。

「全是 NAIVE」和「500」是同一种病的两个版本

配置错误伪装成简单外推的问题已在 2026-09-21 修复。旧版本可能在 /health 正常 · 预测 200 · 所有答案都悄悄是简单外推的状态下运行。无论哪个版本，要看的地方都一样 —— 上面的日志和 TS_TTM_MODEL_CLASS。

不要用版本号来判别 —— 本月的镜像会以 2026.09-<date>-<시각> 被多次重新构建。 上面的日志行才是最可靠的区分方式。

改了配置但数值一位都没变​

那就说明该配置没有生效。 模型库的参数有时会静默吞掉不认识的名称，于是给错的值被无错误地忽略。实际上异常检测的聚合·平滑参数（aggr_win_size · smoothing_window_size）在库参数改名之后一直被完全忽略地运行着（2026-07-24 审计），期间既没有错误也没有警告。

改了配置，请用«数值是否变化»来确认

「没有报错」不算确认。请比较修改前后的分数分布或检出件数，若一位都没变，就视为配置没有生效。

用极端值试一次是最快的办法 —— 把值改得很大而结果完全相同，说明该配置没有生效。

磁盘被占满​

docker system df
df -h /data1

容器日志由 Docker 轮转，不需要手动清理。多数情况是镜像和卷。

docker image prune -f      # 태그 없는 옛 이미지
不要随意执行 docker volume prune

Neo4j · Qdrant · LightRAG 的存储都在卷里。在容器停机期间执行， 知识图谱和向量索引会消失。

紧急恢复​

cd /opt/kopens/plantpulse-ai-docker/bin
./restart.sh                       # 스택 전체. 0 이면 «쓸 수 있다» 는 뜻입니다
docker compose restart plantpulse-lightrag   # 하나만

要重新拉取镜像并启动：

./update.sh
数据所在位置

LightRAG 的原始文档 · 索引 · 知识图谱都在命名 Docker 卷中 （pi-lightrag-inputs · pi-lightrag-storage · pi-qdrant-data · pi-neo4j-data，自 2026.10 起还有工厂图谱 镜像的 pi-digital-thread-neo4j-data 和时序微调权重 pi-ttm-tuned-models）。 它们不是主机目录，所以 rm -rf 删不掉；反过来，一次 docker volume prune 就会一起消失。 删除前务必备份 —— bin/backup.sh 会抓取 compose 卷（日志 · 缓存除外）。

参见​