path: root/PM2_SETUP.md

# PM2 자동 시작 설정 가이드

## 📌 개요

EVCP Next.js 애플리케이션을 PM2로 관리하여 서버 재부팅 시에도 자동으로 시작되도록 설정하는 방법입니다.

## 🔧 사전 요구사항

- Node.js 설치 완료
- 애플리케이션 빌드 완료 (`npm run build`)
- 프로덕션 환경

## 📥 1. PM2 설치

PM2를 전역으로 설치합니다:

```bash
npm install -g pm2
```

설치 확인:
```bash
pm2 --version
```

## 🚀 2. 애플리케이션 시작

### ecosystem.config.js 파일을 사용하여 시작

```bash
pm2 start ecosystem.config.js
```

### 개별 명령어로 시작 (선택사항)

```bash
pm2 start npm --name "evcp" -- run start
```

## 🔄 3. 재부팅 시 자동 시작 설정

### Windows 환경

1. PM2 startup 설정:
```bash
pm2 startup
```

2. 출력된 명령어를 **관리자 권한**으로 실행합니다.
   (예: PowerShell을 관리자 권한으로 실행 후 출력된 명령어 실행)

3. 현재 실행 중인 프로세스 목록을 저장:
```bash
pm2 save
```

4. 설정 확인:
```bash
pm2 list
```

### Linux/Unix 환경

```bash
# startup 스크립트 생성
pm2 startup

# 출력된 명령어를 sudo로 실행 (예: sudo env PATH=...)

# 현재 프로세스 목록 저장
pm2 save
```

## 📊 4. PM2 주요 명령어

### 상태 관리
```bash
# 프로세스 목록 및 상태 확인
pm2 list
pm2 status

# 특정 앱 상세 정보
pm2 show evcp

# 실시간 모니터링 (CPU, 메모리)
pm2 monit
```

### 로그 확인
```bash
# 전체 로그 확인 (실시간)
pm2 logs evcp

# 에러 로그만 확인
pm2 logs evcp --err

# 최근 N개 라인만 확인
pm2 logs evcp --lines 100

# 로그 파일 위치 확인
pm2 show evcp
# 출력에서 "out log path"와 "error log path" 확인
# Windows: C:\Users\<username>\.pm2\logs\evcp-out.log
# Linux/Mac: ~/.pm2/logs/evcp-out.log

# 로그 파일 직접 확인 (Windows)
cat C:\Users\jh\.pm2\logs\evcp-out.log
```

### 재시작 및 중지
```bash
# 재시작 (무중단 재시작)
pm2 reload evcp

# 재시작 (일반)
pm2 restart evcp

# 중지
pm2 stop evcp

# 삭제 (프로세스 목록에서 제거)
pm2 delete evcp

# 전체 재시작
pm2 restart all
```

### 설정 관리
```bash
# 저장된 프로세스 목록 확인
pm2 save

# 저장된 프로세스 복구
pm2 resurrect

# startup 설정 제거
pm2 unstartup
```

## ⚙️ 5. ecosystem.config.js 설정 설명

```javascript
module.exports = {
  apps: [
    {
      name: 'evcp',                          // 애플리케이션 이름
      script: 'npm',                         // 실행할 스크립트
      args: 'run start',                     // npm run start
      cwd: './',                             // 작업 디렉토리
      instances: 1,                          // 인스턴스 수 (1 또는 'max')
      autorestart: true,                     // 크래시 시 자동 재시작
      watch: false,                          // 파일 변경 감지 (프로덕션에서는 false)
      max_memory_restart: '8G',              // 메모리 임계값 초과 시 재시작
      env: {
        NODE_ENV: 'production',              // 환경 변수
        NODE_OPTIONS: '--openssl-legacy-provider'
      },
      // 로그 경로 미지정 시 PM2 기본 경로 사용: ~/.pm2/logs/
      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
      merge_logs: true,                      // 로그 병합
      time: true                             // 로그에 타임스탬프 추가
    }
  ]
};
```

### 로그 파일 관리

