PM2 운영 명령어 정리 (실전 기준)¶

본 섹션은 운영 서버에서 실제로 사용하는 PM2 명령어만 정리함.
모든 명령은 운영 사용자 계정에서 실행하는 것을 전제로 함.

1. 서비스 시작 (start)¶

1.1 development 환경으로 시작 (비운영)¶

pm2 start /var/www/[ProjectName]/current/ecosystem.config.cjs \
  --name [ServiceName] \
  --env development \
  --update-env && pm2 log [ServiceName] --lines 100

1.2 production 환경으로 시작 (운영 표준)¶

pm2 start /var/www/[ProjectName]/current/ecosystem.config.cjs \
  --name [ServiceName] \
  --env production \
  --update-env && pm2 log [ServiceName] --lines 100

설명¶

--env : ecosystem에 정의된 환경 선택
--update-env : 환경 변수 강제 갱신
--name : PM2 내 서비스 식별자
pm2 log : 즉시 로그 확인

⚠️ 운영 환경에서는
반드시 ecosystem.config.cjs 기반으로만 start 함

❌ pm2 start next
❌ pm2 start app.js
❌ npm run start
→ 모두 운영 기준 위반

2. 프로세스 상태 저장 (save) ⚠️ 필수¶

pm2 save --force

왜 필요한가¶

서버 재부팅 후 자동 복구 대상 프로세스 목록 저장
pm2 startup systemd와 반드시 함께 사용

start / reload 후
상태가 정상일 때 반드시 실행

3. 설정 반영 (reload) ✅ 운영 표준¶

pm2 reload ecosystem.config.cjs --env production --update-env \
  && pm2 log [ServiceName] --lines 100

특징¶

무중단 재기동
기존 커넥션 유지
클러스터 사용 시 순차 재기동
운영 환경에서 가장 많이 쓰는 명령

❌ restart 대신 반드시 reload 사용

4. 서비스 중지 (stop)¶

pm2 stop [ServiceName] && pm2 log [ServiceName] --lines 100

사용 시점¶

점검
임시 트래픽 차단
장애 원인 분석 중 Nginx 레벨 차단과 병행

stop은
PM2 정의를 삭제하지 않음

5. 서비스 삭제 (delete)¶

pm2 delete [ServiceName]

주의¶

PM2 관리 대상에서 완전히 제거됨
재부팅 후 자동 복구 대상에서도 제외됨
delete 후에는 반드시 pm2 save 다시 필요

6. 재부팅 후 수동 복구 (resurrect)¶

pm2 resurrect

설명¶

마지막 pm2 save 시점의 상태 복구
systemd 자동 기동 실패 시 최후의 수동 복구 수단

정상 운영에서는 자동으로 호출되므로 직접 쓸 일은 거의 없음

7. 상태 확인 명령어 (필수)¶

전체 프로세스 목록¶

pm2 list

특정 서비스 상세 정보¶

pm2 describe [ServiceName]

리소스 모니터링 (실시간)¶

pm2 monit

CPU / 메모리 급증 시
가장 먼저 확인할 명령

8. 로그 관련 명령어 (운영 핵심)¶

전체 로그 스트림¶

pm2 log

특정 서비스 로그¶

pm2 log [ServiceName]

마지막 N줄만 확인¶

pm2 log [ServiceName] --lines 200

장애 대응 시
가장 먼저 실행해야 하는 명령

9. 잘못 쓰면 사고 나는 명령 (주의)¶

restart (운영 비권장)¶

pm2 restart [ServiceName]

문제점¶

모든 인스턴스 즉시 종료
Next.js SSR 트래픽 순간 끊김
사용자 체감 장애 발생 가능

운영 환경에서는
restart 대신 reload 사용

10. 운영 기준 요약¶

작업	권장 명령
최초 실행	`pm2 start ecosystem.config.cjs`
설정 반영	`pm2 reload ecosystem.config.cjs`
상태 저장	`pm2 save`
로그 확인	`pm2 log`
재부팅 복구	`pm2 resurrect`
즉각 중단	`pm2 stop`
완전 제거	`pm2 delete`

