QuantEngineByItz/DEPLOYMENT_GUIDE.md

# 🚀 Quant Engine Deployment Guide

**생성**: 2026-06-25  
**버전**: v9 Hardening Release  
**패키지 크기**: 24MB  
**배포 대상**: 178.104.200.7 (원격) 또는 로컬

---

## 📦 배포 전 체크리스트

### ✅ 준비된 항목
```
[x] Release 빌드 완료 (24MB)
[x] MudBlazor UI 완성 (91/100 평가)
[x] Dashboard 고도화 (KPI + 시장현황 + 성과 + 알고리즘 + 신호)
[x] Program.cs 수정 (AddMudServices 추가)
[x] 배포 스크립트 준비 (deploy.sh)
[x] Playwright 테스트 통과
[x] git 커밋 완료
```

### 📍 배포 패키지
```
위치: src/dotnet/QuantEngine.Web/publish/
크기: 24MB
파일: 172개

구성:
├── DLL 파일 (10개)
│   ├── QuantEngine.Web.dll (60KB)
│   ├── QuantEngine.Core.dll (28KB)
│   ├── QuantEngine.Application.dll (4KB)
│   ├── QuantEngine.Infrastructure.dll (61KB)
│   ├── MudBlazor.dll (8.7MB) ✨
│   ├── Npgsql.dll (1.5MB)
│   ├── Dapper.dll (242KB)
│   └── 기타
├── 정적 자산 (wwwroot/)
│   ├── CSS (MudBlazor)
│   ├── JS (Blazor Runtime)
│   └── 이미지/폰트
└── 설정 파일
    ├── appsettings.json
    ├── runtimeconfig.json
    └── deps.json
```

---

## 🌐 배포 옵션

### Option 1: 원격 배포 (권장)

#### 전제 조건
```
✓ SSH 키: ~/.ssh/id_ed25519
✓ 원격 서버: 178.104.200.7
✓ 사용자: kjh2064
✓ nginx 설치 완료
```

#### 실행 명령
```bash
cd /c/Temp/data_feed
chmod +x deploy.sh
./deploy.sh
```

#### 배포 과정
```
1. SSH 연결 확인 (10초)
2. 원격 백업 생성 (/var/www/quant_backup_*)
3. 파일 전송 (rsync, 24MB ~ 1분)
4. 권한 설정 (www-data:www-data)
5. nginx 재시작
6. 헬스 체크 (HTTP 200 확인)
```

#### 성공 시 접속
```
URL: http://178.104.200.7/quant/
```

---

### Option 2: 로컬 배포 (개발/테스트)

#### 웹 서비스 실행
```bash
cd src/dotnet/QuantEngine.Web
dotnet QuantEngine.Web.exe
```

#### 접속
```
URL: http://localhost:5265
```

---

### Option 3: IIS 배포 (Windows 전용)

#### 1단계: 호스팅 번들 설치
```
.NET 10.0 Hosting Bundle for IIS
다운로드: https://dotnet.microsoft.com/download/dotnet
```

#### 2단계: IIS 사이트 생성
```
Site Name: Quant Engine
Physical Path: C:\var\www\quant\publish
Protocol: HTTP
Port: 80
```

#### 3단계: 응용 프로그램 풀 설정
```
.NET 런타임 버전: 10.0
파이프라인 모드: Integrated
관리 사용자: ApplicationPoolIdentity
```

#### 4단계: 배포 패키지 복사
```powershell
Copy-Item -Path "src/dotnet/QuantEngine.Web/publish/*" `
          -Destination "C:\var\www\quant\publish" `
          -Recurse -Force
```

#### 5단계: IIS 재시작
```powershell
net stop IISADMIN
net start IISADMIN
```

---

## 🔧 배포 후 확인

### 1. 웹 서비스 상태
```bash
# HTTP 상태 확인
curl -I http://178.104.200.7/quant/

# 기대 결과:
# HTTP/1.1 200 OK
# Content-Type: text/html
```

### 2. 로그 모니터링
```bash
# SSH 접속
ssh kjh2064@178.104.200.7

# nginx 에러 로그
sudo tail -f /var/log/nginx/error.log

# nginx 접근 로그
sudo tail -f /var/log/nginx/access.log

# 애플리케이션 로그 (있으면)
sudo journalctl -u quant-engine -f
```

### 3. 성능 테스트
```bash
# 페이지 로드 시간
time curl http://178.104.200.7/quant/ > /dev/null

# 동시 연결 테스트 (100 users)
ab -n 100 -c 10 http://178.104.200.7/quant/
```

### 4. 기능 검증
```
✓ Dashboard 페이지 로드
✓ KPI 카드 표시
✓ 성과 메트릭 렌더링
✓ 알고리즘 테이블 표시
✓ 신호 피드 업데이트
✓ MudBlazor 스타일 적용
✓ 반응형 레이아웃 (모바일/태블릿/데스크톱)
```

---

## 📊 배포 체크리스트

### 전 배포
```
[ ] Release 빌드 성공 확인
[ ] appsettings.json 데이터베이스 연결 확인
[ ] SSH 키 권한 확인 (chmod 600)
[ ] nginx 설정 확인
[ ] 방화벽 포트 확인 (HTTP 80, HTTPS 443)
[ ] SSL 인증서 확인 (필요시)
```

