跳到主要内容

故障排除

这里汇总了按症状分类的原因和处理方法。大多数问题可以通过以下3个命令缩小原因范围。

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh                  # ① 컨테이너 상태 + 헬스 + 세션 수
curl -s localhost:5170/health       # ② 서버가 살아 있는가
docker logs --tail 100 plantpulse-studio-server   # ③ 무엇이 잘못됐는가

如何查看日志​

对象命令
工作室服务器（最重要）docker logs -f --tail 200 plantpulse-studio-server
Web (nginx)docker logs --tail 100 plantpulse-studio-web
构建器 Sidecardocker logs --tail 100 plantpulse-studio-agent-server
使用脚本跟踪bash bin/logs.sh（默认服务器）· bash bin/logs.sh studio-web
自动备份tail -50 dist/backup.log
应用会话容器通过 docker ps --filter label=plantpulse-studio=1 确认名称后执行 docker logs <name>
按时间范围缩小范围
docker logs --since 30m plantpulse-studio-server
docker logs --since "2026-07-28T09:00:00" plantpulse-studio-server
日志中不会留下密钥

API 密钥和令牌不会记录在日志中（审计日志也只记录指纹而非值）。将日志转交给支持团队时， 只需确认站点名称和设备名称等现场信息即可。

一次性确认此安装“可以做什么”​

GET /api/v1/diagnostics     (관리자 전용)

对于“画面能显示但 PDF 不生成”“应用打不开”之类的咨询，这是首先应该查看的地方。

{"ok": true,
 "os":        {"ok": true, "detail": "Debian GNU/Linux 13"},
 "chromium":  {"ok": true, "detail": "Chromium 153…"},
 "pdf":       {"ok": true, "detail": "26568 bytes"},
 "fontsCjk":  {"ok": true, "detail": "15 faces"},
 "docker":    {"ok": true, "detail": "server 29.8.1"}}

每个项目都有 {ok, detail} ，最上面的 ok 只有在所有项目都为真时才为真。pdf 不是说明， 而是实际生成了一页韩文 PDF 的结果，docker 检查能否启动会话容器。

这是一个与 /health 不同的问题——请不要在画面上轮询

/health 是以低成本、高频率询问“是否存活”，而诊断是高成本、低频率询问“能否完成 （实际生成 PDF）”。如果在仪表板上定期调用，这本身就会造成负载。

症状 → 原因快速对照​

