diff --git a/api.hyungi.net/DEPLOY.md b/api.hyungi.net/DEPLOY.md new file mode 100644 index 0000000..9f8a4b0 --- /dev/null +++ b/api.hyungi.net/DEPLOY.md @@ -0,0 +1,199 @@ +# 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 없음) diff --git a/api.hyungi.net/deploy.sh b/api.hyungi.net/deploy.sh new file mode 100644 index 0000000..5983d8e --- /dev/null +++ b/api.hyungi.net/deploy.sh @@ -0,0 +1,97 @@ +#!/bin/bash + +# 색상 정의 +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +echo -e "${BLUE}========================================${NC}" +echo -e "${BLUE} API 서버 배포 스크립트${NC}" +echo -e "${BLUE}========================================${NC}" +echo "" + +# 현재 디렉토리 확인 +if [ ! -f "package.json" ]; then + echo -e "${RED}❌ 오류: package.json을 찾을 수 없습니다.${NC}" + echo -e "${RED} api.hyungi.net 디렉토리에서 실행해주세요.${NC}" + exit 1 +fi + +echo -e "${BLUE}📂 현재 디렉토리:${NC} $(pwd)" +echo "" + +# 1. Git Pull +echo -e "${YELLOW}1️⃣ Git Pull 시작...${NC}" +git pull +if [ $? -ne 0 ]; then + echo -e "${RED}❌ Git Pull 실패${NC}" + exit 1 +fi +echo -e "${GREEN}✅ Git Pull 완료${NC}" +echo "" + +# 2. NPM Install (package.json 변경 확인) +echo -e "${YELLOW}2️⃣ 의존성 확인 중...${NC}" +if git diff HEAD@{1} HEAD --name-only | grep -q "package.json"; then + echo -e "${YELLOW}📦 package.json 변경 감지 - npm install 실행${NC}" + npm install + if [ $? -ne 0 ]; then + echo -e "${RED}❌ npm install 실패${NC}" + exit 1 + fi + echo -e "${GREEN}✅ npm install 완료${NC}" +else + echo -e "${GREEN}✅ package.json 변경 없음 - 건너뜀${NC}" +fi +echo "" + +# 3. 데이터베이스 마이그레이션 +echo -e "${YELLOW}3️⃣ 데이터베이스 마이그레이션 시작...${NC}" +echo -e "${YELLOW}⚠️ 주의: 마이그레이션 전 데이터베이스 백업을 권장합니다.${NC}" +echo "" +read -p "마이그레이션을 실행하시겠습니까? (y/n): " -n 1 -r +echo +if [[ $REPLY =~ ^[Yy]$ ]]; then + npm run db:migrate + if [ $? -ne 0 ]; then + echo -e "${RED}❌ 마이그레이션 실패${NC}" + echo -e "${YELLOW}💡 롤백이 필요하면 다음 명령어를 실행하세요:${NC}" + echo -e "${YELLOW} npm run db:rollback${NC}" + exit 1 + fi + echo -e "${GREEN}✅ 마이그레이션 완료${NC}" +else + echo -e "${YELLOW}⏭️ 마이그레이션 건너뜀${NC}" +fi +echo "" + +# 4. PM2 재시작 +echo -e "${YELLOW}4️⃣ PM2 서버 재시작...${NC}" +if command -v pm2 &> /dev/null; then + pm2 reload ecosystem.config.js --env production + if [ $? -ne 0 ]; then + echo -e "${RED}❌ PM2 reload 실패${NC}" + exit 1 + fi + echo -e "${GREEN}✅ PM2 reload 완료${NC}" + echo "" + + # PM2 상태 확인 + echo -e "${BLUE}📊 PM2 프로세스 상태:${NC}" + pm2 list +else + echo -e "${YELLOW}⚠️ PM2가 설치되지 않았습니다. 수동으로 서버를 재시작해주세요.${NC}" +fi +echo "" + +echo -e "${GREEN}========================================${NC}" +echo -e "${GREEN} ✅ 배포 완료!${NC}" +echo -e "${GREEN}========================================${NC}" +echo "" +echo -e "${BLUE}📝 배포 후 확인사항:${NC}" +echo -e " 1. API 서버 응답 확인: curl http://localhost:20005/health" +echo -e " 2. 로그 확인: pm2 logs hyungi-api" +echo -e " 3. 에러 발생 시: pm2 logs hyungi-api --err" +echo ""