PROCESS RESTART

PM2 재시작 루프·errored 상태

PM2 restart count와 exit code, 애플리케이션 로그·cwd·Node 경로·의존성을 분리하고 watch·memory restart·startup PATH·backoff 설정을 검토해 반복 호출 없이 복구합니다.

PM2 restart loopPM2 erroredPM2 restart countexp_backoff_restart_delaymax_restartsnvm PM2 startup

환경Linux systemd · PM2 고정 버전 · nvm 또는 system Node.js · 단일 서비스 계정

분류서비스

검토일2026-09-04

진행5단계 · 조회 우선

SAFE OPERATING BOUNDARY

중단·복구 기준부터 확인하세요

STOP CONDITIONS

여기서는 멈추세요

정확한 PM2 소유 사용자·PM2_HOME·애플리케이션 이름을 확인하지 못했다면 restart·save를 실행하지 않습니다.
DB migration·queue consumer·cron job의 중복 실행 영향을 확인하지 못했다면 cluster reload나 instance 증감을 하지 않습니다.
로그·dump.pm2·unit environment에 비밀이 나타나면 수집을 중단하고 접근 통제와 마스킹을 먼저 적용합니다.

ROLLBACK

복구 기준

0600으로 보관한 ecosystem과 이전 정상 artifact·Node version을 같은 묶음으로 복원하고 startOrReload로 한 번만 전환합니다. Node upgrade 뒤라면 startup unit의 절대 PATH도 이전 version으로 다시 생성하고 안정화 후 process list를 저장합니다. 이미 처리 중이던 HTTP·queue·cron 업무는 PM2 rollback이 복원하지 않으므로 idempotency·재처리 기준을 적용합니다.

ESCALATION PACK

담당자에게 전달할 자료

PM2 app 상태·restart count·uptime·exit code·signal과 장애 시각의 제한된 로그
Node·PM2 version과 절대 경로, ecosystem diff, startup unit ExecStart·PATH
port owner·dependency health·memory 추세와 적용 전후 오류율·재시작 변화

2026년 9월 4일 기준 공식 upstream 문서와 현재 지원 명령을 대조했습니다. 먼저 최소 범위 읽기 전용 조회로 사실을 확인하고, 변경은 영향·백업·복구 경로와 담당자 승인을 확보한 대상에만 적용합니다. <...> 자리표시자는 승인된 리터럴 값으로 직접 치환하며 외부 입력으로 shell 명령을 조립하거나 eval하지 않습니다.

BEFORE YOU START

이런 증상에서 시작합니다

pm2 list에서 ↺ 값이 빠르게 증가하고 status가 launching·errored를 반복함
애플리케이션이 online 직후 exit code 1로 종료됨
재부팅 뒤 수동 실행과 다른 Node.js version으로 시작됨
watch 또는 max_memory_restart 때문에 정상 종료 없이 계속 reload됨

CHECK THE BRANCH

놓치기 쉬운 원인 분기

exit code·signal과 애플리케이션 오류가 있는 경우

첫 실패의 stderr·stack trace와 종료 코드를 기준으로 config·module·port·의존 서비스 원인을 해결합니다. restart 횟수 초기화로 증거를 숨기지 않습니다.

watch 또는 memory restart가 원인인 경우

배포·로그·temp 파일이 watch path에 포함됐는지, RSS가 max_memory_restart를 넘는지 확인합니다. threshold만 크게 올리기 전에 메모리 추세를 조사합니다.

재부팅·Node upgrade 뒤에만 실패하는 경우

nvm은 shell 함수이고 PM2 startup unit은 생성 당시의 절대 Node 경로를 사용할 수 있습니다. unit PATH와 서비스 계정의 실제 Node·PM2를 비교합니다.

의존 서비스 장애로 모든 worker가 반복 실패하는 경우

DB·queue·외부 API를 계속 압박하지 않도록 exponential backoff와 제한된 max_restarts를 적용하고 근본 의존성부터 복구합니다.

FOLLOW THE FLOW

순서대로 확인하기

조회시스템을 변경하지 않는 확인 단계

PM2 상태·restart count·systemd 관계 확인

반드시 PM2를 소유한 Unix 계정으로 조회합니다. 다른 계정의 PM2 daemon을 새로 띄우면 장애 상태를 잘못 판단할 수 있습니다.

PM2 목록

sudo -iu <APP_USER> bash -lc '. "$HOME/.nvm/nvm.sh"; nvm use <APPROVED_NODE_24_VERSION> >/dev/null; pm2 list; pm2 ping'

앱 상세

sudo -iu <APP_USER> bash -lc '. "$HOME/.nvm/nvm.sh"; nvm use <APPROVED_NODE_24_VERSION> >/dev/null; pm2 describe <APP_NAME>'

