본문으로 건너뛰기

트러블슈팅

증상별 원인과 조치를 모았습니다. 대부분의 문제는 아래 3개 명령으로 원인이 좁혀집니다.

cd /opt/kopens/plantpulse-studio-docker

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

로그 보는 법​

대상명령
스튜디오 서버(가장 중요)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 <이름>
시간대로 좁혀 보기
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-server1분 기다렸다 재시도
헬스가 계속 DOWN, 로그에 DB 인증 오류기존 데이터가 있는데 PG_PASSWORD 를 바꿈docker logs pp-studio-postgres
docker logs pp-studio-server		원래 비밀번호로 되돌리거나, PostgreSQL 안에서 계정 비밀번호를 먼저 변경
프로젝트 열기가 실패(500)세션 런타임 이미지 없음docker image inspect plantpulse-studio-runtime:latestbash bin/start.sh 재실행(에어갭은 bin/load.sh 로 반입)
프리뷰·배포앱이 빈 화면(IP 접속)방화벽에서 5171 차단curl -I http://<서버IP>:5171/방화벽에서 5171 개방
프리뷰가 빈 화면 + 콘솔 Mixed Content스튜디오는 HTTPS 인데 앱 자산이 HTTP 로 요청됨브라우저 개발자도구 콘솔프록시에 X-Forwarded-Proto $scheme 추가 → 도메인
코드를 고쳐도 프리뷰가 그대로프록시가 HMR 웹소켓을 업그레이드하지 않음개발자도구 → 네트워크 → 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.dvhost 파일명을 zz- 로 시작하게 변경
배포앱에서 실데이터가 401①도메인 분리 전에 로그인한 세션 ②플랫폼 키 미설정로그아웃→재로그인 시도
환경설정 → 플랫폼 탭		①재로그인 1회 ②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 미설치 또는 DB 도달 실패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 로 DB 도달 확인
디스크가 가득 참백업·빌드 산출물 누적df -h
du -sh dist /var/lib/pp-studio/*		보존 개수 축소(BACKUP_KEEP) · 오래된 백업 정리
업데이트했는데 옛 화면이 그대로브라우저 캐시 또는 이미지 pull 실패브라우저 강력 새로고침(Ctrl+Shift+R)
bash bin/start.sh 출력의 pull 결과		레지스트리 로그인 확인 후 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
배포한 앱에 문제 발생스튜디오 화면의 배포 이력에서 이전 버전으로 롤백

지원 요청 시 함께 보내면 좋은 것​

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 키가 들어 있습니다. 위처럼 비밀을 제외한 사본을 만들어 보내세요.

관련 문서​