[아키텍처 설계 명세서] Spring Boot · Embedded Tomcat · Jenkins · Nexus · Git 표준 배포 아키텍처 및 운영 가이드 (SAD)

문서 제·개정 이력 (Revision History)

제1장. 설계 개요 및 아키텍처 원칙 (1. Architecture Overview & Principles)

[설계 핵심 정의 (Architecture Blueprint Summary)]: 본 설계서 및 배포 가이드는 Git(형상 관리) → Jenkins(CI/CD 파이프라인 오케스트레이터) → Sonatype Nexus 3(불변 아티팩트 저장소) → Spring Boot Embedded Tomcat(타겟 WAS 런타임)으로 이어지는 전사 표준 소프트웨어 공급망(Software Supply Chain)과 무중단 롤링 배포(Zero-Downtime Rolling Deployment) 아키텍처를 명세함.

1.1 시스템 컨텍스트 및 불변 아티팩트(Immutable Artifact) 배포 개념

• 시스템 경계 및 빌드·런타임 분리 구조:
  • 모든 애플리케이션 소스코드는 Git에서 단일 진실 공급원(SSOT)으로 관리되며, Jenkins 빌드 클러스터에서 컴파일·단위 테스트·정적 보안 분석(SonarQube)을 통과한 뒤 실행 가능한 단일 Fat JAR(Embedded Tomcat 내장) 형태로 패키징됨.
  • 생성된 바이너리는 Sonatype Nexus 3 저장소에 버전별 불변(Immutable) 아티팩트로 영구 봉인되며, 개발·검증·운영 타겟 서버는 재빌드 없이 오직 Nexus에서 검증된 동일 아티팩트를 다운로드하여 systemd 및 심볼릭 링크(Symlink) 스왑 방식으로 기동함.

1.2 배포 아키텍처 핵심 설계 원칙 명세 (Architecture Principles Specification)

1.3 비기능 품질 속성 및 배포 SLA/SLO 명세 (Quality Attribute Specification)

제2장. 논리 아키텍처 및 컴포넌트 설계 (2. Logical & Component View)

2.1 Git · Jenkins · Nexus · Embedded Tomcat 논리 아키텍처 구조도

• 구조 명세: 전체 배포 시스템은 역할과 네트워크 보안 경계에 따라 SCM & Governance Zone (형상/설정 관리) → CI/CD & Artifact Hub (빌드·품질검증·아티팩트 금고) → Target WAS Runtime Zone (리버스 프록시 및 임베디드 톰캣 런타임)의 3대 영역·8개 표준 컴포넌트(COMP-01 ~ COMP-08)로 구성됨.

2.2 컴포넌트 카탈로그 및 책임 명세표 (Component Specification Catalog)

2.3 Git 리포지토리 및 타겟 WAS 서버 표준 디렉토리 구조 명세

[1] Git 소스 리포지토리 표준 구조 (Source Repository Layout)
{service-name}-backend/
├── Jenkinsfile                        # [COMP-03] 선언적 CI/CD 파이프라인 정의서 (Stage 1~8)
├── build.gradle.kts                   # [COMP-04] Spring Boot 3.3 + Embedded Tomcat + Nexus Publish 설정
├── gradle.properties                  # 그룹 ID, 아티팩트 ID, 기본 버전(SemVer) 명세
├── deploy/
│   ├── scripts/
│   │   └── deploy-rolling.sh          # [COMP-06] Nexus 다운로드 · Symlink 스왑 · Nginx Draining · 롤백 스크립트
│   ├── systemd/
│   │   └── spring-app.service         # [COMP-08] 리눅스 systemd 데몬 유닛 템플릿
│   └── nginx/
│       └── upstream-app.conf          # [COMP-07] Nginx Upstream 로드밸런싱 및 Draining 설정 템플릿
└── src/
    ├── main/java/...                  # 비즈니스 애플리케이션 소스코드
    └── main/resources/
        └── application.yml            # 공통 기본 설정 + Embedded Tomcat 튜닝 + Graceful Shutdown 규격

