GS 인증 준비 자료

양방향 소통시스템 v2.0 (AIX-SBS-OnPrem-v2.0) GS 인증 취득을 위한 조사/정리 자료. 출처: 온라인 후기 6건(2020~2024) + 5개 인증기관 공식 안내 + 사내 상담 결과.

1. GS 인증 개요

• 평가 근거 표준: ISO/IEC 25023, 25041, 25051. 기관마다 같은 기준을 다른 관점으로 해석하므로 평가 방식에 차이가 있음.
• 평가 방식: 블랙박스 테스트 (소스코드·설계 문서는 확인하지 않고, 실행 소프트웨어만으로 평가).
• 등급 체계: 1등급 심사에서 탈락하면 2등급으로 내려가는 게 아니라 완전 탈락. 1등급/2등급은 별도 트랙으로 진행됨.
• 인증 범위: 기능리스트에 등재한 모든 기능이 시험 대상이 됨 → 범위가 넓을수록 기간·비용·결함 발생 가능성 증가. 인증이 반드시 필요한 핵심 기능만 선별하는 것이 일반적 전략.
• 소요 기간: 대기 기간(신청 후 최소 3개월 대기) + 시험 기간(인증 범위/기능 수에 따라 변동, 워크데이 기준 약 7일 사례 있음). 총 3개월 내외가 일반적.
  • 연말은 심사 신청이 몰려 일정 조정이 불리함 (8~9월 계약 → 11월 시험 진행 사례 있음).
• 비용: 수백만 원 ~ 천만 원 이상 (인증 범위와 기관에 따라 편차 큼).
• 오류 수정 기회: 시험 기간 중 원칙적으로 2회 (1차 결함보고서 → 수정 → 2차 리뷰 → 마지막 수정). 이후 회귀 테스트 진행 후 기관에서 결과보고서 작성.
  • 수정은 기관이 지정한 날짜·시간대에 기관 방화벽(원격 접속 환경)으로 들어가 진행하는 방식.
  • 기능상 결함으로 인증이 불가능할 경우, 심사 중단을 1회에 한해 요청 가능.
  • 무결점으로 통과 시 시험비 일부(약 20%) 환급 사례 있음 (매우 드문 경우).
• 시험 장소: 원칙적으로 신청 기업이 시험소에 직접 방문해 SW를 설치. 시험소 환경은 전부 한국어이며 영어 소통이 원활하지 않으므로, 통상 회사 근처 기관을 선택하는 것이 유리함.

필요 시간을 잡아먹는 실수 패턴 (후기 공통 지적)

• 급하게 신청하지 말 것. 시험 전 상담을 충분히 거쳐 기본 작업을 끝낼 수 있는 일정으로 잡을 것 (기관마다 잡혀있는 시험 일정이 다름).
• 오류 수정 기회가 2회로 제한되므로, 신청 전 자체 테스트를 최대한 진행한 뒤 시험에 들어갈 것.
• 시험 기간에는 개발자를 포함해 팀이 GS 대응에만 집중할 수 있도록 업무를 조정할 것.
• SW에 변동이 생기면 제품설명서·사용자설명서 등 서류도 함께 업데이트해야 함 — 대기 기간 중 SW 수정이 있었다면 서류 동기화 여부를 반드시 재확인.
• 실제 시험 환경(운영체제 등)과 SW의 기본 구동 환경이 다르면 문제가 되므로, 시험합의서에 기재하는 시험 환경값을 실제 운영 환경과 일치시킬 것.

사전 준비가 필요한 이유 — 인증기준 (참고: 서류/실행 SW 공통 평가 관점)

제품설명서

• 내용 일관성 유지 (용어·버전 통일)
• 확인 불가한 추상적 문구·홍보성 문구 금지
• 제조자와 공급자가 다를 경우 구분 명시
• 제약사항 정보 명시 필수

사용자설명서

• 각 기능의 용도 및 사용 방법 포함 필수
• 필수 데이터 백업·복구 방법 안내 포함
• 기술된 모든 내용이 실행 소프트웨어와 100% 동일해야 함
• 목차 및 색인 정보 포함

실행 소프트웨어

• 평가 기간 내 일정 기간 가용성 보장
• 높은 신뢰성이 요구되는 경우 회피(우회) 수단 존재
• 효율적이고 정확하게 수정/변경 가능해야 함
• 설치가 용이해야 함

2. 사내 QA 체크리스트 (프로토타입 단계부터 반영)

블랙박스 평가에서는 "사용자가 예상 밖의 행동을 했을 때" 소프트웨어가 어떻게 반응하는지가 핵심 평가 대상이 됨. 개발 초기부터 다음 항목을 반영할 것.

• 가이드 팝업 제작
• 창 크기 조절(리사이징) 시 UI 깨짐 없는지 확인
• 예외 처리
  • 사용자가 임의로 여러 버튼/메뉴를 눌러볼 때의 대응
  • 설정 파일 등이 없을 때의 에러 처리
  • 사용자가 비정상적인 값을 입력했을 때의 대응
  • 텍스트를 과도하게 길게 입력했을 때의 대응
• 프로토타입을 최대한 빨리 만들어 사내 품질팀과 공유하고 피드백 받기 — A-Z를 다 완성한 뒤 공유하지 말고, 만들어지는 대로 바로바로 확인받을 것.

3. 인증기관 5곳 비교

상담 시 반드시 확인할 것: 합격보증제 해당 여부 (한 번에 합격 시 환급액 등 조건 확인).

4. 기관별 상담 필요 서류

공통 서류 (모든 기관 공통으로 요구)

1. 기능리스트 — 스튜디오 프로그램 / 시청자 클라이언트 프로그램 / 통합관리 프로그램별로 기능을 구분해 작성.
2. 제품설명서
3. 사용자매뉴얼(취급설명서)
4. 사업자등록증
5. (해당 시) 중소기업확인서 등 수수료 할인 증빙

TTA (상암시험소)

• GS 시험인증 사전 상담요청서 (지정 워드 양식)
• 기능리스트 (지정 엑셀 양식)
• 매뉴얼 (사용자설명서, 형식 자유 — pdf/hwp/word)
• 사업자등록증
• (선택) 중소기업확인서

TTA는 품질특성별 제품 정보를 상담 전 별도로 요청함 (시험 완료 전까지 TTA와 합의 하에 변경 가능):

• 회사·제품 정보 (설립일, 자본금/매출액, 종업원 수, 주요 사업 분야, 최초 출시일, 주요 납품처)
• 기능 적합성: 제품 사용 목적 및 관련 기능
• 성능 효율성: 수용 가능 최대 동시 사용자 수 — 여기 기재한 인원수대로 실제 동시 접속 시험을 진행하므로, 과도하게 높게 잡으면 동시 접속 시 예상치 못한 오류가 결함으로 간주될 위험이 있음. 신중하게 설정할 것.
• 호환성: 연동하는 외부 제품 목록 및 연동 목적 (예: 엑셀 내보내기 기능이 있으면 엑셀을 기재)
• 사용성: 다국어 지원 언어 (다국어 설정 시 정상 작동 여부만 판단 대상)
• 신뢰성: 이중화 및 데이터 복구 기능 포함 여부
• 보안성: OpenSSL, 업데이트 서버 등 사용 여부
• 유지보수성: 라이선스 파일에 따른 기능 활성화/비활성화 가능 여부 (해당 시 담당 시험관과 반드시 사전 상의)
• 이식성: 설치 예상 소요시간, 최초 출시 여부, 이전 버전 데이터 사용 여부

또한 시험합의서를 통해 시험 대상(실행 SW, 제품설명서, 사용자설명서)과 시험 환경(OS, 하드웨어 사양, 네트워크 환경 등)을 사전 합의함 — 기재한 환경대로 시험이 진행되므로 실제 운영 환경과 반드시 일치시킬 것.

KTL (구로)

• GS인증견적의뢰서
• 제품설명서, 사용자설명서
• 사업자등록증 사본 (KTL 최초 신청 시)
• (해당 시) 중소기업확인서, 중견기업연합회/한국SW협회 회원 증빙 (수수료 할인)

KTC (군포)

• 소프트웨어 품질인증 신청서
• 소프트웨어 품질인증 사전점검 체크리스트
• 소프트웨어 품질인증 저작권확인서
• 개인정보 수집·이용 및 제3자 제공 동의서
• 온라인 신청 시 제품정보(성적서 기재정보) 입력 필요

KTR (과천)

• 사전상담 단계: GS인증 상담요청서, 소프트웨어 품질인증 신청 시 유의사항 및 고객 동의서, 개인정보 동의서, 기능리스트
• 신규신청 단계: GS인증 신청서, GS인증 신청인 확인서, (사전상담 서류 동일 재제출)
• 변경신청 단계 (인증 후 규격 추가 시): 소프트웨어 품질인증 변경신청서, 인증제품 변경 영향 분석서
• 참고: GS인증 준비를 위한 사전점검체크리스트, GS인증 기준 설명서(일반 SW용 / SaaS용 별도)

CIDI (부산)

• 절차: 기업회원 가입 → 제품설명서·사용자취급설명서 작성 → 'GS인증 사전상담요청' 메뉴에 정보 입력 및 서류 업로드 → 상담 요청 완료
• 제품설명서
• 사용자취급설명서
• 참고: GS인증 기준 설명서, GS인증 신청을 위한 체크리스트, 개요·운영환경 작성예시

5. 심사 진행 팁

• 가이드북(부가 자료) 준비 권장: SW 전문성이 높을수록 시험관이 스스로 평가하기 어려워지므로, 아래 내용을 포함한 가이드북을 준비하면 심사가 원활함.
  • 제품 구동 시 최소/권장 사양
  • 프로그램 로그 저장 위치
  • 고객지원 방식
  • 설치/삭제/실행 방법
  • 프로그램 전체 사용 목적
  • 전문 용어 및 조작 설명 (일반적이지 않은 용어가 있는 경우)
  • 모든 버튼에 대한 설명
  • 모든 입력 칸에 대한 설명 (입력 글자 제한 수 등)
  • FAQ
  • 테스트 가이드북(입력값-출력값 샘플 포함)을 제공하면 심사가 더 빠르고 효율적으로 진행됨 (사내 상담 시 확인된 팁).
• 매뉴얼 작성 시 유의사항:
  • 사용자가 실제 참고할 만한 FAQ 내용이 있어야 함.
  • 제품 버전 정보와 가이드북 버전 정보가 반드시 일치해야 함.
  • 제품 출시 이후 업데이트/오류 개선 이력이 있으면 날짜와 내용을 별첨으로 기록 (기록이 없으면 소급 작성 필요).

6. 조달청 공공조달길잡이 문의 결과 (2025-10-24)

Q1. GS인증을 SW의 핵심 기능만으로 범위를 좁혀 받아도 되는지? → 인증 범위 밖의 기능은 이후 "규격추가(업그레이드)" 형태로 재신청 가능하나, 가급적 전체 범위를 GS인증 받는 것이 좋고, 범위를 좁히면 심사위원 평가에 영향을 줄 수 있음. 규격추가는 지정된 기간 중 신청 가능하며 신청 서류는 약 17부.

• 담당: 본청 우수제품과 김보라 (042-724-7233)

Q2. 우수조달물품은 1차 심사 4회 이상 탈락 시 재신청 불가인데, 벤처나라는 여러 번 신청해도 불이익이 없는지? → 심사서(조달청 우수제품지정제도 안내책자 p.195) 기준으로 GS 인증 시 심사특례가 적용됨. 승산 여부는 해당 심사서로 자체 판단.

Q3. 우수조달물품(지정기간 3년, 1년씩 최대 3년 연장) vs 벤처나라(지정기간 6년, 연장 불가) — 어느 순서로 접근하는 게 유리한지? → 벤처나라는 실적·판로·대외적 인정 측면에서 큰 혜택이 없으므로, 조건이 충족되면 벤처나라를 거치지 않고 바로 MAS(다수공급자계약)나 우수조달로 진입하는 것이 유리. 지정기간이 끝나도 "우수조달이었다"는 이력 자체는 대외적으로 유의미하게 어필 가능.

Q4. MAS vs 우수조달물품 진입 난이도 차이 → MAS는 기존 쇼핑몰에 경쟁업체가 이미 등록되어 있으면 공고 확인 후 비교적 수월하게 진입 가능(경쟁은 필요). 유사 물품이 쇼핑몰에 없으면 공공조달성 심사를 새로 요청해야 함. 우수조달물품은 심사가 매우 까다로운 대신 진입 시 혜택이 큼. (추가 확인 필요 — 미확정)

우수조달 지정 시 필요한 저작권 관련 서류 → 기술소명자료 중 "저작권 등록증(구 프로그램등록증) 및 프로그램 등록부(최근 3개월 이내)"가 요구됨. 한국저작권위원회에 별도로 SW 저작권 등록을 진행해야 발급 가능한 것으로 추정 — 확인 필요.

7. 각 인증기관에 확인해야 할 사항 (액션 아이템)

1. 출시일 — 최초 출시 예정일 확정 필요 (TTA 품질특성별 제품 정보 등 여러 서류에서 요구됨).
2. 인증 받고자 하는 기능의 범위 (기능리스트 기반) — 메시지 수신, 날씨/버스 확인 등 생활편의기능도 인증 범위에 포함할지 여부 확인 필요. (§7 Q1 참고: 가급적 전체 포함 권장)
3. 사용자매뉴얼 작성을 위한 캡처 시점 — 매뉴얼은 모든 기능을 실제 화면으로 캡처해 설명해야 함(입력필드명/입력값 유효 범위/사용메시지 내용/메시지 표시조건 포함). 스튜디오/시청자 클라이언트/통합관리 3개 프로그램을 각각 실사용해 볼 수 있는 시점 확인 필요 (QA 단계에서 가능한지, 개발 일정상 언제인지).
4. 시청자 클라이언트 프로그램의 사용 환경 — TV로만 사용 가능한 제품인지 확인 필요. 만약 그렇다면, 매뉴얼 캡처를 카메라로 TV 화면을 촬영하는 방식으로 진행하는 것이 맞는지 확인 필요.
5. 제품 구성도 — 최신 구성도 작성 필요.
6. 저작권 정책 — 정리 필요.
7. 제품 운영환경 — 서버/클라이언트 각각의 운영환경(OS, 하드웨어 등) 최신화 필요.
8. 준수 기준 명시 — 특정 표준/권고안을 따라 구현한 경우 명시. (예시 문구: "본 제품은 소프트웨어 개발 보안을 위해 행정안전부의 C 언어 시큐어코딩가이드(2014)를 적용하여 개발되었습니다.")
9. 제한사항 및 성능 — 명시 필요.
10. 사용자 관점 서술
    • 오류 방지 (입력값 검증 등)
    • 인터페이스 설명
    • 커스텀 가능한 인터페이스 여부
11. 백업 및 복구, 유지관리 내용 — 정리 필요.
12. 제품에 적용된 보안사항 — 정리 필요.
13. 생산, 설치, 고객지원 — 프로세스 정리 필요.

참고: 위 다수 항목은 "규제의 신속확인 요청서" 작성과도 연결되는 항목으로 보임.

부록: 기관별 원본 링크

• TTA: https://cs.tta.or.kr/tta/introduce/introCont.do?menuId=700&tnc_lab=T000003&up_tnc_cls_no=T000020&tnc_cls_no=T000127&tabMode=cont
• KTL: https://customer.ktl.re.kr/web/contents/K101010800.do
• KTC: https://ktc.re.kr/web_united/task/task.asp?pagen=2540
• KTR: https://www.ktr.or.kr/test-evaluation/led/contentsid/2000/index.do
• CIDI: https://www.cidi.re.kr/sub06/sub06_01.php
• 조달청 우수제품지정제도 안내책자: https://www.pps.go.kr/kor/content.do?key=00302

공공 영상회의 표준 연계 아키텍처

작성 목적: 행정안전부 고시 「행정·공공기관 영상회의시스템 상호연계 기술 표준규격」 인증 대응을 위한 기술 분석 및 구현 계획 정리
현재 스택: 8x8 JaaS / lib-jitsi-meet (SFU) · Django/DRF · NHN Cloud

1. 배경 — 표준 규격이란

행정안전부는 기관마다 제각각 구축된 영상회의 시스템 간 상호 통화·회의를 가능하게 하기 위해 「행정·공공기관 영상회의시스템 상호연계 기술 표준규격」 을 고시로 제정했다. 가장 최근 개정은 2021년 12월 13일이다.

공공조달 사업 참여 또는 지자체·행정기관 네트워크 연계 시 아래 5개 요건 충족이 요구된다.

2. 5개 인증 요건 — 현황 분석

왜 JaaS만으로는 부족한가

JaaS / lib-jitsi-meet는 순수 WebRTC 스택이다. 행정기관 영상회의 인프라는 SIP(RFC 3261) 또는 H.323 기반 전용 장비 중심으로 구성되어 있어, 두 세계 사이를 잇는 별도 게이트웨이 레이어가 없으면 연결이 불가능하다.

3. 전체 아키텍처

┌─────────────────────────────────────────────────────────────┐
│                        행정기관 측                            │
│  H.323 단말 ──┐                                              │
│  SIP 소프트폰 ─┼── SIP/TLS or H.323 ──→ [ sip-gw 인스턴스 ] │
│  범정부 GW ───┘                                              │
└─────────────────────────────────────────────────────────────┘
                                │
                    ┌───────────▼───────────┐
                    │   sip-gw (신규 VM)   │
                    │ sip-gw.도메인        │
                    │                     │
                    │  Asterisk           │
                    │    ↓                │
                    │  Jigasi             │
                    │    ↓                │
                    │  E.164 레지스트리     │
                    │  (Redis 캐시)        │
                    │    ↓                │
                    │  BFCP 브리지         │
                    └───────────┬───────────┘
                                │  WebRTC (JaaS 참여자로 join)
                    ┌───────────▼───────────┐
                    │    8x8 JaaS 클라우드  │
                    │  Jitsi Videobridge   │
                    │  (SFU · 변경 없음)    │
                    └───────────┬───────────┘
                                │  WebRTC (기존 그대로)
                    ┌───────────▼───────────┐
                    │   기존 클라이언트     │
                    │  Electron 스튜디오   │
                    │  웹 클라이언트(경로당) │
                    └───────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  Django 백엔드 (icsc-platform)                          │
│  기존: 룸·JWT 관리  |  추가: E.164 API  |  추가: Jigasi 웹훅 │
└─────────────────────────────────────────────────────────────┘

핵심 원칙

• JaaS는 변경하지 않는다. Jigasi가 WebRTC 참여자로 JaaS 룸에 join하므로 JaaS 입장에서는 클라이언트 한 명이다.
• 기존 서버(icsc-platform, mch-media)는 건드리지 않는다. 신규 VM 1대만 추가한다.
• 경로당 클라이언트 영향 없음. 행정기관 연계 트래픽만 sip-gw를 경유한다.

4. sip-gw 인스턴스 상세

4-1. Asterisk

SIP 세계의 교환기 역할. 인스턴스에서 가장 먼저 외부 트래픽을 수신한다.

주요 역할

• 행정기관 SIP 단말로부터 SIP/TLS 콜 수신 (포트 5061)
• H.323 단말 인입 시 H.323 → SIP 변환 (chan_h323 또는 외부 GW 연동)
• Django E.164 API(또는 Redis 캐시)를 조회해 목적지 룸 ID 확인
• 범정부 연계 GW에 SIP trunk로 등록 — 행안부 GW 입장에서 스마트실버가 SIP 서버 한 대로 인식됨
• 내부에서 Jigasi로 콜 전달

보안 구성

4-2. Jigasi

이 아키텍처의 핵심 브리지. SIP 콜을 WebRTC로 변환해 JaaS 룸에 참여시킨다.

동작 흐름

Asterisk → [SIP 콜 전달]
  → Jigasi: Django 웹훅에 JWT 발급 요청
  → JWT 수신
  → JaaS 룸에 WebRTC 참여자로 join
  → 미디어 브리징 시작

미디어 처리

Jigasi는 Jitsi 프로젝트의 공식 컴포넌트로, JaaS 연동 레퍼런스가 공식 문서에 정리되어 있다.

4-3. E.164 레지스트리 (Redis 캐시)

Django가 원본 번호 매핑 데이터를 관리하지만, Asterisk가 콜마다 Django를 직접 호출하면 지연이 발생한다. sip-gw 내부에 Redis로 번호 매핑 테이블을 캐싱한다.

Django (원본 DB)
  → 번호 변경 시 Redis 갱신 or Asterisk reload 신호
  ↓
Redis on sip-gw (캐시)
  ← Asterisk 조회 (콜 수신 시)

번호 매핑 예시:

+82-2-XXXX-1234  →  room-id: smartsilver-gyeongrodang-42
+82-2-XXXX-1235  →  room-id: smartsilver-gyeongrodang-15

4-4. BFCP 브리지

5개 요건 중 구현 난이도가 가장 높다.

BFCP란? RFC 4582. SIP 환경에서 화면 공유 권한(floor)을 협상하는 프로토콜. H.323 환경에서는 H.239가 동일 역할을 한다.

문제: JaaS의 화면 공유는 WebRTC getDisplayMedia() 기반이며 BFCP/H.239 시그널링을 전혀 사용하지 않는다.

구현 방식 (커스텀)

SIP 단말 → BFCP floor request 수신
  → BFCP 브리지가 floor 승인
  → 헤드리스 브라우저(Puppeteer 등)가 JaaS 룸에서 화면 공유 세션 시작
  → SIP 단말의 H.239 콘텐츠 스트림을 두 번째 비디오 트랙으로 JaaS에 publish

표준 구현체가 없어 직접 개발이 필요하다. 인증 심사에서 이 요건을 어느 수준까지 검증하는지 먼저 확인하고 작업 범위를 결정하는 것을 권장한다.

4-5. 포트 정리

5. Django 추가 API

기존 icsc-platform에 엔드포인트 2개만 추가한다. 기존 룸·JWT 관리 로직은 변경하지 않는다.

5-1. E.164 번호 ↔ 룸 매핑 CRUD API

GET    /api/sip/numbers/              # 전체 번호 매핑 목록
POST   /api/sip/numbers/              # 번호 등록
PATCH  /api/sip/numbers/{number}/     # 매핑 수정
DELETE /api/sip/numbers/{number}/     # 번호 삭제

Asterisk가 콜 수신 시 이 API(또는 Redis 캐시)를 조회해 목적지 룸 ID를 얻는다. 번호 변경 시 Redis 갱신 신호도 여기서 발송한다.

5-2. Jigasi 웹훅 (JWT 발급)

POST /api/sip/jwt/
Body: { "room_id": "smartsilver-gyeongrodang-42" }
Response: { "jwt": "<JaaS JWT token>" }

Jigasi가 JaaS 룸에 join하려면 유효한 JWT가 필요하다. Jigasi가 이 엔드포인트를 호출하면 Django가 기존 JWT 발급 로직을 재사용해 토큰을 돌려준다. 기존 코드를 감싸는 얇은 레이어다.

6. 서버 구성 요약

7. 구현 우선순위

난이도와 의존성을 고려한 권장 순서다.

1단계  Asterisk 설치 + SIP 수신 기본 동작 확인
         ↓
2단계  Jigasi 설치 + JaaS 룸 join 연동 검증
         ↓
3단계  Django E.164 API + Redis 캐시 구성
         ↓
4단계  범정부 연계 GW에 SIP trunk 등록
         ↓
5단계  BFCP 브리지 (심사 요건 수준 확인 후 범위 결정)

1~4단계가 완료되면 SIP 연동·연계 GW·E.164 세 가지 요건이 충족된다. H.264는 JaaS가 이미 지원하므로 4개 요건이 동시에 해결된다. BFCP는 별도 단계로 분리 진행한다.

8. 참고 자료

• 행안부 영상회의시스템 상호연계 기술 표준규격 개정 안내 (2021.12.13)
• Jigasi 공식 GitHub
• JaaS 개발자 문서
• RFC 3261 — SIP
• RFC 4582 — BFCP
• ITU-T H.239 — 콘텐츠 공유 (H.323 환경)

2026-06-19 · Smart Silver Center(ssc-api) · Django 5.2 / DRF / Celery / Redis

경로당 관리 시스템에 "알림 허브"를 붙이는 작업의 마지막 퍼즐 — 실제로 이메일이 나가는 운영 파이프라인을 세웠다. 코드는 이미 있었지만, 비동기 발송이 동작하려면 인프라(Redis 브로커, Celery 워커, SMTP)가 받쳐줘야 한다. 그 과정을 섹션별로 남긴다.

1. 배경 — notify() 한 함수로 모든 알림이 통과한다

