跳到主要内容

故障排查

症状、原因和处理方法汇总。大多数问题通过以下 3 条命令即可缩小原因范围。

cd /opt/kopens/plantpulse-studio-docker

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

查看日志​

对象命令
Studio 服务器（最重要）docker logs -f --tail 200 pp-studio-server
网页(nginx)docker logs --tail 100 pp-studio-web
数据库(捆绑模式)docker logs --tail 100 pp-studio-postgres
构建工具边车docker logs --tail 100 pp-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 pp-studio-server
docker logs --since "2026-07-28T09:00:00" pp-studio-server
日志中不保留密钥

API 密钥和令牌不会记录在日志中(审计日志中仅保存指纹而非值)。向支持团队提供日志时，只需确认现场信息(如站点名称、设备名称)即可。

症状 → 原因快速对照表​

症状常见原因检查处理
网页完全打不开堆栈已停止运行，或 80 端口被占用bash bin/status.sh
docker logs pp-studio-web		bash bin/start.sh · 清理占用 80 端口的其他服务
网页能打开但登录失败引导账户未设置，或无法到达平台grep STUDIO_LOCAL_USERS .env
curl -s localhost:5170/health		在 .env 中指定账户后 bash bin/restart.sh
登录突然失败(稍后重试)登录速率限制(每个 IP 每分钟 10 次)docker logs --tail 50 pp-studio-server等待 1 分钟后重试
健康状态一直 DOWN，日志显示数据库认证错误存在既有数据但更改了 PG_PASSWORDdocker logs pp-studio-postgres
docker logs pp-studio-server		改回原密码，或在 PostgreSQL 内先修改账户密码
打开项目失败(500)缺少会话运行时镜像docker image inspect plantpulse-studio-runtime:latest重新运行 bash bin/start.sh (气隙环境使用 bin/load.sh 导入)
预览·部署应用显示空白页(IP 访问)防火墙阻止 5171 端口curl -I http://<server-ip>:5171/防火墙中打开 5171 端口
预览空白页 + 控制台 Mixed ContentStudio 使用 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 pp-studio-web ls /etc/nginx/conf.d将 vhost 文件名改为以 zz- 开头
部署应用中实时数据返回 401① 域名分离前登录的会话 ② 未设置平台密钥尝试登出→重新登录
环境设置 → 平台选项卡		① 重新登录一次 ② 设置 PLATFORM_API_KEY 后 bin/restart.sh
更改密钥但未生效docker restart 不会重新读取 .env环境设置界面是否显示"由环境变量管理"bash bin/restart.sh (或 docker compose up -d --force-recreate)
应用构建因"边车"错误失败构建工具边车未启动docker ps --filter name=pp-studio-agent-server
curl -s localhost:8000/health		bash bin/restart.sh · 紧急情况下可在环境设置 → 代理中将构建引擎切换为内置
聊天显示"AI 提供商无法访问"AI 地址或密钥错误，网关停止运行环境设置 → AI 选项卡的连接测试
docker logs --tail 50 pp-studio-server		修正地址和密钥 → bin/restart.sh
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/start.sh 输出的拉取结果		确认注册表登录后重新运行 bash bin/start.sh

详细诊断​

堆栈无法启动时​

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

如果容器持续重启(Restarting)，日志最后一行会显示原因。最常见的是数据库连接失败和 .env 值错误。

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

一键判定安装是否"状态正常"​

bash bin/smoke-install.sh

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

应用会话(打开项目)问题​

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 pp-studio-server | grep -i platform

如果平台短暂停止运行，观察器执行会自动跳过(重启后自动恢复)。

域名·代理问题​

症状表现多样，但原因通常是 4 项配置中有一项缺失。请对照域名和反向代理的检查清单。

恢复手段​

情况处理
误操作导致堆栈异常恢复 .env 后 bash bin/restart.sh
数据损坏备份和恢复 —— bash bin/restore.sh
更新后出现问题将 .env 中的 TAG 固定到之前的版本后 bash bin/start.sh
部署的应用出现问题在 Studio 界面的部署历史中回滚到之前的版本

提交支持申请时建议附加的信息​

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh                    > /tmp/pp-status.txt
docker logs --tail 500 pp-studio-server &> /tmp/pp-server.log
grep -vE 'KEY|TOKEN|PASSWORD' .env    > /tmp/pp-env-safe.txt   # 비밀 제외본
  • 何时开始，在何种操作下发生的问题
  • 屏幕截图(最好包含浏览器开发者工具控制台)
  • 安装版本(.env 中的 TAG)和访问方式(IP / 域名 / 是否使用代理)
传输日志·配置前的注意

.env 原始文件包含 API 密钥。请如上所述建立不含密钥的副本再传输。

相关文档​