sundol/docs/troubleshooting.md

트러블슈팅 가이드

1. 프론트엔드 502 Bad Gateway

증상

• 브라우저에서 502 Bad Gateway nginx/1.20.1 표시

원인

Next.js standalone 빌드 시 server.js가 sundol-frontend/ 서브디렉토리에 생성되는 경우가 있음. PM2가 .next/standalone/server.js를 찾지만 실제 파일은 .next/standalone/sundol-frontend/server.js에 위치.

확인 방법

pm2 list  # sundol-frontend 상태 확인 (errored 여부)
pm2 logs sundol-frontend --err --lines 20  # 에러 로그 확인
# "Cannot find module .../standalone/server.js" 에러가 나면 이 문제

해결

# server.js 심볼릭 링크 생성
ln -sf /home/opc/sundol/sundol-frontend/.next/standalone/sundol-frontend/server.js \
       /home/opc/sundol/sundol-frontend/.next/standalone/server.js

pm2 restart sundol-frontend

build.sh에 이미 자동 처리 로직 포함되어 있음. 문제가 반복되면 build.sh 확인.

---

2. 프론트엔드 static 파일 404

증상

• 페이지는 로드되지만 CSS/JS가 404
• 브라우저 콘솔에 _next/static/chunks/...js net::ERR_ABORTED 404 다수 표시

원인

standalone 빌드에서 .next/static 심볼릭 링크가 올바른 위치에 걸리지 않음. server.js가 standalone/sundol-frontend/ 안에서 실행되므로 static도 그 안에 있어야 함.

해결

# 중첩 디렉토리에도 static 링크 생성
ln -sf /home/opc/sundol/sundol-frontend/.next/static \
       /home/opc/sundol/sundol-frontend/.next/standalone/sundol-frontend/.next/static

pm2 restart sundol-frontend

build.sh에 자동 처리 로직 포함되어 있음.

---

3. 브라우저 로그인 모달 (HTTP Basic Auth 팝업)

증상

• 페이지 리프레시 시 브라우저 기본 로그인 팝업(username/password)이 뜸
• 특히 JWT 토큰이 만료되었거나 없을 때 발생

원인

Spring Security가 401 응답에 WWW-Authenticate: Basic 헤더를 포함. 브라우저가 이 헤더를 감지하면 자동으로 Basic Auth 로그인 다이얼로그를 표시.

해결

SecurityConfig.java에 커스텀 authenticationEntryPoint 설정:

.exceptionHandling(exceptions -> exceptions
    .authenticationEntryPoint((exchange, ex) -> {
        exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
        return exchange.getResponse().setComplete();
    })
)

이렇게 하면 WWW-Authenticate 헤더 없이 401만 반환되어 브라우저 팝업이 뜨지 않음. 프론트엔드의 axios 인터셉터가 401을 감지하여 자동으로 토큰 갱신 처리.

---

4. YouTube 자막 가져오기 실패 (Caption XML 0 chars)

증상

• YouTube 트랜스크립트 가져오기 시 "자막 텍스트를 파싱할 수 없습니다" 에러
• 로그에 Caption XML fetched: 0 chars 표시

원인

YouTube timedtext API의 caption URL이 서명 기반으로, 브라우저 세션 외부에서 요청하면 빈 응답 반환. HttpURLConnection이나 context.request().get()으로는 쿠키/세션이 유지되지 않음.

해결

두 가지 방법으로 fallback 처리:

1. 방법 A (우선): YouTube 페이지에서 '스크립트 표시' 패널을 열어 DOM에서 직접 텍스트 추출
2. 방법 B: caption URL에 &fmt=json3 추가 후 page.evaluate(fetch())로 브라우저 내에서 요청

자세한 내용은 crawling-guide.md 참조.

---

5. Playwright 브라우저 창이 사라짐

증상

• VNC에서 Playwright Chromium 창이 보이다가 사라짐

원인

page.close() 호출 시 마지막 탭이 닫히면 브라우저 창이 빈 상태가 됨.

해결

page.close() 대신 page.navigate("about:blank")으로 변경하여 탭을 유지:

try {
    page.navigate("about:blank");
} catch (Exception ignored) {
    page.close();
}

---

6. Playwright 의존 라이브러리 누락 경고

증상

• 백엔드 로그에 Host system is missing dependencies to run browsers 경고
• libicudata.so.66, libwoff2dec.so.1.0.2 등 누락 표시

원인

Playwright가 WebKit 브라우저용 의존성까지 검사함. Chromium만 사용하면 대부분 문제없음.

확인

# Chromium 실행 가능 여부 직접 테스트
/home/opc/.cache/ms-playwright/chromium-1161/chrome-linux/chrome --version

해결 (경고 제거하려면)

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

libx264는 WebKit 전용이므로 Chromium만 사용 시 불필요.

---

7. Git Push 인증 실패

증상

• git push origin main 시 could not read Username 에러

원인

.netrc이나 .git-credentials에 인증 정보가 없음.

해결

.env의 GIT_USER, GIT_PASSWORD 사용 (비밀번호에 특수문자 포함 시 URL 인코딩 필요):

set -a && source /home/opc/sundol/.env && set +a
ENCODED_PW=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$GIT_PASSWORD', safe=''))")
git push "https://${GIT_USER}:${ENCODED_PW}@gittea.cloud-handson.com/joungmin/sundol.git" main

---

8. LLM 구조화 내용이 잘림

증상

• 지식 정리(구조화) 결과가 중간에 끊김

원인

OCI GenAI의 maxTokens가 4096으로 제한되어 있어 긴 콘텐츠 정리 시 응답이 잘림.

해결

한 번에 전체를 정리하지 않고, 나눠서 요청하는 방식으로 변경:

1. 1차 호출: Abstract + 목차만 생성
2. 2차~ 호출: 목차 항목별로 상세 정리 요청 (각각 maxTokens 4096 내에서 충분)
3. 최종 조합: 모든 결과를 합침

각 섹션 완료 시 DB에 중간 저장하여 프론트엔드에서 실시간 확인 가능.

---

9. VNC 접속 안 됨

증상

• VNC 클라이언트에서 접속 불가

확인

# VNC 서버 실행 확인
vncserver -list

# 방화벽 확인
sudo firewall-cmd --list-ports

# OCI 보안 목록에서 TCP 5901 인바운드 허용 여부 확인

해결

# VNC 서버 재시작
vncserver -kill :1
vncserver :1 -geometry 1920x1080 -depth 24

# 방화벽 포트 열기
sudo firewall-cmd --permanent --add-port=5901/tcp
sudo firewall-cmd --reload

자세한 내용은 setup-xwindow.md 참조.