![[시리즈 1/5] 무중단 자동 배포 시스템이란? — 전체 아키텍처 이해하기](https://blog.flyerschal.com/uploads/posts/cicd-s1-cover.png)
[시리즈 1/5] 무중단 자동 배포 시스템이란? — 전체 아키텍처 이해하기
[시리즈 1/5] 무중단 자동 배포 시스템이란? — 전체 아키텍처 이해하기
이 글은 "Claude Code로 구축하는 무중단 자동 배포 시스템" 시리즈의 첫 번째 글입니다.
왜 자동 배포가 필요한가?
코드를 수정하고 서버에 반영하기까지, 수동으로 하면 이런 과정을 거칩니다:
- 로컬에서 코드 수정 후
git push - 서버에 SSH 접속
git pull로 최신 코드 가져오기npm install && npm run build- 서비스 재시작
- 브라우저에서 확인
한 번이면 괜찮습니다. 하지만 하루에 5번, 10번 배포한다면? 매번 같은 작업을 반복하는 건 시간 낭비이자 실수의 원인입니다.
수동 배포의 문제점
| 문제 | 영향 |
|---|---|
| 반복 작업 | 배포마다 5~10분 소요, 하루 누적 시간 큼 |
| 휴먼 에러 | 빌드 명령어 누락, 잘못된 브랜치 배포 |
| 다운타임 | 빌드 중 서비스 중단 (사용자 이탈) |
| 추적 불가 | 누가, 언제, 어떤 버전을 배포했는지 기록 없음 |
| 야간/외출 시 | PC 앞에 있어야만 배포 가능 |
자동 배포 시스템은 이 모든 문제를 해결합니다.
우리가 구축할 시스템
이 시리즈에서 구축하는 시스템의 전체 구조입니다:
개발자 (또는 Claude Code)
│
│ git push origin main
▼
┌─────────────────┐
│ GitHub │ ──── Webhook POST ────┐
│ (소스 저장소) │ │
└─────────────────┘ ▼
┌─────────────────────┐
│ Webhook Server │
│ (adnanh/webhook) │
│ 요청 검증 + 트리거 │
└──────────┬──────────┘
│
│ execute-command
▼
┌─────────────────────┐
│ deploy.sh │
│ 1. git clone │
│ 2. npm build │
│ 3. docker build │
│ 4. 컨테이너 시작 │
│ 5. 헬스체크 │
│ 6. nginx 전환 │
│ 7. 텔레그램 알림 │
└──────────┬──────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────────┐ ┌──────────┐
│ 🔵 Blue │ │ 🔀 Nginx │ │ 🟢 Green │
│ (대기) │◄────│ (트래픽 전환) │────►│ (활성) │
└──────────┘ └──────────────┘ └──────────┘
핵심 구성 요소
1. GitHub Repository
소스 코드가 저장되는 곳입니다. main 브랜치에 푸시하면 Webhook이 발동합니다.
2. Webhook Server (adnanh/webhook) GitHub에서 보낸 HTTP 요청을 받아, 서명을 검증하고, 배포 스크립트를 실행합니다. 가벼우면서도 보안이 확실합니다.
3. deploy.sh (배포 스크립트) 실제 배포 로직이 담긴 셸 스크립트입니다. 소스 다운로드부터 Docker 이미지 빌드, 컨테이너 교체, Nginx 전환까지 모든 과정을 자동으로 수행합니다.
4. Docker 애플리케이션을 컨테이너로 패키징합니다. 어떤 환경에서든 동일하게 실행되는 것을 보장합니다.
5. Nginx (리버스 프록시) 사용자의 요청을 받아 적절한 컨테이너로 전달합니다. Blue/Green 전환의 핵심입니다.
6. 텔레그램 알림 배포 시작, 성공, 실패를 모바일로 즉시 알려줍니다.
Blue/Green 배포란?
무중단 배포의 핵심은 Blue/Green 전략입니다.
기본 개념
동일한 애플리케이션을 두 개의 환경(Blue, Green)으로 운영합니다:
- Blue: 현재 트래픽을 처리 중인 환경 (v1.0)
- Green: 대기 중인 환경 (비활성)
새 버전을 배포할 때:
- Green에 새 버전(v1.1)을 배포
- Green이 정상인지 헬스체크
- 정상이면 Nginx가 트래픽을 Green으로 전환
- Blue를 정지
다음 배포에서는 역할이 바뀝니다 (Green이 활성 → Blue에 배포).
왜 Blue/Green인가?
| 방식 | 다운타임 | 롤백 | 복잡도 |
|---|---|---|---|
| 직접 재시작 | 있음 (수초~수분) | 어려움 | 낮음 |
| Rolling Update | 거의 없음 | 복잡 | 중간 |
| Blue/Green | 없음 | 즉시 | 중간 |
| Canary | 없음 | 가능 | 높음 |
Blue/Green의 장점:
- 다운타임 제로: 전환 순간에도 서비스 중단 없음
- 즉시 롤백: 문제 발생 시 이전 환경으로 바로 전환
- 검증 후 전환: 새 환경이 정상인지 확인한 후에만 트래픽 전환
- 심플한 구조: 복잡한 오케스트레이션 없이 Nginx만으로 구현 가능
이 시스템의 장단점
장점
- 별도 CI/CD 서버 불필요 — GitHub Actions, Jenkins 없이 구현
- 저비용 — 추가 인프라 비용 없음 (기존 서버에서 운영)
- 완전 자동화 —
git push한 번으로 전 과정 완료 - 투명성 — 텔레그램으로 모든 과정 실시간 확인
- Claude Code와 시너지 — AI가 코드 작성 + 배포까지 자동으로
단점과 고려사항
- 단일 서버 의존 — 서버가 다운되면 배포 불가 (HA 구성이 아님)
- 빌드가 서버에서 실행 — 서버 리소스 사용 (대규모 프로젝트에는 부적합)
- 수동 설정 필요 — 초기 구축에 시간 투자 필요
💡 이 시스템은 1인 개발자, 소규모 팀, 사이드 프로젝트에 최적화되어 있습니다. 대규모 서비스라면 GitHub Actions + AWS ECS 같은 매니지드 서비스가 더 적합합니다.
필요한 사전 지식
이 시리즈를 따라하기 위해 필요한 최소한의 지식입니다:
| 기술 | 수준 | 설명 |
|---|---|---|
| Git | 기본 | push, pull, commit 정도 |
| Docker | 기본 | Dockerfile 작성, docker run 사용 |
| Linux/Shell | 기본 | 기본 명령어, 셸 스크립트 읽기 |
| Nginx | 초급 | 설정 파일 구조 이해 |
| Claude Code | 기본 | 설치 및 기본 사용법 |
모르는 부분이 있어도 괜찮습니다. 각 단계에서 필요한 만큼 상세히 설명합니다.
필요한 환경
- 서버 — Ubuntu 22.04+ 또는 macOS (Docker 실행 가능한 환경)
- 도메인 — HTTPS를 위한 도메인 (Let's Encrypt 무료 SSL)
- GitHub 계정 — 저장소 + Webhook 설정
- 텔레그램 계정 — BotFather로 봇 생성
- Claude Code — Anthropic CLI 설치
다음 글 미리보기
다음 글에서는 GitHub 저장소 설정과 Webhook 서버 구축을 다룹니다:
- GitHub 저장소 생성 및 Deploy Key 설정
- adnanh/webhook Docker 컨테이너 설정
- hooks.json 작성 및 HMAC-SHA256 보안 설정
- Nginx에서 Webhook 프록시 설정
- 실제 테스트로 동작 확인