症状常见原因确认处理措施
Web 画面完全打不开栈已停止运行，或端口 80 被占用bash bin/status.sh
docker logs plantpulse-studio-web		bash bin/up.sh · 清理其他占用端口 80 的服务
画面能显示但登录失败引导账户未设置，或无法访问平台grep STUDIO_LOCAL_USERS .env
curl -s localhost:5170/health		在 .env 中指定账户后执行 bash bin/restart.sh
登录突然受阻（稍后重试）登录速率限制（每个 IP 每分钟 10 次）docker logs --tail 50 plantpulse-studio-server等待 1 分钟后重试
健康检查持续 DOWN，日志显示数据库认证错误只修改了 DATABASE_URL 的密码，但未修改数据库中的角色docker logs plantpulse-studio-server
在外部 PG 中通过 psql 直接连接		恢复为原始密码，或先在 PostgreSQL 中修改账户密码
项目打开失败（500）缺少会话运行时镜像docker image inspect plantpulse-studio-runtime:latest重新执行 bash bin/up.sh（隔离网络导入请使用 bin/load.sh）
预览或部署应用为空白画面（IP 访问）防火墙阻止了 5171 端口curl -I http://<server-ip>:5171/在防火墙中开放 5171
预览为空白画面 + 控制台 Mixed Content工作室使用 HTTPS，但应用资源通过 HTTP 请求浏览器开发者工具控制台在代理中添加 X-Forwarded-Proto $scheme → 域名
修改了代码但预览未更新代理未升级 HMR WebSocket开发者工具 → 网络 → WS 请求是否为 101在两个 vhost 中添加 Upgrade/Connection 标头
构建聊天耗时较长时出现“连接错误: network error”代理无传输超时（默认 60 秒）检查代理 vhost 配置在两个 vhost 中设置 proxy_read_timeout 3600s
回复不是实时的，而是成块出现proxy_buffering 已开启（默认值）同上proxy_buffering off
使用任何域名访问都跳转到错误的位置Web nginx 配置的加载顺序（第一个 server 是默认服务器）docker exec plantpulse-studio-web ls /etc/nginx/conf.d将 vhost 文件名更改为以 zz- 开头
部署应用中实时数据返回 401①在分离域名之前登录的会话 ②平台密钥未设置尝试注销→重新登录
环境设置 → 平台选项卡		①重新登录一次 ②设置 PLATFORM_API_KEY 后执行 bin/restart.sh
已修改密钥但未生效只修改了 .env ，而 docker restart 未重新读取 .env环境设置界面中的徽章是否为 환경변수 기본값快速方法 —— 在环境设置界面中输入新密钥（无需重启立即生效）。如果需要修改环境变量，请执行 bash bin/restart.sh（或 docker compose up -d --force-recreate）
应用构建因“Sidecar”错误而失败构建器 Sidecar 未启动docker ps --filter name=plantpulse-studio-agent-server
curl -s localhost:8000/health		bash bin/restart.sh · 紧急情况下，在环境设置 → 代理中将构建器引擎切换为内置
聊天中显示**「无法连接到 AI 提供商 <address>。请在环境设置 → AI 选项卡中确认地址和密钥。」**AI 地址或密钥错误，网关宕机环境设置 → AI 选项卡中的连接测试
docker logs --tail 50 plantpulse-studio-server		在画面中修改地址和密钥 — 立即生效（无需重启）
聊天中显示**「未设置 AI 提供商（环境设置）。」**AI 提供商完全为空环境设置 → AI 选项卡输入地址和密钥后点击[连接测试]
3D 或大型应用构建中途崩溃内存不足（会话容器上限 2 GB，主机可用内存不足）docker stats · free -h减少同时打开的项目 · 增加主机内存
自动备份未运行未安装 cron，或无法访问数据库cat /etc/cron.d/pp-studio-backup
tail -50 dist/backup.log		重新安装 sudo bash bin/install-backup-cron.sh · 使用 DRYRUN=1 bash bin/restore.sh 确认数据库可达性
磁盘已满备份和构建产物累积df -h
du -sh dist /var/lib/pp-studio/*		减少保留数量（BACKUP_KEEP） · 清理旧备份
更新后画面仍然显示旧内容浏览器缓存或镜像拉取失败浏览器强制刷新（Ctrl+Shift+R）
bash bin/update.sh 输出的拉取结果		确认注册表登录后重新执行 bash bin/update.sh

详细诊断​

栈无法启动时​

cd /opt/kopens/plantpulse-studio-docker
bash bin/status.sh
docker ps -a --filter name=pp-studio          # Exited 인 컨테이너 찾기
docker logs --tail 200 plantpulse-studio-server

如果容器不断重启（Restarting），日志的最后一行包含原因。最常见的是 数据库连接失败和 .env 值错误。

grep -E '^(DATABASE_URL|COMPOSE_PROFILES|PG_|DATA_ROOT|PLATFORM_API_TARGET)' .env

一次性判定安装“是否处于正常状态”​

bash bin/smoke-install.sh

按顺序检查健康检查、无认证设置 API、Web 响应、实际登录、会话运行时镜像、容器状态， 并告知第一个失败的项目。

应用会话（项目打开）问题​

docker ps --filter label=plantpulse-studio=1     # 지금 떠 있는 세션 컨테이너
docker image inspect plantpulse-studio-runtime:latest >/dev/null && echo "런타임 이미지 OK"
  • 会话容器在空闲 30 分钟后会自动回收——列表中不存在并不代表错误。
  • 服务器重启后，残留的会话容器会自动清理。
  • 多个用户同时打开时会消耗相应的内存（通过 docker stats 确认）。

平台（实时数据）连接问题​

症状通常是“聊天查询可以，但值不出来”或“设备列表为空”。

  1. 在环境设置 → 平台选项卡中确认连接状态。
  2. 确认 .env 的 PLATFORM_API_TARGET 地址是否正确。
  3. 确认是否已设置 PLATFORM_API_KEY → 密钥管理
  4. 在服务器日志中查看平台调用错误。
docker logs --tail 200 plantpulse-studio-server | grep -i platform

当平台暂时不可用时，Watcher 执行会自动跳过（重启后自动恢复）。

域名和代理问题​

症状多种多样，但原因通常是 4 个设置中缺少了一项。 请直接对照域名和反向代理中的检查清单。

恢复手段​

情况处理措施
配置错误导致栈异常恢复到 .env 后执行 bash bin/restart.sh
数据损坏备份与恢复 — bash bin/restore.sh
更新后出现问题将 .env 的 PP_IMAGE_TAG 固定为先前版本后执行 bash bin/update.sh
部署的应用出现问题在工作室界面的部署历史中回滚到先前版本

申请支持时一并发送的内容​

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh                    > /tmp/pp-status.txt
docker logs --tail 500 plantpulse-studio-server &> /tmp/pp-server.log
grep -vE 'KEY|TOKEN|PASSWORD' .env    > /tmp/pp-env-safe.txt   # 비밀 제외본
  • 从何时开始，在哪些操作下发生
  • 画面截图（包含浏览器开发者工具控制台更佳）
  • 安装版本（.env 的 PP_IMAGE_TAG，如果为空，则用 VERSION 的 CalVer）和访问方式（IP / 域名 / 是否有代理）
在发送日志或配置之前

.env 原始文件包含 API 密钥。请按照上述方法创建一个排除机密信息的副本后发送。

相关文档​