sundol/docs/operation-manual.md

Sundol 운영 매뉴얼

프로세스 구성

pm2로 3개 프로세스를 관리한다.

id	name	설명
0	pdf-ocr	PDF OCR 서비스
1	sundol-backend	Spring Boot 백엔드
2	sundol-frontend	Next.js 프론트엔드

pm2 기본 명령어

# 프로세스 목록 확인
pm2 list

# 로그 확인
pm2 logs sundol-backend
pm2 logs sundol-frontend
pm2 logs pdf-ocr

# 특정 프로세스 재시작
pm2 restart sundol-backend
pm2 restart sundol-frontend
pm2 restart pdf-ocr

# 전체 재시작
pm2 restart all

# 프로세스 중지
pm2 stop sundol-backend

# 프로세스 삭제
pm2 delete sundol-backend

백엔드 시작 스크립트

파일: start-backend.sh

#!/bin/bash
set -a
source /home/opc/sundol/.env
set +a

JAVA_HOME=${JAVA_HOME:-/usr/lib/jvm/java-21}
export JAVA_HOME

# Playwright 브라우저 경로
export PLAYWRIGHT_BROWSERS_PATH=/home/opc/.cache/ms-playwright
export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1

# Playwright head 모드용 디스플레이
# :99 = Xvfb 가상 디스플레이 (브라우저 안 보임)
# :1  = VNC 디스플레이 (VNC에서 브라우저 보임)
export DISPLAY=:99

# Xvfb 가상 디스플레이 시작 (DISPLAY=:99일 때만 필요)
if ! pgrep -x Xvfb > /dev/null; then
    Xvfb :99 -screen 0 1280x720x24 -nolisten tcp &
    sleep 1
fi

BACKEND_DIR=/home/opc/sundol/sundol-backend
exec $JAVA_HOME/bin/java -cp "$BACKEND_DIR/target/classes:$BACKEND_DIR/target/dependency/*" com.sundol.SundolApplication

DISPLAY 설정 가이드

DISPLAY 값	용도
:99	Xvfb 가상 디스플레이. 브라우저가 백그라운드에서 동작 (기본값)
:1	VNC 디스플레이. VNC 접속 시 Playwright 브라우저가 화면에 보임 (디버깅용)

VNC에서 Playwright 브라우저를 직접 보려면:

1. start-backend.sh에서 export DISPLAY=:1로 변경
2. pm2 restart sundol-backend

백엔드 빌드

cd /home/opc/sundol/sundol-backend
export JAVA_HOME=/usr/lib/jvm/java-21
set -a && source /home/opc/sundol/.env && set +a
mvn package -q -DskipTests

컴파일만: mvn compile (위 환경변수 동일)

프론트엔드 빌드/배포

cd /home/opc/sundol/sundol-frontend
bash build.sh

.env에 NEXT_PUBLIC_GOOGLE_CLIENT_ID, NEXT_PUBLIC_API_URL 필수.

배포 절차

1. 코드 변경 및 빌드
2. pm2 restart sundol-backend (또는 sundol-frontend)
3. pm2 logs sundol-backend 로 정상 기동 확인
4. git push origin main

DB 접속 (Oracle Autonomous DB)

set -a && source /home/opc/sundol/.env && set +a
/home/opc/sqlcl/bin/sql ${ORACLE_USERNAME}/${ORACLE_PASSWORD}@${ORACLE_TNS_NAME}?TNS_ADMIN=${ORACLE_WALLET_PATH}

Playwright 관련

• 브라우저 경로: /home/opc/.cache/ms-playwright
• WebCrawlerService: Playwright head 모드 (setHeadless(false))
• YouTubeTranscriptService: Playwright head 모드 (setHeadless(false))
• head 모드 사용 시 DISPLAY 환경변수 필수

Playwright 의존 라이브러리

Playwright Chromium 실행에 필요한 시스템 라이브러리:

sudo dnf install -y libicu woff2 harfbuzz-icu libjpeg-turbo libwebp enchant2 hyphen libffi

libx264는 WebKit 전용이므로 Chromium만 사용할 경우 불필요. 로그에 validateDependenciesLinux 에러가 나오면 위 패키지 설치 확인.

Xvfb vs VNC 디스플레이

모드	DISPLAY	설명
Xvfb (운영)	:99	가상 프레임버퍼. 화면 없이 백그라운드 동작
VNC (디버깅)	:1	VNC 접속 시 브라우저가 화면에 보임

Xvfb 모드로 되돌리려면 start-backend.sh에서:

export DISPLAY=:99
if ! pgrep -x Xvfb > /dev/null; then
    Xvfb :99 -screen 0 1280x720x24 -nolisten tcp &
    sleep 1
fi

트러블슈팅

백엔드가 안 뜰 때

pm2 logs sundol-backend --lines 50

Playwright 브라우저가 안 열릴 때

# DISPLAY 확인
echo $DISPLAY

# Xvfb 실행 여부 확인
pgrep -x Xvfb

# VNC 실행 여부 확인
vncserver -list

# Playwright 브라우저 설치 확인
ls /home/opc/.cache/ms-playwright/

pm2 프로세스가 계속 재시작될 때

# 재시작 횟수 확인 (↺ 컬럼)
pm2 list

# 에러 로그 확인
pm2 logs sundol-backend --err --lines 100