[2] 타겟 리눅스 WAS 서버 표준 디렉토리 구조 (Target Server Filesystem: /app/{service})
/app/order-service/
├── current/
│   └── app.jar -> /app/order-service/releases/order-service-1.4.2.jar   # [원자적 Symlink 포인터]
├── releases/                          # [Nexus에서 다운로드한 불변 Fat JAR 보관소 — 최근 5개 버전 유지]
│   ├── order-service-1.4.2.jar        # 현재 운영 버전 (+ order-service-1.4.2.jar.sha256)
│   ├── order-service-1.4.1.jar        # 직전 롤백 대기 버전 (Golden Backup)
│   └── order-service-1.4.0.jar
├── config/                            # [패키지 외부 주입 설정 — 권한 chmod 600 appuser:appgroup]
│   ├── application-prod.yml           # 운영 환경 전용 설정 오버라이드 파일
│   └── env.conf                       # systemd EnvironmentFile (JAVA_OPTS, JASYPT_ENCRYPTOR_PASSWORD)
├── bin/
│   └── deploy-rolling.sh              # 로컬 실행용 배포/롤백 제어 스크립트
└── run/
    └── order-service.pid              # 프로세스 PID 파일
/logs/order-service/                   # [OS 루트 파티션 보호를 위해 별도 디스크 볼륨(/logs) 마운트]
├── app.json.log                       # 실시간 애플리케이션 구조화(JSON) 로그
├── access_log.2026-10-26.log          # Embedded Tomcat 내장 Access Log
└── dump/
    └── heapdump_oom.hprof             # OutOfMemoryError 발생 시 자동 덤프 저장 경로

제3장. 프로세스 및 런타임 파이프라인 설계 (3. Process & Runtime Sequence View)

3.1 표준 8단계 CI/CD 빌드 및 무중단 롤링 배포 시퀀스 다이어그램

• 동적 파이프라인 흐름: 전체 배포 공정은 Phase 1(CI: STEP 1 ~ STEP 4)에서 소스 검증 및 불변 아티팩트를 생성하여 Nexus에 봉인하고, Phase 2(CD: STEP 5 ~ STEP 8)에서 타겟 WAS 서버로 아티팩트를 반입한 뒤 Nginx 트래픽 Draining, Symlink 원자적 스왑, Actuator 헬스 프로브 검증을 거쳐 무중단으로 배포를 완결함.

3.2 단계별 CI/CD 파이프라인 실행 계약 및 실패 시 대응 명세표

제4장. 데이터 및 영속성 아키텍처 설계 (4. Data & Persistence View)

4.1 Nexus 3단 아티팩트 저장소 계층 및 타겟 서버 파일시스템 구조도

• 배포 데이터 뷰 명세: 배포 아키텍처에서의 핵심 영속 데이터는 빌드 바이너리 아티팩트(Nexus Repository), 타겟 서버 릴리스 디렉토리 및 심볼릭 링크 상태(/app/{service}), 런타임 로그(access_log, app.json.log), 그리고 무중단 배포를 위한 하위 호환 데이터베이스 스키마(Flyway Migration)로 구성됨.

4.2 아티팩트 저장소, 설정·로그 볼륨 및 DB 마이그레이션 정책 명세표

제5장. 물리 배포 및 회복탄력성·관측성 설계 (5. Deployment, Resilience & Observability View)

5.1 Multi-Node 무중단 롤링 배포 물리 토폴로지 및 관측성 구조도

• 물리 배치 및 런타임 제어 명세: 배포 제어망(CI/CD Control Plane)의 Jenkins와 Nexus는 배포 전용 보안 채널(SSH)을 통해 운영망(Production WAS Farm)의 Nginx 및 다중 WAS 노드(Group A / Group B)를 순차 제어하며, 모든 Embedded Tomcat 인스턴스는 Actuator 헬스 프로브와 Prometheus/Grafana 관측성 스택에 실시간 연결됨.

5.2 무중단 트래픽 드레이닝(Draining), Embedded Tomcat 튜닝 및 자동 롤백 설계

• Embedded Tomcat · JVM · 무중단 배포 엔지니어링 파라미터 명세표 (Runtime Tuning Specification)

