단일 서버에서 무중단 배포 구현하기 — Jenkins + Docker + Nginx Blue-Green 전략

🙋 들어가며

안녕하세요! 이번 글에서는 서비스의 단일 Oracle Cloud 인스턴스에서 다운타임 없이 배포하는 방법을 공유합니다.

클라우드 비용 최적화를 위해 단일 인스턴스를 사용하고 있었는데, 배포할 때마다 서비스가 잠시 중단되는 문제가 있었습니다. 이를 해결하기 위해 8080 / 8081 포트를 번갈아 사용하는 Blue-Green 전략과 Nginx 심볼릭 링크 전환 방식을 도입했습니다.

이 글에서 다룰 내용은 아래와 같습니다.

• 단일 서버 Blue-Green 배포의 원리
• Jenkins Multibranch Pipeline 설정 및 브랜치별 자동 배포
• Jenkins Pipeline 전체 흐름
• Nginx 심볼릭 링크 전환 방법
• 헬스체크 기반 자동 롤백

---

🏗️ 1. 전체 배포 흐름

GitHub Push (develop / main 브랜치)
  → GitHub Webhook
    → Jenkins Multibranch Pipeline 자동 트리거
      → Gradle bootJar 빌드
        → JAR 파일 원격 서버(SSH)로 전송
          → 원격 서버에서 Docker Image 빌드
            → 새 포트(8080 or 8081)에 컨테이너 실행
              → 헬스체크 통과
                → Nginx 설정 전환 (심볼릭 링크)
                  → 이전 컨테이너 종료

전체 배포가 자동화되어 있으며, 헬스체크 실패 시 자동으로 롤백됩니다.

---

🔵🟢 2. Blue-Green 배포 원리

서버 내부에는 항상 두 개의 포트가 준비되어 있습니다.

• Blue (예: 8080) : 현재 트래픽을 받고 있는 컨테이너
• Green (예: 8081) : 새 버전을 배포할 대기 포트

배포 시 Green에 새 버전을 올리고, 헬스체크가 통과하면 Nginx가 Green으로 트래픽을 전환합니다. 이전 Blue 컨테이너는 그 후에 종료됩니다.

[사용자 요청]
     ↓
  Nginx (80)
     ↓ (심볼릭 링크로 현재 활성 포트 결정)
  app_8080 또는 app_8081 (Docker 컨테이너)
     ↓
  Redis (내부 네트워크)

Nginx 심볼릭 링크 전환

app_8080.conf와 app_8081.conf 두 개의 설정 파일을 미리 만들어두고, 활성화할 파일을 심볼릭 링크로 지정합니다.

# /etc/nginx/sites-available/app_8080.conf
server {
    listen 80;
    server_name _;

    # API 요청
    location / {
        proxy_pass http://localhost:8080;
        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 $scheme;
    }
}

app_8081.conf는 포트 번호만 8081로 바꿔 동일하게 구성합니다.

배포 시 심볼릭 링크를 교체하고 Nginx를 reload하면 트래픽이 전환됩니다.

sudo ln -sf /etc/nginx/sites-available/app_8081.conf /etc/nginx/sites-enabled/app.conf
sudo nginx -t && sudo systemctl reload nginx

systemctl reload nginx는 기존 커넥션을 끊지 않고 새 설정을 적용합니다. 진행 중인 요청은 이전 컨테이너가 처리를 완료하고, 새 요청부터 새 컨테이너로 향합니다.

---

🛠️ 3. Jenkins 설정

Multibranch Pipeline 생성

Jenkins에서 New Item → Multibranch Pipeline을 선택합니다.

일반 Pipeline과 달리 Multibranch Pipeline은 레포지토리를 자동으로 스캔하여 브랜치마다 독립적인 파이프라인을 생성합니다.

• develop 브랜치 Push/Merge → dev 서버 자동 배포
• main 브랜치 Push/Merge → prod 서버 자동 배포

Branch Sources에서 GitHub 레포지토리를 연결하고, Scan Multibranch Pipeline Triggers에서 GitHub hook trigger를 활성화하면 Push/Merge 이벤트 발생 시 파이프라인이 자동으로 실행됩니다.

Credentials 등록

Jenkins > Manage Jenkins > Credentials에서 아래 항목들을 등록합니다.

Credential ID	타입	용도
goody_server_key	SSH Username with private key	배포 서버 SSH 접속 키
jenkins_github_key	SSH Username with private key	GitHub 레포지토리 클론 키
fcm-private-key	Secret text	FCM 서비스 계정 키
SENTRY_AUTH_TOKEN	Secret text	Sentry 배포 알림 토큰

