⚡ PM2 프로세스 관리

Phaser Baduk Metaverse 프로젝트의 PM2를 사용한 프로세스 관리에 대해 설명합니다.

PM2는 Node.js 애플리케이션을 위한 프로덕션 프로세스 관리자입니다. 애플리케이션이 갑자기 종료되어도 자동으로 재시작하고, 성능을 모니터링할 수 있게 해줍니다.

주요 특징:

• 자동 재시작 - 애플리케이션이 종료되면 자동으로 다시 시작합니다.
• 로드 밸런싱 - 여러 CPU 코어를 활용하여 성능을 향상시킵니다.
• 로그 관리 - 애플리케이션 로그를 체계적으로 관리합니다.
• 모니터링 - 실시간으로 애플리케이션 상태를 확인합니다.
• 클러스터 모드 - 여러 인스턴스를 동시에 실행합니다.

왜 PM2를 사용하나요?

• 개발 환경에서는 node server.js로 실행하지만, 실제 서비스에서는 안정성이 중요합니다.
• 서버가 갑자기 다운되어도 자동으로 복구됩니다.
• 트래픽이 많을 때 여러 프로세스로 분산 처리합니다.

npm install -g pm2

설명:

• -g 옵션으로 전역 설치합니다.
• 모든 프로젝트에서 PM2를 사용할 수 있습니다.

# 단순 실행
pm2 start server.js
 
# 이름 지정 실행
pm2 start server.js --name "baduk-metaverse"
 
# 클러스터 모드 실행 (CPU 코어 수만큼)
pm2 start server.js -i max

설명:

• pm2 start server.js - 기본 실행
• –name - 애플리케이션에 이름 부여
• -i max - CPU 코어 수만큼 인스턴스 생성

# 개발 환경 실행
pm2 start server.js --env development
 
# 프로덕션 환경 실행
pm2 start server.js --env production

설명:

• –env 옵션으로 환경을 설정합니다.
• 개발/프로덕션 환경에 따라 다른 설정을 적용합니다.

프로젝트 루트에 ecosystem.config.js 파일을 생성합니다:

module.exports = {
  apps: [{
    name: 'baduk-metaverse',
    script: 'server.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'development',
      PORT: 3000
    },
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
};

설명:

• name - 애플리케이션 이름
• script - 실행할 파일
• instances - 실행할 인스턴스 수 (max = CPU 코어 수)
• exec_mode - 실행 모드 (cluster = 클러스터 모드)
• env - 개발 환경 변수
• env_production - 프로덕션 환경 변수

module.exports = {
  apps: [{
    name: 'baduk-metaverse',
    script: 'server.js',
    instances: 'max',
    exec_mode: 'cluster',
 
    // 환경 설정
    env: {
      NODE_ENV: 'development',
      PORT: 3000
    },
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000
    },
 
    // 로그 설정
    log_file: './logs/combined.log',
    out_file: './logs/out.log',
    error_file: './logs/error.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
 
    // 자동 재시작 설정
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
 
    // 환경 변수 파일
    env_file: '.env'
  }]
};

설명:

• log_file - 모든 로그를 저장할 파일
• out_file - 표준 출력 로그 파일
• error_file - 에러 로그 파일
• log_date_format - 로그 시간 형식
• autorestart - 자동 재시작 여부
• watch - 파일 변경 감지 여부
• max_memory_restart - 메모리 사용량 제한
• env_file - 환경 변수 파일 경로

# 로그 디렉토리 생성
mkdir logs

설명:

• PM2가 로그 파일을 저장할 디렉토리를 생성합니다.
• 설정 파일에서 지정한 경로와 일치해야 합니다.

# 설정 파일로 애플리케이션 시작
pm2 start ecosystem.config.js
 
# 특정 환경으로 시작
pm2 start ecosystem.config.js --env production
 
# 애플리케이션 중지
pm2 stop baduk-metaverse
 
# 애플리케이션 재시작
pm2 restart baduk-metaverse
 
# 애플리케이션 삭제
pm2 delete baduk-metaverse
 
# 모든 애플리케이션 중지
pm2 stop all
 
# 모든 애플리케이션 재시작
pm2 restart all

설명:

• pm2 start - 애플리케이션 시작
• pm2 stop - 애플리케이션 중지
• pm2 restart - 애플리케이션 재시작
• pm2 delete - 애플리케이션 완전 삭제

# 실행 중인 프로세스 목록
pm2 list
 
# 상세 정보 확인
pm2 show baduk-metaverse
 
# 로그 확인
pm2 logs baduk-metaverse
 
# 실시간 로그 모니터링
pm2 logs baduk-metaverse --lines 100
 
# 시스템 정보 확인
pm2 monit

설명:

• pm2 list - 현재 실행 중인 모든 애플리케이션 목록
• pm2 show - 특정 애플리케이션의 상세 정보
• pm2 logs - 로그 확인
• pm2 monit - 실시간 모니터링 대시보드

# 로그 파일 크기 확인
pm2 flush
 
# 로그 파일 삭제
pm2 flush baduk-metaverse
 
# 로그 파일 경로 확인
pm2 describe baduk-metaverse

설명:

• pm2 flush - 로그 파일 정리
• pm2 describe - 애플리케이션 설정 정보 확인

# CPU 코어 수만큼 인스턴스 실행
pm2 start server.js -i max
 
# 특정 개수만큼 인스턴스 실행
pm2 start server.js -i 4
 
# 인스턴스 수 조정
pm2 scale baduk-metaverse 8