알림 허브의 핵심은 단일 코어 함수 notify()다. 비즈니스 이벤트(연계 공지, 긴급방송, 가족 가입)가 발생하면 이 함수를 호출하고, 함수는 이렇게 동작한다.

def notify(*, event_code, idempotency_prefix, object_id, context=None, source="ssc-api"):
    # 1. EventType 활성 확인 (없으면 조용히 return)
    # 2. is_default 템플릿 확인
    # 3. 구독자 조회 (event_type별)
    # 4. 수신자별 NotificationLog(status="queued") 생성 — idempotency_key unique로 중복 차단
    # 5. transaction.on_commit으로 Celery enqueue (호출부 트랜잭션 롤백 시 발송 안 함)
    # 반환: {"queued": N}

설계 원칙 두 가지가 인상적이었다.

• 절대 예외를 호출부로 던지지 않는다. 전체를 try/except로 감싼다. 알림 발송이 실패해도 "공지 생성" 같은 비즈니스 로직이 롤백되면 안 되기 때문.
• 동기 코어 + 비동기 발송 분리. notify()는 조회·검증·로그·enqueue까지만 동기로 하고 즉시 반환. 실제 SMTP 발송은 Celery 워커에 넘겨 뷰 응답을 막지 않는다.

진입점은 두 갈래다.

• 경로 A (코드 직접 호출): ssc-api 내부 3곳에서 함수를 그대로 호출.
• 경로 B (HTTP): POST /api/v2/notifications/notify/ — 외부 서비스용. X-Service-Token + IP 화이트리스트로 이중 방어.

(끝까지 안 만든 경로 C — Loki/Alertmanager 로그 기반 알림 — 은 다음 작업으로 남겼다.)

2. "SMTP 설정도 안 했는데 메일이 간다고?" — 착각의 정체

처음엔 테스트가 통과하니 메일이 나가는 줄 알았다. 코드를 열어보니 아니었다.

# core/base.py
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"  # 진짜 SMTP 백엔드
EMAIL_HOST = os.getenv("EMAIL_HOST")  # ← env 없으면 None → 발송 시 예외

테스트가 "성공"한 건 두 장치 덕이었다.

@override_settings(CELERY_TASK_ALWAYS_EAGER=True, DEFAULT_FROM_EMAIL="from@ssc.com")
@patch("notifications.tasks.EmailMessage.send")  # 실제 send를 mock으로 치환
def test_success_marks_sent(self, mock_send): ...

즉 테스트의 sent는 mock된 가짜 성공이지 실제 메일이 아니다. 운영에서 실제로 메일이 나가려면 세 가지가 모두 필요했다.

이 세 개를 채우는 게 이번 작업의 전부였다.

3. 왜 Celery + Redis인가 — 기술 선택의 근거

"이메일 하나 비동기로 보내는 데 굳이 Celery랑 Redis까지 필요한가?"는 정당한 질문이다. 선택지를 하나씩 따져봤다.

먼저, 왜 동기 발송은 안 되나

가장 단순한 길은 뷰 안에서 send_mail()을 그냥 호출하는 것이다. 하지만 SMTP 발송은 외부 서버(Gmail)와의 네트워크 왕복이라 수 초가 걸리고, 언제든 실패·타임아웃할 수 있다. 이걸 요청 스레드에서 동기로 하면:

• 공지 생성 API 응답이 메일 발송이 끝날 때까지 블로킹된다. 구독자가 10명이면 10번의 SMTP 왕복을 사용자가 기다린다.
• Gmail이 일시적으로 느리거나 막히면 그 API 전체가 같이 느려지거나 죽는다. 알림이 비즈니스 기능을 인질로 잡는 셈.
• gunicorn 워커 스레드가 메일 I/O에 묶여 처리량이 떨어진다.

그래서 "받아서 큐에 넣고 즉시 응답, 발송은 백그라운드에서"라는 비동기 작업 큐가 필요했다. 이 지점부터 선택지가 갈린다.

후보 비교

왜 Celery였나

• 재시도·지수 백오프가 선언형으로 내장. SMTP는 일시 실패가 흔한데, @shared_task(bind=True, max_retries=3, retry_backoff=True) 한 줄로 "실패 시 점점 간격을 늘려 3번 재시도"가 끝난다. 직접 구현하면 의외로 손이 많이 가는 부분.
• Django 생태계의 사실상 표준. autodiscover_tasks()로 각 앱의 tasks.py를 자동 수집하고, settings에 CELERY_* 네임스페이스로 통합된다. 자료·troubleshooting이 압도적으로 많다.
• 워커를 수평 확장할 수 있다. 알림량이 늘면 --concurrency를 올리거나 워커 프로세스를 추가하면 된다. 동기/스레드 방식은 여기서 막힌다.
• 로컬/테스트에서 인프라 없이 돌릴 수 있다. CELERY_TASK_ALWAYS_EAGER=True면 브로커·워커 없이 task가 그 자리에서 동기 실행된다(테스트에서 이걸 썼다). 운영과 개발의 코드가 동일한 게 큰 장점.

왜 RabbitMQ가 아니라 Redis였나

Celery의 브로커로는 RabbitMQ가 "정석"으로 꼽히지만, 이 프로젝트엔 Redis가 더 맞았다.

• 규모가 작다. 알림 메일은 초당 수천 건이 아니라 이벤트당 수~수십 건이다. RabbitMQ의 강력한 메시지 라우팅·보장은 여기선 안 쓰는 기능에 운영 복잡도만 더한다.
• 운영이 가볍다. apt install redis-server 한 번에 끝나고, localhost 바인딩만 하면 보안도 단순하다. RabbitMQ는 Erlang 런타임·vhost·exchange 설정 등 학습/운영 곡선이 가파르다.
• 브로커 + 결과 백엔드를 하나로. Celery는 작업 큐(브로커)와 결과 저장(result backend)이 둘 다 필요한데, Redis는 DB 인덱스만 나눠(/0 브로커, /1 결과) 한 서버로 둘 다 처리한다. RabbitMQ는 결과 백엔드를 따로 둬야 한다.
• 이미 친숙한 스택. 캐시·세션 용도로도 재활용 가능해 한 번 띄워두면 쓰임이 넓다.

정리하면 — "비동기 + 재시도 + 확장 가능"이 필요해서 Celery, "이 규모엔 가볍고 충분"해서 Redis. 트래픽이 폭증하거나 메시지 유실이 절대 불가한 요구가 생기면 그때 RabbitMQ로 브로커만 교체하면 된다(Celery 코드는 그대로).

4. Redis 설치 — "상황 파악 먼저"

운영 서버(Ubuntu 22.04)에 Redis를 올리기 전에, 충돌·중복을 막으려고 현재 상태부터 진단했다.

which redis-server redis-cli || echo "redis 미설치"
sudo ss -tlnp | grep 6379 || echo "6379 사용 안 함(깨끗)"
. /etc/os-release && echo "$NAME $VERSION"
ps aux | grep "[c]elery" || echo "celery 워커 없음"

결과는 "엄청 깨끗" — 미설치, 포트 비어있음, 워커 없음. 그대로 진행했다.

sudo apt update && sudo apt install -y redis-server

# 보안: localhost 전용 바인딩 확인 (Redis는 기본 인증이 없어 외부 노출이 위험)
grep -E "^bind|^protected-mode" /etc/redis/redis.conf
# → bind 127.0.0.1 -::1 / protected-mode yes  (Ubuntu 기본값이 이미 안전)

sudo systemctl enable --now redis-server

검증은 코드가 실제로 쓸 DB 인덱스까지 확인했다. 브로커는 DB 0, 결과 백엔드는 DB 1을 쓰도록 설정돼 있었다(redis://localhost:6379/0, /1).

redis-cli -n 0 set ssc:smoke ok && redis-cli -n 0 get ssc:smoke && redis-cli -n 0 del ssc:smoke
redis-cli -n 1 ping
# → OK / "ok" / (integer) 1 / PONG

5. Celery 워커 systemd 서비스 — 가장 큰 함정

기존 gunicorn.service를 본떠 워커 서비스를 만들었는데, 여기서 이번 작업에서 제일 중요한 발견이 나왔다.

gunicorn은 실행 인자로 core.incheon.wsgi:application을 줘서 settings를 강제한다. 그런데 Celery 워커에는 그런 인자가 없다. 그리고 코드의 기본 폴백은 dev로 잡혀 있다.

# manage.py — ENV_FILE에 ics/mch가 없으면 dev로 폴백
default_settings = next((s for k, s in MAP.items() if k in env_file), "core.dev.settings")

# core/celery.py — 아무것도 안 정하면 dev
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "core.dev.settings")

ENV_FILE=.env만 보고 워커를 띄우면 운영 DB가 아닌 dev DB를 바라보는 사고가 난다. 그래서 워커 서비스에 settings를 명시적으로 박았다.

[Service]
Environment="ENV_FILE=.env"
Environment="DJANGO_SETTINGS_MODULE=core.incheon.settings"   # ★ 이 한 줄이 핵심
ExecStart=/.../.venv/bin/celery -A core worker \
          --loglevel=info --concurrency=2 \
          --logfile=/var/log/ssc_api/celery_worker.log

[Unit]
Requires=redis-server.service
After=network.target redis-server.service

-A core는 core/celery.py의 app을 가리킨다 (gunicorn이 core.incheon.wsgi를 쓰는 것과 같은 core 패키지).

6. 삽질 — status=203/EXEC

첫 기동에서 워커가 바로 죽었다.

Active: activating (auto-restart) (Result: exit-code)
Process: ExecStart=... (code=exited, status=203/EXEC)

203/EXEC는 systemd가 실행 파일 자체에 도달하지 못했다는 뜻이다. celery 바이너리에 닿지도 못했으니 --logfile도 안 생겼다. 원인 후보는 셋: 경로 오타 / 실행권한 / 바이너리 부재.

진단해보니 마지막이었다. 이 브랜치는 아직 서버에 완전히 배포·동기화되지 않아 .venv/bin/celery가 없었다. uv add celery redis는 의존성 선언만 추가할 뿐, 서버에서 실제 설치는 uv sync를 해야 한다.

cd /app/smart-silver-center/ssc-api
uv sync
.venv/bin/celery --version   # 이제 동작

교훈: uv add(선언) ≠ 서버에 설치됨. 배포 서버에선 uv sync가 별도로 필요하다.

7. End-to-End 검증 — 실제 메일이 도착하다

dev 서버에서 먼저 검증(운영 적용 전 안전장치). Django shell로 본인 메일을 구독자로 등록하고 notify()를 직접 호출했다. 멱등성 skip을 피하려고 object_id에 timestamp를 넣은 게 포인트.

import time
oid = f"e2e-{int(time.time())}"   # 매번 고유 → 중복 차단에 안 걸림
result = notify(event_code="notice", idempotency_prefix="notice", object_id=oid)
# → {'queued': 1}

워커 로그가 전 구간을 증명했다.

[10:06:00] Connected to redis://localhost:6379/0
[10:06:01] celery@smartsilver-dev-server ready.
[10:18:02] Task ...send_notification_email[72b287e6...] received      ← Redis 큐에서 꺼냄
[10:18:05] Task ...send_notification_email[72b287e6...] succeeded in 2.41s  ← SMTP 발송 성공

그리고 실제 메일함에 도착. notify → Redis → Celery 워커 → SMTP → 수신 전 구간이 운영 상태로 연결됐다.

8. 배운 것들 (요약)

• 문서를 믿지 말고 코드/서버를 확인하라. 인프라 문서의 경로(/app/...), 계정(shbae), 서비스명(gunicorn-ics)이 실제 서버(/home/ubuntu/..., ubuntu, gunicorn.service)와 전부 달랐다. 진단 명령으로 실물을 확인한 게 사고를 막았다.
• 워커는 settings를 자동으로 모른다. 웹 서버가 인자로 강제하는 settings를, 백그라운드 워커는 환경변수로 명시해줘야 한다. 안 하면 dev DB로 조용히 새어 나간다.
• uv add ≠ 설치. 배포 서버에선 uv sync. 203/EXEC의 범인.
• mock된 테스트 성공 ≠ 실제 동작. 외부 I/O(SMTP)는 운영에서 한 번은 실제로 흘려봐야 한다.
• dev에서 먼저, prod는 나중. 같은 절차를 dev에서 검증한 뒤 prod에 적용하는 순서가 안전하다.
• 기술 선택은 규모에 맞춰라. 비동기·재시도·확장이 필요해서 Celery, 이 규모엔 가볍고 충분해서 Redis를 골랐다. RabbitMQ 같은 "정석"이 항상 정답은 아니다 — 요구가 커지면 그때 브로커만 교체하면 된다.

부록 — 전체 데이터 흐름

[경로 A] 코드 직접 호출 (notice/broadcasting/accounts)  ──┐
[경로 B] HTTP POST /notify/ (X-Service-Token + IP)      ──┤
[경로 C] Alertmanager webhook (미구현)                   ──┘
                          │
                          ▼
              notify() 코어 (동기, 예외 안 던짐)
                          │  NotificationLog(queued) + on_commit enqueue
                          ▼
              Redis 브로커 (DB0)  ──►  Celery 워커
                                          │  EmailMessage.send()
                                          ▼
                                    📧 SMTP → 수신

남은 작업: 경로 C(Alertmanager 어댑터) 구현 — alerts[] 배열 순회, fingerprint:status 멱등성, Bearer 인증.

분산된 Django 서버의 로그를 통합하고 이벤트 알림 보내기 (3) — 알림 아키텍처 설계: 운영 알림과 비즈니스 이벤트를 가르다

2편까지 "로그 → Loki → Ruler → Alertmanager → 알림"이라는 파이프라인을 완성했다. 자연스러운 다음 질문은 이것이다. 그럼 우리가 보내고 싶은 모든 알림을 이 Loki 파이프라인에 태우면 되는가?

답은 "아니오"였다. 이 편은 코드 한 줄보다 그 판단 과정이 핵심이다.

발단: "사용자가 등록한 이벤트를 그 사용자에게 보내고 싶다"

운영 알림(에러 급증, 서버 다운)은 Loki Ruler로 잘 잡힌다. 그런데 요구사항이 하나 더 있었다.

ssc-api의 관리 UI에서 사용자와 이벤트를 등록해두고, 해당 이벤트가 발생하면 그 사용자의 이메일로, 미리 만들어둔 템플릿을 보낸다.

처음엔 "이것도 Loki Ruler + Alertmanager로 하면 되겠지"라고 생각했다. 하지만 따져보니 잘 맞지 않았다.

개념: 운영 알림 vs 비즈니스 이벤트 알림

두 종류의 알림은 성격이 근본적으로 다르다.

Alertmanager는 본질적으로 운영자용 도구다. 수신자를 alertmanager.yml에 미리 박아두는 정적 구조라, "UI에서 사용자가 등록한 임의의 이메일에 동적으로 보낸다"와는 결이 안 맞는다. 게다가 Alertmanager가 보내는 건 집계된 alert라, 개별 이벤트의 풍부한 내용을 담기에도 제약이 있다.

함정: 매몰비용 — "이미 만들었으니까"

여기서 내가 빠질 뻔한 함정이 있다. "Loki/Alertmanager를 이만큼 구축했으니, 이걸 재활용해서 비즈니스 알림도 처리하자"는 생각이다.

이건 전형적인 매몰비용(sunk cost)의 논리다. 짚어야 할 사실은, 비즈니스 알림을 다른 방식으로 처리해도 Loki/Alertmanager는 버려지지 않는다는 것이다. 로그 통합과 Grafana 조회는 그 자체로 값을 하고, 운영 알림은 계속 Alertmanager로 나간다. 두 시스템은 공존하는 거지 택일이 아니다. 따라서 "이미 만들었으니까"는 이 결정의 근거가 못 된다.

핵심 통찰: 비즈니스 이벤트는 로그를 우회하라

결정적인 깨달음은 이거였다. 감지하려는 이벤트가 코드 안의 비즈니스 로직에서 발생한다면, 그걸 굳이 로그로 내보냈다가 다시 주워올 이유가 없다.

비즈니스 이벤트를 Loki Ruler로 잡으면 흐름이 이렇게 된다.

코드에서 이미 이벤트를 앎
  → 로그로 출력 → Alloy 수집 → Loki push
  → Ruler 폴링 평가 → Alertmanager → webhook → 발송

코드가 이미 모든 정보를 쥐고 있는데, 이 긴 우회로를 도는 것이다. 여기서 떠안는 비용이 셋이다.

• 지연 — Ruler는 폴링이라 기본 1분 단위로 늦는다.
• 유실 — 로그 로테이션, 에이전트 재시작, Loki 다운 등 단계마다 유실 지점이 생긴다. 중요한 비즈니스 알림을 로그 파이프라인 신뢰성에 맡기는 건 위험하다.
• 취약성 — 감지가 정규식 파싱에 의존하니, 로그 포맷이 한 번 바뀌면 조용히 안 잡힌다.

반대로 코드에서 직접 처리하면 즉시·확실·구조화된 채로 끝난다. "코드로 잡을 수 있는 이벤트를 로그 파이프라인으로 감지하는 것"은 안티패턴에 가깝다.

(예외: 코드를 수정할 수 없는 서드파티/레거시이거나, 순수하게 로그에만 나타나는 신호라면 Loki Ruler가 맞다. 운영 알림이 바로 이 경우다.)

패턴: 알림 허브 (Notification Hub)

그렇다면 비즈니스 알림은 어떻게 보내야 할까. 여기서 좋은 직관이 하나 있었다. "다른 서비스들도 이메일을 보낼 일이 있을 텐데, 이메일 발송 엔드포인트를 하나 만들어두면 좋지 않을까?"

이게 바로 알림 허브(notification hub) 패턴이다. ssc-api에 단일 알림 엔드포인트를 두고, 여러 서비스가 그걸 호출한다. 모든 메일이 한 지점을 통과하므로 템플릿·발송 로그·레이트리밋·수신자 정책을 일원화할 수 있다.

중요한 구분: 이 허브의 가치는 "Alertmanager webhook이라서"가 아니라 "허브를 하나 둔다"는 것 자체에 있다. 그래서 이 허브는 누가 호출하든 상관없다.

• ssc-api 자신의 비즈니스 이벤트 → 내부 함수로 직접 호출(HTTP 불필요)
• ssc-msg, 다른 서비스의 이벤트 → HTTP로 호출
• 운영 알림(Loki Ruler가 잡은 것) → Alertmanager가 webhook으로 호출

즉 비즈니스 이벤트는 Loki를 우회해 허브를 직접 부르고, 운영 알림만 Loki Ruler를 거쳐 같은 허브로 들어온다.

최종 설계: 역할 분리

정리하면 알림을 세 갈래로 나눴다.

[비즈니스 이벤트]
ssc-api 코드 ──(내부 함수 호출)──┐
ssc-msg 코드 ──(HTTP POST)───────┤
다른 서비스   ──(HTTP POST)───────┤
                                 ▼
                  ssc-api  POST /internal/notify/    ← 알림 허브
                  - event_code 로 구독자·템플릿 조회
                  - 멱등성·레이트리밋 검사 → 비동기 발송
                                 ▲
[운영 알림]                      │
Loki Ruler → Alertmanager ──(webhook)──┘
            POST /internal/notify/alertmanager/  (어댑터)

구현: 허브 데이터 모델

구현: Alertmanager 어댑터

2편에서 캡처한 webhook 페이로드를 받아 허브의 공통 발송 로직으로 넘기는 어댑터다. 페이로드 구조를 다시 보면, alerts가 배열이고 각 alert에 labels.alertname, status, fingerprint가 있었다.

ALERTNAME_TO_EVENT = {
    "GunicornErrorBurst": "ops_error_burst",
    "High5xxRate":        "ops_high_5xx",
    "SscApiNoLogs":       "ops_no_logs",
}

@require_service_token                                # 토큰 + IP 화이트리스트
def alertmanager_webhook(request):
    payload = json.loads(request.body)
    for alert in payload.get("alerts", []):           # ← 배열 순회 필수
        event_code = ALERTNAME_TO_EVENT.get(alert["labels"].get("alertname"))
        if not event_code:
            continue                                  # 매핑 없으면 스킵
        status = alert.get("status", "firing")
        notify(
            event_code=event_code,
            idempotency_key=f"{alert['fingerprint']}:{status}",  # ← status 포함
            source="alertmanager",
            extra={
                "status": status,
                "summary": alert["annotations"].get("summary"),
                "description": alert["annotations"].get("description"),
            },
        )
    return JsonResponse({"status": "ok"})

여기서 두 가지가 핵심이다.

alerts는 배열이다. Alertmanager는 group_by로 묶인 여러 alert를 한 요청에 담아 보낸다. 첫 원소만 처리하면 나머지를 놓친다.

멱등성 키에 status를 반드시 포함한다. fingerprint는 라벨 조합의 해시라 firing이든 resolved든 동일하다. fingerprint만 키로 쓰면 resolved 알림이 "이미 본 것"으로 무시된다. 그래서 fingerprint:status로 만들어 firing 1번, resolved 1번이 각각 나가되 중복은 막는다.

구현: 비즈니스 이벤트 직접 호출

ssc-api 자신의 이벤트는 HTTP를 거치지 않고 내부 함수를 부른다.

from notifications.service import notify

notify(
    event_code="message_delivery_failed",
    idempotency_key=f"msg-{msg.id}",
    source="ssc-api",
)

notify()는 어댑터와 같은 코어를 공유하므로, 운영 알림과 비즈니스 알림이 동일한 발송 로직·발송 로그를 탄다.

보안·신뢰성 체크리스트

허브는 메일을 쏘는 엔드포인트이므로 다음이 필수다.

• 노출 차단·인증 — 공개망에 두면 메일 발사대가 된다. 서비스 토큰(Bearer) + IP 화이트리스트로 잠근다. 공개 HTTPS 도메인으로 노출했다면 인증은 선택이 아니라 전제다.
• 멱등성 — idempotency_key에 unique 제약. 호출자가 재시도해도 중복 발송이 안 되게.
• 레이트리밋 — event_code별 쿨다운. 같은 이벤트 폭주 시 메일 쏟아짐 방지. Alertmanager 쪽의 그룹핑/repeat_interval이 1차 방어, 허브 쿨다운이 2차 방어.
• 비동기·재시도 — 발송은 Celery 같은 큐로 분리해 요청 경로를 막지 않게 하고, 실패는 지수 백오프로 재시도.

마치며: 이 시리즈의 핵심 교훈

세 편을 관통하는 교훈을 하나로 압축하면 이렇다.

"로그를 모으는 것"과 "이벤트를 알리는 것"은 다른 문제다. 그리고 모든 알림을 하나의 도구로 처리하려 하면 어딘가 무리가 생긴다.

• 로그 통합은 디버깅·운영 가시성이라는 본질적 가치를 준다(Loki + Grafana).
• 로그에만 나타나는 운영 신호는 Loki Ruler가 감지해 Alertmanager로 알린다.
• 코드로 잡을 수 있는 비즈니스 이벤트는 로그를 우회해 알림 허브를 직접 부른다.

도구의 화려함이 아니라 "이 신호의 출처가 어디인가"를 기준으로 경로를 나누는 것 — 그게 이 작업에서 얻은 가장 큰 설계 원칙이었다.

분산된 Django 서버의 로그를 통합하고 이벤트 알림 보내기 (2) — Loki Ruler + Alertmanager로 운영 알림 자동화하기

1편에서 두 서버의 로그를 Loki에 모았다. 이제 그 로그를 자동으로 감시하다가 조건이 충족되면 알림을 보내는 파이프라인을 만든다. 이 편은 함정이 가장 많았던 만큼, 디버깅 과정을 그대로 기록했다.

개념: Loki Ruler란

Loki Ruler는 Loki에 내장된 룰 평가 엔진이다. Prometheus의 ruler와 같은 개념으로, 일정 주기(evaluation_interval, 보통 1분)마다 LogQL 쿼리를 실행하고, 결과가 조건을 만족하면 alert를 발생시켜 Alertmanager로 보낸다.

여기서 중요한 구분. Loki 자체는 "이벤트를 감지해 메일을 보내는" 일을 하지 않는다. Loki는 저장소일 뿐이고, 실제 일꾼은 그 위에 얹은 Ruler(감지)와 Alertmanager(발송)다. 그래서 "Loki로 알림을 보낸다"는 표현은 정확히는 "Loki Ruler가 평가하고 Alertmanager가 보낸다"가 맞다.

개념: Alertmanager란

Alertmanager는 Prometheus 생태계의 알림 처리기다. 단순히 메일을 쏘는 게 아니라, 알림의 품질을 관리한다.

