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>
526 lines
40 KiB
Markdown
526 lines
40 KiB
Markdown
# 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
|