설명:

• -i max - 모든 CPU 코어 사용
• -i 4 - 4개의 인스턴스 실행
• pm2 scale - 실행 중인 인스턴스 수 조정

module.exports = {
  apps: [{
    name: 'baduk-metaverse',
    script: 'server.js',
    watch: true,
    ignore_watch: ['node_modules', 'logs'],
    watch_delay: 1000
  }]
};

설명:

• watch: true - 파일 변경 시 자동 재시작
• ignore_watch - 감지하지 않을 폴더/파일
• watch_delay - 변경 감지 후 대기 시간 (밀리초)

module.exports = {
  apps: [{
    name: 'baduk-metaverse',
    script: 'server.js',
    max_memory_restart: '1G',
    node_args: '--max-old-space-size=1024'
  }]
};

설명:

• max_memory_restart - 메모리 사용량 제한
• node_args - Node.js 실행 옵션

# 실시간 대시보드
pm2 monit
 
# 웹 대시보드 (PM2 Plus)
pm2 plus

설명:

• pm2 monit - 터미널 기반 실시간 모니터링
• pm2 plus - 웹 기반 모니터링 (PM2 Plus 계정 필요)

module.exports = {
  apps: [{
    name: 'baduk-metaverse',
    script: 'server.js',
 
    // 로그 설정
    log_file: './logs/combined.log',
    out_file: './logs/out.log',
    error_file: './logs/error.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
 
    // 로그 로테이션
    max_size: '20M',
    log_type: 'json'
  }]
};

설명:

• log_file - 모든 로그 통합 파일
• out_file - 표준 출력 로그
• error_file - 에러 로그
• max_size - 로그 파일 최대 크기
• log_type - 로그 형식

# 실시간 로그 확인
pm2 logs
 
# 특정 애플리케이션 로그
pm2 logs baduk-metaverse
 
# 최근 100줄 로그
pm2 logs baduk-metaverse --lines 100
 
# 에러 로그만 확인
pm2 logs baduk-metaverse --err

설명:

• pm2 logs - 모든 애플리케이션의 실시간 로그
• –lines - 표시할 로그 줄 수
• –err - 에러 로그만 표시

module.exports = {
  apps: [{
    name: 'baduk-metaverse',
    script: 'server.js',
    instances: 'max',
    exec_mode: 'cluster',
 
    // 프로덕션 환경 설정
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000,
      DB_HOST: 'localhost',
      DB_PORT: 27017,
      JWT_SECRET: 'your-secret-key'
    },
 
    // 성능 최적화
    max_memory_restart: '1G',
    node_args: '--max-old-space-size=1024',
 
    // 로그 설정
    log_file: './logs/combined.log',
    out_file: './logs/out.log',
    error_file: './logs/error.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
 
    // 자동 재시작
    autorestart: true,
    watch: false,
 
    // 환경 변수 파일
    env_file: '.env.production'
  }]
};

# 프로덕션 환경으로 시작
pm2 start ecosystem.config.js --env production
 
# 시스템 부팅 시 자동 시작 설정
pm2 startup
pm2 save

설명:

• –env production - 프로덕션 환경 설정을 사용합니다.
• pm2 startup - 시스템 부팅 시 PM2를 자동으로 시작합니다.
• pm2 save - 현재 상태를 저장하여 부팅 시 복원합니다.

애플리케이션이 시작되지 않는 경우:

# 로그 확인
pm2 logs baduk-metaverse
 
# 상세 정보 확인
pm2 show baduk-metaverse
 
# 애플리케이션 재시작
pm2 restart baduk-metaverse

메모리 사용량이 높은 경우:

# 메모리 사용량 확인
pm2 monit
 
# 메모리 제한 설정
pm2 restart baduk-metaverse --max-memory-restart 1G

로그 파일이 너무 큰 경우:

# 로그 파일 정리
pm2 flush
 
# 로그 로테이션 설정 확인
pm2 describe baduk-metaverse

# 디버그 모드로 실행
pm2 start server.js --node-args="--inspect"
 
# 상세 로그 확인
pm2 logs baduk-metaverse --lines 200
 
# 프로세스 정보 확인
pm2 show baduk-metaverse

1단계: ecosystem.config.js 생성

module.exports = {
  apps: [{
    name: 'my-app',
    script: 'server.js',
    instances: 2,
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'development',
      PORT: 3000
    }
  }]
};

2단계: 애플리케이션 시작

pm2 start ecosystem.config.js

3단계: 상태 확인

pm2 list
pm2 monit

로그 디렉토리 생성:

mkdir logs

설정 파일에 로그 설정 추가:

module.exports = {
  apps: [{
    name: 'my-app',
    script: 'server.js',
    log_file: './logs/combined.log',
    out_file: './logs/out.log',
    error_file: './logs/error.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z'
  }]
};

로그 확인:

pm2 logs my-app

PM2 기본을 배웠다면 다음을 학습해보세요:

• Docker 컨테이너화 - Docker와 PM2 함께 사용
• Nginx 리버스 프록시 - 웹 서버와 PM2 연동
• CI/CD 파이프라인 - 자동 배포 설정
• 모니터링 도구 - PM2 Plus, New Relic 등
• 로드 밸런싱 - 여러 서버에서 PM2 사용

추천 학습 순서:

1. 🟢 Node.js 백엔드 설정
2. 🚀 Express.js 웹 프레임워크
3. 🔌 Socket.IO 실시간 통신

— 이 페이지는 자동으로 생성되었습니다.