• 그룹핑(grouping) — 비슷한 alert를 묶어 한 번에 보낸다(메일 폭주 방지).
• 중복제거(deduplication) — 같은 alert가 여러 번 와도 한 번만 처리.
• 억제(inhibition) — 상위 알림이 떴을 때 하위 알림을 누른다.
• 무음(silence) — 점검 중에는 특정 알림을 잠시 끈다.
• 라우팅(routing) — 라벨에 따라 다른 수신자/채널로 보낸다.
• 재발송 간격(repeat_interval) — 문제가 지속될 때 얼마 만에 다시 알릴지.

직접 스크립트로 "로그 보고 메일 쏘기"를 짜면, 처음엔 30줄이면 되지만 운영하다 보면 결국 이 기능들을 하나씩 재구현하게 된다. 그래서 Alertmanager에 위임하는 게 낫다.

개념: LogQL 알림 룰은 "메트릭 쿼리"여야 한다

가장 많이 막히는 지점이다. Loki alert 룰의 expr은 숫자를 내놓는 메트릭 쿼리여야 한다. 단순히 로그를 고르는 셀렉터({service="ssc-api"} |= "ERROR")만으로는 안 된다. 반드시 count_over_time, rate, sum 같은 집계 함수로 감싸 숫자를 만든 뒤 비교해야 한다.

# ❌ 안 됨 — 로그 라인을 고를 뿐, 숫자가 아님
{service="ssc-api"} |= "ERROR"

# ✅ 됨 — 5분간 ERROR 발생 횟수를 세어 비교
sum(count_over_time({service="ssc-api"} |= "ERROR" [5m])) > 10

개념: alert의 생애주기 (inactive → pending → firing)

룰을 이해하려면 상태 전이를 알아야 한다.

• inactive — 평가됐고 조건 미충족. 평소의 정상 상태.
• pending — 조건은 충족됐지만 for에 지정한 시간만큼 아직 안 지났다. "정말 지속되는 문제인지" 기다리는 단계.
• firing — for 시간만큼 조건이 유지됐다. 실제로 alert가 Alertmanager로 발사된다.

for: 2m이면, 조건이 충족돼도 2분간 유지돼야 firing이 된다. 일시적 스파이크로 알림이 튀는 걸 막는 장치다.

개념: fake 테넌트

1편에서 Loki를 auth_enabled: false로 설정했다. 이 경우 Loki 내부의 테넌트 ID가 fake로 고정된다. 이게 룰 파일의 위치를 결정한다. 룰은 ruler.storage.local.directory 아래 fake/ 서브디렉토리에 둬야 한다. 이걸 모르면 룰을 아무리 넣어도 조용히 무시된다(에러도 안 난다).

구축 1: Alertmanager 설치 (Server C)

이미 Prometheus가 있는 Server C에 Alertmanager를 같이 둔다.

cd /tmp
VER=0.28.1   # 릴리스 페이지에서 최신 확인
wget https://github.com/prometheus/alertmanager/releases/download/v${VER}/alertmanager-${VER}.linux-amd64.tar.gz
tar xzf alertmanager-${VER}.linux-amd64.tar.gz
sudo cp alertmanager-${VER}.linux-amd64/{alertmanager,amtool} /usr/local/bin/
sudo useradd --no-create-home --shell /bin/false alertmanager
sudo mkdir -p /etc/alertmanager /var/lib/alertmanager
sudo chown -R alertmanager:alertmanager /var/lib/alertmanager

systemd 서비스로 등록한다.

# /etc/systemd/system/alertmanager.service
[Unit]
Description=Alertmanager
Wants=network-online.target
After=network-online.target

[Service]
User=alertmanager
Group=alertmanager
Type=simple
ExecStart=/usr/local/bin/alertmanager \
  --config.file=/etc/alertmanager/alertmanager.yml \
  --storage.path=/var/lib/alertmanager \
  --web.listen-address=:9093
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now alertmanager   # ← 이걸 빼먹으면 나중에 대형 삽질 (아래)

함정 ①: 서비스 등록을 빼먹으면 9093이 안 뜬다. 우리는 PoC 한다고 Alertmanager를 수동으로만 띄우다가 enable --now를 빼먹었다. 그 결과 amtool ... :9093도, curl :9093/-/reload도 전부 connection refused가 났다. "포트를 잘못 썼나?" 한참 의심했는데, 원인은 단순히 Alertmanager 프로세스가 안 떠 있던 것이었다. sudo systemctl status alertmanager / journalctl -u alertmanager 로 먼저 살아있는지 확인하는 습관이 중요하다.

설정 파일은 운영 알림을 허브로 넘기는 webhook 방식으로 둔다(3편에서 이 설계 이유를 설명한다).

# /etc/alertmanager/alertmanager.yml
route:
  receiver: 'ssc-notify-hub'
  group_by: ['alertname', 'service']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h

receivers:
  - name: 'ssc-notify-hub'
    webhook_configs:
      - url: 'https://your-api.example.com/api/internal/notify/alertmanager/'
        http_config:
          authorization:
            type: Bearer
            credentials: '<SERVICE_TOKEN>'   # 공개 엔드포인트면 인증 필수
        send_resolved: true

함정 ②: 클라우드는 보통 아웃바운드 25번 포트를 막는다. 만약 webhook 대신 Alertmanager가 직접 SMTP로 메일을 보낸다면, 포트 25는 거의 안 된다. 587(STARTTLS)이나 465(TLS) 릴레이를 써야 한다.

구축 2: Loki Ruler 활성화 (Server B)

Loki 설정 파일에 ruler 블록을 추가한다.

ruler:
  storage:
    type: local
    local:
      directory: /var/lib/loki/rules
  rule_path: /var/lib/loki/rules-temp
  alertmanager_url: http://(Server C URL):9093   # Server C 의 Alertmanager
  enable_alertmanager_v2: true
  enable_api: true
  ring:
    kvstore:
      store: inmemory

룰 파일은 fake/ 디렉토리에 둔다.

sudo mkdir -p /var/lib/loki/rules/fake

함정 ③: rule_path 디렉토리 권한과 "invalid user". 처음에 sudo install -o loki -g loki -d /var/lib/loki/rules-temp 를 실행했더니 install: invalid user 'loki' 가 떴다. 시스템에 loki라는 유저가 없었던 것이다. Loki를 어떤 유저로 실행하느냐는 환경마다 다르다. 이미 Loki가 쓰고 있는 /var/lib/loki 하위 디렉토리의 소유자를 보면 실제 실행 유저를 알 수 있다. ls -la /var/lib/loki 로 확인해 그 유저로 rule_path를 만들면 된다(root로 돈다면 그냥 mkdir만 해도 된다). rule_path는 Loki가 룰을 임시로 펼치는 작업 디렉토리라 쓰기 가능해야 한다.

구축 3: 운영 알림 룰 작성

/var/lib/loki/rules/fake/operational.yml 에 운영 신호를 감지하는 룰을 둔다. 여기엔 코드로는 잡기 어려운, 로그에만 나타나는 신호만 넣는다.

groups:
  - name: ssc-operational
    rules:
      # 에러 로그 급증
      - alert: GunicornErrorBurst
        expr: |
          sum by (service) (
            count_over_time({job="gunicorn_error", service=~"ssc-api|ssc-msg"} |= "ERROR" [5m])
          ) > 10
        for: 2m
        labels: { severity: warning, category: operational }
        annotations:
          summary: "{{ $labels.service }} 에러 로그 급증"
          description: "최근 5분간 ERROR {{ $value }}건"

      # 5xx 응답 급증
      - alert: High5xxRate
        expr: |
          sum by (service) (
            count_over_time({job="gunicorn_access", status=~"5.."} [5m])
          ) > 20
        for: 2m
        labels: { severity: critical, category: operational }
        annotations:
          summary: "{{ $labels.service }} 5xx 급증"
          description: "5분간 5xx {{ $value }}건"

      # 로그 유입 중단 = 서비스 다운 징후
      - alert: SscApiNoLogs
        expr: |
          sum(count_over_time({job="gunicorn_access", service="ssc-api"} [10m])) == 0
        for: 5m
        labels: { severity: critical, category: operational }
        annotations:
          summary: "ssc-api 로그 유입 중단"
          description: "10분간 access 로그 없음 — 서비스/수집 파이프라인 점검"

High5xxRate가 동작하는 건 1편에서 Alloy가 status를 라벨로 뽑아둔 덕분이다. 라벨이 있으니 status=~"5.." 로 바로 필터된다.

함정 ④: "로그 끊김 = 다운" 룰을 트래픽이 적은 서버에 그대로 걸지 마라. SscApiNoLogs를 사용률 0~1%인 ssc-msg에도 똑같이 걸면, 정상 상태인데도 평소 로그가 거의 없어 상시 오탐이 난다. 그래서 이 룰은 트래픽이 꾸준한 ssc-api에만 한정했다. 트래픽이 적은 서비스의 생존 확인은 access 로그가 아니라 별도 신호(heartbeat 로그, process exporter 등)로 봐야 한다.

함정 ⑤: 룰을 여러 파일에 중복으로 두지 마라. 우리는 예시로 만든 룰 파일과 운영 룰 파일을 둘 다 뒀다가, 같은 사건에 두 룰이 각각 발화해 중복 알림이 가는 구조를 만들 뻔했다. 특히 > 0 / for: 0m(에러 1건이라도 즉시) 같은 룰은 정상 운영 중에도 가끔 뜨는 ERROR에 매번 반응해 alert fatigue(전부 무시하게 됨)를 부른다. 운영 알림은 "1건이라도"가 아니라 "급증"을 잡아야 한다.

검증 1: 룰이 로드됐는가

Loki를 재시작하고 확인한다.

sudo systemctl restart loki
curl -s http://localhost:3100/loki/api/v1/rules

ssc-operational 그룹과 룰들이 보이면 로드 성공. 비어 있으면 fake/ 위치나 YAML 문법 문제다.

검증 2: 룰이 평가되고 있는가

curl -s http://localhost:3100/prometheus/api/v1/rules | python3 -m json.tool

여기서 봐야 할 필드는 state, health, lastEvaluation이다.

함정 ⑥: 재시작 직후엔 state: unknown이 정상이다. 처음 이 명령을 치면 state: "unknown", health: "unknown", lastEvaluation: "0001-01-01T00:00:00Z"(zero value)가 나온다. 이건 아직 한 번도 평가되지 않았다는 뜻이지 오류가 아니다. evaluation_interval(1분)이 지나면 첫 평가가 돌면서 health: "ok", state: "inactive"로 바뀌고 lastEvaluation이 현재 시각으로 갱신된다. 즉 1분만 기다렸다 다시 확인하면 된다.

정상 평가가 시작되면 이렇게 나온다.

{
  "state": "inactive",
  "health": "ok",
  "lastError": "",
  "lastEvaluation": "2026-06-16T16:11:54.348446425+09:00",
  "evaluationTime": 0.001854222
}

검증 3: webhook 페이로드 구조 확인 (PoC)

알림 허브를 만들기 전에, Alertmanager가 webhook으로 무엇을 보내는지 알아야 한다. 임시 수신기를 띄워 페이로드를 캡처했다. 전부 Server C(Alertmanager가 있는 곳)에서, 같은 호스트의 127.0.0.1에 두면 네트워크 고민이 없다.

# /tmp/webhook_test.py
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
class H(BaseHTTPRequestHandler):
    def do_POST(self):
        n = int(self.headers.get('Content-Length', 0))
        raw = self.rfile.read(n).decode()
        print("="*60)
        try: print(json.dumps(json.loads(raw), indent=2, ensure_ascii=False))
        except Exception: print(raw)
        self.send_response(200); self.end_headers(); self.wfile.write(b'ok')
    def log_message(self, *a): pass
print("listening on 127.0.0.1:9000")
HTTPServer(('127.0.0.1', 9000), H).serve_forever()

alertmanager.yml의 webhook url을 잠깐 http://127.0.0.1:9000/로 돌리고, alert를 주입한다.

함정 ⑦: amtool의 --alertmanager.url은 "Alertmanager 주소"다. 우리는 이걸 임시 수신기(9000)로 줬다가 헷갈렸다. 그러면 amtool이 Alertmanager가 아니라 임시 수신기한테 직접 alert를 쏘기 때문에, 수신기에 찍힌 JSON은 "amtool이 보낸 입력 형식"이지 "Alertmanager가 가공해 내보낸 webhook 출력"이 아니다(구조가 다르다 — version/status/groupLabels/fingerprint가 없다). alert는 반드시 9093(Alertmanager)에 넣고, webhook은 Alertmanager가 9000(수신기)으로 보내게 해야 한다.

올바르게는 9093에 주입한다(한글 파싱 경고를 피하려 curl/JSON 권장).

curl -X POST http://localhost:9093/api/v2/alerts \
  -H "Content-Type: application/json" \
  -d '[{"labels":{"alertname":"GunicornErrorBurst","service":"ssc-api","severity":"warning"},
       "annotations":{"summary":"ssc-api 에러 급증","description":"ERROR 15건"}}]'

group_wait(30초) 뒤에 임시 수신기에 진짜 페이로드가 찍힌다.

{
  "receiver": "ssc-notify-hub",
  "status": "firing",
  "alerts": [
    {
      "status": "firing",
      "labels": { "alertname": "GunicornErrorBurst", "service": "ssc-api", "severity": "warning" },
      "annotations": { "summary": "ssc-api 에러 급증", "description": "ERROR 15건" },
      "startsAt": "2026-06-16T15:31:51+09:00",
      "endsAt": "0001-01-01T00:00:00Z",
      "fingerprint": "d365a1e15c8e4923"
    }
  ],
  "groupLabels": { "alertname": "GunicornErrorBurst", "service": "ssc-api" },
  "version": "4",
  "groupKey": "{}:{alertname=\"GunicornErrorBurst\", service=\"ssc-api\"}"
}

이 구조가 알림 허브 어댑터 설계의 입력이 된다(3편에서 사용). 핵심은 alerts가 배열이라는 것(그룹핑으로 여러 개가 묶여 온다), 그리고 fingerprint가 라벨 해시라 멱등성 키 재료가 된다는 것이다.

검증 4: 실제 발화 테스트 (end-to-end)

마지막으로 진짜 로그를 흘려 전 구간을 확인한다. ssc-api에서 ERROR를 임계 초과로 주입한다.

for i in $(seq 1 15); do
  echo "$(date '+[%Y-%m-%d %H:%M:%S]') [ERROR] ruler firing test $i" >> /var/log/ssc_api/gunicorn_error.log
done

타임라인은 count_over_time[5m] + for: 2m + 평가주기 1분이라 이렇게 흐른다.

1. 주입 직후 — Alloy가 tail → Loki 적재. LogQL로 카운트 확인 가능.
2. ~1분 뒤 — 평가에서 > 10 충족 → state: pending.
3. ~3분 뒤 — pending 2분 경과 → state: firing → Alertmanager로 전송.

각 단계 확인:

# Loki 가 카운트를 잡는가 (Server B)
curl -sG http://localhost:3100/loki/api/v1/query \
  --data-urlencode 'query=sum by (service)(count_over_time({job="gunicorn_error", service=~"ssc-api|ssc-msg"} |= "ERROR" [5m]))'

# 룰이 pending → firing 으로 가는가 (Server B)
curl -s http://localhost:3100/prometheus/api/v1/rules | python3 -m json.tool

# Alertmanager 까지 도달하는가 (Server C)
amtool alert --alertmanager.url=http://localhost:9093

마지막 명령에서 이렇게 뜨면 성공이다.

Alertname           Starts At                Summary              State
GunicornErrorBurst  2026-06-16 07:18:54 UTC  ssc-api 에러 로그 급증   active

이로써 로그 → Loki → Ruler → Alertmanager 전 구간이 자동으로 이어진 게 검증됐다. (Starts At이 UTC인 건 Loki/Alertmanager가 UTC를 쓰기 때문 — 1편의 타임존 메모 참고.)

주입한 ERROR 라인은 5분 윈도우를 벗어나면 카운트에서 빠져 자동으로 inactive로 복귀하고, send_resolved: true 덕에 resolved alert도 한 번 정리된다.

함정 총정리

이 편에서 마주친 함정을 모으면 이렇다.

1. 서비스 등록을 빼먹으면 9093이 안 뜬다 — connection refused의 단골 원인. 프로세스 생존부터 확인.
2. 클라우드의 25번 포트 차단 — SMTP는 587/465 릴레이로.
3. rule_path 권한과 'invalid user' — 실제 Loki 실행 유저로 디렉토리를 만들어야.
4. 트래픽 적은 서버의 NoLogs 룰 오탐 — 생존 확인은 별도 신호로.
5. 룰 중복과 alert fatigue — "1건이라도"가 아니라 "급증"을.
6. 재시작 직후 state: unknown — 오류 아님, 첫 평가 대기 중.
7. amtool --alertmanager.url은 Alertmanager 주소 — 수신기 주소를 주면 안 됨.

그리고 개념적으로 가장 중요한 것: alert 룰의 expr은 반드시 집계된 메트릭 쿼리여야 한다. 로그 셀렉터만으로는 안 된다.

다음 편에서는 한 걸음 물러나, "그럼 모든 알림을 이 Loki Ruler로 처리하면 되는가?"라는 질문을 던진다. 답은 "아니오"였고, 그 이유가 이 시리즈에서 가장 중요한 설계 결정이었다.

분산된 Django 서버의 로그를 통합하고 이벤트 알림 보내기 (1) — Loki + Alloy로 분산 로그 통합하기

이 글에서는 두 서버에 흩어진 로그를 한 곳에 모으고 Grafana에서 보는 것까지 다룬다. 먼저 개념을 충분히 잡고, 실제 설정으로 넘어간다.

개념: 중앙 집중식 로깅이란

서버 한 대일 때는 tail -f /var/log/... 로 충분하다. 하지만 서비스가 여러 서버에 나뉘면, 하나의 사용자 요청이 여러 서버를 거치며 로그를 흩뿌린다. 장애를 추적하려면 각 서버를 돌아다니며 로그를 보고, 시간순으로 머릿속에서 맞춰야 한다.

중앙 집중식 로깅(centralized logging)은 각 서버의 로그를 한 저장소로 모아, 한 화면에서 검색·필터·시각화하는 구조다. 구성요소는 보통 셋이다.

1. 수집 에이전트(agent) — 각 서버에서 로그를 읽어 중앙으로 전송
2. 저장·쿼리 백엔드(store) — 로그를 모아 보관하고 검색에 응답
3. 시각화 UI — 사람이 로그를 보고 검색하는 화면

이 셋의 조합으로 가장 유명한 게 ELK 스택(Elasticsearch + Logstash + Kibana)이고, 우리가 택한 건 Grafana 진영의 Loki + Alloy + Grafana다.

개념: Loki란 무엇인가

Grafana Loki는 로그 집계 시스템이다. 한 줄로 요약하면 "메트릭의 Prometheus에 대응하는, 로그를 위한 시스템"이다.

Loki의 가장 중요한 설계 특징은 로그 본문 전체를 인덱싱하지 않는다는 점이다. Elasticsearch는 모든 단어를 색인해 풀텍스트 검색을 빠르게 하지만, 그만큼 저장·메모리 비용이 크다. 반대로 Loki는 라벨(label)만 인덱싱하고, 로그 본문은 압축해서 통째로 저장한다. 검색할 때는 라벨로 후보를 좁힌 뒤, 그 안에서 텍스트를 훑는다(grep 하듯이).

이 차이가 비용과 운영 부담을 크게 가른다.

소규모~중규모 서비스, 특히 이미 Grafana를 쓰고 있다면 Loki가 비용·일관성 면에서 합리적이다. 우리는 Server C에서 이미 Prometheus + Grafana로 메트릭을 보고 있었기 때문에, 메트릭과 로그를 같은 Grafana 안에서 나란히 보기 위해 Loki를 택했다. ELK는 Elasticsearch가 메모리를 많이 먹어 우리 규모엔 과했다.

개념: Loki와 Grafana는 별개다

여기서 흔한 오해 하나. "Loki를 설치하면 UI도 같이 깔리나?" 아니다.

Loki는 로그를 저장하고 쿼리에 응답하는 백엔드일 뿐, 자체 화면이 없다. 외부에 노출하는 건 HTTP API(/loki/api/v1/...)와 logcli라는 커맨드라인 도구 정도다. 그 Loki에 쿼리를 던져 그래프와 로그를 그려주는 건 Grafana의 몫이다. 둘은 "데이터소스 ↔ 대시보드" 관계이며, Prometheus와 Grafana가 별개인 것과 똑같다.

따라서 이미 Grafana를 운영 중이라면 Grafana를 새로 설치할 필요가 없다. 기존 Grafana에 Loki를 데이터소스로 한 줄 추가하면, 메트릭과 로그를 한 화면에서 보게 된다.

개념: Grafana Alloy (수집 에이전트)

Grafana Alloy는 로그·메트릭·트레이스를 수집해 전송하는 에이전트다. 과거의 Promtail을 잇는 후속으로, 신규 구축이라면 Alloy로 가는 게 흐름에 맞다.

우리 구조에서 Alloy는 각 서버(A, B)에서 gunicorn 로그 파일을 읽어(tail) 가공한 뒤 Loki로 push하는 역할을 한다.

왜 "앱에서 직접 push"가 아니라 "에이전트가 tail"인가

Django에서 python-logging-loki 같은 핸들러로 Loki에 직접 push하는 방법도 있다. 간단해 보이지만 권장하지 않는다. Loki가 잠깐 죽거나 네트워크가 끊기면 로그가 유실되거나, 동기 핸들러면 요청 스레드가 블로킹될 수 있다. 로깅 파이프라인의 장애가 서비스 장애로 번지는 건 피해야 한다.

그래서 Django는 파일에만 로그를 남기고, Alloy가 그 파일을 tail해서 push하는 디커플링 구조가 안정적이다. 앱은 로그만 뱉으면 되고, 전송 책임은 에이전트가 진다.

개념: 라벨 모델과 카디널리티 (가장 중요)

Loki를 쓸 때 반드시 이해해야 하는 개념이 라벨 카디널리티(label cardinality)다.

Loki는 라벨 조합마다 별도의 스트림(stream)을 만든다. 예를 들어 {service="ssc-api", level="ERROR"} 와 {service="ssc-api", level="INFO"} 는 서로 다른 스트림이다. 라벨 값의 종류가 적으면(예: service는 2종, level은 5종) 스트림 수가 관리 가능하다.

문제는 값이 무한히 다양한 것을 라벨로 만들 때 발생한다. 대표적으로 path(URL), request_id, user_id 같은 것이다. 이걸 라벨로 올리면 스트림이 수만~수백만 개로 폭발하면서 Loki가 메모리를 먹고 죽는다. 이것이 카디널리티 폭발이다.

원칙: 라벨은 종류가 적고 고정적인 것(service, host, env, level, status)만. 값이 다양한 것은 로그 본문에 두고, 검색할 때 LogQL의 라인 필터(|=)나 쿼리 타임 파싱(| regexp)으로 처리한다.

이 원칙은 2편의 알림 룰에서도 그대로 적용된다(특정 path 감지 등).

구축: Alloy 설정

이제 실제 설정이다. Alloy 설정은 HCL 비슷한 문법으로, "어디서 읽어(source) → 어떻게 가공해(process) → 어디로 보낸다(write)"는 파이프라인을 선언한다.

Server A (ssc-api)

// Loki 엔드포인트 — Server B 의 Loki 로 보낸다
loki.write "default" {
  endpoint {
    url = "http://(Server B URL):3100/loki/api/v1/push"   // Server B(통합 Loki)
  }
}

// gunicorn access 로그
loki.source.file "gunicorn_access" {
  targets = [{
    __path__ = "/var/log/ssc_api/gunicorn_access.log",
    job      = "gunicorn_access",
    host     = "ssc-api",
    service  = "ssc-api",
    env      = "production",
  }]
  forward_to = [loki.process.gunicorn_access.receiver]
}

loki.process "gunicorn_access" {
  stage.regex {
    expression = `\[(?P<timestamp>[^\]]+)\] "(?P<method>[A-Z]+) (?P<path>\S+)[^"]*" (?P<status>\d{3})`
  }
  stage.labels {
    values = { method = "", status = "" }   // method, status 만 라벨화 (path 는 일부러 제외)
  }
  forward_to = [loki.write.default.receiver]
}

// gunicorn error 로그
loki.source.file "gunicorn_error" {
  targets = [{
    __path__ = "/var/log/ssc_api/gunicorn_error.log",
    job      = "gunicorn_error",
    host     = "ssc-api",
    service  = "ssc-api",
    env      = "production",
  }]
  forward_to = [loki.write.default.receiver]
}

