TK-FB-Project/api.hyungi.net/DEPLOY.md

API 서버 배포 가이드

자동 배포 (권장)

1. 배포 스크립트 실행

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

cd api.hyungi.net
git pull

2. 의존성 설치 (package.json 변경 시)

npm install

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

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

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

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

4. PM2 서버 재시작

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

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

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

---

배포 후 확인사항

1. 서버 상태 확인

# PM2 프로세스 목록
pm2 list

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

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

2. API 응답 확인

# Health Check
curl http://localhost:20005/health

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

3. 마이그레이션 상태 확인

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

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

---

문제 해결

마이그레이션 실패 시

1. 에러 로그 확인

   pm2 logs hyungi-api --err
   

2. 마이그레이션 롤백

   npm run db:rollback
   

3. 특정 마이그레이션만 실행

   npx knex migrate:up 20260119095549_add_worker_display_fields.js --knexfile knexfile.js
   

서버 시작 실패 시

1. 포트 충돌 확인

   lsof -i :20005
   

2. PM2 프로세스 완전 삭제 후 재시작

   pm2 delete hyungi-api
   pm2 start ecosystem.config.js --env production
   

3. 환경변수 확인

   cat .env
   

---

환경별 배포

Development (개발)

NODE_ENV=development npm run db:migrate
pm2 reload ecosystem.config.js --env development

Production (운영)

NODE_ENV=production npm run db:migrate
pm2 reload ecosystem.config.js --env production

---

데이터베이스 백업

백업 생성

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

백업 복구

mysql -h DB_HOST -u DB_USER -p DB_NAME < backup_20260119_120000.sql

---

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

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

# .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 없음)