QuantEngineByItz/docs/archive/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 설치 완료

실행 명령

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: 로컬 배포 (개발/테스트)

웹 서비스 실행

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단계: 배포 패키지 복사

Copy-Item -Path "src/dotnet/QuantEngine.Web/publish/*" `
          -Destination "C:\var\www\quant\publish" `
          -Recurse -Force

5단계: IIS 재시작

net stop IISADMIN
net start IISADMIN

---

🔧 배포 후 확인

1. 웹 서비스 상태

# HTTP 상태 확인
curl -I http://178.104.200.7/quant/

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

2. 로그 모니터링

# 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. 성능 테스트

# 페이지 로드 시간
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. 브라우저 캐시 삭제

---

🔄 배포 후 운영

모니터링

# 실시간 모니터링
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")

백업

# 일일 백업 (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

로그 관리

# 로그 로테이션 설정 (/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 기반 자동배포
문서	✅	완전히 작성됨
배포 준비	✅	즉시 배포 가능

---

🎯 배포 커맨드

빠른 배포 (한 줄 명령)

cd /c/Temp/data_feed && ./deploy.sh

단계별 배포

# 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/

---

배포 준비 완료! 🚀

다음 커맨드를 실행하여 배포를 시작하세요:

./deploy.sh

또는 수동 배포:

dotnet publish -c Release && rsync -avz --delete ./publish/ kjh2064@178.104.200.7:/var/www/quant/publish/