여기서 핵심은 stage.regex로 method, path, status를 추출하지만, stage.labels로는 method와 status만 라벨화하고 path는 일부러 뺀 부분이다. 앞서 설명한 카디널리티 원칙 그대로다. path는 URL이 무한히 다양하므로 라벨로 만들면 안 된다. (그래도 나중에 특정 path를 감지할 수 있다 — 2편에서.)

추출(extract)과 라벨화(label)의 차이: stage.regex가 뽑은 값은 임시 맵에 들어갈 뿐, stage.labels로 올리지 않으면 Loki에 저장되지 않는다. 즉 라벨로 안 올린 추출값은 버려진다. 단, 원본 로그 라인 자체는 그대로 저장되므로, 나중에 쿼리 시점에 다시 파싱해 쓸 수 있다.

Server B (ssc-msg)

거의 동일하되, 이 서버에는 Loki가 같이 떠 있으므로 localhost로 보낸다. error 로그에서는 level을 추출해 라벨화한다.

loki.write "default" {
  endpoint {
    url = "http://localhost:3100/loki/api/v1/push"
  }
}

loki.source.file "gunicorn_error" {
  targets = [{
    __path__ = "/var/log/gunicorn/error.log",
    job      = "gunicorn_error",
    host     = "ssc-msg",
    service  = "ssc-msg",
    env      = "production",
  }]
  forward_to = [loki.process.gunicorn_error.receiver]
}

loki.process "gunicorn_error" {
  stage.regex {
    expression = `\[.*?\] \[\d+\] \[(?P<level>[A-Z]+)\]`
  }
  stage.labels {
    values = { level = "" }
  }
  forward_to = [loki.write.default.receiver]
}

service 라벨(ssc-api / ssc-msg)이 두 서버를 구분하는 핵심이다. 통합 후에는 {service="ssc-api"} / {service="ssc-msg"} 로 골라보게 된다.

구축: Loki 설정 (Server B)

Loki를 통합 저장소로 Server B에 둔다. 규모가 작으니 분산 모드가 아니라 single-binary(monolithic) 모드로 충분하다.

auth_enabled: false

server:
  http_listen_port: 3100
  grpc_listen_port: 9096

common:
  instance_addr: 127.0.0.1
  path_prefix: /var/lib/loki
  storage:
    filesystem:
      chunks_directory: /var/lib/loki/chunks
      rules_directory: /var/lib/loki/rules
  replication_factor: 1
  ring:
    kvstore:
      store: inmemory

schema_config:
  configs:
    - from: 2024-01-01
      store: tsdb
      object_store: filesystem
      schema: v13
      index:
        prefix: index_
        period: 24h

limits_config:
  allow_structured_metadata: false   # Loki 3.x 에서 기본값이 바뀌어 명시 필요
  retention_period: 168h             # 7일 보관

compactor:
  working_directory: /var/lib/loki/compactor
  retention_enabled: true
  delete_request_store: filesystem

설정의 의미를 짚으면,

• auth_enabled: false — 멀티테넌시를 끈다. 단일 조직 내부용이라 인증을 Loki 자체에서 하지 않는다. 대신 네트워크로 보호해야 한다(아래 함정 참고). 이 설정 때문에 내부 테넌트 ID가 fake로 고정되는데, 이게 2편에서 룰 디렉토리 위치를 결정한다.
• tsdb + filesystem — 인덱스는 TSDB, 청크는 로컬 파일시스템에 저장. 오브젝트 스토리지(S3 등) 없이 단순하게 간다.
• retention_period: 168h — 7일치만 보관. compactor의 retention_enabled: true와 짝을 이뤄 오래된 로그를 자동 삭제한다. 이걸 안 켜면 디스크가 조용히 차오르다 어느 날 Loki가 멈춘다.

구축: Grafana에 Loki 데이터소스 등록 (Server C)

마지막으로 Server C의 기존 Grafana에 Loki를 데이터소스로 연결한다. UI에서 클릭으로 해도 되지만, 코드로 관리하려면 provisioning 파일이 깔끔하다.

# /etc/grafana/provisioning/datasources/loki.yaml
apiVersion: 1
datasources:
  - name: Loki-SSC
    type: loki
    access: proxy
    url: http://(Server B URL):3100   # Server B 의 Loki
    jsonData:
      maxLines: 1000

sudo systemctl restart grafana-server

Grafana의 Explore 탭에서 {service="ssc-api"}, {service="ssc-msg"} 가 모두 나오면 통합 성공이다.

access: proxy의 의미: 이 모드에서는 브라우저가 아니라 Grafana 서버가 직접 Loki로 통신한다. 즉 Grafana가 떠 있는 Server C에서 Loki(Server B URL:3100)로 네트워크가 뚫려 있어야 한다. 이게 막혀 있으면 "데이터소스 연결 실패"만 뜨고 원인 찾느라 헤맨다. 먼저 curl http://(Server B URL):3100/ready 로 경로부터 확인하자.

실무 함정 정리

• path를 라벨로 만들지 마라. 카디널리티 폭발의 주범이다. 우리 설정이 stage.labels에서 path를 뺀 게 정답이다.
• access: proxy는 Grafana 서버에서 Loki로 가는 경로가 필요하다. 데이터소스 연결 실패의 단골 원인.
• retention을 반드시 켜라. single-binary로 띄우면 디스크가 조용히 찬다.
• 시간 동기화와 타임존. 두 서버 시간이 어긋나면 통합 로그의 순서가 엉킨다(chrony/NTP 필수). Loki는 UTC로 저장하므로, Django는 UTC로 로깅하고 Grafana 표시 단에서 KST로 보는 게 깔끔하다. KST로 저장해두면 나중에 다른 UTC 소스와 섞일 때 고생한다.
• auth_enabled: false인 Loki(3100)는 절대 공개망에 노출하지 마라. 누구나 로그를 넣고 조회할 수 있다. 사설망/VPN 내부에만 두자.

다음 편에서는 이렇게 모인 로그를 자동으로 감시해 알림을 보내는 Loki Ruler + Alertmanager를 다룬다. 검증 과정에서 함정이 줄줄이 터지는데, 그 디버깅 과정이 사실 가장 배울 게 많았다.

분산된 Django 서버의 로그를 통합하고 이벤트 알림 보내기 (0) — 개요와 아키텍처

서로 다른 서버에서 돌아가는 여러 Django 서비스의 로그를 한 곳에 모으고, 특정 이벤트가 발생하면 메일로 알림을 받기까지의 기록. 이 시리즈는 단순한 설치 매뉴얼이 아니라, 중간에 마주친 함정과 "왜 이 선택을 했는가"라는 의사결정 과정을 함께 담았다.

왜 통합 로그였나

운영 중인 시스템에는 역할이 다른 Django 서비스가 두 대의 서버에 나뉘어 떠 있었다.

• Server A (ssc-api) — 실제 백엔드 API 서버
• Server B (ssc-msg) — 사용자 메시지를 받아 저장·처리하는 서버 (사용률은 0~1% 수준)

문제는 단순했다. 장애를 추적하려면 A에 SSH로 들어가 로그를 보고, 다시 B에 들어가 로그를 보고, 두 화면을 머릿속에서 시간순으로 맞춰야 했다. 서버가 둘이라 이 정도지, 더 늘어나면 감당이 안 된다.

그래서 목표를 두 가지로 잡았다.

1. A·B에서 각각 발생하는 로그를 한 곳(Server B)에 통합한다.
2. 통합 로그를 주기적으로 관찰하다가 특정 이벤트가 발생하면 이메일을 보낸다.

처음엔 "통합 로그 대시보드를 만든다"가 목적인 줄 알았지만, 파고들수록 진짜 목적은 이벤트 감지 → 알림이라는 걸 알게 됐다. 이 깨달음이 나중에 아키텍처를 크게 바꾼다(3편 참고).

전체 그림

최종적으로 구성한 아키텍처는 이렇다. 역시 drawio 혹은 mermaid 로 만들면 좋겠지만 귀찮으니 paint 로

[로그 수집·통합]
Server A (ssc-api) ── Alloy ──┐
                              ├──► Server B 의 Loki ◄── Alloy ── Server B (ssc-msg)
                              │
                  Server C (media) 의 Grafana 가 Loki 를 조회 (Explore/대시보드)

[운영 알림 — 로그 기반 자동 감지]
Loki Ruler ──► Alertmanager(Server C) ──(webhook)──► 알림 허브 ──► 이메일

[비즈니스 이벤트 알림 — 코드에서 직접]
ssc-api / ssc-msg 코드 ──(직접 호출)──► 알림 허브 ──► 이메일

세 대의 서버가 각자 역할을 맡는다.

이미 Server C에서 Prometheus + Grafana로 RTMP 스트림을 모니터링하고 있었다는 점이 중요하다. 메트릭을 보는 Grafana가 이미 있으니, 로그도 같은 생태계(Loki)로 묶는 게 자연스러웠다. 이 결정의 이유는 1편에서 자세히 다룬다.

기술 스택 한눈에

• Grafana Loki — 로그 집계·저장·쿼리 엔진 (메트릭의 Prometheus에 대응하는 로그 버전)
• Grafana Alloy — 로그 수집 에이전트 (Promtail의 후속)
• Grafana — 통합 로그·메트릭 시각화 UI
• Loki Ruler — 로그를 주기적으로 평가해 알림 조건을 판단하는 룰 엔진
• Alertmanager — 알림 라우팅·그룹핑·중복제거·발송
• Django — 비즈니스 이벤트를 직접 잡아 알림 허브로 보내는 애플리케이션

시리즈 구성

• 0편 (이 글) — 개요와 전체 아키텍처
• 1편 — Loki + Alloy로 분산 로그 통합하기: 중앙 집중 로깅의 개념, Loki가 무엇이고 ELK와 어떻게 다른지, Loki와 Grafana의 관계, Alloy로 로그를 수집해 한 곳에 모으고 Grafana에서 보기까지.
• 2편 — Loki Ruler + Alertmanager로 운영 알림 자동화하기: 룰 엔진과 Alertmanager의 개념, LogQL로 알림 룰 짜기, Alertmanager 설치와 연동, 그리고 검증 과정에서 줄줄이 터진 함정들.
• 3편 — 알림 아키텍처 설계: 운영 알림과 비즈니스 이벤트를 가르다: 모든 알림을 Loki로 처리하면 안 되는 이유, 매몰비용의 함정, "알림 허브" 패턴, 그리고 무엇을 어디에 태울지에 대한 설계 결정.

결과 요약

다 끝내고 나니 이런 그림이 됐다.

• 두 서버의 로그가 Server B의 Loki에 통합되어, Server C의 Grafana 한 화면에서 LogQL로 검색·디버깅이 가능해졌다.
• 에러 급증·5xx 급증·로그 유입 중단 같은 운영 신호는 Loki Ruler가 자동 감지해 Alertmanager를 거쳐 알림으로 나간다.
• 코드에서 직접 잡을 수 있는 비즈니스 이벤트는 로그 파이프라인을 우회해 알림 허브를 직접 호출한다.

핵심 교훈을 하나 미리 꼽자면 이렇다. "로그를 모으는 것"과 "이벤트를 알리는 것"은 다른 문제이며, 모든 알림을 하나의 도구로 처리하려 하면 어딘가 무리가 생긴다. 이 시리즈는 그 경계를 찾아가는 과정이기도 하다.

추가 인스턴스 없이 기존 서버 2대에 Loki와 Grafana Alloy를 올려 Django/Gunicorn 로그를 단일 관제 체계로 통합한 과정을 정리합니다.

배경

운영 중인 Smart Silver Center 프로젝트는 두 개의 Django 서비스가 서로 다른 서버에 올라가 있다.

각 서버 로그가 분산되어 있어 장애 추적이 번거로웠고, 인스턴스를 추가로 빌릴 수 없는 상황이었다. 트래픽이 거의 없는 Server B에 Loki를 올리고, 두 서버 모두 Alloy로 중앙 수집하는 구조로 결정했다.

개념 정리

Prometheus vs Loki

Loki가 로그 내용을 인덱싱하지 않는 덕분에 Elasticsearch 대비 스토리지 비용이 낮다. 대신 로그 내용으로 필터링할 때는 LogQL의 |=, | regex 등을 사용한다.

수집 에이전트 비교

Prometheus 스택:  node_exporter(/metrics 노출) ← Prometheus(scrape, PULL)
Loki 스택:        Alloy(tail 후 push, PUSH)    → Loki

node_exporter : Promtail = Prometheus : Loki 구조로 이해하면 쉽다. 단, 결정적인 차이는 수집 주체다.

• Prometheus: Prometheus 자신이 각 서버에 접속해 데이터를 가져간다 (PULL)
• Loki: 각 서버에 설치된 Agent가 Loki로 데이터를 밀어넣는다 (PUSH)

Grafana Alloy (구 Promtail)

Promtail은 2026년 3월 2일 EOL이 됐다. Grafana Labs는 logs / metrics / traces / profiles를 하나의 바이너리로 처리하는 Grafana Alloy로 통합했다. 링크

• Promtail: YAML 설정, Loki 전용
• Alloy: 컴포넌트 기반 파이프라인 문법(.alloy), OpenTelemetry 호환, Loki/Prometheus/Tempo 모두 지원

Promtail config는 alloy convert --source-format=promtail 명령으로 자동 변환 가능하다.

최종 아키텍처

[Server A]  Alloy ──┐
                     ├──(push)──→ [Server B] Loki :3100 ←── [Server C] Grafana
[Server B]  Alloy ──┘

Step 1 — Loki 설치 (Server B)

바이너리 설치

cd ~
wget https://github.com/grafana/loki/releases/download/v3.7.2/loki-linux-amd64.zip
unzip loki-linux-amd64.zip
chmod +x loki-linux-amd64
sudo mv loki-linux-amd64 /usr/local/bin/loki
rm loki-linux-amd64.zip

# 데이터 디렉토리 생성
sudo mkdir -p /etc/loki /var/lib/loki/{chunks,rules,wal}

주의: /etc 디렉토리에서 wget을 실행하면 Permission denied가 난다. 홈(~)이나 /tmp에서 다운로드 후 sudo mv로 옮겨야 한다.

config.yaml 작성

# /etc/loki/config.yaml
auth_enabled: false

server:
  http_listen_port: 3100
  grpc_listen_port: 9096
  log_level: warn

common:
  instance_addr: 127.0.0.1
  path_prefix: /var/lib/loki
  storage:
    filesystem:
      chunks_directory: /var/lib/loki/chunks
      rules_directory: /var/lib/loki/rules
  replication_factor: 1
  ring:
    kvstore:
      store: inmemory

schema_config:
  configs:
    - from: 2024-01-01
      store: tsdb
      object_store: filesystem
      schema: v13
      index:
        prefix: index_
        period: 24h

limits_config:
  allow_structured_metadata: false
  retention_period: 168h   # 7일

compactor:
  working_directory: /var/lib/loki/compactor
  retention_enabled: true
  delete_request_store: filesystem   # ← Loki 3.x 필수

systemd 서비스 등록

sudo tee /etc/systemd/system/loki.service > /dev/null <<EOF
[Unit]
Description=Loki log aggregation system
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/loki -config.file=/etc/loki/config.yaml
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now loki

# 정상 확인
curl -s http://localhost:3100/ready
# 출력: ready

Step 2 — Grafana Alloy 설치 (공통)

Server A, B 양쪽에 동일하게 설치한다.

sudo mkdir -p /etc/apt/keyrings/
wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | \
  sudo tee /etc/apt/keyrings/grafana.gpg > /dev/null

echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | \
  sudo tee /etc/apt/sources.list.d/grafana.list

sudo apt-get update
sudo apt-get install alloy

alloy --version

systemd 서비스는 apt 설치 시 자동 등록된다.

Step 3 — Alloy config (Server B)

Alloy는 YAML이 아닌 컴포넌트 기반 파이프라인 문법을 사용한다.

loki.source.file  →  loki.process  →  loki.write
(파일 tail)          (레이블 추출)      (Loki push)

# /etc/alloy/config.alloy  (Server B: ssc-msg)

loki.write "default" {
  endpoint {
    url = "http://localhost:3100/loki/api/v1/push"
  }
}

loki.source.file "gunicorn_access" {
  targets = [{
    __path__ = "/var/log/gunicorn/access.log",
    job      = "gunicorn_access",
    host     = "server-b",
    service  = "ssc-msg",
    env      = "production",
  }]
  forward_to = [loki.process.gunicorn_access.receiver]
}

loki.process "gunicorn_access" {
  stage.regex {
    expression = `\[(?P<timestamp>[^\]]+)\] "(?P<method>[A-Z]+) (?P<path>\S+)[^"]*" (?P<status>\d{3})`
  }
  stage.labels {
    values = {
      method = "",
      status = "",
    }
  }
  forward_to = [loki.write.default.receiver]
}

loki.source.file "gunicorn_error" {
  targets = [{
    __path__ = "/var/log/gunicorn/error.log",
    job      = "gunicorn_error",
    host     = "server-b",
    service  = "ssc-msg",
    env      = "production",
  }]
  forward_to = [loki.process.gunicorn_error.receiver]
}

loki.process "gunicorn_error" {
  stage.regex {
    expression = `\[.*?\] \[\d+\] \[(?P<level>[A-Z]+)\]`
  }
  stage.labels {
    values = {
      level = "",
    }
  }
  forward_to = [loki.write.default.receiver]
}

Step 4 — Alloy config (Server A)

Server B와 동일한 구조, loki.write URL과 레이블만 다르다.

# /etc/alloy/config.alloy  (Server A: ssc-api)

loki.write "default" {
  endpoint {
    url = "http://<SERVER_B_IP>:3100/loki/api/v1/push"
  }
}

loki.source.file "gunicorn_access" {
  targets = [{
    __path__ = "/var/log/ssc_api/gunicorn_access.log",
    job      = "gunicorn_access",
    host     = "server-a",
    service  = "ssc-api",
    env      = "production",
  }]
  forward_to = [loki.process.gunicorn_access.receiver]
}

loki.process "gunicorn_access" {
  stage.regex {
    expression = `\[(?P<timestamp>[^\]]+)\] "(?P<method>[A-Z]+) (?P<path>\S+)[^"]*" (?P<status>\d{3})`
  }
  stage.labels {
    values = {
      method = "",
      status = "",
    }
  }
  forward_to = [loki.write.default.receiver]
}

loki.source.file "gunicorn_error" {
  targets = [{
    __path__ = "/var/log/ssc_api/gunicorn_error.log",
    job      = "gunicorn_error",
    host     = "server-a",
    service  = "ssc-api",
    env      = "production",
  }]
  forward_to = [loki.write.default.receiver]
}

Alloy 시작

# config 문법 검사 (실행 전 필수)
alloy fmt /etc/alloy/config.alloy

sudo systemctl enable --now alloy
sudo journalctl -u alloy -f

정상 기동 시 로그:

{^_^} Alloy is running
start tailing file ... path=/var/log/.../access.log

failed to register collector with remote server ... err="noop client" 에러는 Grafana Cloud remotecfg 기능 관련 메시지로, 자체 호스팅 환경에서는 정상적으로 출력된다. 무시해도 된다.

Step 5 — Grafana 데이터소스 추가 (Server C)

Connections → Data sources → Add → Loki

Name : Loki
URL  : http://<SERVER_B_IP>:3100

저장 후 Data source connected and labels found 메시지 확인.

Grafana가 Server B에 직접 접근하므로 필요 시 방화벽 추가:

# Server B에서 Grafana 서버 IP 허용
sudo ufw allow from <GRAFANA_IP> to any port 3100 proto tcp

유용한 LogQL 쿼리

-- 두 서버 통합 조회
{job="gunicorn_access"}

-- 서버별 필터
{job="gunicorn_access", host="server-a"}
{job="gunicorn_access", host="server-b"}

-- 서비스별 필터
{job="gunicorn_access", service="ssc-api"}

-- HTTP 5xx 에러
{job="gunicorn_access", status=~"5.."}

-- HTTP 4xx (404 스캐닝 탐지 등)
{job="gunicorn_access", status="404"} |= "phpinfo"

-- Gunicorn worker 재시작 추적
{job="gunicorn_error"} |= "Booting worker"

-- 에러 레벨 필터
{job="gunicorn_error", level="ERROR"}

-- Server A polling 엔드포인트
{job="gunicorn_access", host="server-a"} |= "/api/center/polling/"

트러블슈팅

1. wget Permission denied

loki-linux-amd64.zip: Permission denied

원인: /etc 등 시스템 디렉토리에서 wget 실행
해결: cd ~ 후 홈 디렉토리에서 다운로드

2. Loki 기동 실패 — delete-request-store 에러

CONFIG ERROR: invalid compactor config:
compactor.delete-request-store should be configured when retention is enabled

원인: Loki 3.x에서 retention_enabled: true 시 delete_request_store 필수
해결: config.yaml의 compactor 섹션에 추가

compactor:
  working_directory: /var/lib/loki/compactor
  retention_enabled: true
  delete_request_store: filesystem   # ← 추가

3. allow_structured_metadata 불일치

Loki 3.x + Alloy 3.x 조합에서 Alloy가 structured metadata를 자동으로 붙여 보내는데, Loki 설정과 불일치 시 push가 실패할 수 있다.
해결: limits_config에 명시

limits_config:
  allow_structured_metadata: false

레이블 설계 원칙

Loki는 레이블만 인덱싱하므로 카디널리티 관리가 핵심이다.

URL 경로로 필터링하려면 레이블 대신 LogQL 필터를 사용한다:

{job="gunicorn_access"} |= "/api/center/polling/"

다음 단계

• Grafana Explore에서 LogQL 쿼리 검증
• Django settings.py에 파일 핸들러 추가 (애플리케이션 레벨 로그 분리)
• Loki 기반 알람 설정 (5xx 급증, 특정 에러 패턴)
• Alloy로 Prometheus metrics scraping 통합 (node_exporter 대체 고려)

__date / __year / __month 같은 날짜 필터가 로컬에서만 0건 나온다면, 로컬 MySQL의 타임존 테이블이 비어 있어서 CONVERT_TZ가 NULL을 반환하는 게 원인일 수 있다. (배경 개념은 Django + MySQL 타임존 글 참고) 이 글은 Windows에 직접 설치된 MySQL에서 공식 SQL 덤프로 타임존 테이블을 적재하는 실전 절차다.

TL;DR

1. https://dev.mysql.com/downloads/timezones.html 에서 POSIX standard zip을 받는다.
2. 압축을 풀어 timezone_posix.sql을 꺼낸다.
3. PowerShell에서 Get-Content ...sql | mysql.exe -u root -p mysql 로 import.
4. CONVERT_TZ('2026-06-08 05:00:00','UTC','Asia/Seoul') 가 NULL이 아니라 14:00:00이면 성공.

사전 확인 — 정말 비어 있는가

먼저 문제가 실재하는지 확인한다. (읽기 전용, 안전)

& "C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe" -u root -p -e "SELECT COUNT(*) AS tz_rows FROM mysql.time_zone_name; SELECT CONVERT_TZ('2026-06-08 05:00:00','UTC','Asia/Seoul') AS converted;"

mysql.exe는 보통 PATH에 등록돼 있지 않다. C:\Program Files\MySQL\MySQL Server <버전>\bin\mysql.exe 전체 경로로 호출한다. (경로에 공백이 있어 PowerShell에서는 & 호출 연산자가 필요하다.)

적재 전 결과 예:

+---------+
| tz_rows |
+---------+
|       1 |   <- 사실상 비어 있음
+---------+
+-----------+
| converted |
+-----------+
| NULL      |   <- CONVERT_TZ 실패
+-----------+

converted가 NULL이면 타임존 테이블 적재가 필요하다.

STEP 1 — 공식 타임존 SQL 덤프 다운로드

https://dev.mysql.com/downloads/timezones.html 에 접속하면 두 종류가 보인다.

timezone_2026b_posix_sql.zip - POSIX standard                 ← 이것을 받는다
timezone_2026b_leaps_sql.zip - Non POSIX with leap seconds    ← 받지 않는다

POSIX standard를 받아야 하는 이유

• leap seconds(윤초) 버전은 피한다. 1972년 이후 누적된 윤초(현재 27초)를 시각 계산에 반영해서, 일반 애플리케이션에서는 오히려 시각이 수십 초 어긋날 수 있다.
• 목적은 Asia/Seoul(UTC+9 고정, 서머타임 없음) 날짜 변환을 프로덕션과 동일하게 만드는 것이다. 프로덕션도 일반적으로 POSIX 기준이므로 POSIX를 받아야 동작이 일치한다.
• 파일명의 2026b는 IANA 타임존 DB 버전이다. 한국은 서머타임이 없어 버전 차이의 영향을 받지 않으니, 페이지에 보이는 최신 POSIX 버전을 받으면 된다.

