204 lines
5.5 KiB
Markdown
204 lines
5.5 KiB
Markdown
# PM2 배포 및 프로세스 관리 가이드
|
|
|
|
본 문서는 ONA 프론트엔드 모노레포 프로젝트(`frontend_as`)에서 **PM2를 활용한 애플리케이션 배포, 실행, 중지 및 모니터링 명령**을 체계적으로 정리한 가이드입니다.
|
|
|
|
---
|
|
pnpm build:common && pnpm build:as && pm2 reload as2-app
|
|
pnpm --filter=as... build
|
|
pnpm --filter=as... build && pm2 reload as2-app
|
|
## 1. 개요 및 아키텍처
|
|
|
|
- **설정 파일**: 프로젝트 루트의 `ecosystem.config.js`
|
|
- **배포 워크플로우**: `.gitea/workflows/deploy.yml` (Gitea Actions 자동 배포)
|
|
- **실행 모드**: `cluster` (2개 인스턴스로 로드밸런싱 및 무중단 롤링 배포 지원)
|
|
- **운영 대상**:
|
|
- `as2-app` (또는 `as-app`, `cs-app`, `st-app`, `cm-app` 등)
|
|
|
|
---
|
|
|
|
## 2. CI/CD 자동 배포 흐름
|
|
|
|
Gitea 저장소의 `deploy` 브랜치로 푸시될 때 원격 서버(192.168.0.4)에서 다음 스크립트가 순차 실행됩니다:
|
|
|
|
```bash
|
|
cd ~/frontend
|
|
git restore . # 변경된 로컬 파일 원복
|
|
git clean -fd # 추적되지 않는 불필요한 파일/디렉터리 정리
|
|
git pull origin deploy # 최신 deploy 브랜치 코드 반영
|
|
pnpm install # 의존성 패키지 설치
|
|
pnpm turbo build # 프로덕션 빌드 (.next 산출물 생성)
|
|
pm2 reload all # 무중단 서비스 리로드 (클러스터 롤링 재시작)
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 수동 배포 (Manual Deploy) 명령어
|
|
|
|
서버 터미널에 직접 접속하여 수동으로 최신 코드를 배포할 때 사용하는 명령어입니다.
|
|
|
|
### 3.1 전체 애플리케이션 수동 배포
|
|
```bash
|
|
# 1. 프로젝트 루트 이동
|
|
cd ~/frontend
|
|
|
|
# 2. 최신 코드 가져오기
|
|
git pull origin deploy
|
|
|
|
# 3. 의존성 설치 및 전체 빌드
|
|
pnpm install
|
|
pnpm turbo build
|
|
|
|
# 4. PM2 전체 무중단 리로드
|
|
pm2 reload all
|
|
```
|
|
|
|
### 3.2 `as` (행정지원) 앱만 단독 빌드 및 배포
|
|
```bash
|
|
cd ~/frontend
|
|
|
|
# as 앱만 타겟 빌드
|
|
pnpm --filter as build
|
|
|
|
# as2-app 프로세스만 무중단 리로드
|
|
pm2 reload as2-app
|
|
```
|
|
|
|
---
|
|
|
|
## 4. PM2 실행 및 프로세스 등록 (Start & Save)
|
|
|
|
최초 서버 환경 구성 시 또는 프로세스 목록에서 삭제된 후 새롭게 등록할 때 실행합니다.
|
|
|
|
```bash
|
|
# 1. 로그 디렉터리 사전 생성 (필수)
|
|
mkdir -p apps/as/logs
|
|
|
|
# 2. ecosystem.config.js 기반 전체 앱 최초 실행
|
|
pm2 start ecosystem.config.js
|
|
|
|
# 3. 특정 앱(as2-app)만 지정하여 최초 실행
|
|
pm2 start ecosystem.config.js --only as2-app
|
|
|
|
# 4. 서버 재부팅 시에도 PM2 프로세스가 자동 복구되도록 현재 상태 저장 (필수!)
|
|
pm2 save
|
|
|
|
# 5. OS 부팅 시 PM2 데몬 자동 등록 (최초 1회 설정)
|
|
pm2 startup
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 중지, 재시작 및 삭제 명령어
|
|
|
|
### 5.1 재시작 (Restart vs Reload)
|
|
> **TIP: 운영 환경에서는 항상 `reload`를 권장합니다.**
|
|
> - `reload`: 0-second downtime(무중단). 클러스터의 인스턴스를 하나씩 순차적으로 재시작하여 사용자 요청이 끊기지 않음.
|
|
> - `restart`: 모든 인스턴스를 일시에 강제 종료 후 다시 띄우므로 짧은 다운타임 발생.
|
|
|
|
```bash
|
|
# [권장] 무중단 재로드 (운영 배포 시)
|
|
pm2 reload as2-app
|
|
pm2 reload all
|
|
|
|
# 강제 재시작 (설정 변경이 반영되지 않거나 프로세스가 비정상일 때)
|
|
pm2 restart as2-app
|
|
pm2 restart all
|
|
```
|
|
|
|
### 5.2 프로세스 중지 (Stop)
|
|
프로세스를 메모리에서 내리고 실행을 일시 중단합니다 (PM2 목록에는 유지됨).
|
|
|
|
```bash
|
|
# 특정 앱 중지
|
|
pm2 stop as2-app
|
|
|
|
# 전체 앱 중지
|
|
pm2 stop all
|
|
```
|
|
|
|
### 5.3 프로세스 목록에서 제거 (Delete)
|
|
PM2 관리 대상 목록에서 프로세스를 완전히 삭제합니다.
|
|
|
|
```bash
|
|
# 특정 앱 삭제
|
|
pm2 delete as2-app
|
|
|
|
# 전체 앱 삭제
|
|
pm2 delete all
|
|
|
|
# 삭제 상태를 영구 저장할 경우
|
|
pm2 save
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 상태 모니터링 및 로그 확인
|
|
|
|
### 6.1 프로세스 상태 확인
|
|
```bash
|
|
# 간략한 프로세스 상태 표 확인 (online, stopped, cpu, memory 등)
|
|
pm2 status
|
|
# 또는
|
|
pm2 list
|
|
|
|
# 특정 앱 상세 정보 확인 (환경변수, 파일 경로, 재시작 횟수 등)
|
|
pm2 show as2-app
|
|
```
|
|
|
|
### 6.2 실시간 로그 스트리밍 (Logs)
|
|
```bash
|
|
# 특정 앱 실시간 로그 확인 (표준 출력 + 에러 출력)
|
|
pm2 logs as2-app
|
|
|
|
# 최근 100줄 출력 후 실시간 스트리밍
|
|
pm2 logs as2-app --lines 100
|
|
|
|
# 에러 로그만 확인
|
|
pm2 logs as2-app --err
|
|
|
|
# 전체 프로세스 로그 확인
|
|
pm2 logs
|
|
|
|
# 이전 로그 비우기(Flush)
|
|
pm2 flush
|
|
```
|
|
|
|
### 6.3 터미널 대시보드 모니터링 (Monit)
|
|
CPU 및 메모리 실시간 사용량을 터미널 대시보드로 확인합니다.
|
|
```bash
|
|
pm2 monit
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 주요 트러블슈팅 (FAQ)
|
|
|
|
### Q1. `EADDRINUSE: address already in use :::3004` 포트 충돌 발생
|
|
- **원인**: 로컬 개발 서버(`pnpm --filter as dev`) 또는 이전 Node 프로세스가 3004번 포트를 계속 점유 중인 상태입니다.
|
|
- **해결**:
|
|
```bash
|
|
# 3004 포트 사용 중인 PID 확인
|
|
lsof -i :3004
|
|
|
|
# 해당 프로세스 종료
|
|
kill -9 <PID>
|
|
|
|
# PM2 리로드
|
|
pm2 reload as2-app
|
|
```
|
|
|
|
### Q2. `Could not find a production build in the '.next' directory`
|
|
- **원인**: Next.js 프로덕션 실행 전에 빌드 산출물(`.next`)이 생성되지 않았습니다.
|
|
- **해결**:
|
|
```bash
|
|
pnpm --filter as build
|
|
pm2 reload as2-app
|
|
```
|
|
|
|
### Q3. `logs` 디렉터리 관련 에러 발생
|
|
- **원인**: `ecosystem.config.js`의 `cwd: './apps/as'` 설정에 따라 `./logs` 경로가 없을 경우 발생할 수 있습니다.
|
|
- **해결**:
|
|
```bash
|
|
mkdir -p apps/as/logs
|
|
```
|