Docs: [2.0.9] 트러블슈팅 가이드 상세화

- Nginx 404, n8n JSON 에러, Docker 쿠키 마운트 이슈 문서화
- YouTube 봇 감지 원인 및 대응 방법 정리
- 쿠키 갱신 절차에 심볼릭 링크 주의사항 추가

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/operations.md

@@ -59,6 +59,8 @@ docker compose logs -f news-summary-bot
 
 ## 트러블슈팅
 
+### 일반 에러
+
 | 증상 | 원인 | 해결 |
 |------|------|------|
 | 자막 추출 실패 (자막 없음) | 영상에 자막 없음 | 자동생성 자막이 없는 영상은 스킵됨 |
@@ -68,27 +70,66 @@ docker compose logs -f news-summary-bot
 | Claude API 오류 | API 키 만료 또는 잔액 부족 | Anthropic 콘솔에서 확인 |
 | Discord embed 글자 수 초과 | 요약이 4096자 초과 | `summarizer.py`의 `max_tokens` 줄이기 |
 
+> 에러 발생 시 FastAPI가 자동으로 Discord에 에러 상세 내용(에러 타입, 메시지, 영상 정보)을 전송합니다.
+
+### Nginx 404 에러
+
+Nginx가 `/api/news/` prefix를 strip하여 FastAPI로 전달합니다. FastAPI 내부 라우트는 `/summarize`, `/health`이며, 외부에서는 `/api/news/summarize`, `/api/news/health`로 접근합니다.
+
+- 404가 발생하면 Nginx 설정에 `/api/news/` location 블록이 있는지 확인
+- FastAPI 라우트가 prefix 없이 `/summarize`, `/health`로 되어 있는지 확인
+
+### n8n HTTP Request 에러
+
+| 증상 | 원인 | 해결 |
+|------|------|------|
+| `JSON parameter needs to be valid JSON` | 영상 제목에 큰따옴표(`"`) 포함 시 JSON 깨짐 | Specify Body를 **Expression 모드**로 설정 (Fixed 모드 사용 금지) |
+| 404 Not Found | Nginx → FastAPI 프록시 미설정 또는 라우트 불일치 | Nginx 설정 및 FastAPI 라우트 확인 |
+
+### Docker 쿠키 마운트 관련
+
+| 증상 | 원인 | 해결 |
+|------|------|------|
+| `Is a directory: '/app/cookies.txt'` | 쿠키 파일이 없는 상태에서 컨테이너 생성 시 Docker가 디렉토리로 자동 생성 | `down` + `up`으로 컨테이너 완전 재생성 (`restart`로는 안 됨) |
+| CI/CD 후 쿠키가 디렉토리로 변경됨 | `compose.apps.yml`이 심볼릭 링크일 때 상대경로 볼륨 마운트가 실제 파일 위치 기준으로 해석됨 | 볼륨 마운트에 **절대경로** 사용: `/home/ubuntu/nkeysworld/news-summary-bot/cookies.txt:/app/cookies.txt:ro` |
+| `Read-only file system: '/app/cookies.txt'` | `:ro`로 마운트된 쿠키 파일에 yt-dlp가 쓰기 시도 | 코드에서 임시 파일에 복사 후 사용 (현재 적용됨) |
+| `Requested format is not available` | yt-dlp가 영상 포맷 선택 단계에서 실패 | `extract_info()`에 `process=False` 옵션으로 포맷 처리 건너뜀 (현재 적용됨) |
+
+### YouTube 봇 감지 (클라우드 서버)
+
+YouTube는 OCI/AWS/GCP 등 **데이터센터 IP를 봇으로 감지**하여 자막 추출을 차단합니다. 도메인 유무와 무관하게 요청 출처 IP 기반으로 판단합니다.
+
+- 로컬(가정용 IP)에서는 쿠키 없이 동작
+- 서버(데이터센터 IP)에서는 반드시 YouTube 쿠키 필요
+- 로그에 `Sign in to confirm you're not a bot` 메시지가 나타나면 쿠키 만료
+
 ---
 
 ## 쿠키 갱신
 
 YouTube는 클라우드 서버 IP를 봇으로 감지하여 자막 추출을 차단합니다. 이를 우회하기 위해 브라우저 쿠키를 사용하며, 약 6개월~1년 주기로 만료됩니다.
 
-**만료 증상:** 자막 추출 시 500 에러 + 로그에 `Sign in to confirm you're not a bot` 메시지
+**만료 증상:** 자막 추출 시 500 에러 + 로그에 `Sign in to confirm you're not a bot` 메시지 + Discord 에러 알림
 
 **갱신 절차:**
 
-1. Chrome 확장 **Get cookies.txt LOCALLY**로 YouTube 쿠키 export
+1. Chrome 확장 **Get cookies.txt LOCALLY**로 YouTube 쿠키 export (youtube.com에 로그인한 상태에서)
 2. 서버에 업로드:
    ```bash
-   scp cookies.txt ubuntu@nkeystudy.site:~/nkeysworld/news-summary-bot/cookies.txt
+   scp -i <SSH_KEY_PATH> ~/Downloads/cookies.txt ubuntu@nkeystudy.site:~/nkeysworld/news-summary-bot/cookies.txt
    ```
-3. 컨테이너 재시작:
+3. 컨테이너 완전 재생성 (`restart`가 아닌 `down` + `up`):
    ```bash
-   docker compose -p nkeys-apps -f /nkeysworld/compose.apps.yml restart news-summary-bot
+   docker compose -p nkeys-apps -f /nkeysworld/compose.apps.yml down news-summary-bot
+   docker compose -p nkeys-apps -f /nkeysworld/compose.apps.yml up -d news-summary-bot
+   ```
+4. 마운트 확인:
+   ```bash
+   docker exec news-summary-bot head -3 /app/cookies.txt
    ```
 
-> `compose.apps.yml`에서 `./news-summary-bot/cookies.txt:/app/cookies.txt:ro`로 마운트되어 있어야 합니다.
+> `compose.apps.yml`에서 쿠키 볼륨은 **절대경로**로 마운트해야 합니다: `/home/ubuntu/nkeysworld/news-summary-bot/cookies.txt:/app/cookies.txt:ro`
+> (심볼릭 링크된 compose 파일에서 상대경로 사용 시 경로 해석 오류 발생)
 
 ---