다운로드에는 Oracle 계정 로그인이 요구될 수 있다. 페이지 하단의 "No thanks, just start my download" 링크로 로그인 없이 받을 수도 있다.

STEP 2 — 압축 해제

받은 zip을 풀면 timezone_posix.sql 파일이 들어 있다.

Expand-Archive -Path "$env:USERPROFILE\Downloads\timezone_2026b_posix_sql.zip" -DestinationPath "$env:USERPROFILE\Downloads\timezone_2026b_posix_sql" -Force
Get-ChildItem "$env:USERPROFILE\Downloads\timezone_2026b_posix_sql" -Recurse -Filter *.sql | Select-Object FullName

출력된 .sql 전체 경로를 STEP 3에 사용한다. (예: C:\Users\<사용자>\Downloads\timezone_2026b_posix_sql\timezone_posix.sql)

STEP 3 — 시스템 스키마 mysql에 import

root 비밀번호 입력이 필요하므로, 비밀번호가 로그에 남지 않도록 터미널에서 직접 실행한다.

Get-Content "C:\Users\<사용자>\Downloads\timezone_2026b_posix_sql\timezone_posix.sql" | & "C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe" -u root -p mysql

Enter password: 프롬프트에 root 비밀번호를 입력한다. 에러 없이 프롬프트로 돌아오면 성공이다.

명령 구조 해설

• Get-Content ...sql | — PowerShell은 mysql < file.sql 같은 입력 리다이렉션을 지원하지 않는다('<' 연산자는 예약되어 있습니다 에러). 대신 Get-Content로 파일을 읽어 파이프로 넘긴다.
• & "...\mysql.exe" — 경로에 공백(Program Files)이 있으므로 &(호출 연산자)로 실행한다.
• -u root -p — -p만 쓰면 프롬프트로 비밀번호를 물어본다. 명령줄에 비밀번호를 붙이지 않는 편이 안전하다.
• 맨 끝의 mysql — import 대상 데이터베이스 이름이다. 앱 DB(smartsilvercenter)가 아니라 시스템 스키마 mysql에 넣는다. 타임존 테이블은 서버 전역으로 공유되므로, 한 번 넣으면 모든 DB의 쿼리에 자동 적용된다. 이 인자를 빼면 No database selected 에러가 난다.

즉, "특정 DB에 적용"이 아니라 "이 MySQL 서버 전체에 적용"이다. 결과적으로 smartsilvercenter의 CONVERT_TZ가 동작하게 된다.

STEP 4 — 검증

& "C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe" -u root -p -e "SELECT COUNT(*) AS tz_rows FROM mysql.time_zone_name; SELECT CONVERT_TZ('2026-06-08 05:00:00','UTC','Asia/Seoul') AS converted;"

적재 후 결과 예:

+---------+
| tz_rows |
+---------+
|     598 |   <- 타임존 이름이 채워짐
+---------+
+---------------------+
| converted           |
+---------------------+
| 2026-06-08 14:00:00 |   <- UTC 05:00 + 9 = KST 14:00, 정상 동작
+---------------------+

converted가 NULL에서 한국시간으로 바뀌면 CONVERT_TZ가 정상 동작하는 것이다.

STEP 5 — 실제 애플리케이션에서 확인

개념 검증(CONVERT_TZ)이 끝났으면, 실제로 깨졌던 날짜 필터 API가 정상 응답하는지 확인한다.

/api/v2/broadcasting/?start_date=2026-04-26&end_date=2026-06-07

적재 전 0건이던 응답이 정상 건수로 돌아오면 완전히 해결된 것이다.

트러블슈팅

ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: YES) → 비밀번호 오타. 명령을 다시 실행하고 비밀번호를 정확히 입력한다. (이 경우 import는 아무것도 적재되지 않았으므로, 올바른 비밀번호로 STEP 3를 다시 실행하면 된다.)

'<' 연산자는 나중에 사용하도록 예약되어 있습니다 → PowerShell에서 mysql < file.sql을 쓴 경우다. Get-Content file.sql | mysql.exe ... 파이프 형태로 바꾼다.

'mysql'은(는) ... 인식되지 않습니다 → mysql이 PATH에 없다. & "C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe" 전체 경로로 호출한다.

No database selected → import 명령 끝에 대상 DB mysql을 빠뜨린 경우다. ... mysql.exe -u root -p mysql처럼 맨 끝에 mysql을 붙인다.

한 줄 정리

Windows 네이티브 MySQL에서 CONVERT_TZ가 NULL을 뱉으면, MySQL 공식 사이트의 POSIX standard 타임존 SQL 덤프를 받아 Get-Content ...sql | mysql.exe -u root -p mysql로 시스템 스키마 mysql에 import하면 된다. 코드 변경 없이 로컬이 프로덕션과 동일하게 동작한다.

DB 에 저장은 됐는데 조회해보면 로컬은 0건. 코드 버그처럼 보였지만 범인은 로컬 MySQL의 타임존 테이블이었다. 그 과정을 디버깅하며 정리한 타임존 개념 노트.

TL;DR

• CONVERT_TZ는 설정이 아니라 시각 변환 계산기다. DB에 저장된 값을 바꾸지 않고, 읽을 때 임시로 계산만 한다.
• USE_TZ=True면 Django는 서버 시간과 무관하게 무조건 UTC로 저장한다.
• KST 변환은 두 군데서 따로 일어난다: 보여주기 = 파이썬, 날짜 필터(__date 등) = DB의 CONVERT_TZ.
• CONVERT_TZ('...','UTC','Asia/Seoul')처럼 타임존 이름을 쓰면 MySQL에 타임존 테이블(이름표 사전)이 적재돼 있어야 한다. 없으면 NULL 반환 → 모든 비교가 거짓 → 0건.

증상

방송 목록 API에 날짜 필터를 걸었다.

/api/v2/broadcasting/?start_date=2026-04-26&end_date=2026-06-07

• 로컬: 0건 ❌
• 프로덕션: 정상 ✅

같은 코드인데 결과가 달랐다.

진단 — 어디서 깨졌나

네 가지 경로로 같은 데이터를 조회해봤다.

마지막 줄이 결정적이었다. __date를 거치지 않는 raw 비교는 199건이 정상으로 나온다. → 데이터/저장 문제가 아니라, 그 필터가 의존하는 DB 기능(CONVERT_TZ)이 고장난 것.

개념 1 — CONVERT_TZ는 설정이 아니라 계산기다

CONVERT_TZ(시각, '이 타임존에서', '저 타임존으로')

시각 하나를 받아 다른 타임존 기준으로 바꿔 돌려주는 함수일 뿐이다. 서버나 DB에 무언가를 설정하지 않는다.

CONVERT_TZ('2026-06-08 05:00:00', 'UTC', 'Asia/Seoul')
-- 결과: '2026-06-08 14:00:00'   (UTC + 9시간)

• DB에 저장된 원본 값을 바꾸지 않는다.
• 읽어올 때 임시로 계산만 한다. 원본은 그대로 UTC.

개념 2 — 저장은 Django가, 날짜 필터는 DB가 변환한다

변환의 주체가 방향에 따라 다르다. 이게 가장 헷갈리는 지점.

저장할 때 (Django → DB)

Django(한국시간 14:00) → Django가 직접 UTC 05:00으로 변환 → DB에 05:00 저장

• 변환 주체: Django(파이썬).
• USE_TZ=True면 서버 시간(UTC든 KST든)과 무관하게 무조건 UTC로 저장.
• 이유: 서버를 어디로 옮기든 DB 값은 늘 같은 단일 기준(UTC)이어야 어긋나지 않으니까.
• 여기선 CONVERT_TZ가 쓰이지 않는다.

주의: 흔히 "서버가 UTC라서 UTC로 저장된다"고 생각하지만, 정확히는 "Django 설정이 UTC로 저장한다". 서버 시간은 보지 않는다.

읽을 때 — 보여주기 (DB → 화면)

DB에서 05:00(UTC) 꺼냄 → 파이썬이 14:00(KST)으로 표시

• 변환 주체: Django(파이썬).
• CONVERT_TZ 안 씀.

읽을 때 — 날짜 필터/집계 (__date, __year, __month)

DB가 WHERE 단계에서 05:00(UTC) → 14:00(KST) 변환 후 날짜 비교

• 변환 주체: DB(MySQL).
• 이때 CONVERT_TZ를 쓴다.

왜 필터만 DB에서 변환하나? "6월 7일 방송만 줘"라는 조건은 DB가 행을 고르는 단계(WHERE) 에서 날짜를 잘라야 한다. 파이썬이 데이터를 꺼낸 뒤에 거를 수 없다. DB 안에 값은 UTC로 있으니, DB가 KST로 바꿔서 날짜를 잘라야 정확하다.

핵심 구분:

• 데이터를 꺼낸 뒤의 변환 = 파이썬
• 데이터를 고르는 중(WHERE)의 변환 = DB(CONVERT_TZ)

-- start_time__date=2026-06-07 는 내부적으로 이렇게 바뀐다
WHERE DATE(CONVERT_TZ(start_time, 'UTC', 'Asia/Seoul')) = '2026-06-07'

개념 3 — 타임존 "이름표 사전"이 있어야 한다

CONVERT_TZ가 'Asia/Seoul'이 UTC+9라는 걸 알려면, MySQL의 mysql.time_zone* 시스템 테이블(이름표 사전)이 적재돼 있어야 한다.

-- 로컬 (사전 없음)
CONVERT_TZ('2026-06-08 05:00:00', 'UTC', 'Asia/Seoul')  →  NULL    ❌

-- 프로덕션 (사전 있음)
CONVERT_TZ('2026-06-08 05:00:00', 'UTC', 'Asia/Seoul')  →  '2026-06-08 14:00:00'  ✅

NULL = '2026-06-07' 비교는 항상 거짓이므로 → 전부 0건.

참고: CONVERT_TZ('...', '+00:00', '+09:00')처럼 숫자 오프셋으로 쓰면 사전이 필요 없다. Django가 자동으로 이름('Asia/Seoul')을 쓰기 때문에 사전이 필요했던 것.

전체 그림

[저장] — 문제 없음 ✅
  Django(KST 14:00) → Django가 UTC 05:00으로 변환 → DB에 05:00 저장
  (서버 시간 무관, CONVERT_TZ 안 씀)

[보여주기] — 문제 없음 ✅
  DB에서 05:00(UTC) 꺼냄 → 파이썬이 14:00(KST)으로 표시
  (CONVERT_TZ 안 씀)

[날짜 필터] — 여기가 깨짐 ❌
  DB가 WHERE에서 05:00(UTC) → 14:00(KST) 변환 시도 → 이름표 사전 없음 → NULL → 0건

해결 — 코드 변경 0

로컬 MySQL에 타임존 테이블을 한 번만 적재하면 된다.

# Docker MySQL (호스트에서):
mysql_tzinfo_to_sql /usr/share/zoneinfo | docker exec -i <컨테이너이름> mysql -u root -p mysql

# 컨테이너 안에서:
mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql

적재 후 확인:

SELECT CONVERT_TZ('2026-06-08 05:00:00','UTC','Asia/Seoul');
-- NULL이 아니라 '2026-06-08 14:00:00' 이면 성공

• 맨 끝의 mysql 인자는 적재 대상 DB 이름이다 (앱 DB가 아니라 시스템 스키마 mysql).
• 시스템 테이블을 건드리므로 root 권한이 필요하다.
• 한 번 적재하면 컨테이너를 재생성하지 않는 한 유지된다.

Windows + Docker라 호스트에 /usr/share/zoneinfo가 없다면, 컨테이너 안에서 실행한다:

docker exec -i <컨테이너이름> sh -c "mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p'<루트비번>' mysql"

한 줄 정리

__date / __year / __month 같은 날짜 부분 필터는 USE_TZ=True인 Django에서 CONVERT_TZ(컬럼,'UTC','Asia/Seoul')로 변환된다. 로컬 MySQL에 타임존 이름표 사전이 비어 있으면 그 계산이 NULL이 되어 모든 결과가 0건이 된다. 코드 버그가 아니라 로컬 MySQL 환경 문제이고, 타임존 테이블만 적재하면 해결된다.

production DB 백업(.sql.gz)을 로컬 MySQL에 복원하는 PowerShell 스크립트가 ERROR 1062 Duplicate entry '' for key 'linkserver_linkserver.name' 로 죽었다. dump 파일도 멀쩡하고 스크립트 로직도 멀쩡한데, 왜? 범인은 콘솔 인코딩이었고, 잡는 데 한참 헤맨 이유는 "내 환경에선 재현이 안 돼서" 였다.

TL;DR

• 텍스트는 시스템 경계를 넘을 때마다 bytes ↔ text 변환(인코딩)이 일어난다. 경계마다 인코딩이 다르면 깨진다.
• PowerShell이 외부 프로세스(mysql)의 stdin으로 보낼 때, 그 인코딩은 콘솔의 [Console]::OutputEncoding 을 상속한다. 한글 Windows 콘솔은 기본 CP949다.
• CP949로 인코딩된 한글 바이트를 mysql이 utf8mb4로 읽으니 한글이 통째로 깨져 빈 문자열 '' 이 됐고, UNIQUE 제약에서 '' 중복 → 1062.
• "내 환경에선 됨"은 결론이 아니라 단서다. 환경 의존 버그는 실패하는 환경의 조건을 재현해야 잡힌다.

1. 증상

기존 DB 초기화: DROP & CREATE DATABASE `smartsilvercenter` ... 초기화 완료
ERROR 1062 (23000) at line 1753: Duplicate entry '' for key 'linkserver_linkserver.name'

DB 초기화는 성공했는데, 데이터를 부어 넣는 도중 죽었다. 키워드 두 개:

• Duplicate entry '' — 중복된 값이 NULL이 아니라 빈 문자열이다.
• key 'linkserver_linkserver.name' — name 컬럼에 UNIQUE 제약이 걸려 있다.

💡 MySQL의 UNIQUE 인덱스는 NULL은 여러 개 허용하지만 빈 문자열 '' 은 하나만 허용한다. 즉 여러 행의 name 이 전부 '' 로 들어가려 해서 충돌한 것.

2. dump 파일은 멀쩡했다

.sql.gz 를 풀어 해당 테이블의 INSERT를 직접 확인:

INSERT INTO `linkserver_linkserver` VALUES
 (1,'인천시',...),(2,'강화군',...),(4,'미추홀',...);

이름이 셋 다 다르고, 빈 값도 없다. 그러니 이 파일을 그대로 복원하면 1062가 날 이유가 없다. → 빈 문자열은 "복원 과정 어딘가"에서 생겨났다는 뜻.

3. 데이터 흐름을 경계로 쪼개기

복원 스크립트는 dump를 한 줄씩 읽어 mysql의 stdin 파이프로 흘려보낸다. 경계를 그려보면:

dump(.sql.gz, UTF-8 bytes)
  └─[StreamReader: UTF-8 decode]→ 메모리의 올바른 "인천시"
       └─[StreamWriter: ??? encode]→ mysql stdin (bytes)
            └─[mysql: utf8mb4 decode]→ DB

StreamWriter 가 무슨 인코딩으로 내보내는가? 이게 핵심 경계였다.

4. 헤맨 구간 — 정직한 기록

여기서 한참 돌았다. 가설은 처음부터 맞았다("stdin 인코딩이 깨진다"). 그런데:

• 내 개발 환경에서 똑같은 로직을 돌리면 항상 성공했다.
• 그래서 "인코딩이 원인이 아니다"라고 잘못 결론 내리고 수정을 되돌리길 반복했다.

문제는 검증을 내 환경에서만 했다는 것. 알고 보니:

결정타는 사용자 환경에서 딱 한 줄 측정한 값:

$p=[Diagnostics.Process]::Start((New-Object Diagnostics.ProcessStartInfo -Property @{
  FileName='cmd';RedirectStandardInput=$true;UseShellExecute=$false}))
"stdin=$($p.StandardInput.Encoding.WebName) CP$($p.StandardInput.Encoding.CodePage)"
# → stdin=ks_c_5601-1987 CP949

CP949. 범인 확정.

5. 재현 → 수정 → 재검증

콘솔을 CP949로 강제(chcp 949)하니 그제서야 원래 코드가 1062로 죽었다. 비로소 진짜 재현.

수정: 콘솔 설정에 의존하지 말고 stdin을 UTF-8로 직접 고정한다.

$proc = [System.Diagnostics.Process]::Start($psi)
# .NET Framework/PS5.1 엔 ProcessStartInfo.StandardInputEncoding 속성이 없으므로
# BaseStream 위에 UTF-8(BOM 없음) StreamWriter 를 직접 씌운다.
$stdin = New-Object System.IO.StreamWriter(
    $proc.StandardInput.BaseStream,
    (New-Object System.Text.UTF8Encoding($false)))

CP949 콘솔에서 검증:

오늘 배운 것 (인코딩 너머의 일반 원칙)

① 인코딩은 "저장"이 아니라 "경계를 건널 때" 일어나는 변환이다

"텍스트가 깨졌다" = 어떤 경계의 encode 인코딩 ≠ 다음 경계의 decode 인코딩. 깨진 결과를 보지 말고 경계의 목록을 그려라: 파일 읽기 / 파이프 / 네트워크 / DB 연결 / 터미널 출력.

② "내 환경에선 되는데요"는 버그 리포트의 절반이다

재현 불가는 결론이 아니라 단서다. "A 성공 + B 실패" = 두 환경의 차이에 범인이 있다. → 추측한 원인을 내 환경에서 검증하지 말고, 실패하는 환경의 조건을 재현하라.

③ 에러의 "값"은 지문, "숫자"는 좌표계를 의심하라

• ''(빈 문자열) ← 값이 통째로 사라짐 = 인코딩 절단의 지문.
• at line 1753 ← dump 파일 줄이 아니라 mysql 입력 스트림 줄. 숫자는 항상 "어느 좌표계?"를 물어라.

④ 추측으로 고치지 말고: 가설 → 최소검증 → 확정 → 수정

같은 곳을 3번 두드리면 멈추고 "내가 검증하는 방법이 틀린 건 아닐까"를 의심하라.

한글 Windows + PowerShell 5.1 실전 함정 모음

근본 해법: 시스템/터미널을 UTF-8로 통일하거나 PowerShell 7+로 이주. 방어적으로는 스크립트 상단에 $OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false).

보너스 ① — 유니코드 정규화 (Normalization)

같은 글자가 여러 바이트 표현을 가질 수 있다. 한글 한:

• NFC(완성형): 한 = 코드포인트 1개 (U+D55C)
• NFD(조합형): ㅎ+ㅏ+ㄴ = 자모 3개 (U+1112 U+1161 U+11AB)

눈엔 똑같지만 "한"(NFC) == "한"(NFD) 은 false, 길이도 1 vs 3.

⚠️ macOS 함정: macOS 파일시스템은 한글 파일명을 NFD로 저장한다. "Mac에서 만든 한글 파일명을 git에 올렸더니 Windows에서 깨지거나 중복으로 보인다"가 여기서 온다.

원칙: 외부 입력(사용자 입력/업로드 파일명/API)은 저장 전 NFC로 정규화.

import unicodedata
clean = unicodedata.normalize("NFC", user_input)

보너스 ② — DB charset / collation

• charset(문자셋): 글자를 어떤 바이트로 저장 → 데이터의 표현
• collation(정렬규칙): 글자를 어떻게 비교·정렬 → 데이터의 동작 (UNIQUE / WHERE / ORDER BY / GROUP BY)

오늘의 '' 중복은 바로 collation의 영역 — 두 값을 "같다"고 판정해 UNIQUE를 위반시켰다.

MySQL 필수 상식:

1. utf8 은 가짜다. 글자당 최대 3바이트 → 이모지·일부 한자 저장 불가. 항상 utf8mb4.

2. collation 접미사가 동작을 결정한다:

   collation	특징
   utf8mb4_general_ci	_ci=대소문자 무시, 빠르지만 부정확(구식)
   utf8mb4_unicode_ci	유니코드 정렬, 더 정확
   utf8mb4_0900_ai_ci	MySQL 8.0+ 기본·권장 ✅ (_ai=악센트 무시)
   ..._bin	바이트 그대로, 전부 구분

3. 악명 높은 사고 — collation 불일치 JOIN:

   SELECT * FROM A JOIN B ON A.name = B.name;
   -- ERROR 1267: Illegal mix of collations

   서버/DB/테이블/컬럼 + 클라이언트 연결까지 전부 동일 charset·collation으로 통일해야 한다. (오늘 버그도 DB는 utf8mb4였지만 연결로 보낸 바이트가 어긋나 깨졌다 — "DB만 맞아선 부족하다"는 산 증거.)

두 보너스를 잇는 한 줄

정규화(NFC)는 "같은 글자를 같은 바이트로" 만드는 입구 작업이고, collation은 "그 바이트들을 어떻게 같다고 볼지" 정하는 DB 규칙이다. 둘 다 통일하지 않으면, 분명 같아 보이는 값이 검색·UNIQUE·JOIN에서 제멋대로 갈라진다.

그리고 오늘 가장 크게 남은 한 줄:

데이터가 경계를 넘을 때마다 인코딩 변환이 일어나고, "내 환경에선 됨"은 환경 차이라는 단서이며, 버그는 추측이 아니라 재현으로 잡는다.

Base64는 주로 어디에 쓰일까?

Base64는 바이너리 데이터를 텍스트(ASCII) 형태로 변환해야 할 때 사용한다. 텍스트만 허용되는 채널에서 바이너리를 안전하게 전송·저장하는 것이 핵심 목적이다.

대표적인 사용처

이메일 (MIME) — SMTP는 7-bit ASCII 기반 프로토콜이다. 이미지·첨부파일 같은 바이너리를 본문에 실으려면 base64로 인코딩해야 한다. Content-Transfer-Encoding: base64 헤더가 붙는 경우가 바로 이것이다.

웹/API 통신 — JSON이나 XML 같은 텍스트 포맷 안에 이미지·PDF 등 바이너리 파일을 넣을 때 활용된다. Anthropic API에 이미지를 보낼 때 source.type: "base64"로 넣는 패턴이 대표적이다. Data URI(data:image/png;base64,…)로 HTML/CSS에 이미지를 인라인 삽입할 때도 동일한 원리다.

인증 헤더 — HTTP Basic Authentication에서 username:password 문자열을 base64로 변환해 Authorization: Basic <encoded> 형태로 전송한다. 암호화가 아니라 단순 변환이므로 보안 목적은 아니다.

인증서·키 저장 — PEM 형식의 SSL/TLS 인증서, SSH 공개키 등이 base64로 표현되어 -----BEGIN CERTIFICATE----- 블록 안에 들어간다.

쿠키·토큰 — JWT의 header/payload 부분이 base64url로 처리되고, 쿠키에 구조화된 값을 담을 때도 종종 활용된다.

정리하면, base64 자체는 암호화나 압축이 아니라 "바이너리 → 텍스트 안전 변환"이 본질이며, 텍스트 전용 프로토콜·포맷과 바이너리 사이의 브릿지 역할을 한다. 다만 원본 대비 약 33% 크기가 늘어나는 오버헤드가 있어서, 대용량 파일에는 멀티파트 전송이 더 효율적이다.

Base64 말고 다른 종류들

문자 인코딩 (Character Encoding)

텍스트를 바이트로 표현하는 방식이다. ASCII가 영문 128자만 다루던 한계를 넘어 다국어를 지원하는 방향으로 발전해 왔다.

• ASCII — 7비트, 영문·숫자·기본 기호만 표현 (0~127)
• EUC-KR / CP949 — 한글 완성형. 과거 한국 웹에서 널리 쓰였고, 지금도 레거시 시스템에서 만난다
• UTF-8 — 가변 길이(1~4바이트) 유니코드 구현체. 현재 웹 표준이며 ASCII와 하위 호환된다
• UTF-16 — 2 또는 4바이트. JavaScript 내부 문자열, Windows API 등에서 채택
• UTF-32 — 고정 4바이트. 처리는 단순하지만 메모리 낭비가 커서 실무에선 드물다
• ISO-8859-1 (Latin-1) — 서유럽어 확장. HTTP 기본 charset으로 오래 활용되었다

바이너리→텍스트 (Binary-to-Text)

base64와 같은 계열로, 바이너리를 텍스트 안전 문자열로 바꾼다.