**PM2 기본 로그 경로 사용:**
- `error_file`과 `out_file`을 지정하지 않으면 PM2 기본 경로 사용
- Windows: `C:\Users\<username>\.pm2\logs\`
- Linux/Mac: `~/.pm2/logs/`
- 로그 파일명: `evcp-out.log`, `evcp-error.log`

**ecosystem.config.js의 로그 설정:**
- `log_date_format`: 로그의 날짜 형식
- `merge_logs`: 여러 인스턴스의 로그를 하나의 파일로 병합
- `time`: 로그에 타임스탬프 추가

**커스텀 로그 경로 (선택사항):**
```javascript
error_file: './logs/pm2-error.log',   // 프로젝트 내 logs 폴더 사용
out_file: './logs/pm2-out.log',       // 상대 경로
// 또는
error_file: '/var/log/evcp/error.log', // 절대 경로 (Linux)
```

**⚠️ Windows 환경에서 `~` 심벌 사용 주의:**
- `~/.pm2/logs/` 형식은 Windows에서 제대로 해석되지 않을 수 있음
- 경로를 지정하지 않거나 절대 경로 사용 권장

**pm2-logrotate (자동 적용):**
- ecosystem.config.js에 별도 설정 불필요
- 이미 설치되어 있으면 자동으로 모든 로그 파일에 적용
- 로그 파일이 10MB 초과 시 자동으로 로테이션
- 30개의 백업 파일 유지
- `pm2 conf pm2-logrotate` 명령으로 설정 확인 가능

### 메모리 설정 가이드

`max_memory_restart`는 프로세스가 해당 메모리를 **초과**하면 자동으로 재시작하는 임계값입니다.

**중요**: 메모리가 자동으로 늘어나는 것이 아니라, 임계값 초과 시 **재시작**됩니다.

#### 권장 설정 (16GB 시스템 기준)

| 애플리케이션 규모 | 권장 값 | 설명 |
|-----------------|---------|------|
| 소규모 (경량) | `1G` ~ `2G` | 간단한 페이지, 적은 트래픽 |
| 중규모 (일반) | `2G` ~ `4G` | 일반적인 엔터프라이즈 앱 |
| 대규모 (대용량) | `4G` ~ `8G` | 많은 페이지, 높은 트래픽, 많은 동시 사용자 |

**EVCP 현재 설정**: `8G`
- 16GB 시스템에서 8GB 가용 메모리 활용
- Next.js SSR 렌더링 및 대용량 데이터 처리 고려
- 메모리 누수 방지를 위한 안전 장치
- 높은 트래픽 환경에 적합

### 인스턴스 수 설정

```javascript
instances: 1,              // 단일 인스턴스
// instances: 2,           // 2개 인스턴스
// instances: 'max',       // CPU 코어 수만큼
```

## 🔍 6. 트러블슈팅

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

```bash
# 로그 확인
pm2 logs evcp --lines 50

# 프로세스 삭제 후 재시작
pm2 delete evcp
pm2 start ecosystem.config.js
```

### 재부팅 후 자동 시작되지 않는 경우

```bash
# startup 설정 확인
pm2 startup

# 다시 저장
pm2 save

# Windows: 작업 스케줄러에서 PM2 확인
# Linux: systemd 서비스 확인
systemctl status pm2-<username>
```

### 메모리 문제

```bash
# 현재 메모리 사용량 확인
pm2 list

# 메모리 상세 확인
pm2 show evcp

# 메모리 임계값 조정이 필요한 경우
# ecosystem.config.js에서 max_memory_restart 값 수정 후
pm2 reload ecosystem.config.js
```

### 로그가 너무 큰 경우

**현재 pm2-logrotate 설정 (이미 적용 중)**

```bash
# 현재 설정 확인
pm2 conf pm2-logrotate

# 현재 적용된 설정:
# - max_size: 10M (로그 파일이 10MB 초과 시 로테이션)
# - retain: 30 (30개 백업 파일 보관)
# - compress: false (압축 미사용)
# - rotateInterval: 0 0 * * * (매일 자정 로테이션)
```

**설정 변경이 필요한 경우:**

```bash
# 로그 파일 최대 크기 (기본: 10M)
pm2 set pm2-logrotate:max_size 50M

# 보관할 백업 파일 수 (기본: 30)
pm2 set pm2-logrotate:retain 60

# 로그 압축 활성화 (기본: false)
pm2 set pm2-logrotate:compress true

# 설정 확인
pm2 conf pm2-logrotate
```

**참고**: pm2-logrotate는 ecosystem.config.js와 **독립적**으로 동작합니다. 
별도 설정이 없어도 이미 설치되어 있으면 자동으로 모든 PM2 프로세스의 로그에 적용됩니다.

## 📈 7. 모니터링

### PM2 Plus (선택사항)

무료 모니터링 서비스 연결:

```bash
pm2 link <secret_key> <public_key>
```

웹 대시보드: https://app.pm2.io

### 기본 모니터링

```bash
# 실시간 모니터링
pm2 monit

# 주기적 상태 확인
watch -n 1 pm2 list
```

## 🔒 8. 보안 고려사항

1. **로그 파일 권한**: 로그 파일에 민감한 정보가 포함될 수 있으므로 적절한 권한 설정
2. **환경 변수**: 민감한 환경 변수는 `.env` 파일 사용
3. **업데이트**: PM2를 주기적으로 업데이트

```bash
npm update -g pm2
pm2 update
```

## 📚 9. 추가 자료

- [PM2 공식 문서](https://pm2.keymetrics.io/docs/)
- [PM2 Ecosystem File](https://pm2.keymetrics.io/docs/usage/application-declaration/)
- [PM2 Startup](https://pm2.keymetrics.io/docs/usage/startup/)

## 📝 10. 체크리스트

배포 전 확인사항:

- [ ] PM2 전역 설치 완료
- [ ] `npm run build` 빌드 완료
- [ ] `ecosystem.config.js` 설정 확인
- [ ] `pm2 start ecosystem.config.js` 실행
- [ ] `pm2 startup` 및 `pm2 save` 완료
- [ ] 재부팅 테스트 완료
- [ ] 로그 확인 (`pm2 logs evcp`)
- [ ] 모니터링 설정 (`pm2 monit`)

---

**마지막 업데이트**: 2025-11-02
**관리자**: EVCP 개발팀