---

⚙️ 4. Jenkins Pipeline 전체 흐름

파이프라인은 총 4단계로 구성됩니다.

단계	설명
Git Clone	브랜치 기준으로 코드 클론
Jar Build	Gradle로 bootJar 생성
Find Jar File	빌드된 JAR 파일 경로 확인
Remote Deploy	원격 서버에 JAR 전송 → 활성 포트 감지 후 다른 포트에서 Docker 이미지 빌드 및 실행 → 헬스체크 → Nginx 심볼릭 링크 변경 → 이전 컨테이너 정리

def jarFile

pipeline {
    agent any

    environment {
        IMAGE_NAME = "goody-api"
        SERVER = env.BRANCH_NAME == 'main' ? '<prod_server_ip>' : '<dev_server_ip>'
        SSH_USER = "ubuntu"
        SSH_KEY = credentials('goody_server_key')
        GIT_CREDENTIALS_ID = 'jenkins_github_key'
        SENTRY_AUTH_TOKEN = credentials('SENTRY_AUTH_TOKEN')
    }

    stages {
        stage('Git Clone') {
            steps {
                checkout([$class: 'GitSCM',
                    branches: [[name: env.BRANCH_NAME]],
                    userRemoteConfigs: [[
                        url: 'git@github.com:<org>/<repo>.git',
                        credentialsId: "${GIT_CREDENTIALS_ID}"
                    ]]
                ])
            }
        }

        stage('Jar Build') {
            steps {
                sh 'chmod +x ./gradlew'
                sh './gradlew --no-daemon clean :goody-server-api:bootJar'
            }
        }

        stage('Find Jar File') {
            steps {
                script {
                    def jarPath = "./goody-server-api/build/libs/"
                    jarFile = sh(script: "find ${jarPath} -name '*.jar' -print -quit", returnStdout: true).trim()
                    if (jarFile.isEmpty()) {
                        error "Jar file not found in ${jarPath}"
                    }
                    echo "Found Jar: ${jarFile}"
                }
            }
        }

        stage('Remote Deploy') {
            steps {
                script {
                    withCredentials([string(credentialsId: 'fcm-private-key', variable: 'FCM_KEY_JSON')]) {

                        // JAR 파일을 원격 서버로 전송
                        sh "scp -i $SSH_KEY ${jarFile} $SSH_USER@$SERVER:/home/$SSH_USER/app.jar"

                        // 원격 서버에서 배포 스크립트 실행
                        sh """
                        ssh -i $SSH_KEY $SSH_USER@$SERVER /bin/bash -s << 'EOF'
                            # 현재 활성 포트 감지
                            activePort=\\$(docker ps --format "{{.Names}}" | grep -oE "app_(8080|8081)" | cut -d'_' -f2)

                            if [ "\\$activePort" = "8080" ]; then
                                nextPort="8081"
                                prevContainer="app_8080"
                            else
                                nextPort="8080"
                                prevContainer="app_8081"
                            fi
                            nextContainer="app_\\${nextPort}"

                            # 원격 서버에서 Docker 이미지 빌드
                            docker build -t ${IMAGE_NAME} -f /home/${SSH_USER}/Dockerfile /home/${SSH_USER}/

                            # 기존 대기 컨테이너 정리 후 새 버전 실행
                            docker stop \\$nextContainer || true
                            docker rm \\$nextContainer || true

                            docker run -d --name \\$nextContainer \\\\
                                --env-file /home/${SSH_USER}/.env \\\\
                                --network ubuntu_goody-net \\\\
                                -p \\$nextPort:8080 \\\\
                                ${IMAGE_NAME}

                            # 헬스체크 — 90초(18회 × 5초) 시도
                            for i in {1..18}; do
                                status_code=\\$(curl -s -o /dev/null -w "%{http_code}" <http://localhost>:\\${nextPort}/actuator/health)

                                if [ "\$status_code" -eq 200 ]; then
                                    echo "헬스체크 성공 — Nginx 전환"

                                    sudo ln -sf /etc/nginx/sites-available/app_\${nextPort}.conf \\
                                        /etc/nginx/sites-enabled/app.conf
                                    sudo nginx -t && sudo systemctl reload nginx

                                    docker stop \${prevContainer} || true
                                    docker rm \${prevContainer} || true
                                    exit 0
                                fi

                                echo "헬스체크 실패 (\\${i}/18) — 5초 후 재시도"
                                sleep 5
                            done

                            # 90초 후에도 실패 → 롤백
                            echo "배포 실패 — 롤백"
                            docker stop \\${nextContainer} || true
                            docker rm \\${nextContainer} || true
                            exit 1
                        'EOF'
                        """
                    }
                }
            }
        }
    }
}