• Base32 — AZ + 27 사용. 대소문자 구분 없는 환경(DNS, OTP 시크릿)에 적합
• Base16 (Hex) — 09, AF. MAC 주소, 해시값, 색상 코드(#FF5733) 등에서 일상적으로 볼 수 있다
• Base85 (Ascii85) — base64보다 효율적(약 25% 오버헤드). PDF 내부, Git 바이너리 패치에 쓰인다
• Quoted-Printable — 이메일에서 대부분 ASCII인 텍스트에 간헐적 비ASCII 문자가 섞일 때 활용. =EC=9D=B4 같은 형태
• UUencode — Unix 시절 이메일 첨부 방식. base64/MIME에 거의 대체되었다

웹/URL

• Percent-encoding (URL encoding) — URL에 넣을 수 없는 문자를 %XX 형태로 변환. 예: 공백 → %20, 한글 → %ED%95%9C
• HTML Entity encoding — HTML 특수문자를 안전하게 표현. < → <, & → &, 숫자 참조 가 등

전송/압축 (Transfer Encoding)

전송 효율이나 스트리밍을 위한 방식이다.

• Chunked Transfer Encoding — HTTP/1.1에서 전체 크기를 모른 채 응답을 조각 단위로 전송
• gzip / deflate / br (Brotli) — HTTP Content-Encoding 헤더로 지정. 엄밀히는 압축이지만 전송 계층으로 분류되기도 한다

미디어 (Audio/Video/Image)

• 영상 — H.264, H.265(HEVC), VP9, AV1
• 음성 — AAC, Opus, MP3, FLAC
• 이미지 — JPEG, PNG, WebP, AVIF

이들은 "코덱"이라고도 부르며, 손실/무손실 압축과 디코딩 규격을 함께 정의한다.

보안 관련 변환

변환과 암호화는 다르지만, 실무에서 함께 언급되는 경우가 많다.

• 해싱 — SHA-256, MD5 등. 단방향 처리라 디코딩 불가. 무결성 검증·비밀번호 저장용
• 암호화 — AES, RSA, ChaCha20 등. 키가 있어야 복호화 가능. 파이프라인에서 인코딩과 결합되어 활용된다 (예: 암호화 → base64 → JSON 전송)

핵심 구분은 목적이다. 문자 표현이면 UTF-8 계열, 바이너리의 텍스트 안전 변환이면 base64 계열, 전송 효율이면 gzip/chunked, 미디어 압축이면 코덱.

바이너리→텍스트 인코딩, 실제로 어디서 쓰이나?

바이너리→텍스트 변환이 추상적으로 느껴지는 이유는, 대부분 "이미 변환된 결과물"을 매일 보면서도 그 사실을 의식하지 못하기 때문이다.

핵심 전제: 왜 필요한가?

세상에는 "텍스트만 통과시키는 통로"가 생각보다 많다. JSON, XML, HTTP 헤더, 이메일 본문, 환경변수, 설정 파일, 소스코드 — 이런 곳에 바이너리(이미지, 인증서, 암호화 결과물 등)를 넣으려면 텍스트로 바꿔야 한다. 그 변환기가 base64, hex 같은 바이너리→텍스트 기법이다.

1. SSH 키 / SSL 인증서 (Base64)

~/.ssh/id_rsa.pub를 열어보면 이런 형태다:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB... user@host

가운데 긴 문자열이 base64이다. 공개키의 실체는 바이너리 숫자(큰 정수)인데, 이걸 텍스트 파일에 한 줄로 저장하고 터미널에 복사·붙여넣기 하려면 텍스트여야 한다. NHN Cloud 인스턴스에 SSH 키 등록할 때 콘솔에 붙여넣는 것도 같은 이유다.

SSL 인증서(*.pem)도 마찬가지다:

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkq...
-----END CERTIFICATE-----

nginx 설정에서 ssl_certificate 경로를 지정하면 nginx가 이 base64를 디코딩해서 바이너리 인증서로 해석한다.

2. 이메일 첨부파일 (Base64)

이메일로 이미지를 보내면, 실제 전송되는 원문(raw message)은 이렇다:

Content-Type: image/png; name="photo.png"
Content-Transfer-Encoding: base64

iVBORw0KGgoAAAANSUhEUgAAAPAAAADwCAYAAAA+VemSAAA...

SMTP는 7-bit 텍스트 프로토콜이라 PNG 바이너리를 그대로 보낼 수 없다. 메일 클라이언트가 자동으로 base64 처리해서 전송하고, 수신 측에서 복원하는 것이다. 우리가 의식하지 못할 뿐 매일 일어나는 일이다.

3. API 요청 안에 파일 담기 (Base64)

Anthropic API에 이미지를 보내는 코드가 대표적이다:

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/jpeg",
    "data": "/9j/4AAQSkZJRgABAQ..."
  }
}

JSON은 텍스트 포맷이라 바이너리 바이트를 직접 넣을 수 없다. multipart/form-data로 파일을 따로 보내는 방법도 있지만, JSON body 하나로 깔끔하게 처리하고 싶을 때 base64가 활용된다.

4. Data URI — HTML/CSS 안에 이미지 삽입 (Base64)

<img src="data:image/png;base64,iVBORw0KGgo..." />

별도 HTTP 요청 없이 HTML 자체에 이미지를 포함시킨다. 아이콘 같은 작은 이미지에 적용하면 네트워크 왕복을 줄일 수 있다. 이메일 HTML 템플릿에서 특히 많이 쓰인다 (외부 이미지 URL이 차단되는 메일 클라이언트 대응).

5. JWT 토큰 (Base64url)

로그인 후 받는 JWT를 .으로 쪼개면 세 파트다:

eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMjN9.서명부분

앞 두 파트를 base64url 디코딩하면:

{"alg":"HS256"}
{"user_id":123}

JSON 객체를 HTTP 헤더(Authorization: Bearer ...)나 URL 파라미터에 넣어야 하는데, JSON을 그대로 넣으면 {, ", : 같은 특수문자가 문제를 일으킨다. base64url로 감싸면 알파벳·숫자·-·_만 남아서 어디에든 안전하게 들어간다.

6. Git 바이너리 diff (Base85)

Git에서 이미지 파일이 변경되면 diff에 이런 내용이 나타난다:

diff --git a/icon.png b/icon.png
GIT binary patch
literal 2345
zcmV+^3E7mhP)<h;3K|Lk000e1NJLTq...

텍스트 기반 diff/patch 포맷 안에 바이너리 변경분을 담기 위해 base85를 채택한다.

7. Hex (Base16) — 해시값, MAC 주소, 디버깅

매일 접하는 것들이다:

sha256sum file.tar.gz
# e3b0c44298fc1c149afbf4c8996fb924...  ← hex로 표현된 해시

ip link show
# link/ether 3a:2b:1c:4d:5e:6f  ← MAC 주소도 hex

hexdump -C /dev/urandom | head
# 바이너리 파일 내용을 사람이 읽을 수 있게 hex로 표시

해시 함수의 출력은 바이너리(32바이트 등)인데, 터미널에 표시하거나 로그에 기록하려면 hex 문자열로 변환한다.

정리하면 패턴은 하나다: "텍스트만 허용되는 곳에 바이너리를 넣어야 할 때." JSON, HTTP 헤더, 이메일, 설정 파일, 소스코드, 터미널 출력 — 이 모든 텍스트 전용 통로가 존재하는 한 바이너리→텍스트 기법은 계속 쓰인다. 눈에 잘 안 보이는 이유는 대부분 라이브러리나 프로토콜이 자동 처리해주기 때문이다.

바이너리는 0과 1인데 이게 이미지라고?

맞다. 바이너리는 0과 1의 나열이 맞고, 이미지도 음악도 영상도 결국 전부 0과 1이다. 핵심은 "해석 방식이 다르다"는 것이다.

컴퓨터에서 모든 것은 바이너리

텍스트 파일도 바이너리다. 예를 들어 A라는 글자는 내부적으로 01000001(65번)로 저장된다. 다만 텍스트 파일은 모든 바이트가 "사람이 읽을 수 있는 문자 범위(0~127)" 안에 있어서, 에디터로 열면 글자로 보이는 것이다.

반면 PNG 이미지 파일을 메모장으로 열어보면 ‰PNG\r\n... 뒤에 깨진 문자가 쏟아진다. 같은 0과 1인데 "문자로 해석할 수 없는 바이트"가 대부분이기 때문이다.

이미지가 바이너리인 구조

3×2 픽셀짜리 아주 작은 이미지가 있다고 하면, 각 픽셀은 RGB 값을 가진다:

픽셀(0,0) = 빨강 255, 초록 0, 파랑 0

이걸 바이너리로 쓰면:

11111111 00000000 00000000

이게 한 픽셀이고, 이런 바이트가 수십만~수백만 개 이어지면 사진 한 장이 된다. 거기에 파일 헤더(이미지 크기, 포맷 정보 등)가 앞에 붙고, 압축 알고리즘이 적용되면 PNG나 JPEG 파일이 되는 것이다.

"텍스트"와 "바이너리"의 실무적 구분

둘 다 0과 1인 건 같지만, 실무에서 말하는 구분은 이것이다:

텍스트 — 모든 바이트가 문자로 매핑되는 형태. JSON, HTML, 소스코드, 설정 파일 등. 에디터로 열면 사람이 읽을 수 있다.

바이너리 — 문자 범위 밖의 바이트가 포함된 형태. 이미지, 동영상, 실행파일, 압축 아카이브 등. 에디터로 열면 깨져 보인다.

그래서 base64가 필요한 이유

JSON 같은 텍스트 포맷은 "문자"만 담을 수 있게 설계되어 있다. 그런데 이미지 바이너리에는 0x00(null), 0x89, 0xFF 같은 바이트가 들어 있고, 이런 값들을 JSON 문자열 안에 그대로 넣으면 파싱이 깨진다.

base64가 하는 일:

원본 바이너리:  10001001 01010000 01001110 01000111 ...
                (0x89)    (P)      (N)      (G)

 ↓ base64 변환

텍스트 문자열:  "iVBORw0KGgo..."
                (A~Z, a~z, 0~9, +, / 만 사용)

0x89 같은 "텍스트로 표현 불가능한 바이트"까지 포함해서 전부 알파벳·숫자 조합으로 바꿔주는 것이다. 받는 쪽에서 다시 디코딩하면 원본이 그대로 복원된다.

바이너리→텍스트 변환은 "모든 바이트를 문자 안전 영역으로 옮기는 번역"이라고 생각하면 된다.

Django에서 base64를 만나는 경우

Django가 내부적으로 자동 처리하는 경우

CSRF 토큰 — {% csrf_token %}이 생성하는 토큰 값이 base64로 처리되어 있다. 내부적으로 랜덤 바이트를 생성한 뒤 변환해서 폼 hidden 필드나 쿠키에 넣는다. 바이너리 랜덤 값을 HTML과 쿠키(텍스트 통로)에 안전하게 담기 위해서다.

세션 — SESSION_ENGINE이 기본 DB 백엔드일 때, 세션 딕셔너리를 직렬화한 뒤 base64로 변환해서 저장한다. django_session 테이블의 session_data 컬럼을 직접 보면 base64 문자열이 들어 있는 것을 확인할 수 있다.

비밀번호 해싱 — PBKDF2로 해싱된 비밀번호가 DB에 저장될 때 형태가 이렇다:

pbkdf2_sha256$600000$salt$hash값

여기서 salt와 hash 부분이 base64로 표현된 바이너리다. 해시 함수 출력은 바이너리인데 DB varchar 컬럼(텍스트)에 저장해야 하기 때문이다.

Signed Cookie / signing 모듈 — django.core.signing이 HMAC 서명값을 base62/base64로 변환한다. 쿠키나 URL에 들어가야 하니까 텍스트 안전 형태가 필요하다.

API 개발할 때 직접 쓰는 경우

클라이언트에서 이미지를 JSON으로 받을 때 — 모바일 앱이나 프론트엔드가 파일을 multipart/form-data 대신 JSON body에 base64로 담아 보내는 경우:

import base64
from django.core.files.base import ContentFile

def upload_profile(request):
    data = json.loads(request.body)
    # "data:image/png;base64,iVBORw0KGgo..." 형태로 올 수 있음
    image_data = data['image'].split(',')[1]  # base64 부분만 추출
    binary = base64.b64decode(image_data)
    file = ContentFile(binary, name='profile.png')
    # 이후 모델에 저장하거나 Object Storage에 업로드

API 응답으로 작은 파일을 내려줄 때 — 별도 파일 다운로드 엔드포인트를 만들기 번거로울 때, 썸네일 같은 작은 이미지를 JSON 응답에 포함시키기도 한다:

import base64

def get_thumbnail(request, pk):
    obj = MyModel.objects.get(pk=pk)
    with obj.thumbnail.open('rb') as f:
        encoded = base64.b64encode(f.read()).decode('ascii')
    return JsonResponse({
        'thumbnail': f'data:image/jpeg;base64,{encoded}'
    })

외부 API 연동에서 Basic Auth — 외부 서비스를 호출할 때:

import base64
import requests

credentials = base64.b64encode(b'api_user:api_password').decode()
response = requests.get(url, headers={
    'Authorization': f'Basic {credentials}'
})

바이너리를 캐시에 저장할 때 — Redis 캐시에 바이너리를 넣어야 할 때 base64로 변환하면 직렬화 문제를 피할 수 있다.

공통 패턴

Django에서 base64가 등장하는 모든 경우를 관통하는 공통점은, DB 컬럼(텍스트), JSON 응답(텍스트), 쿠키(텍스트), HTTP 헤더(텍스트) 같은 텍스트 전용 통로에 바이너리 값(해시, 서명, 이미지, 랜덤 토큰)을 넣어야 하는 상황이라는 것이다. 프레임워크가 내부적으로 해주는 것과 개발자가 직접 하는 것의 차이만 있을 뿐, 원리는 동일하다.

Django + Gunicorn 환경에서 로그를 파일로 기록하고, logrotate로 자동 관리하며, 쌓인 데이터를 별도 블록 스토리지에 연/월 구조로 보관하는 전 과정을 다룬다.

목차

1. 블록 스토리지 연결 및 마운트
2. Gunicorn 로그 출력 설정
3. Logrotate 옵션 상세 정리
4. Logrotate 설정 작성
5. 아카이브 스크립트 설계
6. 디스크 사용량 계산
7. 기존 거대 로그 정리
8. 요약

1. 블록 스토리지 연결 및 마운트

1-1. 현재 디스크 상태 확인

lsblk

마운트 여부와 관계없이 연결된 블록 디바이스를 모두 트리 형태로 보여준다. 파일시스템 타입과 UUID까지 함께 확인하려면 -f 옵션을 붙인다.

lsblk -f

NHN Cloud 등 클라우드 환경에서 추가 볼륨을 attach하면 vdb와 같은 이름으로 나타난다.

1-2. 파티션 분리 여부 판단

클라우드 블록 스토리지를 단순 용량 확장 목적으로 쓴다면, 파티션 없이 디스크 전체를 그대로 사용하는 것이 깔끔하다. 파티션이 유용한 경우는 다음과 같다.

• 용도별(/data, /logs)로 용량을 강제 제한하고 싶을 때
• 한 영역이 꽉 차도 나머지에 영향이 없도록 격리하고 싶을 때

1-3. 포맷 및 마운트

# ext4로 포맷
sudo mkfs.ext4 /dev/vdb

# 마운트 포인트 생성
sudo mkdir -p /mnt/data

# 마운트
sudo mount /dev/vdb /mnt/data

# 확인
df -h

1-4. 재부팅 후 자동 마운트 (fstab 등록)

장치명(vdb)은 재부팅 시 바뀔 수 있어 UUID 기반으로 등록해야 안전하다.

# UUID 확인
sudo blkid /dev/vdb

출력 예시:

/dev/vdb: UUID="3de85581-2e2a-43f5-878e-b6a87d2fd905" BLOCK_SIZE="4096" TYPE="ext4"

# fstab에 추가
echo "UUID=3de85581-2e2a-43f5-878e-b6a87d2fd905  /mnt/data  ext4  defaults  0  2" | sudo tee -a /etc/fstab

# 재부팅 없이 검증
sudo mount -a

# 최종 확인
df -h

2. Gunicorn 로그 출력 설정

2-1. 문제: stdout으로 흘러가는 기본 구성

일반적인 gunicorn.service 파일은 이렇게 되어 있다.

ExecStart=/path/to/.venv/bin/gunicorn \
          --access-logfile - \
          --error-logfile - \
          ...

여기서 -는 stdout/stderr로 출력한다는 의미다. journald로만 데이터가 흘러가 별도 경로에 기록되지 않는다. journald는 용량 제한이 있고 검색도 불편하기 때문에, 운영 환경에서는 직접 경로를 지정하는 것이 일반적이다.

2-2. 로그 디렉토리 생성

sudo mkdir -p /var/log/mch_api
sudo chown ubuntu:www-data /var/log/mch_api
sudo chmod 755 /var/log/mch_api

• ubuntu:www-data: gunicorn이 ubuntu 계정으로 구동되므로 해당 소유자에게 쓰기 권한을 부여한다.
• 디렉토리명은 서비스에 맞게 자유롭게 지정(ssc_api, mch_api 등).

2-3. gunicorn.service 수정

[Unit]
Description=gunicorn daemon for MCH
Requires=gunicorn.socket
After=network.target

[Service]
User=ubuntu
Group=www-data
WorkingDirectory=/workspace/smart-silver-center/ssc-api

ExecStart=/workspace/smart-silver-center/ssc-api/.venv/bin/gunicorn \
          --access-logfile /var/log/mch_api/access.log \
          --error-logfile /var/log/mch_api/error.log \
          --workers 4 \
          --threads 2 \
          --worker-class gthread \
          --timeout 60 \
          --graceful-timeout 30 \
          --max-requests 1000 \
          --max-requests-jitter 100 \
          --keep-alive 5 \
          --bind unix:/run/gunicorn.sock \
          --preload \
          --capture-output \
          --enable-stdio-inheritance \
          --log-level info core.michuhol.wsgi:application

Environment="ENV_FILE=.env"
Restart=on-failure
RestartSec=5
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target

변경점은 두 줄이다.

- --access-logfile - \
- --error-logfile - \
+ --access-logfile /var/log/mch_api/access.log \
+ --error-logfile /var/log/mch_api/error.log \

2-4. 적용 및 확인

sudo systemctl daemon-reload
sudo systemctl restart gunicorn

# 경로 생성 확인
ls -la /var/log/mch_api/

# 실시간 확인
tail -f /var/log/mch_api/access.log

기록이 안 된다면 아래 순서로 점검한다.

sudo systemctl status gunicorn.service
sudo journalctl -u gunicorn.service -n 30 --no-pager
ls -la /var/log/ | grep mch_api
cat /etc/systemd/system/gunicorn.service | grep logfile

3. Logrotate 옵션 상세 정리

3-1. 회전 주기

API 서버라면 daily가 일반적이다.

3-2. 보관 관련

3-3. 압축 관련

3-4. 파일 생성/처리

3-5. 예외 처리

3-6. 스크립트 실행

postrotate
    systemctl reload gunicorn 2>/dev/null || true
endscript

sharedscripts가 없으면 access.log 회전 후 한 번, error.log 회전 후 또 한 번 reload가 중복 호출된다.

2>/dev/null 이란?

리눅스의 모든 프로세스는 세 가지 기본 스트림을 가진다.

즉 2>/dev/null은 stderr(에러 메시지)를 /dev/null(쓰레기통)로 버리라는 의미다.

systemctl reload gunicorn 2>/dev/null || true
#                          ↑              ↑
#             에러 메시지 무시    실패해도 종료 코드 0으로 처리

gunicorn이 내려가 있거나 reload 자체가 실패해도, logrotate 전체가 오류로 처리되지 않도록 하는 방어 코드다.

3-7. 네이밍

4. Logrotate 설정 작성

4-1. 설정 파일 생성

/etc/logrotate.d/ 아래에 서비스명으로 생성한다. 파일 이름은 서비스명과 일치할 필요 없다. 중요한 건 안에 적는 경로다.

sudo nano /etc/logrotate.d/ssc_api

4-2. 내용

