Files

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

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

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

2026-03-24 17:48:35 +09:00

5.7 KiB

Raw Blame History

운영 가이드

YouTube 뉴스 요약 봇의 배포 및 운영 가이드.

아키텍처: n8n (RSS 트리거) → FastAPI 앱 (Docker 컨테이너) → Claude API → Discord 웹훅

배포 절차

1. Docker 이미지 빌드 & Push

docker build -t nkey/news-summary-bot:latest .
docker push nkey/news-summary-bot:latest

2. OCI 서버 설정

docker-compose.yml과 .env 파일을 서버에 준비
.env에 아래 값 설정:
- ANTHROPIC_API_KEY — Claude API 키
- DISCORD_WEBHOOK_URL — Discord 웹훅 URL
- API_SECRET — n8n에서 호출 시 인증용 시크릿
컨테이너 실행:

docker compose pull && docker compose up -d

3. 업데이트 시

# 로컬에서
docker build -t nkey/news-summary-bot:latest .
docker push nkey/news-summary-bot:latest

# OCI 서버에서
docker compose pull && docker compose up -d

헬스체크

curl http://localhost:8000/health

로그 확인

docker compose logs -f news-summary-bot

트러블슈팅

일반 에러

증상	원인	해결
자막 추출 실패 (자막 없음)	영상에 자막 없음	자동생성 자막이 없는 영상은 스킵됨
자막 추출 실패 (봇 감지)	YouTube 쿠키 만료	브라우저에서 쿠키 재export 후 서버에 업로드 (아래 쿠키 갱신 참고)
Discord 전송 실패	웹훅 URL 만료	Discord에서 웹훅 재생성 후 `.env` 업데이트
401 Unauthorized	API_SECRET 불일치	n8n 헤더와 `.env` 값 확인
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 메시지 + Discord 에러 알림

갱신 절차:

Chrome 확장 Get cookies.txt LOCALLY로 YouTube 쿠키 export (youtube.com에 로그인한 상태에서)

서버에 업로드:

scp -i <SSH_KEY_PATH> ~/Downloads/cookies.txt ubuntu@nkeystudy.site:~/nkeysworld/news-summary-bot/cookies.txt

컨테이너 완전 재생성 (restart가 아닌 down + up):

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

마운트 확인:

docker exec news-summary-bot head -3 /app/cookies.txt

compose.apps.yml에서 쿠키 볼륨은 절대경로로 마운트해야 합니다: /home/ubuntu/nkeysworld/news-summary-bot/cookies.txt:/app/cookies.txt:ro (심볼릭 링크된 compose 파일에서 상대경로 사용 시 경로 해석 오류 발생)

모니터링 포인트

/health 엔드포인트로 컨테이너 상태 확인
Discord 채널에 요약이 정상적으로 올라오는지 확인
docker compose logs로 에러 로그 모니터링

비용 관리

Claude Sonnet 4.6: Input $3/MTok, Output $15/MTok
일 1~2건 기준 월 ~$3 이내
Anthropic 콘솔에서 usage 확인

5.7 KiB Raw Blame History