Node.js 운영 Do Not Do List¶
운영 서버(Production Server) 환경에서 Node.js 서비스를 운영할 때 절대 사용해서는 안 되는 패턴을 정리한 문서임.
본 문서에 포함된 항목들은 실제 운영 환경에서 장애, 보안 사고, 재시작 실패, 원인 추적 불가 문제를 반복적으로 유발함.
“대안 제시”가 목적이 아님.
왜 이 패턴을 쓰면 안 되는지를 명확히 기록하기 위한 문서임.
1. root 계정에 nvm 설치 후 다른 사용자에게 공유¶
export PATH=$PATH:/root/.nvm/versions/node/v22.x.x/bin
export NVM_DIR="/root/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
일반 사용자의 .bashrc 또는 .profile에 root 계정의 nvm 경로를 강제로 주입하는 방식.
왜 문제인가¶
- nvm은 사용자 쉘 전용 도구
- systemd 서비스는
.bashrc를 로드하지 않음 - PM2 재시작 시 환경이 사라짐
- root 전용 경로를 일반 사용자가 실행
- 보안 감사 시 즉시 지적 대상
실제 발생하는 문제¶
- 서버 재부팅 후 서비스 미기동
- PM2 reload 실패
- 동일 서버에서 사용자별 동작 불일치
- 장애 발생 시 원인 추적 불가
운영 기준¶
운영 서버에서는 nvm 자체를 사용하지 않음
Node.js는 반드시/usr/bin/node기반 전역 설치 사용
2. 운영 서버에서 node 직접 실행¶
node index.js
npm run start
왜 문제인가¶
- 프로세스 종료 시 자동 복구 불가
- 서버 재부팅 시 서비스 미기동
- 로그 관리 불가
- 메모리/CPU 상태 추적 불가
실제 발생하는 문제¶
- 트래픽 중 프로세스 사망
- “갑자기 서비스 안 됨” 상태 발생
- 운영자가 직접 서버 접속해야만 복구 가능
운영 기준¶
Node.js는 반드시 PM2 하에서 실행함
systemd 직접 실행은 예외적인 경우만 허용
3. 운영 서버의 Service 위치(/var/www/[ProjectName]/current)에서 npm install 수행¶
npm install
npm sudo install -g
운영 서버에서 의존성을 직접 변경하는 방식.
왜 문제인가¶
- 코드 변경과 의존성 변경이 섞임
- 재현 불가능한 상태 발생
- 롤백 불가
- CI/CD 파이프라인 붕괴
실제 발생하는 문제¶
- “어제는 됐는데 오늘은 안 됨”
- 서버마다 node_modules 상태 불일치
- 장애 원인 재현 실패
운영 기준¶
운영 서버에서는 패키지 업데이트 금지
변경은/home/[User]/[ProjectName]또는 동등한 작업 경로에서만 수행
4. /var/www 경로에서 개발 작업 수행¶
cd /var/www/[ProjectName]/current
npm install
vim index.js
왜 문제인가¶
- 운영 파일 직접 수정
- SELinux / 권한 충돌
- 빌드 산출물과 실행 파일 혼재
실제 발생하는 문제¶
- 실수로 운영 코드 손상
- 장애 시 이전 상태 복구 불가
- 누가 언제 무엇을 바꿨는지 알 수 없음
운영 기준¶
/home/[User]/[ProjectName]는 개발/검증용 작업 경로로 사용하고
운영 실행 경로와 혼합하지 않음
운영 실행:/var/www/[ProjectName]/current
5. Node.js 포트를 외부에 직접 노출¶
firewall-cmd --add-port=3000/tcp
왜 문제인가¶
- 인증, TLS, rate limit 없음
- 스캔/공격에 즉시 노출
- Node.js는 네트워크 보호 기능이 약함
실제 발생하는 문제¶
- 무차별 요청
- 메모리 고갈
- 프로세스 다운
운영 기준¶
외부 트래픽은 반드시 Nginx만 수용
Node.js는 localhost 또는 내부 네트워크에서만 수신
6. Nginx 없이 Node.js 단독 운영¶
- Node.js가 직접 443 포트 수신
- 인증/보안 로직을 Node에 구현
왜 문제인가¶
- TLS 관리 어려움
- 인증/차단 로직 중복
- 장애 대응 포인트 증가
운영 기준¶
Node.js는 Application Runtime
Nginx는 Gateway
7. 운영 기준 없이 즉흥적 설정 변경¶
- 장애 발생 시 서버에서 즉석 수정
- 문서 반영 없음
- 변경 이력 없음
왜 문제인가¶
- 동일 장애 반복
- 팀 내 지식 단절
- 신뢰할 수 없는 운영 환경
운영 기준¶
모든 변경은 문서 → 적용 순서로 진행
8. 정리¶
- 이 문서의 패턴들은 편해 보여도 결국 사고로 이어짐
- “일단 되게 하자”는 운영 환경에서 가장 위험한 생각
- 운영은 예측 가능성과 재현성이 전부임