Next.js 기반 본 사이트 iKnowABit 자동화 배포 프로세스 소개 | 기술 아키텍처

본 사이트(iKnowABit)는 Next.js 프레임워크를 기반으로 개발되었습니다. 무거운 CI/CD 도구(예: Jenkins 또는 GitLab CI)를 도입하지 않고, 네이티브 Shell 스크립트와 PM2 및 Node.js를 결합하여 가볍고 다운타임이 없는(Zero-downtime) 동시에 장애 자동 롤백 기능을 갖춘 자동 배포 프로세스를 구현했습니다.

본 문서에서는 이 배포 프로세스의 설계 사상, 해결한 문제점 및 구체적인 기술 구현 메커니즘을 상세히 분석합니다.

1. 페인 포인트 및 요구 사항 분석

네이티브 스크립트를 사용하여 Next.js 풀스택 프로젝트를 배포할 때, 일반적으로 다음과 같은 기술적 페인 포인트 에 직면하게 됩니다.

1. 서비스 중단 문제 : 프로덕션 디렉토리에서 직접 소스 코드 풀 및 종속성 설치를 실행하면 빌드 중에 서비스를 사용할 수 없게 됩니다.
2. 상태 오염 및 롤백의 어려움 : 종속성 설치가 실패하거나 데이터베이스 마이그레이션 중 오류가 발생하면 프로덕션 환경이 손상된 중간 상태가 되어 수동 복구 비용이 매우 높아집니다.
3. 다중 SQLite 데이터베이스 동시 관리 : 본 프로젝트의 기본 계층은 비즈니스 라인을 분리하기 위해 여러 개의 독립적인 SQLite 데이터베이스 파일을 사용합니다. 구조 마이그레이션을 수동으로 실행하면 누락이나 파일 잠금이 발생하기 쉽습니다.
4. 서버 리소스 소비 : 서버 로컬에서 완전한 Webhook 수신 서비스를 실행하면 추가적인 메모리 및 포트 리소스가 소비됩니다.

2. 아키텍처 설계 및 핵심 메커니즘

위의 문제를 해결하기 위해 본 사이트는 "경량 폴링 모니터링 + 원자적 심볼릭 링크 릴리스 + 장애 자동 정리" 의 아키텍처 솔루션을 설계했습니다.

• 경량화 모니터링 : 예약된 작업 시스템과 원격 Hash 읽기 명령을 결합하여 전체 코드를 다운로드하지 않고도 서버 측에 업데이트가 있는지 확인할 수 있습니다.
• 원자적 배포(Atomic Deployment) : 배포할 때마다 독립적인 타임스탬프 디렉토리를 생성하고, 격리된 디렉토리 내에서 코드 풀 및 종속성 설치를 수행하며, 최종적으로 심볼릭 링크(Symlink)를 전환하여 애플리케이션 버전을 업데이트합니다.
• 원활한 리로드 : PM2의 무중단 리로드 기능을 기반으로 심볼릭 링크 전환 후 Node 프로세스를 자동으로 다시 시작하여 온라인 사용자 요청이 중단되지 않도록 보장합니다.
• 안전한 롤백 메커니즘 : Bash 프로세스를 통해 비정상적인 신호를 포착하며, 배포 도중 0이 아닌 종료 코드가 발생하면 즉시 현재 빌드 디렉토리를 자동으로 삭제하여 안정적인 프로덕션 환경의 오염을 방지합니다.

자동화 배포 전체 순서도

Loading diagram...

3. 핵심 구현 원리 분석

전체 배포 아키텍처는 모니터링 모듈, 배포 모듈 및 다중 데이터베이스 마이그레이션 모듈에 의해 공동으로 구동됩니다. 민감한 정보를 완전히 제거하기 위해 아래에서는 각 모듈의 기본 작동 로직을 중점적으로 분석합니다.

3.1 모니터링 트리거 모듈

이 모듈은 시스템의 예약된 작업을 통해 높은 빈도로 호출됩니다. 동시성 안전 및 성능을 보장하기 위해 특정 측면에서 최적화 전략을 채택했습니다.

Loading diagram...

• 동시성 잠금 제어 : 실행 전마다 확인하여 임시 디렉토리에 프로세스 잠금 파일(Lock File)을 생성합니다. 잠금 파일이 설정된 임계값(예: 20분)을 초과하여 남아 있는 것이 감지되면 교착 상태로 간주하고 강제로 해제하여 모니터링 작업이 영구적으로 중단되는 것을 방지합니다.
• 초고속 버전 비교 : 대역폭과 디스크 IO를 소비하는 전체 코드 풀 명령 사용을 포기하고, 시간 초과가 설정된 읽기 전용 네트워크 요청으로 변경하여 원격 저장소의 포인터 Hash 값을 직접 가져와 로컬에 기록된 파일과 비교합니다. 차이가 감지될 때만 후속 릴리스 프로세스를 트리거합니다.

