# 운영 가이드

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

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

---

## 배포 절차

### 1. Docker 이미지 빌드 & Push

```bash
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에서 호출 시 인증용 시크릿
- 컨테이너 실행:

```bash
docker compose pull && docker compose up -d
```

### 3. 업데이트 시

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

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

---

## 헬스체크

```bash
curl http://localhost:8000/health
```

---

## 로그 확인

```bash
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` 줄이기 |

---

## 쿠키 갱신

YouTube는 클라우드 서버 IP를 봇으로 감지하여 자막 추출을 차단합니다. 이를 우회하기 위해 브라우저 쿠키를 사용하며, 약 6개월~1년 주기로 만료됩니다.

**만료 증상:** 자막 추출 시 500 에러 + 로그에 `Sign in to confirm you're not a bot` 메시지

**갱신 절차:**

1. Chrome 확장 **Get cookies.txt LOCALLY**로 YouTube 쿠키 export
2. 서버에 업로드:
   ```bash
   scp cookies.txt ubuntu@nkeystudy.site:~/nkeysworld/news-summary-bot/cookies.txt
   ```
3. 컨테이너 재시작:
   ```bash
   docker compose -p nkeys-apps -f /nkeysworld/compose.apps.yml restart news-summary-bot
   ```

> `compose.apps.yml`에서 `./news-summary-bot/cookies.txt:/app/cookies.txt:ro`로 마운트되어 있어야 합니다.

---

## 모니터링 포인트

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

---

## 비용 관리

- **Claude Sonnet 4.6:** Input $3/MTok, Output $15/MTok
- 일 1~2건 기준 월 ~$3 이내
- [Anthropic 콘솔](https://console.anthropic.com/)에서 usage 확인