# AutonetSellCar.com 배포 가이드 이 문서는 코드 수정부터 운영 배포까지의 전체 과정을 설명합니다. --- ## 1. 전체 배포 흐름 개요 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 배포 파이프라인 전체 흐름 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ 1. 개발 │ ───▶ │ 2. 커밋 │ ───▶ │ 3. 스테이징 │ ───▶ │ 4. 운영 │ │ (서버4) │ │ & Push │ │ 테스트 │ │ 배포 │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ ▼ ▼ ▼ ▼ 코드 수정 git commit Docker 빌드 promote 로컬 테스트 git push staging 포트 3001/8001 포트 3000/8000 ``` --- ## 2. 서버 환경 구성 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 네트워크 구성도 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────────────────┐ ┌────────────────────────────────┐ │ 서버4 │ │ 서버2 │ │ (개발 서버) │ │ (운영 서버) │ │ │ SSH/SCP │ 192.168.0.202 │ │ ┌──────────────┐ │ ─────────────────▶ │ │ │ │ 소스 코드 │ │ │ ┌────────────┐ ┌────────────┐ │ │ │ (로컬 개발) │ │ │ │ Staging │ │ Production │ │ │ └──────────────┘ │ │ │ :3001/:8001│ │ :3000/:8000│ │ │ │ │ └────────────┘ └────────────┘ │ │ D:\Workspace\ │ │ │ │ claudeCode\ │ │ /opt/autonet/ │ │ AutonetSellCar.com│ │ ├── staging/ │ │ │ │ ├── production/ │ │ │ │ └── git/autonet.git │ └────────────────────┘ └────────────────────────────────┘ ``` --- ## 3. 디렉토리 구조 ``` 서버2 (/opt/autonet/) │ ├── git/ │ └── autonet.git/ # Bare Git Repository │ └── hooks/ │ └── post-receive # 자동 배포 훅 │ ├── staging/ # 스테이징 환경 │ ├── frontend/ │ ├── backend/ │ └── docker-compose.staging.yml │ ├── production/ # 운영 환경 │ ├── frontend/ │ ├── backend/ │ └── docker-compose.production.yml │ ├── releases/ # 롤백용 백업 │ ├── 20241230_140000/ │ └── 20241230_150000/ │ └── scripts/ ├── deploy-staging.sh └── deploy.sh ``` --- ## 4. 단계별 상세 설명 ### Step 1: 코드 수정 (서버4) ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Step 1: 코드 수정 │ └─────────────────────────────────────────────────────────────────────────────┘ 개발자 PC (서버4) ┌─────────────────────────────────────────┐ │ │ │ D:\Workspace\claudeCode\ │ │ └── AutonetSellCar.com\ │ │ ├── backend\ │ │ │ └── app\ │ │ │ ├── api\ ◀── 수정 │ │ │ ├── models\ │ │ │ └── schemas\ ◀── 수정 │ │ │ │ │ └── frontend\ │ │ └── src\ │ │ ├── app\ ◀── 수정 │ │ ├── components\ ◀── 수정 │ │ └── lib\ ◀── 수정 │ │ │ │ ┌─────────────────────────────────┐ │ │ │ 로컬 테스트 서버 │ │ │ │ Frontend: http://localhost:3000│ │ │ │ Backend: http://localhost:8000│ │ │ └─────────────────────────────────┘ │ │ │ └─────────────────────────────────────────┘ 명령어: ┌─────────────────────────────────────────┐ │ # Backend 실행 │ │ cd backend │ │ venv\Scripts\activate │ │ uvicorn app.main:app --reload --port 8000│ │ │ │ # Frontend 실행 │ │ cd frontend │ │ npm run dev │ └─────────────────────────────────────────┘ ``` ### Step 2: Git Commit & Push ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Step 2: Git Commit & Push │ └─────────────────────────────────────────────────────────────────────────────┘ ┌───────────────┐ ┌───────────────┐ │ 서버4 │ │ 서버2 │ │ (개발) │ │ (운영) │ └───────┬───────┘ └───────┬───────┘ │ │ │ 1. git add . │ │ 2. git commit -m "message" │ │ │ ▼ │ ┌───────────────┐ │ │ Local Repo │ │ │ (main) │ │ └───────┬───────┘ │ │ │ │ 3. git push staging main │ │ │ │ SSH (포트 22) │ │ ════════════════════════════════════▶ │ │ ▼ │ ┌───────────────┐ │ │ Bare Repo │ │ │ autonet.git │ │ └───────┬───────┘ │ │ │ │ post-receive 훅 실행 │ ▼ │ ┌───────────────┐ │ │ 스테이징 │ │ │ 자동 배포 │ │ └───────────────┘ 명령어: ┌─────────────────────────────────────────┐ │ git status │ │ git add . │ │ git commit -m "feat: 기능 설명" │ │ git push staging main │ └─────────────────────────────────────────┘ ``` ### Step 3: 스테이징 테스트 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Step 3: 스테이징 테스트 │ └─────────────────────────────────────────────────────────────────────────────┘ 서버2 스테이징 환경 ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ /opt/autonet/staging/ │ │ │ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │ │ Frontend Container │ │ Backend Container │ │ │ │ │ │ │ │ │ │ autonet-frontend │ │ autonet-backend │ │ │ │ -staging │ │ -staging │ │ │ │ │ │ │ │ │ │ Port: 3001 ─────┼─────▶ Port: 8001 │ │ │ │ │ API │ │ │ │ └─────────────────────┘ └──────────┬──────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ staging-db │ │ │ │ (SQLite/Volume) │ │ │ └─────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ 테스트 URL: ┌─────────────────────────────────────────┐ │ Frontend: http://192.168.0.202:3001 │ │ Backend: http://192.168.0.202:8001 │ │ API Docs: http://192.168.0.202:8001/docs│ └─────────────────────────────────────────┘ 수동 빌드 명령어 (SSH 접속 후): ┌─────────────────────────────────────────┐ │ cd /opt/autonet/staging │ │ docker compose -f docker-compose.staging.yml down│ │ docker compose -f docker-compose.staging.yml build --no-cache│ │ docker compose -f docker-compose.staging.yml up -d│ └─────────────────────────────────────────┘ ``` ### Step 4: 운영 배포 (Promote) ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Step 4: 운영 배포 (Promote) │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────┐ ┌─────────────────────┐ │ 스테이징 │ promote │ 운영 │ │ (테스트 완료) │ ══════════▶ │ (서비스 중) │ │ :3001 / :8001 │ │ :3000 / :8000 │ └─────────────────────┘ └─────────────────────┘ │ │ │ ▼ │ ┌─────────────────────┐ │ │ 백업 생성 │ │ │ /releases/ │ │ │ 20241230_160000/ │ │ └─────────────────────┘ 배포 흐름: ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 1. 현재 운영 백업 │ │ └── /opt/autonet/releases/20241230_160000/ │ │ │ │ 2. 운영 컨테이너 중지 │ │ └── docker compose down │ │ │ │ 3. 스테이징 → 운영 복사 (DB/uploads 제외) │ │ └── rsync -av --exclude='*.db' staging/ production/ │ │ │ │ 4. 운영 컨테이너 빌드 & 시작 │ │ └── docker compose up -d --build │ │ │ │ 5. 헬스체크 │ │ └── curl http://localhost:3000 && curl http://localhost:8000 │ │ │ │ 6. 실패 시 자동 롤백 │ │ └── deploy.sh rollback │ │ │ └─────────────────────────────────────────────────────────────────────┘ 명령어: ┌─────────────────────────────────────────┐ │ # 스테이징 → 운영 승격 │ │ /opt/autonet/scripts/deploy.sh promote │ │ │ │ # 롤백 (문제 발생 시) │ │ /opt/autonet/scripts/deploy.sh rollback │ │ │ │ # 상태 확인 │ │ /opt/autonet/scripts/deploy.sh status │ └─────────────────────────────────────────┘ ``` --- ## 5. 수동 배포 방법 (SCP 직접 전송) 긴급 배포 또는 post-receive 훅 미설정 시 사용합니다. ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 수동 배포 (SCP 방식) │ └─────────────────────────────────────────────────────────────────────────────┘ 서버4 (개발) 서버2 (운영) ┌───────────────┐ ┌───────────────┐ │ │ │ │ │ 수정된 파일 │ SCP 전송 │ production/ │ │ frontend/ │ ═══════════════════════▶│ frontend/ │ │ backend/ │ │ backend/ │ │ │ │ │ └───────────────┘ └───────┬───────┘ │ ▼ ┌───────────────┐ │ Docker 재빌드 │ │ │ │ docker build │ │ docker run │ └───────────────┘ Step 1: 파일 전송 (PowerShell에서) ┌─────────────────────────────────────────────────────────────────────┐ │ # Frontend 파일 전송 │ │ scp -r frontend/src/app/admin/*.tsx \ │ │ damon@192.168.0.202:/opt/autonet/production/frontend/src/app/admin/│ │ │ │ # Backend 파일 전송 │ │ scp -r backend/app/* \ │ │ damon@192.168.0.202:/opt/autonet/production/backend/app/ │ └─────────────────────────────────────────────────────────────────────┘ Step 2: Docker 재빌드 (서버2 SSH 접속 후) ┌─────────────────────────────────────────────────────────────────────┐ │ cd /opt/autonet/production │ │ │ │ # Frontend 재빌드 │ │ docker stop autonet-frontend │ │ docker rm autonet-frontend │ │ docker build -t autonet-frontend-prod \ │ │ --build-arg NEXT_PUBLIC_API_URL=http://192.168.0.202:8000 \ │ │ ./frontend │ │ docker run -d --name autonet-frontend \ │ │ -p 3000:3000 \ │ │ -e NEXT_PUBLIC_API_URL=http://192.168.0.202:8000 \ │ │ autonet-frontend-prod │ │ │ │ # Backend 재빌드 │ │ docker stop autonet-backend │ │ docker rm autonet-backend │ │ docker build -t autonet-backend-prod ./backend │ │ docker run -d --name autonet-backend \ │ │ -p 8000:8000 \ │ │ -v $(pwd)/backend/uploads:/app/uploads \ │ │ -v $(pwd)/backend/autonet.db:/app/autonet.db \ │ │ autonet-backend-prod │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 6. Docker 컨테이너 구성 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Docker 컨테이너 구성도 │ └─────────────────────────────────────────────────────────────────────────────┘ 운영 환경 (Production) ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Docker Network │ │ │ │ │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ autonet-frontend│ API │ autonet-backend │ │ │ │ │ │ │───────▶│ │ │ │ │ │ │ Next.js 14 │ │ FastAPI │ │ │ │ │ │ Port: 3000 │ │ Port: 8000 │ │ │ │ │ │ │ │ │ │ │ │ │ └──────────────────┘ └────────┬─────────┘ │ │ │ │ │ │ │ │ │ ┌────────▼─────────┐ │ │ │ │ │ │ │ │ │ │ │ Volumes │ │ │ │ │ │ - autonet.db │ │ │ │ │ │ - uploads/ │ │ │ │ │ │ │ │ │ │ │ └──────────────────┘ │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────┐ │ │ │ carmodoo-agent │ (Playwright 브라우저 자동화) │ │ │ - PDF 생성 │ │ │ │ - 차량 스펙 조회 │ │ │ └──────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ 포트 매핑: ┌─────────────────────────────────────────┐ │ 호스트:3000 ──▶ 컨테이너:3000 (Frontend)│ │ 호스트:8000 ──▶ 컨테이너:8000 (Backend) │ └─────────────────────────────────────────┘ ``` --- ## 7. 롤백 절차 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 롤백 절차 │ └─────────────────────────────────────────────────────────────────────────────┘ 문제 발생! │ ▼ ┌───────────────┐ 아니오 ┌───────────────┐ │ 자동 롤백 │ ◀────────────── │ 헬스체크 통과?│ │ 실행됨 │ └───────────────┘ └───────┬───────┘ │ 예 │ ▼ │ ┌───────────────┐ │ │ 배포 완료 │ │ └───────────────┘ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ /opt/autonet/releases/ │ │ │ │ │ ├── 20241230_140000/ ◀── 이전 버전으로 복원 │ │ ├── 20241230_150000/ │ │ └── 20241230_160000/ ◀── 현재 (문제 발생) │ │ │ └───────────────────────────────────────────────────────────────────────┘ 롤백 명령어: ┌─────────────────────────────────────────┐ │ # 직전 버전으로 롤백 │ │ /opt/autonet/scripts/deploy.sh rollback │ │ │ │ # 특정 버전으로 롤백 │ │ /opt/autonet/scripts/deploy.sh \ │ │ rollback-to 20241230_140000 │ │ │ │ # 사용 가능한 버전 확인 │ │ ls /opt/autonet/releases/ │ └─────────────────────────────────────────┘ ``` --- ## 8. 빠른 참조 명령어 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 빠른 참조 명령어 │ └─────────────────────────────────────────────────────────────────────────────┘ ╔═══════════════════════════════════════════════════════════════════════════╗ ║ 개발 (서버4) ║ ╠═══════════════════════════════════════════════════════════════════════════╣ ║ git status # 변경 파일 확인 ║ ║ git add . # 스테이징 ║ ║ git commit -m "message" # 커밋 ║ ║ git push staging main # 서버2로 푸시 ║ ╚═══════════════════════════════════════════════════════════════════════════╝ ╔═══════════════════════════════════════════════════════════════════════════╗ ║ 운영 (서버2) ║ ╠═══════════════════════════════════════════════════════════════════════════╣ ║ docker ps # 실행 중인 컨테이너 확인 ║ ║ docker logs autonet-frontend # 프론트엔드 로그 ║ ║ docker logs autonet-backend # 백엔드 로그 ║ ║ docker restart autonet-frontend # 프론트엔드 재시작 ║ ║ docker restart autonet-backend # 백엔드 재시작 ║ ╚═══════════════════════════════════════════════════════════════════════════╝ ╔═══════════════════════════════════════════════════════════════════════════╗ ║ 배포 스크립트 ║ ╠═══════════════════════════════════════════════════════════════════════════╣ ║ ./deploy.sh promote # 스테이징 → 운영 승격 ║ ║ ./deploy.sh rollback # 직전 버전 롤백 ║ ║ ./deploy.sh rollback-to # 특정 버전 롤백 ║ ║ ./deploy.sh status # 현재 상태 확인 ║ ╚═══════════════════════════════════════════════════════════════════════════╝ ``` --- ## 9. 체크리스트 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 배포 전 체크리스트 │ └─────────────────────────────────────────────────────────────────────────────┘ 배포 전: ┌─────────────────────────────────────────────────────────────────────────┐ │ [ ] 로컬에서 테스트 완료 │ │ [ ] git status로 변경 파일 확인 │ │ [ ] 불필요한 파일 제외 (.env, node_modules 등) │ │ [ ] 커밋 메시지 작성 │ └─────────────────────────────────────────────────────────────────────────┘ 스테이징 테스트: ┌─────────────────────────────────────────────────────────────────────────┐ │ [ ] Frontend 정상 작동 (http://192.168.0.202:3001) │ │ [ ] Backend API 정상 작동 (http://192.168.0.202:8001/docs) │ │ [ ] 주요 기능 테스트 완료 │ │ [ ] 에러 로그 확인 (docker logs) │ └─────────────────────────────────────────────────────────────────────────┘ 운영 배포 후: ┌─────────────────────────────────────────────────────────────────────────┐ │ [ ] 헬스체크 통과 │ │ [ ] 주요 페이지 접속 확인 │ │ [ ] API 응답 확인 │ │ [ ] 이전 버전 백업 확인 (/opt/autonet/releases/) │ └─────────────────────────────────────────────────────────────────────────┘ ``` --- ## 10. 문제 해결 | 문제 | 해결 방법 | |------|----------| | 컨테이너 시작 안됨 | `docker logs ` 로그 확인 | | 포트 충돌 | `netstat -tlnp \| grep ` 확인 후 프로세스 종료 | | 이미지 빌드 실패 | `docker build --no-cache` 캐시 없이 재빌드 | | DB 연결 오류 | Volume 마운트 확인, 파일 권한 확인 | | API 404 오류 | Backend 컨테이너 재시작, 라우터 등록 확인 | --- **최종 업데이트**: 2024-12-30