TK-FB-Project/deploy/tkfb-package/api.hyungi.net/DEPLOY.md

# API 서버 배포 가이드

## 자동 배포 (권장)

### 1. 배포 스크립트 실행

```bash
cd api.hyungi.net

# 처음 한 번만: 실행 권한 부여
chmod +x deploy.sh

# 배포 실행
./deploy.sh
```

배포 스크립트는 다음을 자동으로 처리합니다:
1. ✅ Git Pull
2. ✅ NPM Install (package.json 변경 시)
3. ✅ 데이터베이스 마이그레이션 (확인 후 실행)
4. ✅ PM2 서버 재시작
5. ✅ 상태 확인

---

## 수동 배포

### 1. Git Pull
```bash
cd api.hyungi.net
git pull
```

### 2. 의존성 설치 (package.json 변경 시)
```bash
npm install
```

### 3. 데이터베이스 마이그레이션

⚠️ **중요**: 마이그레이션 전 데이터베이스 백업을 권장합니다!

```bash
# 마이그레이션 실행
npm run db:migrate

# 마이그레이션 롤백 (문제 발생 시)
npm run db:rollback
```

### 4. PM2 서버 재시작

```bash
# 무중단 재시작 (권장)
pm2 reload ecosystem.config.js --env production

# 또는 일반 재시작
pm2 restart hyungi-api

# 서버 중지 후 시작
pm2 stop hyungi-api
pm2 start ecosystem.config.js --env production
```

---

## 배포 후 확인사항

### 1. 서버 상태 확인
```bash
# PM2 프로세스 목록
pm2 list

# 실시간 로그 확인
pm2 logs hyungi-api

# 에러 로그만 확인
pm2 logs hyungi-api --err
```

### 2. API 응답 확인
```bash
# Health Check
curl http://localhost:20005/health

# 또는
curl http://api.hyungi.net/health
```

### 3. 마이그레이션 상태 확인
```bash
# 현재 마이그레이션 버전 확인
npx knex migrate:currentVersion --knexfile knexfile.js

# 적용된 마이그레이션 목록
npx knex migrate:list --knexfile knexfile.js
```

---

## 문제 해결

### 마이그레이션 실패 시

1. **에러 로그 확인**
   ```bash
   pm2 logs hyungi-api --err
   ```

2. **마이그레이션 롤백**
   ```bash
   npm run db:rollback
   ```

3. **특정 마이그레이션만 실행**
   ```bash
   npx knex migrate:up 20260119095549_add_worker_display_fields.js --knexfile knexfile.js
   ```

### 서버 시작 실패 시

1. **포트 충돌 확인**
   ```bash
   lsof -i :20005
   ```

2. **PM2 프로세스 완전 삭제 후 재시작**
   ```bash
   pm2 delete hyungi-api
   pm2 start ecosystem.config.js --env production
   ```

3. **환경변수 확인**
   ```bash
   cat .env
   ```

---

## 환경별 배포

### Development (개발)
```bash
NODE_ENV=development npm run db:migrate
pm2 reload ecosystem.config.js --env development
```

### Production (운영)
```bash
NODE_ENV=production npm run db:migrate
pm2 reload ecosystem.config.js --env production
```

---

## 데이터베이스 백업

### 백업 생성
```bash
# MySQL 백업
mysqldump -h DB_HOST -u DB_USER -p DB_NAME > backup_$(date +%Y%m%d_%H%M%S).sql
```

### 백업 복구
```bash
mysql -h DB_HOST -u DB_USER -p DB_NAME < backup_20260119_120000.sql
```

---

## CI/CD 자동화 (향후 개선안)

GitHub Actions 또는 GitLab CI/CD를 사용한 자동 배포:

```yaml
# .github/workflows/deploy.yml 예시
name: Deploy to Production

on:
  push:
    branches: [ master ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: SSH and Deploy
        run: |
          ssh user@server 'cd /path/to/api.hyungi.net && ./deploy.sh'
```

---

## 참고사항

- **마이그레이션은 한 방향으로만 진행** (forward-only)
- **rollback은 개발 환경에서만 사용 권장**
- **운영 환경에서는 반드시 백업 후 마이그레이션**
- **PM2 reload는 무중단 재시작** (downtime 없음)