제6장. 표준 인터페이스 및 코드 템플릿 명세 (6. Standard Interface & Code Specification)

6.1 CI/CD 파이프라인 및 타겟 서버 배포 구성 표준 템플릿 (Reference Implementation Templates)

• [Template 1] Spring Boot + Embedded Tomcat 런타임 및 Nexus 배포 설정 (build.gradle.kts & application-prod.yml)
  YAML

  # File: /app/order-service/config/application-prod.yml
  server:
    port: 8080
    shutdown: graceful                                  # [필수] 우아한 종료 활성화 (SIGTERM 수신 시 In-flight 요청 대기)
    tomcat:
      threads:
        max: 200                                        # 최대 워커 스레드 수
        min-spare: 50                                   # 상시 유지 최소 스레드 수
      max-connections: 8192                             # NIO 최대 동시 연결 수
      accept-count: 100                                 # 스레드 포화 시 OS 소켓 큐 대기열 크기
      connection-timeout: 5000ms
      keep-alive-timeout: 20000ms                       # 앞단 Nginx keepalive_timeout(15s)보다 크게 설정 (502 에러 방지)
      max-keep-alive-requests: 1000
      basedir: /app/order-service/work                  # OS /tmp 자동 삭제(tmpwatch)로 인한 Multipart 업로드 오류 방지
      accesslog:
        enabled: true
        directory: /logs/order-service
        prefix: access_log
        suffix: .log
        file-date-format: .yyyy-MM-dd
        pattern: '%h %l %u %t "%r" %s %b %D "%{X-Forwarded-For}i" "%{X-B3-TraceId}i"'
  
  spring:
    lifecycle:
      timeout-per-shutdown-phase: 30s                   # Graceful Shutdown 최대 대기 시간 (30초)
    jpa:
      open-in-view: false
  
  management:
    server:
      port: 8081                                        # [보안] 관리/헬스체크 포트 분리 (외부 노출 차단)
    endpoint:
      health:
        probes:
          enabled: true                                 # /actuator/health/liveness, /actuator/health/readiness 활성화
        show-details: when-authorized
    endpoints:
      web:
        exposure:
          include: health,info,prometheus,metrics,threaddump