3.2 배포 및 롤백 모듈

이 모듈은 원자적 릴리스를 완료하는 핵심 실행 엔진이며, 그 핵심 특징은 내결함성과 환경의 격리입니다.

Loading diagram...

• 엄격한 예외 처리 및 자동 롤백 : 모듈은 엄격한 모드를 활성화했으며, 중간의 어떤 명령(예: 종속성 설치, 네트워크 시간 초과)이라도 실패하면 즉시 예외가 발생합니다. 동시에 종료 훅(Trap)이 등록되어 있으며, 비정상 종료 신호를 수신하고 성공 플래그가 설정되지 않은 경우 자동으로 정리 로직을 실행하여 빌드가 불완전한 결함 디렉토리를 파괴합니다.
• 데이터와 코드의 분리 : 영구 데이터(각 비즈니스 라인의 독립적인 SQLite 데이터베이스 파일 및 WAL 캐시 등)와 사용자의 정적 리소스는 절대적인 물리적 공유 경로에 저장됩니다. 배포할 때마다 새로운 버전의 디렉토리 내에 이러한 물리적 경로를 가리키는 심볼릭 링크를 생성하여 코드 업데이트와 데이터 상태가 완전히 분리되도록 합니다.
• 무중단 전환 및 이전 버전 정리 : 모든 준비 작업(종속성 설치, 데이터 마운트)이 독립적으로 격리된 디렉토리에서 완료된 후, 심볼릭 링크를 재설정하여 프로덕션 엔트리를 순식간에 새로운 디렉토리로 지정하고, 그 후 데몬을 호출하여 구성을 업데이트합니다. 마지막으로 자동 정리 명령을 실행하여 타임스탬프 역순으로 오래된 디렉토리를 삭제하고 서버의 디스크 공간을 확보하기 위해 극소수의 과거 버전만 유지합니다.

3.3 다중 데이터베이스 마이그레이션 모듈

Node.js 스크립트와 Drizzle ORM을 기반으로 구축된 다중 데이터베이스 자동 마이그레이션 모듈로, 기본 테이블 구조의 변경에 따른 비즈니스 간 동기화를 해결하는 역할을 합니다.

Loading diagram...

• 다중 데이터베이스 매핑 관리 : 모듈 내부에서는 핵심 비즈니스 데이터베이스, 시스템 구성 데이터베이스, 콘텐츠 데이터베이스 등 여러 엔터티 데이터베이스의 이름, 물리적 파일의 절대 경로 및 컴파일된 SQL 마이그레이션 스크립트 경로의 매핑 매트릭스를 유지 관리합니다. 독립적인 실행 환경에서 필요에 따라 글로벌 환경 변수를 읽어오고 해당하는 연결 풀을 초기화합니다.
• 상태 연동 및 안전한 차단 : 각 데이터베이스의 구조 업그레이드 작업을 엄격하게 반복하여 실행합니다. 이 과정에서 SQL 수준의 오류나 테이블 구조의 충돌이 발생하면 즉시 예외를 포착하고 현재 파일의 연결 잠금을 안전하게 차단하며 0이 아닌 상태 코드로 프로세스를 강제 종료합니다. 이 비정상적인 상태 코드는 외부 모니터링 시스템의 엄격한 모드에 의해 포착되어 애플리케이션 계층의 리로드 동작을 직접 차단하고 물리적 디렉토리의 자동 정리 롤백을 트리거하여 이전 버전의 서비스가 의존하는 데이터 구조가 파괴되지 않도록 보호합니다.

---

위 아키텍처의 배포로 생성된 대량의 매개변수 로그를 조사하거나 비즈니스와 관련된 깊은 구조의 구성 파일을 독립적으로 디버깅할 때 다음 시스템 문제 해결 보조 도구를 사용하는 것을 권장합니다.

🔗 로컬 순수 프론트엔드 JSON 검증 및 구조 분석 도구

즉각적인 구문 오류 강조 및 시각적 트리 검색 상호 작용을 제공하며, 클라우드에 민감한 매개변수를 유출하지 않고 전적으로 로컬 브라우저 메모리 내에서 포맷팅을 계산합니다.

→

---

본 문서는 iknowabit 팀에서 원본을 작성했습니다. 기술 지원: Next.js, 일반 Bash 클러스터 아키텍처 및 Drizzle ORM을 기반으로 한 자동화 배포 전략.