# 트러블슈팅 가이드

## 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`에 위치.

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

### 해결
```bash
# 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도 그 안에 있어야 함.

### 해결
```bash
# 중첩 디렉토리에도 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` 설정:

```java
.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](crawling-guide.md) 참조.

---

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

### 증상
- VNC에서 Playwright Chromium 창이 보이다가 사라짐

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

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

```java
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만 사용하면 대부분 문제없음.

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

### 해결 (경고 제거하려면)
```bash
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 인코딩 필요):

```bash
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 클라이언트에서 접속 불가

### 확인
```bash
# VNC 서버 실행 확인
vncserver -list

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

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

### 해결
```bash
# 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](setup-xwindow.md) 참조.