/var/log/ssc_api/*.log {
    daily
    missingok
    rotate 14
    maxsize 100M
    compress
    delaycompress
    notifempty
    create 0644 ubuntu www-data
    dateext
    sharedscripts
    postrotate
        systemctl reload gunicorn 2>/dev/null || true
        /usr/local/bin/archive_logs.sh >> /var/log/archive_logs.log 2>&1
    endscript
}

4-3. 검증 및 실행

# 문법 검증 (dry-run, 실제 동작 없음)
sudo logrotate -d /etc/logrotate.d/ssc_api

# 강제 실행 + verbose
sudo logrotate -vf /etc/logrotate.d/ssc_api

# 결과 확인
ls -lh /var/log/ssc_api/

logrotate는 데몬이 아니므로 설정 수정 후 별도 재시작이 필요 없다. cron이 매일 호출하는 구조이기 때문에, 저장 즉시 다음 실행부터 반영된다.

자주 보이는 메시지

glob finding logs to compress failed
glob finding old rotated logs failed

에러가 아니다. "이전에 회전된 항목을 찾으려 했는데 아직 없다"는 정보성 메시지로, 최초 실행 시 정상적으로 출력된다.

5. 아카이브 스크립트 설계

5-1. 전체 구조

/var/log/ssc_api/              ← 현재 활성 로그 (그대로 유지)
    gunicorn_access.log
    gunicorn_error.log
    gunicorn_error.log-20260304  ← delaycompress 대기 중 (미압축)

/mnt/data/logs/ssc_api/        ← 압축 완료된 항목 아카이브
    2026/
        03/
            gunicorn_access.log-20260301.gz
            gunicorn_error.log-20260304.gz
        04/
            ...

5-2. 디렉토리 준비

sudo mkdir -p /mnt/data/logs/ssc_api
sudo chown ubuntu:ubuntu /mnt/data/logs/ssc_api

5-3. 스크립트 작성

sudo nano /usr/local/bin/archive_logs.sh

#!/bin/bash

SRC="/var/log/ssc_api"
DEST="/mnt/data/logs/ssc_api"

# .gz 항목만 대상 (delaycompress로 압축 완료된 것만)
for f in "$SRC"/*.log-[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]*.gz; do
    [ -f "$f" ] || continue

    filename=$(basename "$f")

    # 파일명에서 날짜 추출 (예: gunicorn_access.log-20260304.gz → 20260304)
    datestr=$(echo "$filename" | grep -oP '\d{8}')
    [ -z "$datestr" ] && continue

    year="${datestr:0:4}"
    month="${datestr:4:2}"

    target_dir="$DEST/$year/$month"
    mkdir -p "$target_dir"

    mv "$f" "$target_dir/"
    echo "[$(date)] Archived: $filename → $target_dir/"
done

sudo chmod +x /usr/local/bin/archive_logs.sh

5-4. ⚠️ delaycompress와의 충돌 주의

delaycompress는 직전 회전본을 하루 동안 압축하지 않은 채 둔다. glob 패턴을 .gz 없이 작성하면 미압축 항목도 매칭되어 /mnt/data로 이동해버린다. 다음 날 logrotate가 압축 대상을 찾지 못해 아카이브에 비압축 항목이 쌓이는 결과로 이어진다.

# ❌ 잘못된 패턴 (미압축도 매칭됨)
"$SRC"/*.log-[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]*

# ✅ 올바른 패턴 (압축 완료본만 이동)
"$SRC"/*.log-[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]*.gz

5-5. 전체 동작 흐름 검증

Day 1 logrotate 실행:
  - access.log → access.log-20260303 (압축 안 됨, delaycompress)
  - postrotate: archive_logs.sh → .gz 없으므로 아무것도 안 함 ✅

Day 2 logrotate 실행:
  - access.log-20260303 → access.log-20260303.gz (압축 완료)
  - access.log → access.log-20260304 (새로 회전)
  - postrotate: archive_logs.sh → access.log-20260303.gz를 /mnt/data/2026/03/ 으로 이동 ✅

/var/log/ssc_api/ 에는:
  - gunicorn_access.log          (현재 활성)
  - gunicorn_access.log-20260304 (어제, 아직 압축 전)
  → 깔끔하게 유지 ✅

5-6. cron 등록 (보조 보험용)

수동 생성 항목 등 누락 케이스를 대비한 추가 트리거다.

sudo crontab -e

# 매일 새벽 2시 실행
0 2 * * * /usr/local/bin/archive_logs.sh >> /var/log/archive_logs.log 2>&1

이미 이동된 항목은 glob 매칭에서 걸리지 않으므로 중복 실행해도 무방하다.

6. 디스크 사용량 계산

6-1. 일일 생성량 파악

gunicorn_access.log   2.6GB / 5일 → 약 520MB/day
gunicorn_error.log    582MB / 5일 → 약 116MB/day

6-2. 회전 빈도 계산

maxsize 100M 적용 시:

• access: 520MB ÷ 100MB = 하루 약 5회 회전
• error: 116MB ÷ 100MB = 하루 약 1~2회 회전

6-3. 실제 보관 기간

rotate 14는 회전된 항목 14개를 유지한다는 뜻이다. 하루에 5회 회전한다면 14개는 약 2~3일치에 불과하다.

14일치 보장이 필요하다면:

rotate 70      # 하루 5회 × 14일 = 70개

6-4. 디스크 사용량 추정

gzip 압축 시 텍스트 로그는 원본의 약 10~15% 수준이 된다.

access.log 기준 (rotate 14 적용):

error.log도 동일 구조로 약 344MB. 총 합계: 약 700MB (기존 7GB 대비 1/10 수준)

rotate 70 적용 시 약 1.2GB 수준으로 여전히 기존 대비 대폭 절감된다.

7. 기존 거대 로그 정리

logrotate 도입 전 이미 쌓인 대용량 항목은 수동으로 처리한다.

# 압축 보관
sudo gzip /var/log/ssc_api/gunicorn_access.log
sudo gzip /var/log/ssc_api/gunicorn_error.log

# 불필요하다면 삭제
sudo rm /var/log/ssc_api/gunicorn_access.log

# 여유 공간 확인
df -h /var/log

8. 요약

libnginx-mod-rtmp + ffmpeg 기반 HLS 미디어 서버에 Prometheus와 Grafana를 붙여 생사 여부를 실시간으로 파악하는 대시보드를 구축한 과정을 기록한다.

아키텍처 개요

nginx-rtmp (/stat) ──→ Python Exporter (9101)  ─┐
node_exporter (9100)                              ├──→ Prometheus (9090) ──→ Grafana (3000)
ffmpeg 프로세스 상태                              ─┘

세 가지 수집 레이어로 구성된다.

• node_exporter : 서버 CPU/메모리/디스크/네트워크 등 시스템 지표
• 커스텀 Python exporter : nginx-rtmp /stat XML을 파싱해 스트림 상태를 Prometheus 포맷으로 변환
• Prometheus : 위 두 exporter를 주기적으로 스크랩해 시계열 DB에 저장
• Grafana : Prometheus를 데이터소스로 연결해 대시보드 시각화

1단계 — Prometheus 설치

사용자 및 디렉토리 준비

sudo useradd --no-create-home --shell /bin/false prometheus

sudo mkdir -p /etc/prometheus /var/lib/prometheus
sudo chown prometheus:prometheus /etc/prometheus /var/lib/prometheus

바이너리 다운로드

cd /tmp
wget https://github.com/prometheus/prometheus/releases/download/v3.4.1/prometheus-3.4.1.linux-amd64.tar.gz
tar xvf prometheus-3.4.1.linux-amd64.tar.gz
cd prometheus-3.4.1.linux-amd64

sudo cp prometheus promtool /usr/local/bin/
sudo chown prometheus:prometheus /usr/local/bin/prometheus /usr/local/bin/promtool

console 패키지는 3 버전에서 더이상 제공되지 않습니다. 왜냐하면 관리, 유지보수가 어렵고 그냥 모든 사람들도 grafana 와 같은 third-party library 와 함께 사용하는 게 국룰이 되어버렸기 때문에 tar 로 압축을 풀어봐도 console 패키지가 없으니 스킵!

prometheus.yml 작성

sudo nano /etc/prometheus/prometheus.yml

global:
  scrape_interval:     15s
  evaluation_interval: 15s
  scrape_timeout:      15s

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

  - job_name: 'node'
    static_configs:
      - targets: ['localhost:9100']

  - job_name: 'nginx_rtmp'
    static_configs:
      - targets: ['localhost:9101']
    scrape_interval: 10s

sudo chown prometheus:prometheus /etc/prometheus/prometheus.yml

systemd 서비스 등록

sudo nano /etc/systemd/system/prometheus.service

[Unit]
Description=Prometheus Monitoring
Wants=network-online.target
After=network-online.target

[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/usr/local/bin/prometheus \
    --config.file=/etc/prometheus/prometheus.yml \
    --storage.tsdb.path=/var/lib/prometheus/ \
    --storage.tsdb.retention.time=30d \
    --web.console.templates=/etc/prometheus/consoles \
    --web.console.libraries=/etc/prometheus/console_libraries \
    --web.listen-address=0.0.0.0:9090 \
    --web.enable-lifecycle

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now prometheus

--web.enable-lifecycle 플래그를 추가해두면 재시작 없이 설정 리로드가 가능하다.

# 설정 변경 후 무중단 리로드
curl -X POST http://localhost:9090/-/reload

2단계 — node_exporter 설치

cd /tmp
wget https://github.com/prometheus/node_exporter/releases/download/v1.9.0/node_exporter-1.9.0.linux-amd64.tar.gz
tar xvf node_exporter-1.9.0.linux-amd64.tar.gz

sudo useradd --no-create-home --shell /bin/false node_exporter
sudo install -m 755 node_exporter-1.9.0.linux-amd64/node_exporter /usr/local/bin/node_exporter
sudo chown node_exporter:node_exporter /usr/local/bin/node_exporter

Tip. 기존에 node_exporter가 실행 중인 상태에서 cp로 덮어쓰려 하면 Text file busy 오류가 발생한다. 이때는 install 명령을 쓰거나 서비스를 먼저 중단한 뒤 복사한다.

# 방법 1: install 명령 (서비스 중단 불필요)
sudo install -m 755 node_exporter /usr/local/bin/node_exporter

# 방법 2: 서비스 중단 후 복사
sudo systemctl stop node_exporter
sudo cp node_exporter /usr/local/bin/
sudo systemctl start node_exporter

sudo nano /etc/systemd/system/node_exporter.service

[Unit]
Description=Node Exporter
Wants=network-online.target
After=network-online.target

[Service]
User=node_exporter
Group=node_exporter
Type=simple
ExecStart=/usr/local/bin/node_exporter \
    --collector.systemd \
    --collector.processes

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now node_exporter

3단계 — nginx-rtmp 커스텀 Exporter

nginx-rtmp의 /stat XML 엔드포인트를 파싱해 Prometheus 포맷으로 9101번 포트에 노출하는 Python 스크립트다.

패키지 설치

# apt로 시스템 전역 설치 (pip install은 systemd 서비스에서 인식 못함)
sudo apt install -y python3-lxml python3-requests
sudo apt install -y python3-prometheus-client
# apt에 없다면:
# sudo pip3 install prometheus_client --break-system-packages

pip3 install을 일반 사용자 권한으로 실행하면 시스템 Python에 반영되지 않는다. systemd 서비스는 시스템 Python을 바라보므로 반드시 apt 또는 sudo pip3로 설치해야 한다.

설치 후 한 번에 검증:

python3 -c "import prometheus_client, requests, lxml; print('모두 OK')"

exporter 스크립트

sudo mkdir -p /opt/nginx_rtmp_exporter
sudo nano /opt/nginx_rtmp_exporter/exporter.py

#!/usr/bin/env python3
"""
nginx-rtmp → Prometheus Exporter
포트 9101에서 메트릭 노출
"""

import time
import requests
import logging
from lxml import etree
from prometheus_client import start_http_server, Gauge

logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(message)s')

RTMP_STAT_URL  = "http://localhost:8888/stat"
SCRAPE_INTERVAL = 10

# ── 메트릭 정의 ────────────────────────────────────────────────────────────
rtmp_up = Gauge('nginx_rtmp_up', 'nginx-rtmp 서버 접근 가능 여부 (1=정상, 0=장애)')

rtmp_stream_count = Gauge('nginx_rtmp_stream_count', '현재 활성 스트림 수', ['app'])
rtmp_clients      = Gauge('nginx_rtmp_clients',      '스트림별 클라이언트 수', ['app', 'stream'])
rtmp_bw_in        = Gauge('nginx_rtmp_bw_in_bps',    '입력 대역폭 (bps)',     ['app', 'stream'])
rtmp_bw_out       = Gauge('nginx_rtmp_bw_out_bps',   '출력 대역폭 (bps)',     ['app', 'stream'])
rtmp_bytes_in     = Gauge('nginx_rtmp_bytes_in_total','누적 수신 바이트',      ['app', 'stream'])
rtmp_ffmpeg_count = Gauge('nginx_rtmp_ffmpeg_processes', '실행 중인 ffmpeg 프로세스 수')
hls_segment_count = Gauge('nginx_rtmp_hls_segment_count', 'HLS .ts 세그먼트 파일 수', ['stream'])

# ── 수집 함수 ──────────────────────────────────────────────────────────────
def count_ffmpeg_processes() -> int:
    import subprocess
    try:
        r = subprocess.run(['pgrep', '-c', 'ffmpeg'], capture_output=True, text=True)
        return int(r.stdout.strip()) if r.returncode == 0 else 0
    except Exception:
        return 0

def count_hls_segments(hls_root: str = '/var/hls') -> dict:
    import os
    counts = {}
    try:
        for entry in os.scandir(hls_root):
            if entry.is_dir():
                counts[entry.name] = len([f for f in os.listdir(entry.path) if f.endswith('.ts')])
    except FileNotFoundError:
        pass
    return counts

def collect():
    try:
        resp = requests.get(RTMP_STAT_URL, timeout=5)
        resp.raise_for_status()
        rtmp_up.set(1)
    except Exception as e:
        logging.warning(f"stat 엔드포인트 접근 실패: {e}")
        rtmp_up.set(0)
        return

    try:
        root = etree.fromstring(resp.content)
        for server in root.findall('.//server'):
            for app in server.findall('application'):
                app_name = app.findtext('name', default='unknown')
                live = app.find('live')
                if live is None:
                    continue
                streams = live.findall('stream')
                rtmp_stream_count.labels(app=app_name).set(len(streams))
                for stream in streams:
                    name   = stream.findtext('name', default='unknown')
                    rtmp_clients.labels(app=app_name, stream=name).set(len(stream.findall('.//client')))
                    rtmp_bw_in.labels(app=app_name,   stream=name).set(int(stream.findtext('bw_in',    '0')))
                    rtmp_bw_out.labels(app=app_name,  stream=name).set(int(stream.findtext('bw_out',   '0')))
                    rtmp_bytes_in.labels(app=app_name,stream=name).set(int(stream.findtext('bytes_in', '0')))
    except Exception as e:
        logging.error(f"XML 파싱 오류: {e}")

    rtmp_ffmpeg_count.set(count_ffmpeg_processes())
    for sname, cnt in count_hls_segments().items():
        hls_segment_count.labels(stream=sname).set(cnt)

if __name__ == '__main__':
    start_http_server(9101)
    logging.info("nginx-rtmp exporter 가동 — :9101")
    while True:
        collect()
        time.sleep(SCRAPE_INTERVAL)

systemd 서비스 등록

sudo nano /etc/systemd/system/nginx_rtmp_exporter.service

[Unit]
Description=nginx-rtmp Prometheus Exporter
After=network.target

[Service]
User=prometheus
ExecStart=/usr/bin/python3 /opt/nginx_rtmp_exporter/exporter.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now nginx_rtmp_exporter

# 정상 동작 확인
curl http://localhost:9101/metrics | grep nginx_rtmp

4단계 — 수집 타겟 확인

설정 변경 후에는 반드시 리로드하고 타겟 상태를 점검한다.

curl -X POST http://localhost:9090/-/reload

sleep 30 && curl -s http://localhost:9090/api/v1/targets \
  | python3 -m json.tool \
  | grep -E '"job"|"health"|"lastError"'

세 job 모두 "health": "up" 이어야 정상이다.

"job": "nginx_rtmp"  →  "health": "up"
"job": "node"        →  "health": "up"
"job": "prometheus"  →  "health": "up"

주의. Prometheus를 재시작하지 않고 prometheus.yml만 수정하면 변경 사항이 반영되지 않는다. --web.enable-lifecycle 플래그가 있다면 위처럼 reload API를 활용하면 되고, 없다면 sudo systemctl restart prometheus로 재시작해야 한다.

5단계 — Grafana 설치

sudo apt install -y apt-transport-https software-properties-common
wget -q -O - https://apt.grafana.com/gpg.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/grafana.gpg
echo "deb [signed-by=/usr/share/keyrings/grafana.gpg] https://apt.grafana.com stable main" \
  | sudo tee /etc/apt/sources.list.d/grafana.list

sudo apt update && sudo apt install grafana -y
sudo systemctl enable --now grafana-server

6단계 — nginx 리버스 프록시 + 리다이렉트 루프 해결

서브경로(/grafana/)로 Grafana를 서빙하려면 nginx 설정과 grafana.ini 두 곳을 모두 올바르게 맞춰야 한다. 한쪽이라도 어긋나면 301 무한 루프가 발생한다.

자주 하는 실수들

nginx — 기존 서버 블록에 location 추가

별도 conf 파일을 만들지 말고, 해당 도메인의 기존 블록에 아래 location을 추가한다.

http {

        ##
        # Basic Settings
        ##

        ...

        server {
                listen 8888;
                allow 127.0.0.1;
                deny all;

                location /stat {
                        rtmp_stat all;
                        rtmp_stat_stylesheet stat.xsl;
                }
        }

}

location /grafana/ {
    proxy_pass            http://localhost:3000;   # 끝 슬래시 없음!
    proxy_set_header      Host $host;
    proxy_set_header      X-Real-IP $remote_addr;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto https;  # $scheme 대신 하드코딩
    proxy_redirect        off;
}

proxy_pass http://localhost:3000/ (슬래시 있음)으로 설정하면 /grafana/login 요청이 http://localhost:3000/login으로 전달된다. Grafana는 /login을 받으면 /grafana/login으로 301을 내리고, nginx가 다시 /login으로 벗겨서 보내는 무한 루프가 생긴다. 슬래시를 빼면 /grafana/login 그대로 http://localhost:3000/grafana/login으로 전달된다.

grafana.ini

sudo nano /etc/grafana/grafana.ini

[server]
protocol            = http
domain              = your-domain.com          # 실제 도메인
root_url            = https://your-domain.com/grafana/
serve_from_sub_path = true

주석 기호(;)를 반드시 제거해야 적용된다.

적용

sudo nginx -t && sudo systemctl reload nginx
sudo systemctl restart grafana-server

브라우저에서 https://your-domain.com/grafana/ 접속 후 초기 계정 admin / admin으로 로그인.

7단계 — Prometheus 데이터소스 연결

Grafana UI에서 Connections → Data Sources → Add → Prometheus 선택 후:

8단계 — 대시보드 주요 PromQL

# 서버 생존 여부
nginx_rtmp_up

# 활성 스트림 수
nginx_rtmp_stream_count{app="live"}

# 전체 시청자 합계
sum(nginx_rtmp_clients)

# 입력 비트레이트 (Mbps)
sum(nginx_rtmp_bw_in_bps) / 1000000

# ffmpeg 프로세스 수
nginx_rtmp_ffmpeg_processes

# CPU 사용률 (%)
100 - (avg by(instance)(rate(node_cpu_seconds_total{mode="idle"}[1m])) * 100)

# 메모리 사용률 (%)
(1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes) * 100

# 네트워크 수신 (Mbps)
rate(node_network_receive_bytes_total{device!="lo"}[1m]) * 8 / 1000000

포트 정리 및 보안 그룹 권장 설정

Prometheus와 각 exporter는 외부에 노출할 이유가 없다. NHN Cloud 등 클라우드 보안 그룹에서 9090/9100/9101은 차단하고, Grafana는 nginx 리버스 프록시를 통해서만 접근하도록 구성하는 것을 권장한다.

트러블슈팅 요약

exporter가 9101에서 응답하지 않음

sudo journalctl -u nginx_rtmp_exporter -n 30

ModuleNotFoundError: No module named 'lxml' → sudo apt install -y python3-lxml python3-requests python3-prometheus-client

Prometheus 타겟이 1개뿐

설정 파일 수정 후 reload를 빠뜨린 경우.

curl -X POST http://localhost:9090/-/reload

Grafana 접속 시 500 에러

nginx 에러 로그와 curl -sIL 리다이렉트 체인을 먼저 확인한다.

sudo tail -50 /var/log/nginx/error.log
curl -sIL --max-redirs 5 https://your-domain.com/grafana/

301 무한 루프

• proxy_pass 끝 슬래시 제거 (http://localhost:3000 ← 슬래시 없음)
• grafana.ini의 domain, root_url, serve_from_sub_path 주석 해제 및 올바른 값 입력
• proxy_set_header X-Forwarded-Proto https 하드코딩 (변수 대신)

1. telegram 가입

현재로선 구글링한 어떤 방법으로도 2천원을 내지 않고 telegram 에 신규 가입할 수 있는 방법은 없습니다. 우선 2천원을 내고 신규 가입을 합니다.

그리고 오른쪽 위에 검색을 눌러 BotFather 를 누릅니다. 이때, 굉장히 다양한 가짜 계정이 있으니 반드시 blue check 을 확인합니다.

2. bot 생성

굉장히 다양한 메뉴가 있는데 /newbot 클릭

이름을 정해합니다. 처음 정하는 이름은 상태창에 뜨는 이름이고 두번째 정하는 이름은 bot 자체의 이름입니다. 이때, 만약 본인이 자비스를 만들고 싶다면

1. Javis
2. Jav13_bot 등 으로 지으면 됩니다. (뒤에는 bot 으로 끝나야하고 id 처럼 이미 선점된 bot 이름은 설정 불가)

이때, 나온 HTTP API 키를 잘 보관 형식은 숫자:문자열 형식.

3. clawd bot 연결

clawdbot 에 연결할 때 따로 json 에서 설정을 잡아줘도 되지만 clawdbot dashboard 로 간편하게 해당 부분만 설정해도 됩니다. 이때, 저장해준 숫자:문자열 형식의 token 을 입력 후 상단의 본인 bot 을 클릭하면 대화창이 뜨게 됩니다.

그리고 여기서 user id 를 저장! (Pairing code 아님) 이 부분을 web UI 에서 Allow From 부분을 추가하고 사용하면 됩니다.

그리고 말을 걸어보면 잘 연결 된 것을 확인할 수 있읍니다.

4. service 등록

window 에서 service 등록 방법엔 여러가지가 있는데 가장 편리한 것은 WinSW 가 편리할 듯 합니다. 예전에 window 서버에 .jar 말아서 올리던 기억이 있어서 저에게 가장 편한 WinSW 로 서비스화 하였습니다. 이제 pc 를 재부팅 해도 자연스럽게 telegram 으로 연결이 됩니다.

5. moltbot VS Claud desktop

Moltbot이 더 적합한 경우

1. local 에서 완전한 자동화 권한(shell, file, browser, cron)을 주고 AI가 “백그라운드에서 알아서 하게” 하고 싶을 때.
2. claude 외에 GPT, 로컬 모델을 섞어서 쓰고 싶거나, 자체 스킬/플러그인을 만들어 붙이고 싶은 경우.

Claude Desktop이 더 적합한 경우

1. claude 계정 기반 워크플로우(project, code, cowork)를 데스크톱에서 안정적으로 쓰고 싶은 경우.
2. 미친 장점 OAuth 방식이라 구독료 이외의 지출 X

사설

moltbot 에 claude 를 붙이기는 너무 사치고 qwen 같은 가성비 모델을 붙여서 막 굴리는 게 좋지 않을까 물론 정보는 중국에 넘어갈지도..?

window 에서는 현재까지 moltbot 이 아닌, clawdbot 으로 써야합니다.

disconnected (1008): unauthorized: gateway token missing (open a tokenized dashboard URL or paste token in Control UI settings)

web ui 에서 다음과 같이 뜬다면 아래 명령어를 입력하면 됨.

https://www.answeroverflow.com/m/1465993262190956688

clawdbot dashboard

claudebot onboard

위 help 의 wizard settup 에서 볼 수 있듯, 혹시 telegram 2천원 때문에 @clawdbot/line 으로 시도하려다 설치가 안 돼서 설정이 꼬인 분들은 clawd onboard 로 reset all 을 선택하시면 설정을 처음부터 다시 잡을 수 있습니다.

참고로 npm 에 들어가보니 베트남에서 많이 쓰이는 Zola 가 존재하고 line 은 없더라구요. 심지어 line 은 일본, 베트남 등 동남아에서 많이 쓰는 메신져 앱이라고 소개됨.

RDB 중 가장 버그가 안 나고 편리한 DB tool 중 Heidsql 을 사용하고 있다. 문제는 5Mb 가 넘는 대용량 sql 파일을 import 할 때 주로 에러가 나온다. 이때, CMD로 훨씬 빠르게 실행하는 방법이 있다.

1. 로컬 pc 에 mysql 서버 설치하기

본인 pc 환경에 맞는 MSI 를 설치한다. (링크)

2. DB 서버 세팅

1. DB 서버에 user 접속 권한이 전체 권한인지 확인

   # DB 접속 둘 중 하나
   sudo mysql -u root -p
   mysql -u SmartSilverAdmin -p

# 호스트 확인
SELECT user, host FROM mysql.user;

% 설정이 안 되어있다면

ALTER USER 'SmartSilverAdmin'@'localhost' IDENTIFIED BY '비밀번호';
CREATE USER 'SmartSilverAdmin'@'%' IDENTIFIED BY '비밀번호';
GRANT ALL PRIVILEGES ON SmartSilverCenter.* TO 'SmartSilverAdmin'@'%';
FLUSH PRIVILEGES;

2. DB 서버에 DB 포트가 뚫려있는지 확인 기본값: 3306

   sudo ufw status | grep 3306
   sudo ufw allow 3306/tcp
   sudo ufw reload

3. DB 서버에 원격으로 접속 가능한지 .conf 값 설정

   sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf
   bind-address = 0.0.0.0

4. DB 서버가 설치된 인스턴스에 인그레스 방화벽 확인

3. 로컬 pc 에서 mysql 서버 접속하기

1. 이제 로컬 서버에서 mysql 서버의 DB 포트에 붙을 수 있는지 확인

   Test-NetConnection -ComputerName [DB서버IP주소] -Port 3306

2. 앞서 설치한 mysql server 위치에서 MySQL 콘솔 접속

   C:\Program Files\MySQL\MySQL Server 8.4\bin>mysql -h [DB서버IP주소] -P 3306 -u SmartSilverAdmin -p
   # 아래 문구가 뜨면 성공
   Enter password:

아니면 시스템 환경변수로 등록해줘도 됨.

3. 덤프 파일 바로 복원

   # exit 으로 나간 후
   C:\Program Files\MySQL\MySQL Server 8.4\bin>mysql -h [DB서버IP주소] -P 3306 -u SmartSilverAdmin -p [DB 명] < "C:\경로\대용량.sql"

📌 RTSP (Real Time Streaming Protocol)

🛠️ 용도

"컨트롤" 프로토콜에 가까움. → 영상/오디오 데이터를 직접 실어나르기보다는 재생, 일시정지, 중지 같은 명령 제어에 집중.

📦 데이터 전달

보통 RTP(Real-time Transport Protocol)랑 짝꿍으로 사용. 실제 영상 데이터는 RTP로 전달하고, RTSP는 그걸 관리.

⚙️ 사용처

CCTV, IP 카메라, 실시간 모니터링 시스템. (네트워크 카메라 주소가 rtsp://...인 경우가 많음.)

👍 특징

낮은 지연 시간(수백 ms 수준). 다만 방화벽이나 NAT 환경에서 잘 막히기도 함.

📌 RTMP (Real Time Messaging Protocol)

🛠️ 용도

원래 Adobe Flash Player 용으로 만든 "데이터 전송" 프로토콜. → 영상/오디오 데이터를 서버로 업로드하거나 내려받을 때 직접 씀.

📦 데이터 전달

TCP 기반, 자체 포맷으로 전송. 지금은 HLS/DASH 같은 표준 스트리밍으로 변환할 때 업로드(ingest) 프로토콜로 자주 사용.

⚙️ 사용처

유튜브 라이브, 트위치, 페이스북 라이브 등 방송 플랫폼 송출.

👍 특징

지연 시간은 RTSP보다 약간 크지만(1~5초), 범용 지원이 좋고 안정적임. 방화벽 우회도 상대적으로 쉬움.

ffmpeg 으로 미디어 스트림 hls 변환

0. libnginx-mod-rtmp 라이브러리

📜 정의

Debian/Ubuntu에서 제공하는 Nginx용 RTMP 동적 모듈 패키지다. 업스트림 오픈소스인 nginx-rtmp-module(일반적으로 arut/nginx-rtmp-module)을 배포판 포맷으로 묶어둔 것이라 보면 됨.

⚙️ 역할

1. Nginx에 rtmp {} 블록과 application {}/live on; 같은 RTMP 서버 기능을 추가
2. OBS 같은 퍼블리셔가 RTMP로 업로드(publish) 하면 이를 받아 중계(play/relay)
3. on_publish, on_play 등 이벤트 콜백(HTTP)로 인증/로깅을 붙일 수 있음. (관련 훅 링크)
4. exec로 FFmpeg를 자동 스폰하여 트랜스코딩/HLS 세그먼팅 파이프라인을 바로 붙일 수 있음.
5. (선택) 모듈 자체의 HLS/DASH 세그먼팅 기능도 있으나, 세밀한 제어·ABR 구성은 보통 FFmpeg가 더 유연함.

⚠️ 주의/제한

1. Nginx 공식 번들 모듈이 아닌 서드파티 모듈임. (배포판에서 편하게 쓰도록 패키징한 것)
2. RTMPS(SSL)를 네이티브로 직접 처리하지 않ㅓ는다. 필요하면 stunnel/Nginx stream 프록시 등으로 감싸 쓰는 패턴을 사용.
3. 무거운 실시간 트랜스코딩은 FFmpeg(또는 SRS 내장/외부 트랜스코드)로 처리하는 것이 일반적임.

1. RTMP Ingest 방식

패키지 설치

sudo apt update
sudo apt install -y nginx libnginx-mod-rtmp ffmpeg
sudo mkdir -p /var/www/hls
sudo chown -R www-data:www-data /var/www/hls

nginx.conf 작성

동적 모듈 로딩 + RTMP 인젯 + FFmpeg 자동 변환 + HLS 서빙

# 동적 RTMP 모듈 로드 (Ubuntu/Debian 표준 경로)
load_module modules/ngx_rtmp_module.so;

worker_processes auto;

events { worker_connections 1024; }

# ---------- RTMP(Ingest) 이 부분은 아예 새로 추가 ----------
rtmp {
    server {
        listen 1935;          # RTMP default 포트
        chunk_size 4096;

        application live {
            live on;          # publish/play 허용
            record off;

            # (선택) 퍼블리시 인증 HTTP 콜백 예시
            # on_publish http://127.0.0.1:8080/auth?name=$name&key=$arg_key;

            # 스트림이 들어오면 스트림 이름($name)별로 FFmpeg를 띄워 HLS를 생성
            # : ABR(1080/720/480) 3종, 2초 짜리 세그먼트, 오래된 세그먼트 삭제
            exec_kill_signal term;
            exec /usr/bin/ffmpeg -loglevel error -hide_banner \
                -reconnect 1 -reconnect_streamed 1 -reconnect_on_network_error 1 \
                -i rtmp://127.0.0.1/live/$name \
                -c:v libx264 -preset veryfast -profile:v high -level 4.1 -pix_fmt yuv420p \
                -sc_threshold 0 -g 60 -keyint_min 60 \
                -c:a aac -ar 48000 -ac 2 -b:a 128k \
                -filter:v:0 "scale=w=-2:h=1080" -b:v:0 6000k -maxrate:0 6420k -bufsize:0 12000k \
                -filter:v:1 "scale=w=-2:h=720"  -b:v:1 3500k -maxrate:1 3740k -bufsize:1 7000k  \
                -filter:v:2 "scale=w=-2:h=480"  -b:v:2 1200k -maxrate:2 1320k -bufsize:2 2400k  \
                -map 0:v:0 -map 0:a:0 -map 0:v:0 -map 0:a:0 -map 0:v:0 -map 0:a:0 \
                -hls_time 2 -hls_list_size 6 \
                -hls_flags delete_segments+program_date_time+independent_segments \
                -master_pl_name "$name/master.m3u8" \
                -var_stream_map "v:0,a:0 name:1080p v:1,a:1 name:720p v:2,a:2 name:480p" \
                -hls_segment_type mpegts \
                -hls_segment_filename "/var/www/hls/$name/v%v/seg_%06d.ts" \
                "/var/www/hls/$name/v%v/index.m3u8";
        }
    }
}

# ---------- HLS 서빙(HTTP) 일부 옵션 추가 ----------
http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;

    server {
        listen 80;
        server_name _;

        # HLS 정적 파일 제공
        location /hls/ {
            types {
                application/vnd.apple.mpegurl m3u8;
                video/mp2t ts;
            }
            alias /var/www/hls/;
            add_header Cache-Control no-cache;
            add_header Access-Control-Allow-Origin *;
            add_header Access-Control-Allow-Headers *;
        }
    }
}

적용:

sudo nginx -t && sudo systemctl reload nginx

OBS 설정

• 서버: rtmp://<서버IP 또는 도메인>/live
• 스트림 키: 예) mystream (인증을 붙였다면 mystream?key=YOURSECRET 식으로)

푸시가 성공하면 HLS는 다음 경로에 생긴다.

• 마스터 플레이리스트: http://<서버>/hls/mystream/master.m3u8
• 개별 레벨: /hls/mystream/v0/index.m3u8(1080p), v1(720p), v2(480p)

2. RTMP Ingress

exec를 쓰지 않고, 고정 스트림을 별도 서비스로 돌리는 방법 이게 훨씬 보기가 좋음. 대충 -p 옵션으로 /usr/local/bin/rtmp2hls.sh 작성

#!/usr/bin/env bash
set -Eeuo pipefail

IN="rtmp://127.0.0.1/live/mystream"   # OBS가 푸시하는 RTMP
OUTDIR="/var/www/hls/mystream"

mkdir -p "$OUTDIR"
exec /usr/bin/ffmpeg -loglevel error -hide_banner \
  -reconnect 1 -reconnect_streamed 1 -reconnect_on_network_error 1 \
  -i "$IN" \
  -c:v libx264 -preset veryfast -profile:v high -level 4.1 -pix_fmt yuv420p \
  -sc_threshold 0 -g 60 -keyint_min 60 \
  -c:a aac -ar 48000 -ac 2 -b:a 128k \
  -hls_time 2 -hls_list_size 6 \
  -hls_flags delete_segments+program_date_time+independent_segments \
  -f hls -hls_segment_filename "$OUTDIR/seg_%06d.ts" \
  "$OUTDIR/index.m3u8"

권한 추가

sudo chmod +x /usr/local/bin/rtmp2hls.sh

서비스 파일(.ini) 작성

# /etc/systemd/system/rtmp2hls.service
[Unit]
Description=RTMP -> HLS (FFmpeg)
After=network.target nginx.service

[Service]
User=www-data
Group=www-data
ExecStart=/usr/local/bin/rtmp2hls.sh
Restart=always
RestartSec=2
WorkingDirectory=/var/www/hls

[Install]
WantedBy=multi-user.target

데몬 로드 후 서비스 자동 등록 및 실행

sudo systemctl daemon-reload
sudo systemctl enable --now rtmp2hls

3. 체크리스트

권한: /var/www/hls에 www-data(또는 Nginx/FFmpeg가 도는 사용자) 쓰기 권한이 있어야 함.

경로: load_module modules/ngx_rtmp_module.so;가 실패하면 modules 경로(대개 /usr/lib/nginx/modules/)를 확인.

CORS: 웹 플레이어에서 크로스도메인 요청이면 /hls/에 CORS 헤더 추가(위 예시 포함).

키프레임 간격: 세그먼트 길이(예: 2초)의 정수배로 -g(GOP) 맞추는 것이 안정적.

성능: -preset veryfast부터 시작해서 여유되면 faster/fast로 올리기.

브라우저 RTMP: 불가. 웹은 HLS(또는 LL-HLS/WEBRTC)를 사용.

1. systemd 서비스 설정

yt-dlp 설치 및 경로 설정

yt-dlp 를 반드시 설치해야하는데, pipx로 설치하면 yt-dlp는 보통 ~/.local/bin/yt-dlp 또는 pipx venv 경로에 다 따라서 서비스에 PATH를 명시하고 스크립트에 절대경로를 없애거나 또는 정확한 절대경로로 수정 (/home/ubuntu/.local/bin/yt-dlp) 하면 된다.

서비스 파일(.ini) 작성 예시

[Unit]
Description=HLS live stream author.KJW
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/opt/live-stream
Environment="PATH=/home/ubuntu/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
Environment=PYTHONUNBUFFERED=1
ExecStart=/usr/bin/bash -lc /opt/live-stream/live-stream.sh
Restart=always
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=false
ProtectSystem=full
ReadWritePaths=/var/www/videos/hls/live/720p /opt/live-stream
StandardOutput=journal
StandardError=inherit

[Install]
WantedBy=multi-user.target

권한/마운트 이슈를 우회하고 진단도 쉬운 형태로 설정.

ExecStart=/usr/bin/bash -lc /opt/live-stream/live-stream.sh

참고로 -l(login)은 /etc/profile 등을 읽어서 PATH가 더 풍부해지지만, 사용자 셸 설정(~/.bashrc)은 기본으론 안 읽힐 수 있다. 그래서 서비스 파일에서 Environment=PATH=...를 명시하는 것이다.

스크립트 파일 작성 예시

#!/usr/bin/env bash
set -Eeuo pipefail

VIDEO_URL="${VIDEO_URL:-https://www.youtube.com/watch?v=채널_id}"
COOKIES="${COOKIES:-/opt/live-stream/cookies.txt}"
OUTPUT_DIR="${OUTPUT_DIR:-/var/www/videos/hls/live/720p}"

YTDLP_BIN="${YTDLP_BIN:-$(command -v yt-dlp)}"
FFMPEG_BIN="${FFMPEG_BIN:-$(command -v ffmpeg)}"

if [[ -z "${YTDLP_BIN}" ]]; then
  echo "yt-dlp not found in PATH" >&2; exit 127
fi
if [[ -z "${FFMPEG_BIN}" ]]; then
  echo "ffmpeg not found in PATH" >&2; exit 127
fi

mkdir -p "$OUTPUT_DIR"

RESTART_DELAY=15
UA="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115 Safari/537.36"
REF="https://www.youtube.com/"

if [[ -s "$COOKIES" ]]; then
  COOKIES_ARG=(--cookies "$COOKIES")
  FFMPEG_COOKIE_ARG=()  # 필요 시 -headers "Cookie: ..." 방식으로 교체
else
  COOKIES_ARG=()
  FFMPEG_COOKIE_ARG=()
fi

while true; do
  echo "[$(date)] Fetching fresh HLS URL from YouTube..."
  if ! HLS_URL="$("$YTDLP_BIN" -g "${COOKIES_ARG[@]}" --no-warnings -f "bv*[height<=720]+ba/b" "$VIDEO_URL")"; then
    echo "[$(date)] yt-dlp failed. Retrying in $RESTART_DELAY sec..."
    sleep "$RESTART_DELAY"; continue
  fi

  if [[ -z "$HLS_URL" ]]; then
    echo "[$(date)] Empty HLS URL. Retrying in $RESTART_DELAY sec..."
    sleep "$RESTART_DELAY"; continue
  fi

  echo "[$(date)] Got HLS URL: $HLS_URL"
  echo "[$(date)] Starting ffmpeg HLS restream..."

  set +e
  "$FFMPEG_BIN" -hide_banner -loglevel warning \
    -user_agent "$UA" -referer "$REF" "${FFMPEG_COOKIE_ARG[@]}" \
    -re -reconnect 1 -reconnect_streamed 1 -reconnect_delay_max 15 \
    -rw_timeout 20000000 -timeout 20000000 -seekable 0 \
    -fflags +genpts+discardcorrupt -probesize 15M -analyzeduration 20M \
    -i "$HLS_URL" -c copy -bufsize 20M -max_delay 5000000 \
    -f hls -hls_time 10 -hls_list_size 20 \
    -hls_flags delete_segments+append_list+omit_endlist \
    "$OUTPUT_DIR/index.m3u8"
  CODE=$?
  set -e

  echo "[$(date)] ffmpeg exited with code $CODE. Waiting $RESTART_DELAY sec before restart..."
  sleep "$RESTART_DELAY"
done

쓰기 경로 권한부여

출력 경로(/var/www/videos/hls/live/720p)는 User=ubuntu가 쓰기 가능해야 한다.

sudo mkdir -p /var/www/videos/hls/live/720p
sudo chown -R ubuntu:www-data /var/www/videos
sudo chmod -R 775 /var/www/videos

혹은 서비스에 아래 줄을 넣어주면 되는데,

ReadWritePaths=/var/www/videos/hls/live/720p /opt/live-stream

이 코드는 systemd sandbox 가 쓰기를 허용하는 줄이다. 참고로 디렉터리 자체 권한, 소유권까지 제대로 맞춰줘야 한다.

쿠키/헤더 옵션

작동 후 품질 개선을 위해 쿠키 및 헤더 옵션을 넣어준다. ffmpeg의 -cookies 옵션은 name=value; name2=value2 형태가 일반적인데, -cookies "file=/path" 는 ffmpeg 표준 옵션은 아니니(빌드마다 다를 수 있음) 헤더로 넘기는 방법을 고려하였다.

쿠키 파일을 헤더로 붙이는 예 (Netscape cookies.txt라면 변환 필요)

FFMPEG_COOKIE_ARG=(-headers "Cookie: $(awk 'BEGIN{ORS="; "}$0 !~ /^#/ {print $6"="$7}' "$COOKIES")")

일단 지금처럼 yt-dlp -g로 m3u8을 받아서 -user_agent와 -referer만 맞춰도 동작하는 경우가 많으니, 우선 권한/경로부터 해결하고 필요 시 다듬자.

트러블 슈팅 방법

1. 스크립트와 경로 권한 확인

# 각 경로 구성요소의 권한을 한 눈에 보기
namei -l /opt/live-stream/live-stream.sh

# 퍼미션/소유자 확인
ls -l /opt/live-stream/live-stream.sh
ls -ld /opt/live-stream

조건: live-stream.sh에 실행 비트가 있어야 함 => -rwxr-xr-x(0755) 추천 /opt 와 /opt/live-stream 디렉터리에 실행 권한이 있어야 User=사용자명 가 경로를 탐색(traverse) 가능 (보통 755)

수정

sudo chown 사용자명:사용자명 /opt/live-stream/live-stream.sh /opt/live-stream
sudo chmod 0755 /opt/live-stream /opt/live-stream/live-stream.sh

참고: 디렉터리의 x 권한은 “들어갈 수 있음”이다. 따라서 아무리 파일을 755로 바꿔도, 디렉터리가 700이면 여전히 Permission denied가 뜰 수 있다.

2) CRLF(윈도우 개행) 및 shebang 확인

윈도우에서 만든 스크립트면 커널이 인터프리터를 못 찾아서 문제를 낼 수 있다.

head -n1 /opt/live-stream/live-stream.sh
file /opt/live-stream/live-stream.sh

첫번째 명령어는 쉬뱅인 #!/usr/bin/env bash 가, 두번째 명령어는 with CRLF line terminators 가 보이면 안 된다.

캐리지 리턴, 라인 피드 정리를 위해선 아래 명령어를 입력하면 된다.

sudo sed -i 's/\r$//' /opt/live-stream/live-stream.sh

3) noexec 마운트 여부 확인

참고로 그럴일은 없겠지만 opt가 noexec로 마운트 되어있으면 실행 자체가 막힌다. 따라서 아래 명령어를 실행한 뒤,

findmnt -no TARGET,OPTIONS /opt
# 또는
mount | grep ' /opt '

noexec 가 보이면 가급적 스크립트를 noexec 아닌 경로(예: /usr/local/bin)로 옮기거나, 서비스에서 인터프리터로 실행하면 된다. ExecStart=/usr/bin/bash /opt/live-stream/live-stream.sh 참고로 이 방식은 스크립트에 x 비트가 없어도 동작한다. 대신 보안상 최선은 아님.

정리.

# 1) 권한/소유/개행 정리
sudo chown ubuntu:ubuntu /opt/live-stream /opt/live-stream/live-stream.sh
sudo chmod 0755 /opt/live-stream /opt/live-stream/live-stream.sh
sudo sed -i 's/\r$//' /opt/live-stream/live-stream.sh

# 2) 출력 디렉터리 준비
sudo mkdir -p /var/www/videos/hls/live/720p
sudo chown -R ubuntu:www-data /var/www/videos
sudo chmod -R 775 /var/www/videos

혹은 서비스 파일에 명시

# 3) /opt noexec 여부 점검(필요 시만 보통은 필요 없을꺼임.)
findmnt -no TARGET,OPTIONS /opt

# 4) 서비스 파일 수정(예: /etc/systemd/system/live-stream.service)
#   - ExecStart=/usr/bin/bash -lc /opt/live-stream/live-stream.sh
#   - Environment="PATH=/home/ubuntu/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"

# 5) systemd 반영 및 재기동
sudo systemctl daemon-reload
sudo systemctl restart live-stream
sudo journalctl -u live-stream -e --no-pager

비록 정책 문제와 맞물려 채택되지 못한 아이디어이지만 굉장히 참신한 아디어라 소개해본다.

1. 아이디어

0. 특정 주소 접속해서 라이브 변환기 가 켜져있는지 확인.
1. 대상 채널 코드을 youtube api에 주고, 켜져 있는 라이브 방송이 있는지 알아본다. (100 가스 소요.)

--> response 라이브 방송 클립코드 2. 라이브 방송 클립코드가 live인지 체크한다. (1 가스 소요.) 3. 라이브 방송 채널 코드를 주고, yt-dlp로 돌린걸 ffmpeg으로 넘겨준다. 3.1 yt-dlp로 hls 주소를 확인한다. 3.2 방송을 ffmpeg으로 포장 -> response ffmpeg으로 넘겨준 master.m3u8 경로 4. nginx가 master.m3u8을 서빙 5. 2번, 3번을 서비스로 등록

2. Youtube API

1) youtube API 설정

1. gcp 콘솔에서 프로젝트를 하나 만들고 API 및 서비스에 접근한다.

2. 사용자 인증 정보 탭에 들어가서 API 키를 생성한다.

이때, API키 수정을 누른 다음

YouTube Data API v3 만 선택하여 사용하도록 하자.

2) youtube API 사용

Search: list 를 사용해야한다. (관련 문서)

요청 req url 예시

https://www.googleapis.com/youtube/v3/search?part=snippet&q=@CHANNEL_HANDLE&eventType=live&type=video&key=YOUR_KEY

4. 구현

1) HLS 패스스루

“라이트 리스팀” — YouTube Live → (내 서버) HLS 패스스루 유튜브의 라이브 HLS(m3u8)를 받아서, 내 도메인에서 HLS로 재공급하는 방식이다.

이 방식의 문제는 cookie, 정책 등의 문제로 아쉽게도 탈락 되었다. 일일이 수동으로 해야할 경우가 많고 문제를 일으킬 요소도 굉장히 많았기 때문이다.

장점은 Youtube Live Url 을 인코딩 없이 -c copy로 리패키징(패스스루) 하면 CPU 부담 거의 없고 Youtube Live Url은 만료 토큰이 있으므로 주기적으로 새 URL을 갱신하는 작은 스크립트만 추가하면 되기 때문에 굉장히 간단하다.

하지만 담점으로 약관/저작권 이슈를 스스로 관리해야 하고(특히 외부 공개 재배포 시), URL 만료 시 자동 재연결 로직이 필요하다.

2) 최소 구현 예시

0. 필수 lib 설치

pipx install yt-dlp
source ~/.bashrc
which yt-dlp

여기서 yt-dlp 가 잘 나오는 것을 확인.

1. 유튜브 라이브 스트리밍 HLS(m3u8) URL 얻기

유튜브에서 방송 중인 채널의 HLS 주소를 직접 얻기 위해 youtube download player 를 사용

yt-dlp --cookies 쿠키경로 -g "https://www.youtube.com/watch?v=스트리밍ID"

# ex)
yt-dlp --cookies /opt/yt-restream/cookies.txt -g "https://www.youtube.com/watch?v=스트리밍ID"

2. ffmpeg로 재인코딩 & HLS 세그먼트 생성

유튜브의 HLS 스트림을 ffmpeg가 받아서, 우리 서버에서 쓸 수 있는 HLS로 변환하는 작업이다.

ffmpeg \
    -i "$(yt-dlp -g https://www.youtube.com/watch?v=스트리밍ID)" \
    -c copy \
    -f hls \
    -hls_time 4 \
    -hls_list_size 5 \
    -hls_flags delete_segments \
    /var/www/html/stream/index.m3u8


# ex)
ffmpeg -i "$(yt-dlp --cookies /opt/yt-restream/cookies.txt -g https://www.youtube.com/watch?v=스트리밍ID)" \
    -c copy -f hls -hls_time 4 -hls_list_size 5 -hls_flags delete_segments \
    /var/www/html/stream/index.m3u8

설명: -c copy → 재인코딩 없이 원본 그대로 복사 (CPU 부담 ↓) -hls_time 4 → 세그먼트 길이 4초 -hls_list_size 5 → m3u8에 최신 5개 세그먼트만 유지 -hls_flags delete_segments → 오래된 ts 파일 삭제 /var/www/html/stream/index.m3u8 → Nginx 같은 웹서버에서 접근 가능한 경로

• 참고로 이때, 지정한 path 에 폴더가 있어야한다.

3. (옵션) 권한 설정하기

sudo mkdir -p /opt/yt-restream
sudo nano /opt/yt-restream/restream.sh
sudo chmod +x /opt/yt-restream/restream.sh

4. nginx 설정 해주고

이때, CORS 필요한 경우 nginx에 add_header Access-Control-Allow-Origin *; 등 옵션 추가

5. 이제 위 수동 테스트를 바탕으로 자동화 sh 파일 작성

#!/usr/bin/env bash
set -Eeuo pipefail

VIDEO_URL="https://www.youtube.com/watch?v=NJUjU9ALj4A"
COOKIES="/opt/yt-restream/cookies.txt"
OUTPUT_DIR="/var/www/html/stream"

mkdir -p "$OUTPUT_DIR"

while true; do
    echo "[$(date)] Fetching new m3u8 URL..."
    M3U8_URL=$(/home/ubuntu/.local/bin/yt-dlp --cookies "$COOKIES" -g "$VIDEO_URL")

    echo "[$(date)] Starting ffmpeg restream..."
    ffmpeg \
        -loglevel error \
        -i "$M3U8_URL" \
        -c copy \
        -f hls \
        -hls_time 4 \
        -hls_list_size 5 \
        -hls_flags delete_segments \
        "$OUTPUT_DIR/index.m3u8"

    echo "[$(date)] ffmpeg stopped. Restarting in 5 seconds..."
    sleep 5
done

이때, ffmpeg 옵션으로 -hls_time 2, -hls_list_size 6 이면 보통 6~12초. 더 낮추면 끊김 위험이 높다.

6. 서비스 등록

systemd 서비스 파일 작성

[Unit]
Description=YouTube to HLS Restream Service
After=network.target

[Service]
Type=simple
User=ubuntu
ExecStart=/opt/yt-restream/restream.sh
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

7. 실행 및 로그

sudo systemctl daemon-reload
sudo systemctl enable 서비스이름
sudo systemctl start 서비스이름

로그 확인

journalctl -u 서비스이름 -f

결론. 이 아이디어가 채택이 안 된 이유.

트랜스코딩 없이 패스스루(-c copy)라 CPU는 가볍지만, 원본 코덱(보통 H.264/MP4 또는 VP9/WEBM)에 따라 일부 레거시 플레이어 호환성에 차이가 날 수 있다. 이때, 문제가 생기면 -c:v h264 -c:a aac 로 트랜스코딩을 고려하면 되는데 대신 CPU/GPU 코스트가 상승한다. 참고로 CDN을 앞단에 두면 대규모 시청자도 안정적으로 처리가 가능하다.

무튼 이 아이디어가 채택이 안 된 이유는 요청 빈도(yt-dlp & ffmpeg) 때문이다. 동작 과정이

1. yt-dlp yt-dlp -g 명령을 실행하는 순간, 유튜브 페이지를 12번 요청해서 실제 m3u8 주소를 뽑습는다. 평상시에 1초마다 계속 호출하는 건 아니고, 명령 실행할 때만 요청한다. m3u8 URL은 보통 몇 분몇 시간 유효하지만, 유튜브 라이브는 1시간 이내 만료되는 경우가 많다. → 그래서 주기적으로 새로 받아와야 함 (예: 30분~1시간마다)
2. ffmpeg 그리고 사실 여기가 문제인데 ffmpeg는 yt-dlp가 뽑아준 m3u8 URL을 읽어오는데, 이건 내부적으로 유튜브의 세그먼트(ts) 파일을 받아오는 HTTP 요청을 세그먼트 길이(내 경우 12초)마다 보낸다. 그럼 youtube 측에서는 요청을 너무 많이 보내서 429 too many req 에러를 보낸다.