4-1. Remote Deploy 단계 흐름

Remote Deploy 스테이지는 원격 서버에서 아래 순서로 동작합니다.

① 활성 포트 감지

docker ps로 현재 실행 중인 컨테이너 이름을 확인해 활성 포트(8080 또는 8081)를 감지합니다. 감지된 포트의 반대 포트가 다음 배포 대상이 됩니다.

activePort=$(docker ps --format "{{.Names}}" | grep -oE "app_(8080|8081)" | cut -d'_' -f2)
# activePort=8080 이면 → nextPort=8081
# activePort=없음(초기 배포) 이면 → nextPort=8080

② Docker 이미지 빌드 및 컨테이너 실행

Jenkins에서 전송받은 JAR 파일로 원격 서버의 Dockerfile을 이용해 이미지를 빌드하고, 비활성 포트에 새 컨테이너를 실행합니다. 이 시점에는 아직 Nginx가 이전 컨테이너를 바라보고 있어 서비스는 정상 운영 중입니다.

③ 헬스체크 및 자동 롤백 (최대 90초)

새 컨테이너가 정상적으로 뜰 때까지 5초 간격으로 최대 18회 /actuator/health 엔드포인트를 호출합니다.

결과 동작

HTTP 200 응답	Nginx 심볼릭 링크 전환 → 이전 컨테이너 종료 (정상 배포)
90초 초과 실패	새 컨테이너 즉시 제거 → 이전 컨테이너 유지 (자동 롤백)

이전 컨테이너를 미리 종료하지 않기 때문에, 롤백 시에도 서비스 중단이 없습니다.

---

Docker 빌드를 원격 서버에서 하는 이유

초기에는 Jenkins 서버에서 Docker 이미지를 빌드해 .tar로 저장한 뒤 원격 서버로 전송하는 방식을 사용했습니다.

[초기 방식]
Jenkins: Gradle 빌드 → Docker 빌드 → docker save(.tar) → scp → docker load

그런데 dev 서버와 prod 서버는 Dockerfile 내용이 서로 달라, Jenkins 서버 한 곳에서 Dockerfile을 관리하면 환경별 차이를 제어하기 어렵기 때문에, 각 서버가 자신의 Dockerfile을 직접 유지하고 빌드하도록 방식을 변경했습니다.

[개선 방식]
Jenkins: Gradle 빌드 → scp(JAR만 전송) → 원격 서버에서 Docker 빌드 및 실행 (서버별 Dockerfile 사용)

---

📊 5. 서버 내부 구조 정리

goody-server-001
├── Nginx (Host:80)
│     └── 리버스 프록시 → app_8080 또는 app_8081
│
└── Docker 네트워크 (ubuntu_goody-net)
      ├── app_8080 (Spring Boot)
      ├── app_8081 (Spring Boot)  ← 배포 시 새 버전
      └── redis    (내부 통신 전용, 외부 미노출)

 

---

 

⚠️ 6. 트러블슈팅

activePort 감지 오류

처음에 아래처럼 작성했다가 app_8081이 실행 중일 때 app_8080도 매칭되는 버그가 있었습니다.

# 잘못된 코드 — app_8081 실행 중에도 app_8080이 매칭될 수 있음
activePort=$(docker ps --format "{{.Names}}" | grep app_8080 || true | cut -d'_' -f2)

# 수정된 코드 — 정확한 패턴 매칭
activePort=$(docker ps --format "{{.Names}}" | grep -oE "app_(8080|8081)" | cut -d'_' -f2)

---

🔎 7. 마무리

단일 인스턴스라도 두 포트 + Nginx 심볼릭 링크 조합으로 충분히 무중단 배포가 가능합니다. 핵심은 헬스체크 기반 자동 롤백으로 배포 실패 시 안전하게 이전 버전을 유지하는 것입니다.

배포 결과 — 다운타임 비교

배포 방식	다운타임
기존 (프로세스 종료 → 재기동)	약 32~45초
개선 (Blue-Green + Nginx 전환)	약 1초

 

→ 단순한 포트 전환만으로 다운타임 약 97% 단축을 달성했습니다.