[MAICE 개발기 5편] 무거운 AI 컨테이너를 무중단 배포하기 (Blue-Green with Jenkins)

0. 2026-03 업데이트 노트

이 글은 MAICE 백엔드에 Blue-Green 배포를 도입하던 시점의 기록입니다. 핵심 아이디어(무중단 배포, 헬스 체크, 빠른 롤백)는 여전히 유효하지만, 현재 운영 환경에서는 배포 자동화가 더 세분화되었습니다.

빌드 노드와 배포 노드를 분리해 파이프라인을 운영합니다.
사설 레지스트리를 통해 이미지 태그 기반으로 배포 이력을 관리합니다.
서비스별 헬스 체크 엔드포인트를 기준으로 배포 성공/실패를 판단합니다.

운영 방식은 프로젝트별로 다를 수 있으며, 본문 코드는 “원리 설명” 중심 예시입니다.

1. AI 서비스 배포의 어려움

일반적인 웹 서버는 가볍습니다. 재시작하는 데 1초도 안 걸리죠. 하지만 AI 에이전트 서버는 무겁습니다. Pytorch 등 거대한 라이브러리를 로딩하고, RAG를 위한 벡터 DB에 연결한 후, 초기 메모리 웜업까지 완료해야 하기 때문입니다.

서버를 껐다 켜는 데 30초~1분이 걸립니다. 배포할 때마다 1분씩 서비스가 멈춘다면 학습 흐름이 끊기게 됩니다. 그래서 Zero-downtime(무중단) 배포를 우선 과제로 두었습니다.

본 연구 기간(3주) 동안 측정한 시스템 가동률은 99.2%였습니다. 이 수치는 실험 규모의 트래픽 하에서의 결과이며, Blue-Green 배포는 안정성 확보에 기여한 요소 중 하나였습니다.

2. Blue-Green 배포 전략

우리는 Blue-Green 전략을 채택했습니다. 이는 두 개의 똑같은 운영 환경(Blue, Green)을 구축해두고, 트래픽만 스위칭하는 방식입니다.

현재 상태: Blue가 운영 중 (Live), Green은 대기 중 (Idle).
배포 시작: 새로운 코드를 Green 컨테이너에 배포합니다.
Health Check: Green 서버가 완전히 켜지고, AI 모델이 로딩될 때까지 기다립니다.
Traffic Switch: Nginx 설정을 변경하여 사용자의 요청을 Blue에서 Green으로 순식간에 돌립니다.
종료: Blue를 대기 상태로 전환합니다.

3. Jenkins Pipeline과 Groovy 스크립트

이 모든 과정은 Jenkins 파이프라인으로 자동화되어 있습니다. deploy-scripts/v5/deploy-backend-agent.groovy 스크립트는 다음과 같은 일을 수행합니다.

stage('Deploy to Idle Environment') {
    steps {
        script {
            // 현재 활성화된 컬러 확인 (Blue or Green?)
            def activeColor = sh(script: "./scripts/get_active_color.sh", returnStdout: true).trim()
            def targetColor = (activeColor == "blue") ? "green" : "blue"

            // 타겟 환경에 도커 컨테이너 실행
            sh "docker-compose -f docker-compose.${targetColor}.yml up -d"

            // 헬스 체크 (최대 30회 재시도)
            sh "./scripts/health_check.sh ${targetColor}"
        }
    }
}

4. Nginx를 이용한 트래픽 스위칭

트래픽 전환은 Nginx의 include 지시어를 활용해 심볼릭 링크를 교체하는 방식으로 아주 가볍게 처리합니다.

# scripts/deploy_backend_blue_green.sh 발췌

# 1. 새로운 업스트림 설정 파일 생성
echo "upstream backend { server <BACKEND_HOST>:${TARGET_PORT}; }" > nginx/conf.d/backend_upstream.new

# 2. 파일 교체 (Atomic Operation)
mv nginx/conf.d/backend_upstream.new nginx/conf.d/backend_upstream.conf

# 3. Nginx 설정 리로드 (연결 끊김 없음)
nginx -s reload

이 방식 덕분에 배포 중에도 기존 연결된 소켓은 유지되며, 새로운 요청만 새 서버로 연결됩니다.

5. 자동 롤백 (Rollback)

AI 모델은 예측 불가능한 동작을 보일 수 있어 배포 후 버그가 발견되기도 합니다. 우리는 scripts/rollback_backend_blue_green.sh를 통해, 문제가 생기면 약 10초 내 이전 버전(이전 컬러)으로 되돌릴 수 있는 안전장치를 마련했습니다. 이전 컨테이너를 바로 끄지 않고 일정 시간 살려두기 때문에 가능한 전략입니다.

이 파이프라인을 통해 학생들이 공부하는 저녁 시간대에도 배포를 진행할 수 있었습니다.