(김준회) pm2 별도 설정파일로 분리 및 배포담당자를 위한 문서 추가

2 files changed, 359 insertions, 0 deletions

diff --git a/PM2_SETUP.md b/PM2_SETUP.md
new file mode 100644
index 00000000..e674ff5e
--- /dev/null
+++ b/PM2_SETUP.md
@@ -0,0 +1,335 @@
+# 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
+
+# 로그 파일 위치: ./logs/pm2-out.log, ./logs/pm2-error.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'
+      },
+      error_file: './logs/pm2-error.log',   // 에러 로그 파일
+      out_file: './logs/pm2-out.log',       // 출력 로그 파일
+      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
+      merge_logs: true,                      // 로그 병합
+      time: true                             // 로그에 타임스탬프 추가
+    }
+  ]
+};
+```
+
+### 로그 파일 관리
+
+**ecosystem.config.js의 로그 설정:**
+- `error_file`: 에러 로그 파일 경로 지정
+- `out_file`: 일반 출력 로그 파일 경로 지정
+- `log_date_format`: 로그의 날짜 형식
+- `merge_logs`: 여러 인스턴스의 로그를 하나의 파일로 병합
+
+**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 개발팀
+
diff --git a/ecosystem.config.js b/ecosystem.config.js
new file mode 100644
index 00000000..e639cffd
--- /dev/null
+++ b/ecosystem.config.js
@@ -0,0 +1,24 @@
+module.exports = {
+  apps: [
+    {
+      name: 'evcp',
+      script: 'npm',
+      args: 'run start',
+      cwd: './',
+      instances: 1,
+      autorestart: true,
+      watch: false,
+      max_memory_restart: '8G',
+      env: {
+        NODE_ENV: 'production',
+        NODE_OPTIONS: '--openssl-legacy-provider'
+      },
+      error_file: './logs/pm2-error.log',
+      out_file: './logs/pm2-out.log',
+      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
+      merge_logs: true,
+      time: true
+    }
+  ]
+};
+