====== ⚡ PM2 프로세스 관리 ======

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

----
===== 1. PM2란 무엇인가요? =====

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

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

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

----
===== 2. 설치 및 기본 사용법 =====

==== 1) PM2 설치 ====

<file bash>
npm install -g pm2
</file>

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

==== 2) 기본 실행 방법 ====

<file bash>
# 단순 실행
pm2 start server.js

# 이름 지정 실행
pm2 start server.js --name "baduk-metaverse"

# 클러스터 모드 실행 (CPU 코어 수만큼)
pm2 start server.js -i max
</file>

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

==== 3) 환경별 실행 ====

<file bash>
# 개발 환경 실행
pm2 start server.js --env development

# 프로덕션 환경 실행
pm2 start server.js --env production
</file>

**설명:**
  * ''--env'' 옵션으로 환경을 설정합니다.
  * 개발/프로덕션 환경에 따라 다른 설정을 적용합니다.

----
===== 3. 설정 파일 (ecosystem.config.js) =====

==== 1) 기본 설정 파일 생성 ====

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

<file javascript>
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
    }
  }]
};
</file>

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

==== 2) 고급 설정 ====

<file javascript>
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'
  }]
};
</file>

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

==== 3) 로그 디렉토리 생성 ====

<file bash>
# 로그 디렉토리 생성
mkdir logs
</file>

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

----
===== 4. 기본 명령어 =====

==== 1) 프로세스 관리 ====

<file bash>
# 설정 파일로 애플리케이션 시작
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
</file>

**설명:**
  * ''pm2 start'' - 애플리케이션 시작
  * ''pm2 stop'' - 애플리케이션 중지
  * ''pm2 restart'' - 애플리케이션 재시작
  * ''pm2 delete'' - 애플리케이션 완전 삭제

==== 2) 상태 확인 ====

<file bash>
# 실행 중인 프로세스 목록
pm2 list

# 상세 정보 확인
pm2 show baduk-metaverse

# 로그 확인
pm2 logs baduk-metaverse

# 실시간 로그 모니터링
pm2 logs baduk-metaverse --lines 100

# 시스템 정보 확인
pm2 monit
</file>

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

==== 3) 로그 관리 ====

<file bash>
# 로그 파일 크기 확인
pm2 flush

# 로그 파일 삭제
pm2 flush baduk-metaverse

# 로그 파일 경로 확인
pm2 describe baduk-metaverse
</file>

**설명:**
  * ''pm2 flush'' - 로그 파일 정리
  * ''pm2 describe'' - 애플리케이션 설정 정보 확인

----
===== 5. 고급 기능 =====

==== 1) 클러스터 모드 ====

<file bash>
# CPU 코어 수만큼 인스턴스 실행
pm2 start server.js -i max

# 특정 개수만큼 인스턴스 실행
pm2 start server.js -i 4

# 인스턴스 수 조정
pm2 scale baduk-metaverse 8
</file>

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

==== 2) 파일 변경 감지 ====

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

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

==== 3) 메모리 제한 ====

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

**설명:**
  * ''max_memory_restart'' - 메모리 사용량 제한
  * ''node_args'' - ''Node.js'' 실행 옵션

----
===== 6. 모니터링 및 로깅 =====

==== 1) 실시간 모니터링 ====

<file bash>
# 실시간 대시보드
pm2 monit

# 웹 대시보드 (PM2 Plus)
pm2 plus
</file>

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

==== 2) 로그 설정 ====

<file javascript>
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'
  }]
};
</file>

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

==== 3) 로그 확인 ====

<file bash>
# 실시간 로그 확인
pm2 logs

# 특정 애플리케이션 로그
pm2 logs baduk-metaverse

# 최근 100줄 로그
pm2 logs baduk-metaverse --lines 100

# 에러 로그만 확인
pm2 logs baduk-metaverse --err
</file>

**설명:**
  * ''pm2 logs'' - 모든 애플리케이션의 실시간 로그
  * ''--lines'' - 표시할 로그 줄 수
  * ''--err'' - 에러 로그만 표시

----
===== 7. 프로덕션 환경 설정 =====

==== 1) 프로덕션용 설정 파일 ====

<file javascript>
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'
  }]
};
</file>

==== 2) 프로덕션 실행 ====

<file bash>
# 프로덕션 환경으로 시작
pm2 start ecosystem.config.js --env production

# 시스템 부팅 시 자동 시작 설정
pm2 startup
pm2 save
</file>

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

----
===== 8. 문제 해결 =====

==== 1) 일반적인 문제들 ====

**애플리케이션이 시작되지 않는 경우:**
<file bash>
# 로그 확인
pm2 logs baduk-metaverse

# 상세 정보 확인
pm2 show baduk-metaverse

# 애플리케이션 재시작
pm2 restart baduk-metaverse
</file>

**메모리 사용량이 높은 경우:**
<file bash>
# 메모리 사용량 확인
pm2 monit

# 메모리 제한 설정
pm2 restart baduk-metaverse --max-memory-restart 1G
</file>

**로그 파일이 너무 큰 경우:**
<file bash>
# 로그 파일 정리
pm2 flush

# 로그 로테이션 설정 확인
pm2 describe baduk-metaverse
</file>

==== 2) 디버깅 ====

<file bash>
# 디버그 모드로 실행
pm2 start server.js --node-args="--inspect"

# 상세 로그 확인
pm2 logs baduk-metaverse --lines 200

# 프로세스 정보 확인
pm2 show baduk-metaverse
</file>

----
===== 9. 실습 예제 =====

==== 1) 간단한 PM2 설정 ====

**1단계: ecosystem.config.js 생성**
<file javascript>
module.exports = {
  apps: [{
    name: 'my-app',
    script: 'server.js',
    instances: 2,
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'development',
      PORT: 3000
    }
  }]
};
</file>

**2단계: 애플리케이션 시작**
<file bash>
pm2 start ecosystem.config.js
</file>

**3단계: 상태 확인**
<file bash>
pm2 list
pm2 monit
</file>

==== 2) 로그 설정 예제 ====

**로그 디렉토리 생성:**
<file bash>
mkdir logs
</file>

**설정 파일에 로그 설정 추가:**
<file javascript>
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'
  }]
};
</file>

**로그 확인:**
<file bash>
pm2 logs my-app
</file>

----
===== 10. 다음 단계 =====

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

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

**추천 학습 순서:**
  - [[wiki:it:dream_of_enc:metaverse:nodejs|🟢 Node.js 백엔드 설정]]
  - [[wiki:it:dream_of_enc:metaverse:express|🚀 Express.js 웹 프레임워크]]
  - [[wiki:it:dream_of_enc:metaverse:socketio|🔌 Socket.IO 실시간 통신]]

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