• [Template 2] Jenkins 선언적 CI/CD 파이프라인 (Jenkinsfile — Git → Gradle → SonarQube → Nexus → Rolling Deploy)
  GROOVY

  // File: Jenkinsfile (Declarative Pipeline for Spring Boot + Nexus + Embedded Tomcat)
  pipeline {
      agent { label 'linux-jdk21-agent' }
      options {
          timeout(time: 15, unit: 'MINUTES')
          disableConcurrentBuilds()                     // 동일 파이프라인 동시 배포 충돌 방지
          buildDiscarder(logRotator(numToKeepStr: '30'))
      }
      parameters {
          choice(name: 'TARGET_ENV', choices: ['staging', 'prod'], description: '배포 대상 환경')
          string(name: 'RELEASE_VERSION', defaultValue: '1.4.2', description: '배포 아티팩트 버전 (SemVer)')
          booleanParam(name: 'ROLLBACK_MODE', defaultValue: false, description: '긴급 롤백 실행 여부')
      }
      environment {
          APP_NAME       = 'order-service'
          GROUP_PATH     = 'com/company/order'
          NEXUS_BASE_URL = 'https://nexus.internal.company.com/repository/maven-releases'
      }
      stages {
          stage('1. SCM Checkout & Build Info') {
              when { expression { !params.ROLLBACK_MODE } }
              steps {
                  checkout scm
                  sh "./gradlew --version"
              }
          }
          stage('2. Unit Test & Fat JAR Package') {
              when { expression { !params.ROLLBACK_MODE } }
              steps {
                  withCredentials([usernamePassword(credentialsId: 'nexus-maven-cred', usernameVariable: 'NEXUS_USER', passwordVariable: 'NEXUS_PASS')]) {
                      sh "./gradlew clean test bootJar -Pversion=${params.RELEASE_VERSION} --no-daemon"
                  }
              }
              post {
                  always { junit '**/build/test-results/test/*.xml' }
              }
          }
          stage('3. SonarQube Quality Gate') {
              when { expression { !params.ROLLBACK_MODE } }
              steps {
                  withSonarQubeEnv('SonarQube-Enterprise') {
                      sh "./gradlew sonar -Dsonar.projectVersion=${params.RELEASE_VERSION}"
                  }
                  timeout(time: 5, unit: 'MINUTES') {
                      waitForQualityGate abortPipeline: true
                  }
              }
          }
          stage('4. Publish Immutable JAR to Nexus') {
              when { expression { !params.ROLLBACK_MODE } }
              steps {
                  withCredentials([usernamePassword(credentialsId: 'nexus-maven-cred', usernameVariable: 'NEXUS_USER', passwordVariable: 'NEXUS_PASS')]) {
                      sh "./gradlew publish -Pversion=${params.RELEASE_VERSION} --no-daemon"
                  }
              }
          }
          stage('5. Production Approval & Rolling Deploy') {
              steps {
                  script {
                      if (params.TARGET_ENV == 'prod' && !params.ROLLBACK_MODE) {
                          input message: "[운영 배포 승인] ${APP_NAME} v${params.RELEASE_VERSION} 버전을 운영 WAS에 롤링 배포하시겠습니까?", ok: "배포 승인"
                      }
                      def targetHosts = (params.TARGET_ENV == 'prod') ? ['10.10.20.11', '10.10.20.12'] : ['10.20.20.11']
                      def actionFlag  = params.ROLLBACK_MODE ? "--rollback" : "--deploy"
  
                      withCredentials([usernamePassword(credentialsId: 'nexus-maven-cred', usernameVariable: 'NEXUS_USER', passwordVariable: 'NEXUS_PASS')]) {
                          sshagent(credentials: ['was-deploy-ssh-key']) {
                              for (host in targetHosts) {
                                  echo ">>> Rolling Deploy on Target WAS Node: ${host}"
                                  sh """
                                      ssh -o StrictHostKeyChecking=no appuser@${host} \
                                          "/app/${APP_NAME}/bin/deploy-rolling.sh ${actionFlag} \
                                           --version ${params.RELEASE_VERSION} \
                                           --nexus-url ${NEXUS_BASE_URL}/${GROUP_PATH}/${APP_NAME}/${params.RELEASE_VERSION}/${APP_NAME}-${params.RELEASE_VERSION}.jar \
                                           --nexus-user ${NEXUS_USER} --nexus-pass '${NEXUS_PASS}'"
                                  """
                              }
                          }
                      }
                  }
              }
          }
      }
  }

• [Template 3] 타겟 WAS systemd 데몬 유닛 및 무중단 롤링 배포·롤백 스크립트 (spring-app.service & deploy-rolling.sh)
  INI

  # File: /etc/systemd/system/order-service.service
  [Unit]
  Description=Spring Boot Embedded Tomcat Service (order-service)
  After=network-online.target
  Wants=network-online.target
  
  [Service]
  Type=simple
  User=appuser
  Group=appgroup
  WorkingDirectory=/app/order-service
  EnvironmentFile=/app/order-service/config/env.conf
  ExecStart=/usr/lib/jvm/temurin-21-jdk/bin/java $JAVA_OPTS \
      -jar /app/order-service/current/app.jar \
      --spring.profiles.active=prod \
      --spring.config.additional-location=optional:file:/app/order-service/config/
  KillMode=process
  KillSignal=SIGTERM
  TimeoutStopSec=40
  SuccessExitStatus=143
  Restart=on-failure
  RestartSec=5
  LimitNOFILE=65536
  LimitNPROC=16384
  
  [Install]
  WantedBy=multi-user.target

#!/usr/bin/env bash
# File: /app/order-service/bin/deploy-rolling.sh
set -euo pipefail

APP_NAME="order-service"
APP_HOME="/app/${APP_NAME}"
RELEASES_DIR="${APP_HOME}/releases"
CURRENT_LINK="${APP_HOME}/current/app.jar"
NGINX_DRAIN_FLAG="/etc/nginx/drain/${APP_NAME}.drain"
HEALTH_URL="http://127.0.0.1:8081/actuator/health/readiness"

