a2a82084ba
All checks were successful
news-summary-bot-cicd / build_push_deploy (push) Successful in 25m15s
- README: 아키텍처, 환경변수, API 응답 형식 업데이트 - n8n-setup: RSS → YouTube Data API playlistItems 전환, 노드별 상세 설정 - development: discord.py 제거 반영, API 응답 형식 추가 - operations: CI/CD 자동 배포 설명, DISCORD_WEBHOOK_URL 제거 - testing: DISCORD_WEBHOOK_URL 더미값 제거 - .env.example: DISCORD_WEBHOOK_URL 제거 - tests/test_discord.py 삭제 (모듈 삭제됨) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
138 lines
5.4 KiB
Markdown
138 lines
5.4 KiB
Markdown
# 운영 가이드
|
|
|
|
YouTube 뉴스 요약 봇의 배포 및 운영 가이드.
|
|
|
|
**아키텍처:** n8n (YouTube Data API로 새 영상 감지) → FastAPI 앱 (자막 추출 + Claude 요약) → JSON 응답 → n8n (Discord 웹훅 전송)
|
|
|
|
---
|
|
|
|
## 배포
|
|
|
|
### CI/CD (자동)
|
|
|
|
main 브랜치에 push하면 GitHub Actions가 자동으로:
|
|
1. Docker 이미지 빌드
|
|
2. Docker Hub에 push
|
|
3. OCI 서버에서 `docker compose pull && up -d`
|
|
4. Discord에 배포 결과 알림
|
|
|
|
커밋 메시지에 `[x.y.z]` 버전 태그가 있으면 해당 버전 태그로도 이미지가 push됩니다.
|
|
|
|
### 수동 배포
|
|
|
|
```bash
|
|
# 로컬에서
|
|
docker build -t nkey/news-summary-bot:latest .
|
|
docker push nkey/news-summary-bot:latest
|
|
|
|
# OCI 서버에서
|
|
docker compose -p nkeys-apps -f /nkeysworld/compose.apps.yml pull news-summary-bot
|
|
docker compose -p nkeys-apps -f /nkeysworld/compose.apps.yml up -d news-summary-bot
|
|
```
|
|
|
|
### OCI 서버 환경변수
|
|
|
|
`.env`에 아래 값 설정:
|
|
- `ANTHROPIC_API_KEY` — Claude API 키
|
|
- `API_SECRET` — n8n에서 호출 시 인증용 시크릿
|
|
|
|
---
|
|
|
|
## 헬스체크
|
|
|
|
```bash
|
|
curl http://localhost:8000/health
|
|
```
|
|
|
|
---
|
|
|
|
## 로그 확인
|
|
|
|
```bash
|
|
docker compose logs -f news-summary-bot
|
|
```
|
|
|
|
---
|
|
|
|
## 트러블슈팅
|
|
|
|
### 일반 에러
|
|
|
|
| 증상 | 원인 | 해결 |
|
|
|------|------|------|
|
|
| 자막 추출 실패 (자막 없음) | 영상에 자막 없음 | 자동생성 자막이 없는 영상은 status: error로 반환됨 |
|
|
| 자막 추출 실패 (봇 감지) | YouTube 쿠키 만료 | 브라우저에서 쿠키 재export 후 서버에 업로드 (아래 쿠키 갱신 참고) |
|
|
| 401 Unauthorized | API_SECRET 불일치 | n8n 헤더와 `.env` 값 확인 |
|
|
| Claude API 오류 | API 키 만료 또는 잔액 부족 | Anthropic 콘솔에서 확인 |
|
|
|
|
> 에러 발생 시 FastAPI가 `status: error`로 응답하고, n8n이 Switch 노드에서 분기하여 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`로 되어 있는지 확인
|
|
|
|
### 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년 주기로 만료됩니다.
|
|
|
|
**만료 증상:** 자막 추출 에러 + 로그에 `Sign in to confirm you're not a bot` 메시지 + Discord 에러 알림
|
|
|
|
**갱신 절차:**
|
|
|
|
1. Chrome 확장 **Get cookies.txt LOCALLY**로 YouTube 쿠키 export (youtube.com에 로그인한 상태에서)
|
|
2. 서버에 업로드:
|
|
```bash
|
|
scp -i <SSH_KEY_PATH> ~/Downloads/cookies.txt ubuntu@nkeystudy.site:~/nkeysworld/news-summary-bot/cookies.txt
|
|
```
|
|
3. 컨테이너 완전 재생성 (`restart`가 아닌 `down` + `up`):
|
|
```bash
|
|
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`에서 쿠키 볼륨은 **절대경로**로 마운트해야 합니다: `/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 콘솔](https://console.anthropic.com/)에서 usage 확인
|
|
- **YouTube Data API v3:** 무료 (일일 10,000 units 쿼터, 현재 사용량 ~48 units/일)
|