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

1. forever란 무엇인가?

Node.js는 단일 스레드 기반으로 동작하기 때문에, 코드에서 처리되지 않은 예외(에러)가 발생하면 프로세스가 즉시 종료되어 서비스가 다운되는 치명적인 단점이 있습니다.

forever는 이러한 Node.js 애플리케이션의 프로세스를 모니터링하다가, 예기치 않게 종료되었을 때 자동으로 재시작해주는 매우 유용한 CLI(Command Line Interface) 도구입니다. 이를 통해 서비스의 안정성과 가용성을 크게 높일 수 있습니다.

2. forever 설치

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

npm install forever -g

3. forever 핵심 명령어

1) 프로세스 시작 (start)

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

기본 사용법

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

예시:

forever start app.js

로그 파일 지정하여 시작 (권장)

기본적으로 로그는 ~/.forever/ 디렉토리에 저장됩니다. 로그를 원하는 경로에 파일로 저장하면 관리가 훨씬 용이합니다.

forever start -o out.log -e err.log [실행할 스크립트 파일.js]

• -o OUTFILE: console.log와 같은 표준 출력(stdout)을 OUTFILE에 저장합니다.
• -e ERRFILE: console.error나 에러 스택 트레이스 같은 표준 에러(stderr)를 ERRFILE에 저장합니다.
• -l LOGFILE: forever 자체의 실행 로그를 LOGFILE에 저장합니다.
• -a (--append): 기존 로그 파일이 있을 경우, 그 뒤에 이어서 로그를 작성합니다.

종합 예시:

# logs 폴더 아래에 out.log와 error.log를 생성하며 app.js를 실행
forever start -a -o ./logs/out.log -e ./logs/error.log app.js

2) 실행 목록 확인 (list)

forever로 실행 중인 모든 프로세스의 목록을 확인합니다.

forever list

실행 결과 예시:

info:    Forever processes running
data:        uid  command       script    forever pid   logfile                 uptime
data:    [0] jgN5 /usr/bin/node app.js    21181   21183 /home/user/.forever/jgN5.log 0:0:1:20.123

• : 프로세스의 인덱스(index)입니다. stop, restart 등에서 사용됩니다.
• uid: forever가 프로세스에 부여한 고유 ID입니다.
• script: 실행된 스크립트 파일명입니다.
• pid: 실제 시스템의 프로세스 ID입니다.
• logfile: forever 자체의 로그 파일 경로입니다. (-o, -e 옵션과는 별개)
• uptime: 프로세스가 실행된 시간입니다.

3) 프로세스 종료 (stop)

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

특정 프로세스 종료

forever list에서 확인한 인덱스(index), uid, pid, 또는 스크립트명을 사용할 수 있습니다. 인덱스를 사용하는 것이 가장 간단합니다.

# 인덱스로 종료 (가장 일반적)
forever stop 0

# uid로 종료
forever stop jgN5

# 스크립트명으로 종료
forever stop app.js

# 모든 프로세스 종료 : `forever`로 실행된 모든 프로세스를 한 번에 중지합니다.
forever stopall

4) 프로세스 재시작 (restart)

실행 중인 프로세스를 재시작합니다. 코드를 수정한 후 적용할 때 사용합니다.

# 인덱스로 재시작
forever restart 0

# 모든 프로세스 재시작
forever restartall

참고: restart는 기존 프로세스를 **종료(stop)한 후 다시 시작(start)**하는 방식입니다. 따라서 아주 짧은 시간 동안 서비스 중단(downtime)이 발생할 수 있습니다.

4. 유용한 추가 옵션 및 명령어

1) 로그 실시간 확인 (logs)

실시간으로 출력되는 로그를 터미널에서 바로 확인할 수 있습니다. 디버깅 시 매우 유용합니다.

# 특정 프로세스(인덱스: 0)의 로그를 실시간으로 보기
forever logs 0

# 로그 파일의 마지막 100줄만 보기
forever logs 0 -n 100

로그 확인을 종료하려면 Ctrl + C를 누릅니다.

2) 프로세스에 ID 부여하기 (--uid)

app.js와 같이 동일한 이름의 스크립트를 여러 개 실행할 때, 각 프로세스를 구분하기 위해 직접 고유한 ID(uid)를 부여할 수 있습니다.

forever start --uid "api-server" app.js
forever start --uid "worker-1" worker.js

이제 stop, restart 등에서 파일명이나 인덱스 대신 부여한 uid를 사용할 수 있습니다.

forever restart api-server

3) 스크립트 변경 감지하여 자동 재시작 (-w 또는 --watch)

개발 환경에서 유용한 기능으로, 소스 파일이 변경될 때마다 자동으로 프로세스를 재시작해줍니다.

# 현재 디렉토리 및 하위 디렉토리의 파일 변경을 감지
forever start -w app.js

주의: node_modules 폴더 등 불필요한 변경까지 감지할 수 있으므로, .foreverignore 파일을 만들어 감시에서 제외할 파일이나 폴더를 지정하는 것이 좋습니다.

.foreverignore 파일 예시:

node_modules
logs/\*
\*.log

4) 재시작 관련 고급 옵션

스크립트가 실행되자마자 계속해서 충돌하며 무한 재시작되는 것을 방지하기 위한 옵션입니다.

• --minUptime [ms]: 스크립트가 최소한 이 시간(밀리초) 이상 실행되어야 '안정적'으로 간주합니다. 이 시간 내에 종료되면 '불안정'으로 판단합니다.
• --spinSleepTime [ms]: 불안정한 스크립트가 충돌했을 때, 다음 재시작까지 대기하는 시간입니다. 서버 부하를 줄일 수 있습니다.

# 1초(1000ms) 이상 실행되지 못하면 불안정한 것으로 간주하고,
# 충돌 시 5초(5000ms) 후에 재시작
forever start --minUptime 1000 --spinSleepTime 5000 app.js

이 옵션들은 서비스 안정성을 위해 운영 환경에서도 설정해두는 것이 좋습니다.