출력에 내부 경로·environment 차이가 포함될 수 있어 외부 공유 전 마스킹합니다.

startup unit

systemctl status pm2-<APP_USER>.service --no-pager -l
systemctl cat pm2-<APP_USER>.service

process·port

ps -eo pid,ppid,user,%cpu,%mem,rss,etime,stat,comm --sort=-rss | head -30
sudo ss -lntp | grep -E ':<APP_PORT>\b'

결과 읽기

PM2 status, restart count, uptime와 systemd NRestarts를 구분합니다. 서로 다른 사용자·PM2_HOME·process manager가 같은 app을 관리하는지 확인합니다.

다음 판단

첫 실패 로그와 exit code를 제한된 범위로 수집합니다.

조회시스템을 변경하지 않는 확인 단계

첫 실패 로그·exit code·재시작 전략 확인

실시간 tail 대신 고정 줄 수와 장애 시각을 확인합니다. PM2 report·jlist·환경 전체는 secret을 포함할 수 있어 외부 공유용으로 실행하지 않습니다.

고정 로그 범위

sudo -iu <APP_USER> bash -lc '. "$HOME/.nvm/nvm.sh"; nvm use <APPROVED_NODE_24_VERSION> >/dev/null; pm2 logs <APP_NAME> --lines 200 --nostream --timestamp'

PM2 daemon 로그

sudo -iu <APP_USER> bash -lc '. "$HOME/.nvm/nvm.sh"; nvm use <APPROVED_NODE_24_VERSION> >/dev/null; tail -n 200 "$HOME/.pm2/pm2.log"'

systemd 최근 로그

journalctl -u pm2-<APP_USER>.service --since '<INCIDENT_START>' --until '<INCIDENT_END>' --no-pager

Node·PM2 경로

sudo -iu <APP_USER> bash -lc '. "$HOME/.nvm/nvm.sh"; nvm use <APPROVED_NODE_24_VERSION> >/dev/null; command -v node; node --version; command -v pm2; pm2 --version'

결과 읽기

MODULE_NOT_FOUND·EADDRINUSE·permission·config parse·dependency timeout·signal·memory restart를 첫 exit와 연결합니다. 반복 로그의 마지막 문장만 보지 않습니다.

다음 판단

artifact·cwd·config·dependency를 PM2 밖에서 안전하게 검증합니다.

조회시스템을 변경하지 않는 확인 단계

cwd·artifact·config·의존성 사전 검증

현재 process를 건드리지 않고 ecosystem 문법, script 존재·권한, port 소유자와 dependency endpoint를 확인합니다. 실제 secret 값은 출력하지 않습니다.

ecosystem 문법

sudo -iu <APP_USER> bash -lc '. "$HOME/.nvm/nvm.sh"; nvm use <APPROVED_NODE_24_VERSION> >/dev/null; node --check <ECOSYSTEM_FILE>'

cwd·script 권한

namei -l <APP_CWD>/<APP_SCRIPT>
sudo -u <APP_USER> test -r <APP_CWD>/<APP_SCRIPT> && echo readable

port 소유자

sudo ss -lntp | grep -E ':<APP_PORT>\b'

승인된 dependency health

curl -fsS --connect-timeout 3 <APPROVED_DEPENDENCY_HEALTH_URL>

인증정보를 URL에 넣지 않고 사설 health endpoint만 조회합니다.

결과 읽기

같은 artifact가 foreground에서도 즉시 종료하면 PM2 문제가 아니라 애플리케이션·환경 문제입니다. port owner·권한·Node ABI를 함께 봅니다.

다음 판단

watch·restart·memory·startup PATH와 이전 정상 ecosystem 차이를 검토합니다.

조회시스템을 변경하지 않는 확인 단계

ecosystem·startup PATH·메모리 원인 비교

이전 정상 revision과 현재 ecosystem을 source control에서 비교합니다. watch, autorestart, min_uptime, max_restarts, backoff, max_memory_restart와 startup unit Node 경로를 확인합니다.

ecosystem diff

git -C <APP_REPOSITORY> diff <LAST_GOOD_REVISION> -- <ECOSYSTEM_RELATIVE_PATH>

unit 실행 경로

systemctl show pm2-<APP_USER>.service -p ExecStart -p ExecStop -p User -p FragmentPath

환경 변수 원문은 비밀을 포함할 수 있으므로 조회하지 않고 Node·PM2 실행 경로만 확인합니다.

memory 추세 기준선

sudo -iu <APP_USER> bash -lc '. "$HOME/.nvm/nvm.sh"; nvm use <APPROVED_NODE_24_VERSION> >/dev/null; pm2 monit'