### 배포 중
```
[ ] deploy.sh 실행
[ ] 파일 전송 진행 상황 모니터링
[ ] 권한 설정 확인
[ ] nginx 재시작 확인
```

### 배포 후
```
[ ] 웹 서비스 접속 확인
[ ] HTTP 상태 200 확인
[ ] 로그 에러 확인
[ ] 성능 메트릭 확인
[ ] 기능 테스트 완료
[ ] 모바일 반응형 확인
```

---

## ⚠️ 문제 해결

### 문제 1: SSH 연결 실패
```
원인: SSH 키 없음 또는 권한 문제
해결:
1. SSH 키 생성: ssh-keygen -t ed25519
2. 키 권한 설정: chmod 600 ~/.ssh/id_ed25519
3. 서버 공개 키 등록: ssh-copy-id kjh2064@178.104.200.7
```

### 문제 2: 파일 전송 실패
```
원인: 네트워크 끊김 또는 디스크 부족
해결:
1. 네트워크 상태 확인
2. 원격 서버 디스크 확인: df -h
3. rsync 재시도: rsync -avz --delete ...
```

### 문제 3: nginx 403 Forbidden
```
원인: 파일 권한 문제
해결:
sudo chown -R www-data:www-data /var/www/quant/publish
sudo chmod -R 755 /var/www/quant/publish
```

### 문제 4: 데이터베이스 연결 실패
```
원인: PostgreSQL 미실행 또는 자격 증명 오류
해결:
1. PostgreSQL 상태 확인: sudo systemctl status postgresql
2. 연결 문자열 확인: appsettings.json
3. 방화벽 포트 확인: netstat -tuln | grep 5432
```

### 문제 5: MudBlazor 스타일 미적용
```
원인: CSS 파일 로드 실패
해결:
1. nginx 설정에서 정적 파일 경로 확인
2. _content/MudBlazor/ 폴더 권한 확인
3. 브라우저 캐시 삭제
```

---

## 🔄 배포 후 운영

### 모니터링
```bash
# 실시간 모니터링
watch -n 5 'curl -s -o /dev/null -w "%{http_code}\n" http://178.104.200.7/quant/'

# 로그 집계 (ELK Stack 권장)
sudo tail -f /var/log/nginx/access.log | grep quant

# 성능 모니터링
top -p $(pgrep -f "QuantEngine.Web.exe")
```

### 백업
```bash
# 일일 백업 (cron)
0 2 * * * /usr/local/bin/backup-quant-engine.sh

# 백업 스크립트
#!/bin/bash
BACKUP_DIR="/var/backups/quant-engine"
mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/quant-$(date +%Y%m%d_%H%M%S).tar.gz /var/www/quant/publish/
find $BACKUP_DIR -name "quant-*.tar.gz" -mtime +30 -delete
```

### 로그 관리
```bash
# 로그 로테이션 설정 (/etc/logrotate.d/quant-engine)
/var/log/nginx/quant/*.log {
    daily
    rotate 7
    compress
    delaycompress
    notifempty
    create 0640 www-data www-data
    sharedscripts
    postrotate
        systemctl reload nginx
    endscript
}
```

---

## 📋 배포 요약

| 항목 | 상태 | 비고 |
|------|:----:|------|
| Release 빌드 | ✅ | 24MB, 172 파일 |
| UI 완성도 | ✅ | 91/100 (우수) |
| 테스트 | ✅ | Playwright 통과 |
| 배포 스크립트 | ✅ | SSH 기반 자동배포 |
| 문서 | ✅ | 완전히 작성됨 |
| **배포 준비** | **✅** | **즉시 배포 가능** |

---

## 🎯 배포 커맨드

### 빠른 배포 (한 줄 명령)
```bash
cd /c/Temp/data_feed && ./deploy.sh
```

### 단계별 배포
```bash
# 1. Release 빌드
cd src/dotnet/QuantEngine.Web
dotnet publish -c Release --output ./publish

# 2. 백업 생성
ssh kjh2064@178.104.200.7 \
  'sudo cp -r /var/www/quant/publish /var/www/quant_backup_$(date +%Y%m%d_%H%M%S)'

# 3. 파일 전송
rsync -avz --delete ./publish/ \
  kjh2064@178.104.200.7:/var/www/quant/publish/

# 4. 권한 설정
ssh kjh2064@178.104.200.7 \
  'sudo chown -R www-data:www-data /var/www/quant/publish && \
   sudo chmod -R 755 /var/www/quant/publish'

# 5. 서비스 재시작
ssh kjh2064@178.104.200.7 \
  'sudo systemctl restart nginx'

# 6. 상태 확인
curl -I http://178.104.200.7/quant/
```

---

**배포 준비 완료!** 🚀

다음 커맨드를 실행하여 배포를 시작하세요:
```bash
./deploy.sh
```

**또는** 수동 배포:
```bash
dotnet publish -c Release && rsync -avz --delete ./publish/ kjh2064@178.104.200.7:/var/www/quant/publish/
```