MODE="${1:---deploy}"
VERSION="${3:-}"
NEXUS_JAR_URL="${5:-}"
NEXUS_USER="${7:-}"
NEXUS_PASS="${9:-}"

drain_traffic() {
    echo "[STEP 6] Draining L7 traffic from current WAS node..."
    touch "${NGINX_DRAIN_FLAG}" && sudo /usr/sbin/nginx -s reload
    sleep 3
}

undrain_traffic() {
    echo "[STEP 8] Restoring L7 traffic to current WAS node..."
    rm -f "${NGINX_DRAIN_FLAG}" && sudo /usr/sbin/nginx -s reload
}

wait_for_readiness() {
    for i in $(seq 1 30); do
        STATUS=$(curl -sf "${HEALTH_URL}" | grep -o '"status":"UP"' || true)
        if [[ "${STATUS}" == '"status":"UP"' ]]; then
            echo "[OK] Embedded Tomcat Readiness UP verified (attempt ${i}/30)."
            return 0
        fi
        sleep 2
    done
    return 1
}

rollback_previous() {
     PREV_JAR=$(ls -1t "${RELEASES_DIR}"/${APP_NAME}-*.jar | sed -n '2p')
    echo "[ROLLBACK] Reverting symlink to previous golden artifact: ${PREV_JAR}"
    ln -sfn "${PREV_JAR}" "${CURRENT_LINK}"
    sudo /bin/systemctl restart "${APP_NAME}.service"
    wait_for_readiness && undrain_traffic
}

if [[ "${MODE}" == "--rollback" ]]; then
    drain_traffic
    rollback_previous
    exit 0
fi

# [STEP 5] Nexus에서 불변 아티팩트 및 SHA-256 체크섬 다운로드 후 무결성 대조
TARGET_JAR="${RELEASES_DIR}/${APP_NAME}-${VERSION}.jar"
curl -fSL -u "${NEXUS_USER}:${NEXUS_PASS}" -o "${TARGET_JAR}" "${NEXUS_JAR_URL}"
curl -fSL -u "${NEXUS_USER}:${NEXUS_PASS}" -o "${TARGET_JAR}.sha256" "${NEXUS_JAR_URL}.sha256"
echo "$(cat "${TARGET_JAR}.sha256")  ${TARGET_JAR}" | sha256sum -c -

# [STEP 6 & 7] 트래픽 Draining → Graceful Shutdown → Symlink 원자적 스왑 → 기동
drain_traffic
sudo /bin/systemctl stop "${APP_NAME}.service"
ln -sfn "${TARGET_JAR}" "${CURRENT_LINK}"
sudo /bin/systemctl start "${APP_NAME}.service"

# [STEP 8] Readiness 헬스체크 검증 (실패 시 자동 롤백)
if wait_for_readiness; then
    undrain_traffic
    ls -1t "${RELEASES_DIR}"/${APP_NAME}-*.jar | tail -n +6 | xargs -r rm -f
    echo "[SUCCESS] Deployment of ${APP_NAME} v${VERSION} completed with zero downtime."
else
    echo "[ERROR] Readiness check failed! Initiating automatic rollback..."
    rollback_previous
    exit 1
fi

제7장. 아키텍처 적합성 검증 및 기술 스택 명세 (7. Architecture Fitness & Tech Stack BOM)

7.1 배포 파이프라인 및 런타임 적합성 자동 검증 규칙 (Deployment Fitness Functions)

모든 Spring Boot 서비스 리포지토리와 타겟 WAS 서버는 아래 5대 배포 적합성 검증 규칙(DEPLOY-RULE-01 ~ DEPLOY-RULE-05)을 준수해야 하며, Jenkins 파이프라인 사전 검증(Pre-flight Check) 단계에서 단 1건이라도 위반 시 배포가 즉시 차단됨.

7.2 전사 표준 빌드·배포·런타임 기술 스택 명세서 (Standard CI/CD & Runtime BOM)