PM2와 클러스터로 Node.js 무중단 배포

개요

Node.js 애플리케이션을 운영할 때 프로세스 관리와 무중단 배포는 필수 요소다. PM2는 프로세스 관리와 클러스터링, 그리고 graceful reload(무중단 재시작)를 지원한다. 이 글에서는 pm2 무중단 배포 설정을 중심으로 Node.js clustering pm2 사용법과 pm2 ecosystem 파일 설정 예시를 단계별로 설명한다. 초보자도 이해하도록 순서를 나누고 예제를 제공한다.

클러스터 모드 개념

클러스터 모드는 싱글 스레드인 Node.js의 CPU 활용을 높이는 방법이다. PM2가 여러 워커 프로세스를 띄워 요청을 분산시킨다. 각 프로세스는 독립된 메모리 공간을 가지므로 하나가 죽어도 나머지가 서비스한다. 이 점이 무중단 배포의 기반이 된다.

장점과 고려사항

• 장점: CPU 활용 극대화, 프로세스 격리, 자동 재시작
• 주의: 세션 스토리지 또는 메모리 기반 캐시 사용 시 동기화 필요
• 로드밸런싱: PM2 자체 라운드로빈 또는 외부 로드밸런서 사용 가능

무중단 배포의 핵심 원리

무중단 배포는 기존 연결을 끊지 않고 새 코드로 전환하는 방식이다. PM2는 gracefulReload, gracefulRestart 같은 명령어로 워커를 순차 교체한다. 각 워커는 현재 처리 중인 요청을 마친 뒤 종료되므로 다운타임이 발생하지 않는다.

흐름

• 새 프로세스 시작
• 트래픽 일부를 새 프로세스로 전환
• 기존 프로세스의 처리 완료 대기
• 종료 후 자원 정리

ecosystem 파일로 관리하기

ecosystem 파일은 여러 앱 설정을 한 곳에서 관리한다. 환경변수, 인스턴스 수, 로그 경로 등을 정의할 수 있다. 아래 예시는 production 환경에서 클러스터 모드로 실행하는 기본 구성이다.

module.exports = {
  apps: [
    {
      name: "my-app",
      script: "./server.js",
      instances: "max",
      exec_mode: "cluster",
      env: {
        NODE_ENV: "development",
        PORT: 3000
      },
      env_production: {
        NODE_ENV: "production",
        PORT: 8080
      }
    }
  ]
};

주요 옵션 설명

• instances: 'max' 또는 숫자 지정(코어 수 기반)
• exec_mode: 'cluster'로 설정해야 클러스터링 적용
• env_production: 배포 환경에서 사용할 변수 모음

무중단 배포 절차

다음은 PM2로 무중단 배포를 수행하는 일반적인 절차다. 간단한 수동 배포와 자동화 파이프라인에 모두 적용할 수 있다.

1. 코드 빌드 및 테스트
2. 서버에 코드 업로드
3. 환경 변수 확인 및 적용
4. PM2로 graceful reload 실행
5. 로그와 헬스체크 확인

실제 명령 예시

# 프로세스 첫 실행
pm2 start ecosystem.config.js --env production

# 설정 변경 후 무중단 재시작
pm2 reload ecosystem.config.js --env production

# 특정 앱만 graceful reload
pm2 reload my-app

# 상태 확인
pm2 ls
pm2 logs my-app --lines 200

운영 체크리스트

• 세션 관리를 외부 스토리지로 전환(Redis 등)
• 정상 종료 시 cleanup 핸들러 구현(process.on('SIGINT' 등))
• 헬스체크 엔드포인트로 워커 상태 검증
• 로그와 메트릭으로 배포 전후 비교
• 롤백 절차 문서화

문제 발생 시 트러블슈팅

무중단 배포 실패의 흔한 원인은 종료 대기 시간 초과, 메모리 누수, 또는 외부 의존성 지연이다. 다음 점검을 권장한다.

• PM2 로그로 에러 원인 확인
• 메모리/CPU 사용량 추적
• 외부 API 타임아웃 설정 검토
• 세션 동기화 문제 여부 점검

요약 및 권장 구성

PM2의 클러스터 모드와 ecosystem 파일을 활용하면 무중단 배포를 안정적으로 구현할 수 있다. graceful reload로 워커를 순차 교체하고, 세션 및 상태 관리는 외부 시스템으로 분리한다. 또한 배포 전후 헬스체크와 로그 모니터링을 통해 위험을 최소화한다. 이 과정을 자동화 파이프라인에 통합하면 운영 부담을 크게 줄일 수 있다.