pm2를 이용한 Node.js 프로세스 관리 가이드

1. pm2란 무엇인가?

pm2는 Node.js 애플리케이션을 위한 프로덕션 레벨의 프로세스 관리자(Process Manager)입니다. forever와 마찬가지로 예기치 않은 에러로 인해 프로세스가 종료되었을 때 자동으로 재시작해주는 기본 기능을 제공하지만, 거기에 더해 무중단 서비스, 클러스터링, 모니터링, 로그 관리 등 운영 환경에 필수적인 고급 기능들을 내장하고 있습니다.

현재 Node.js 생태계에서 가장 널리 사용되는 프로세스 관리 도구이자 사실상의 표준(de facto standard)입니다.

2. pm2 설치

pm2는 전역(-g)으로 설치하여 어느 위치에서든 명령어를 사용할 수 있도록 합니다.

npm install pm2 -g

3. pm2 핵심 명령어

1) 프로세스 시작 (start)

Node.js 스크립트를 백그라운드에서 실행하고 관리를 시작합니다.

기본 사용법

pm2 start [실행할 스크립트 파일.js]

예시:

pm2 start app.js

이름 지정 및 옵션 추가 (권장)

--name 옵션으로 프로세스에 고유한 이름을 부여하면 관리가 매우 편리해집니다.

pm2 start app.js --name "api-server"

클러스터 모드로 시작 (성능 극대화)

pm2의 가장 강력한 기능 중 하나입니다. -i 옵션으로 실행하면 별도의 코드 수정 없이 CPU 코어 수만큼 프로세스를 생성하여 요청을 분산 처리합니다. 이를 통해 Node.js의 단일 스레드 한계를 극복하고 성능을 극대화할 수 있습니다.

# 사용 가능한 모든 CPU 코어를 사용하여 클러스터 모드로 실행
pm2 start app.js -i max --name "api-cluster"

# 4개의 프로세스만 사용
pm2 start app.js -i 4 --name "api-cluster"

주의: 클러스터 모드는 상태를 공유하지 않으므로, 세션 관리 등은 Redis와 같은 외부 저장소를 사용해야 합니다.

2) 실행 목록 확인 (list)

pm2가 관리 중인 모든 프로세스의 목록을 확인합니다.

pm2 list

단축 명령어:

pm2 ls

실행 결과 예시:

┌────┬──────────────────┬──────────┬───┬─────┬───────────┬─────────┬──────────┬─────┐
│ id │ name │ mode │ ↺ │ pid │ status │ cpu │ memory │ user│
├────┼──────────────────┼──────────┼───┼─────┼───────────┼─────────┼──────────┼─────┤
│ 0 │ api-server │ fork │ 15│ 12345 │ online │ 0.3% │ 80.5 MB │ user│
│ 1 │ api-cluster │ cluster │ 2 │ 12348 │ online │ 15.6% │ 95.8 MB │ user│
│ 2 │ api-cluster │ cluster │ 2 │ 12349 │ online │ 12.1% │ 92.4 MB │ user│
└────┴──────────────────┴──────────┴───┴─────┴───────────┴─────────┴──────────┴─────┘

• id / name: 프로세스를 식별하는 고유 ID와 이름입니다.
• mode: fork (단일) 또는 cluster 모드를 표시합니다.
• ↺ (restarts): 자동 재시작 횟수입니다.

3) 프로세스 종료 (stop)

실행 중인 프로세스를 중지합니다.

# 이름으로 종료 (가장 일반적)
pm2 stop api-server

# ID로 종료
pm2 stop 0

# 모든 프로세스 종료
pm2 stop all

4) 프로세스 재시작

restart (일반 재시작)

기존 프로세스를 종료(stop)한 후 다시 시작(start)합니다. 짧은 다운타임이 발생합니다.

pm2 restart api-server

reload (무중단 재시작 - ★강력 추천★)

pm2의 핵심 기능입니다. 기존 프로세스는 유지한 채 새로운 프로세스를 먼저 실행하고, 새 프로세스가 준비되면 기존 프로세스를 종료합니다. 따라서 서비스 중단 없이 애플리케이션을 업데이트할 수 있습니다.

pm2 reload api-server

# 모든 프로세스를 무중단 재시작
pm2 reload all

운영 환경에서는 restart 대신 reload를 사용하는 것이 기본입니다.

4. pm2의 유용한 기능들

1) 실시간 모니터링 대시보드 (monit)

터미널에서 CPU, 메모리 사용량, 로그, 재시작 횟수 등 프로세스의 상세 정보를 실시간으로 확인할 수 있는 대시보드를 제공합니다.

pm2 monit

대시보드를 종료하려면 q 키를 누릅니다.

2) 로그 관리 (logs)

pm2는 로그를 자동으로 관리하며, 보기 쉬운 명령어를 제공합니다.

# 특정 앱의 실시간 로그 보기 (에러와 출력을 모두 보여줌)
pm2 logs api-server

# 실시간 에러 로그만 보기
pm2 logs api-server --err

# 로그 파일의 마지막 200줄만 보기
pm2 logs api-server --lines 200

# 모든 로그 삭제
pm2 flush

로그 파일의 기본 경로는 ~/.pm2/logs/ 입니다.

3) 프로세스 삭제 (delete)

pm2 관리 목록에서 프로세스를 완전히 제거합니다. (프로세스가 실행 중이면 먼저 중지됩니다.)

pm2 delete api-server

4) 서버 재부팅 시 자동 실행 설정

서버가 예기치 않게 재부팅되더라도 pm2가 관리하던 프로세스들을 자동으로 다시 실행하도록 설정할 수 있습니다.

# 1. 현재 실행 중인 프로세스 목록을 저장
pm2 save

# 2. 현재 OS에 맞는 시작 스크립트를 생성하고 등록
pm2 startup

pm2 startup 명령을 실행하면, 터미널에 sudo ...로 시작하는 명령어가 나타납니다. 이 명령어를 복사하여 그대로 실행해주어야 시스템 서비스에 등록됩니다.

5. forever vs pm2 비교

결론

forever는 가볍고 간단한 스크립트를 빠르게 실행하고 관리하는 데 적합합니다. 하지만 안정적인 서비스 운영을 위한 무중단 배포, 성능 관리, 상세 모니터링이 필요한 프로덕션 환경에서는 pm2가 훨씬 더 강력하고 적합한 솔루션입니다.

특별한 이유가 없다면, 새로운 Node.js 프로젝트에는 pm2를 사용하는 것을 강력히 권장합니다.