본문으로 건너뛰기

문제 해결

증상별 원인과 조치를 모았습니다. 대부분의 문제는 아래 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
웹(nginx)docker logs --tail 100 plantpulse-studio-web
빌더 사이드카docker 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 <이름>
시간대로 좁혀 보기
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 를 실제로 굽습니다). 대시보드에서 주기적으로 호출하면 그 자체가 부하가 됩니다.

증상 → 원인 빠른 대조​

증상흔한 원인확인조치
웹 화면이 아예 안 열림스택이 내려가 있거나 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-server1분 기다렸다 재시도
헬스가 계속 DOWN, 로그에 DB 인증 오류DATABASE_URL 의 비밀번호만 바꾸고 DB 안의 역할은 안 바꿈docker logs plantpulse-studio-server
외부 PG 에서 psql 로 직접 접속		원래 비밀번호로 되돌리거나, PostgreSQL 안에서 계정 비밀번호를 먼저 변경
프로젝트 열기가 실패(500)세션 런타임 이미지 없음docker image inspect plantpulse-studio-runtime:latestbash bin/up.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 plantpulse-studio-web ls /etc/nginx/conf.dvhost 파일명을 zz- 로 시작하게 변경
배포앱에서 실데이터가 401①도메인 분리 전에 로그인한 세션 ②플랫폼 키 미설정로그아웃→재로그인 시도
환경설정 → 플랫폼 탭		①재로그인 1회 ②PLATFORM_API_KEY 설정 후 bin/restart.sh
키를 바꿨는데 반영되지 않음.env 만 고쳤고 docker restart 는 .env 를 다시 읽지 않음환경설정 화면의 배지가 환경변수 기본값 인지빠른 길 — 환경설정 화면에 새 키를 입력(재기동 없이 즉시 적용). 환경변수 쪽을 바꿔야 한다면 bash bin/restart.sh (또는 docker compose up -d --force-recreate)
앱 빌드가 "사이드카" 오류로 실패빌더 사이드카 미기동docker ps --filter name=plantpulse-studio-agent-server
curl -s localhost:8000/health		bash bin/restart.sh · 급하면 환경설정 → 에이전트에서 빌더 엔진을 내장으로 전환
채팅에 「AI 프로바이더 <주소> 에 접속할 수 없습니다. 환경설정 → AI 탭에서 주소·키를 확인하세요.」AI 주소·키 오류, 게이트웨이 다운환경설정 → AI 탭의 연결 테스트
docker logs --tail 50 plantpulse-studio-server		주소·키를 화면에서 수정 — 즉시 적용됩니다(재기동 불필요)
채팅에 「AI 프로바이더가 설정되지 않았습니다(환경설정).」AI 프로바이더가 아예 비어 있음환경설정 → AI 탭주소·키 입력 후 [연결 테스트]
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/update.sh 출력의 pull 결과		레지스트리 로그인 확인 후 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 · 웹 응답 · 실제 로그인 · 세션 런타임 이미지 · 컨테이너 상태를 순서대로 검사하고, 실패한 첫 항목을 알려 줍니다.

앱 세션(프로젝트 열기) 문제​

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

플랫폼이 잠시 내려가면 와처 실행은 자동으로 건너뜁니다(재기동 후 자동 재개).

도메인·프록시 문제​

증상이 여러 가지로 나타나지만 원인은 대개 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 의 칼버)과 접속 방식(IP / 도메인 / 프록시 유무)
로그·설정을 전달하기 전에

.env 원본에는 API 키가 들어 있습니다. 위처럼 비밀을 제외한 사본을 만들어 보내세요.

관련 문서​