215a3aa880
Comprehensive documentation covering: - Full deployment pipeline overview - Server environment configuration - Step-by-step deployment process - Manual SCP deployment method - Docker container architecture - Rollback procedures - Quick reference commands - Troubleshooting guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
40 KiB
40 KiB
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 <ts> # 특정 버전 롤백 ║
║ ./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 <container> 로그 확인 |
| 포트 충돌 | netstat -tlnp | grep <port> 확인 후 프로세스 종료 |
| 이미지 빌드 실패 | docker build --no-cache 캐시 없이 재빌드 |
| DB 연결 오류 | Volume 마운트 확인, 파일 권한 확인 |
| API 404 오류 | Backend 컨테이너 재시작, 라우터 등록 확인 |
최종 업데이트: 2024-12-30