11. 보조 명령어 및 사용 주의 명령 정리¶

아래 명령어들은 PM2에서 제공되지만 운영 서버에서는 사용에 주의가 필요함.
각 명령의 의미와 위험도를 명확히 인지한 경우에만 사용함.

11.1 pm2 status (보조 상태 확인)¶

pm2 status

pm2 list와 동일한 기능
프로세스 상태를 간략하게 확인할 때 사용 가능

운영 표준은 pm2 list
status는 보조 명령 정도로만 사용함

11.2 pm2 flush (⚠️ 로그 전체 초기화)¶

pm2 flush

동작¶

PM2가 관리 중인 모든 로그 파일 즉시 삭제
파일 로그 + 콘솔 로그 모두 대상

위험성¶

장애 분석 중 사용 시 증거 완전 소실
되돌릴 수 없음

⚠️ 장애 원인 분석 완료 후에만 사용
일상 운영에서는 사용하지 않는 것을 원칙으로 함

11.3 pm2 kill (❌ 운영 금지)¶

pm2 kill

동작¶

PM2 데몬 자체 종료
모든 Node.js 프로세스 즉시 종료

문제점¶

서비스 전체 다운
systemd 자동 복구가 개입하지 않으면 서비스 미기동 상태 지속
운영 중 사용 시 즉시 장애

❌ 운영 서버에서 사용 금지

11.4 pm2 reset (⚠️ 극히 제한적 사용)¶

pm2 reset [ServiceName]

동작¶

해당 프로세스의 메트릭(재시작 횟수, CPU, 메모리 통계 등) 초기화
프로세스는 종료되지 않음

사용 시점¶

장기 운영 중 통계 리셋이 필요한 경우
운영 영향은 적지만 일반적으로 불필요

기본 운영에서는 사용할 필요 없음

11.5 pm2 unstartup (❌ 운영 금지)¶

pm2 unstartup

동작¶

PM2 systemd 자동 기동 설정 제거

문제점¶

systemd 자동 기동 제거
재부팅 후 서비스 미기동 확정
서버 재부팅 후 서비스 자동 기동 불가
운영 기준 완전 붕괴

❌ 운영 서버에서 절대 사용하지 않음

11.6 ecosystem 없이 start (❌ 금지)¶

pm2 start app.js
pm2 start next

문제점¶

ecosystem.config.cjs 기준 운영 원칙 위반
설정이 코드와 분리됨
재현성, 관리성 급격히 저하
운영 상태 추적 불가

❌ 운영 환경에서는 ecosystem.config.cjs 없이 start 하지 않음

11.7 pm2 scale (⚠️ 운영 중 사용 비권장)¶

pm2 scale [ServiceName] 4

동작¶

실행 중인 인스턴스 수를 즉시 변경

문제점¶

ecosystem 설정과 불일치 발생
reload 시 원복
운영 문서와 실제 상태 불일치

운영 환경에서 인스턴스 변경은 instances 변경은 ecosystem.config.cjs 수정 후 reload로만 수행

12. 운영 명령 사용 원칙 요약¶

PM2 명령은 “할 수 있다(가능)”와 “해도 된다(허용)”가 다름
이 문서에 명시적으로 허용된 명령만 사용함
의심되면 reload + save 외에는 실행하지 않음

PM2는
강력한 만큼, 실수 1번으로 장애를 만드는 도구다.

핵심 원칙 정리¶

ecosystem.config.cjs 없이 운영하지 않는다
reload 사용. restart 금지
start / reload 후 반드시 pm2 save
모든 명령은 항상 운영 사용자 계정에서 실행

PM2는
명령 하나 잘못 치면 바로 장애로 이어지는 도구다.
이 목록에 없는 명령은 운영 서버에서 쓰지 않는다.