PM2로 Node 서버 운영하기 — 설치부터 운영·모니터링·무중단 배포까지

 

PM2로 Node 서버 운영하기 — 설치부터 운영·모니터링·무중단 배포까지

PM2(Process Manager 2)는 Node.js 애플리케이션을 프로덕션 환경에서 안정적으로 운영하기 위한 프로세스 매니저입니다. 이 글은 설치 · 기본 명령 · 클러스터 모드 · 로그/모니터링 · 자동 시작(부팅) · 배포 팁까지 실무에서 바로 쓸 수 있도록 정리했습니다.

한눈에 요약

• PM2는 프로세스 관리(재시작·로그·모니터링), 클러스터링(멀티 코어 활용), 부팅 시 자동 실행 기능을 제공
• 주요 명령: pm2 start|stop|restart|list|logs|monit|save|startup|resurrect
• 프로덕션 운영 팁: cluster mode, max_memory_restart, gracefulReload, logrotate, 환경변수 관리
• 배포 시 ecosystem.config.js를 사용하면 무중단 배포와 여러 앱 관리가 편리

1. 설치

PM2는 npm으로 전역 설치합니다.

npm install -g pm2

설치 후 pm2 --version으로 정상 설치 확인.

2. 기본 명령(실전 예제)

• pm2 start app.js --name myapp — 앱 시작
• pm2 start npm --name "myapp" -- start — npm start로 실행할 때
• pm2 list — 프로세스 목록
• pm2 logs myapp — 실시간 로그 보기
• pm2 monit — CPU/메모리 실시간 모니터링
• pm2 restart myapp, pm2 stop myapp, pm2 delete myapp
• pm2 save — 현재 프로세스 상태 저장(부팅 복원용)
• pm2 resurrect — 이전에 저장한 상태 복원

팁: --name 옵션으로 보기 편하게 이름 붙이기.

3. ecosystem.config.js — 여러 앱/환경 관리

여러 앱과 환경변수를 관리하려면 ecosystem 파일을 사용하세요.

module.exports = {
  apps: [{
    name: "myapp",
    script: "./dist/server.js",
    instances: "max",        // 'max' 또는 숫자
    exec_mode: "cluster",    // cluster 모드
    watch: false,
    max_memory_restart: "300M",
    env: {
      NODE_ENV: "development",
      PORT: 3000
    },
    env_production: {
      NODE_ENV: "production",
      PORT: 8080
    }
  }]
}

시작: pm2 start ecosystem.config.js --env production

4. 클러스터(Cluster) 모드 vs 포크(Fork) 모드

• Fork 모드 — 단일 프로세스로 디버깅에 유리, 한 프로세스만 실행
• Cluster 모드 — 멀티 코어 활용(예: -i max), 로드 분산으로 처리량 증가
• 노드 상태 공유(세션 등)는 외부 저장소(Redis 등)로 처리하세요 — 프로세스 간 메모리 공유는 불가

예: pm2 start app.js -i max --name myapp

5. 무중단(Zero-downtime) 배포

Cluster 모드 + pm2 reload 또는 gracefulReload로 무중단 재시작 가능합니다.

pm2 reload myapp          # 무중단 재시작 (cluster 모드 권장)
pm2 gracefulReload myapp    # 워커들을 순차적으로 재시작(버전 차이 대응)

팁: 장기 연결(웹소켓 등) 있으면 graceful 옵션과 타임아웃 처리를 꼭 구현하세요.

6. 로그 관리

PM2는 out / err 로그 파일을 자동으로 생성합니다. 운영에서는 로그 로테이션이 필수입니다.

pm2 logs myapp
# logrotate 모듈 사용 예
pm2 install pm2-logrotate

# 설치 후 설정 예시
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 7

중요: 로그를 파일에만 쌓지 말고 중앙 로그 수집(ELK/Fluentd/Cloud Logging)으로 연동하세요.

7. 모니터링 & 알람

• pm2 monit — CPU/메모리 실시간 모니터
• 프로덕션에서는 PM2가 제공하는 모니터링(상용 솔루션)이나 Prometheus + Grafana 연동 권장
• 알람: 메모리 과다/프로세스 반복 재시작 감지 시 슬랙·이메일 알림 설정

8. 서버 재부팅 시 자동 시작 설정

systemd에 PM2를 등록하여 부팅 시 프로세스 복원합니다.

pm2 save
pm2 startup systemd

# 출력된 명령을 복사해서 실행 (예: sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u ubuntu --hp /home/ubuntu)

설명: pm2 save로 현재 프로세스 상태(스냅샷)를 저장하면 부팅 시 복원됩니다.

9. 리소스 제어 (메모리 제한 등)

프로세스가 메모리를 너무 많이 쓰면 자동 재시작하도록 설정할 수 있습니다.

pm2 start app.js --name myapp --max-memory-restart 300M
# 또는 ecosystem 파일에서
max_memory_restart: "300M"

주의: 재시작 주기가 잦으면 루프에 빠질 수 있으니 모니터링과 함께 임계값 조절

10. 개발 편의: watch 모드 주의사항

--watch는 파일 변경 시 자동 재시작해 개발에 편리하지만, 프로덕션에서는 권장되지 않습니다(불필요한 재시작 유발).

# 개발
pm2 start app.js --watch

# 프로덕션: 비활성화
pm2 start app.js --no-autorestart

11. 배포 파이프라인과 연계하기

• CI/CD(예: GitHub Actions, GitLab CI)에서 빌드 → 원격 서버에서 코드 동기화 → pm2 reload 또는 pm2 restart 실행
• ecosystem + pm2 deploy 기능도 제공 — 단순한 프로젝트에 편리
• 배포 전 스테이징에서 pm2 reload로 무중단 동작 검증

12. 자주 겪는 문제와 해결법

• 프로세스가 즉시 재시작을 반복 — 로그 확인(에러 루프). start 스크립트가 오류로 종료되는지 확인
• pm2가 부팅 시 복원되지 않음 — pm2 save 후 pm2 startup 스텝이 올바르게 실행되었는지 확인
• 메모리 누수 — max_memory_restart로 임시 완화, 원인 분석하여 누수 해결
• 환경변수 미적용 — ecosystem의 env_production 등을 사용하거나 systemd 환경에서 PATH/ENV 전달 문제 확인

13. 운영 체크리스트 (권장)

1. ecosystem으로 앱/환경 관리
2. Cluster 모드로 멀티코어 활용(Stateless 서비스 권장)
3. 로그 로테이트 설정 및 중앙 로그 수집 연동
4. pm2 save + pm2 startup 으로 부팅 복원 구성
5. 모니터링·알람 체계(메모리·CPU·재시작 빈도)를 구축
6. 무중단 배포(rolling reload) 검증

마무리 — PM2는 '운영 편의성'을 크게 높입니다

PM2는 간단한 명령으로 프로세스 관리를 자동화하고 클러스터링·무중단 배포·로그 관리를 가능하게 합니다. 다만 프로덕션에서는 모니터링·로그 수집·백업·배포 검증을 함께 설계해야 안정적인 운영이 가능합니다. 위 체크리스트를 기준으로 한 번 셋업해 보세요.

PM2 설정/배포 도와달라고 요청하기