대화형 조회입니다. 장애 중 장시간 열어두지 않고 RSS·restart 시각만 기록합니다.

Node module ABI 확인

sudo -iu <APP_USER> bash -lc '. "$HOME/.nvm/nvm.sh"; nvm use <APPROVED_NODE_24_VERSION> >/dev/null; node -p "process.version + \" modules=\" + process.versions.modules"'

결과 읽기

짧은 uptime을 failure로 제한하는 max_restarts와 backoff가 없으면 외부 의존성을 압박합니다. nvm Node 변경 뒤 unit PATH가 이전 version이면 startup만 실패할 수 있습니다.

다음 판단

근본 원인 수정안과 정상 revision·backup을 승인합니다.

변경데이터·서비스 상태가 달라질 수 있는 단계

승인된 ecosystem·artifact 적용 후 안정성 검증

변경 전 ecosystem과 PM2 process 목록을 0600으로 보관하고 코드·의존성·restart 전략 중 확인한 원인만 수정합니다. 즉시 pm2 save하지 않습니다.

변경 단계입니다. 실행 전 대상 이름과 경로, 서비스 중단 영향, 복구 방법을 다시 확인하세요.

백업

sudo install -d -o root -g root -m 0700 <APPROVED_BACKUP_DIR>
if sudo test -f <ECOSYSTEM_FILE>; then sudo cp --archive --no-clobber <ECOSYSTEM_FILE> <APPROVED_BACKUP_DIR>/ecosystem.before.cjs; fi
if sudo test -f /home/<APP_USER>/.pm2/dump.pm2; then sudo cp --archive --no-clobber /home/<APP_USER>/.pm2/dump.pm2 <APPROVED_BACKUP_DIR>/dump.before.pm2; fi
if sudo test -f <APPROVED_BACKUP_DIR>/ecosystem.before.cjs; then sudo chmod 0600 <APPROVED_BACKUP_DIR>/ecosystem.before.cjs; fi
if sudo test -f <APPROVED_BACKUP_DIR>/dump.before.pm2; then sudo chmod 0600 <APPROVED_BACKUP_DIR>/dump.before.pm2; fi

존재하는 ecosystem·dump만 변경 전에 no-clobber로 복사합니다. dump에는 환경값이 포함될 수 있으므로 0700/0600 경로에서만 보관하고 외부 공유 전에 비밀·개인정보를 마스킹합니다.

검토·reload

sudo -iu <APP_USER> bash -lc '. "$HOME/.nvm/nvm.sh"; nvm use <APPROVED_NODE_24_VERSION> >/dev/null; node --check <REVIEWED_ECOSYSTEM_FILE>; pm2 startOrReload <REVIEWED_ECOSYSTEM_FILE> --only <APP_NAME>'

관찰

sudo -iu <APP_USER> bash -lc '. "$HOME/.nvm/nvm.sh"; nvm use <APPROVED_NODE_24_VERSION> >/dev/null; pm2 describe <APP_NAME>; pm2 logs <APP_NAME> --lines 100 --nostream --timestamp'
curl -fsS http://127.0.0.1:<APP_PORT>/<HEALTH_PATH>

안정 후 목록 저장

sudo -iu <APP_USER> bash -lc '. "$HOME/.nvm/nvm.sh"; nvm use <APPROVED_NODE_24_VERSION> >/dev/null; pm2 save'

승인한 관찰 시간 동안 restart count가 증가하지 않고 업무 smoke test가 성공한 뒤에만 실행합니다.

결과 읽기

online·health뿐 아니라 restart count가 증가하지 않고 오류율·dependency 부하가 회복돼야 합니다. backoff만으로 원인이 해결된 것은 아닙니다.

다음 판단

악화되면 백업 ecosystem과 이전 artifact를 복원해 startOrReload하고, Node version이 바뀌었다면 PM2 공식 절차에 따라 startup unit을 이전 절대 경로로 재생성합니다. DB migration·queue 처리는 별도 보정합니다.

PRIMARY REFERENCES

공식 문서

배포판과 버전에 따라 옵션·로그 위치가 다를 수 있습니다. 실행 전 서버의 --help와 로컬 매뉴얼을 함께 확인하세요.

중단·복구 기준부터 확인하세요

여기서는 멈추세요

복구 기준

담당자에게 전달할 자료

이런 증상에서 시작합니다

놓치기 쉬운 원인 분기

exit code·signal과 애플리케이션 오류가 있는 경우

watch 또는 memory restart가 원인인 경우

재부팅·Node upgrade 뒤에만 실패하는 경우

의존 서비스 장애로 모든 worker가 반복 실패하는 경우

순서대로 확인하기

공식 문서

함께 확인할 가이드

구성 가이드에서 다시 확인하기