Files
music_quiz/docs/09-deploy-ops.md

4.2 KiB

09. 배포 · 운영

구성

인터넷 → NPMplus (192.168.10.3:443, mquiz.tkrmagid.kr, Let's Encrypt)
       → 192.168.10.9:2974 → 컨테이너 music_quiz-app:3000 (Bun)
                                 └─ /data/app.db      (SQLite, WAL)
       ↘ 음악은 각자 브라우저의 유튜브 플레이어가 재생(연령제한 곡만 서버가 받아 둔 음원 /data/audio, docs/08 §2-1)
       ↘ Lavalink 192.168.10.6:2333 (유튜브 검색·재생 가능 확인, 읽기 전용 사용)
  • 위치: .9 /home/claude/projects/music_quiz (joke-app과 같은 방식)
  • compose 프로젝트 music_quiz, 볼륨 music_quiz_app-data, 포트 2974:3000
  • 갱신: git pull && cd deploy && docker --context default compose -f docker-compose.proxy.yml up -d --build (--context default 필수 — 기본 컨텍스트가 docker5라서)
  • 컨테이너 메모리 상한 1GB, 수집기는 별도 프로세스(상한 2GB)

환경변수 (deploy/.env, 권한 600, 커밋 금지)

이름 값
PUBLIC_ORIGIN https://mquiz.tkrmagid.kr
APP_PORT 2974
SESSION_SECRET 새로 생성(32자 이상)
DISCORD_CLIENT_ID 1561284577564037140
DISCORD_CLIENT_SECRET 비밀 저장소에서 주입
SUPERADMIN_DISCORD_IDS 293719842274541579,1352267557213573160
LAVALINK_URL / LAVALINK_PW music_bot_v2 설정 재사용
YT_COOKIE_PATH /run/secrets/music_quiz/ytm_cookie.txt — compose가 지정(.env 값보다 우선). 호스트 폴더 /home/claude/.config/music_quiz를 쓰기 가능으로 연결(서버가 쿠키를 10분마다 갱신해 파일에 씀, 08 §1). 새 쿠키는 이 폴더의 ytm_cookie.txt를 바꾸면 재시작 없이 1분 안에 반영

프록시 · 인증서

  • DNS: mquiz.tkrmagid.kr → CNAME tkrmagid.kr (이미 등록돼 있음 확인)
  • NPMplus에 프록시 호스트 추가: 대상 192.168.10.9:2974, WebSocket 켜기, joke-app과 같은 보안 헤더(npmplus-advanced.conf 기반, CSP에 음원 주소 허용)
  • 인증서: Let's Encrypt, joke-app 때 쓴 인증서 스크립트 방식 그대로

백업

  • 매일 새벽 SQLite VACUUM INTO 스냅샷 → 7일 보관(.9) + 주 1회 Nextcloud /claude/music_quiz/로 복사

모니터링

  • /healthz(DB·디스크·Lavalink 연결 상태), 컨테이너 healthcheck
  • 관리자 대시보드에 수집 작업 실패, 유튜브 차단 신호, 쿠키 만료 표시
  • 주 1회 유튜브 주소 재확인(삭제·지역제한 감지 → "재생 불가"로 표시 후 재매칭)

디스크

  • .9 남은 공간 약 140GB(72% 사용). 음원은 연령제한 곡만 받아 두므로(곡당 3~5MB, 드묾) 이 프로젝트는 DB 정도만 쓴다
  • 용량이 부족해지면(남은 공간 50GB 미만) ~/disk-low-cleanup.sh가 다시 받으면 되는 설치 캐시(pip·uv·npm·bun)만 지운다(도커 빌드 캐시는 docker-disk-guard.sh). ~/.tmp·모델·프로젝트·DB·실행 중인 작업은 건드리지 않는다 (12 문서)

실제 배포 상태 (2026-10-18)

  • .9 /home/claude/projects/music_quiz (gitea main 클론), 컨테이너 music_quiz-app-1, 볼륨 music_quiz_app-data, deploy/.env 권한 600
  • NPMplus 프록시 호스트 id 14 → 192.168.10.9:2974, 고급 설정은 deploy/npmplus-advanced.conf, 인증서는 deploy/cert.sh(다시 돌려도 안전)
  • 백업(매일 VACUUM INTO)은 노래 DB가 생기는 3단계에서 붙인다
  • 수집 cron(.9 crontab, 컨테이너 안에서 docker exec): 02:00 차트, 02:20 멜론 곡 정보 1,000곡, 03:15 하이라이트 400곡(4초 간격), 03:55 난이도, 08:10 유튜브 원곡 찾기 300곡(5초 간격, 429면 멈춤 — 2026-11-03에 3,000곡에서 줄임, 04:00~08:00은 봇이 Claude를 부르지 않는 시간이라 피함), 12:30 소리 크기 재기 3,000곡(3초 간격, 새로 확정된 곡), 15:40 연령제한 곡 음원 받기 100곡(age-audio, 3초 간격), 02:50 제목 정리·정답 만들기(clean-titles, 새 곡만 — 일본어·확인 필요는 관리자 → 제목 정리 검토, docs 13). 로그 ~/music_quiz-collect.log, ~/music_quiz-match.log. 관리자 "수집" 화면에서 따로 실행·멈추기 가능
  • 9단계 전 DB 백업: ~/backups/music_quiz/app-before-stage9-*.db