QuantEngineByItz/DEPLOYMENT_SSH_GUIDE.md

🔐 SSH 배포 가이드

목표: SSH로 원격 서버에 직접 접속하여 환경을 파악한 후 배포
대상: 178.104.200.7 (공인 IP) / 192.168.123.100 (내부 IP)

---

📋 사전 준비

1. SSH 키 설정 (최초 1회)

1.1 로컬에서 SSH 키 생성

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""

1.2 공개 키를 원격 서버에 등록

ssh-copy-id -i ~/.ssh/id_ed25519.pub kjh2064@178.104.200.7
# 또는 내부 IP
ssh-copy-id -i ~/.ssh/id_ed25519.pub kjh2064@192.168.123.100

1.3 SSH 연결 테스트

ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100 "echo '✅ 연결 성공'"

---

🔍 Step 1: 환경 파악

시스템 정보 확인

# SSH 접속
ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100

# 원격 서버에서 실행:
# ─────────────────────────────────────────────

# 1. 시스템 정보
uname -a
lsb_release -a

# 2. 디스크 상태
df -h

# 3. 웹 서버 상태
sudo systemctl status nginx

# 4. 웹 서버 경로
ls -la /var/www/quant/
ls -la /var/www/quant/publish/

# 5. Nginx 설정 확인
sudo cat /etc/nginx/sites-available/default | grep -A 10 "location"

# 6. 포트 상태
sudo netstat -tuln | grep :80

# 7. 사용자 권한 확인
id
sudo -l

예상 환경

✓ Linux (Ubuntu 20.04 또는 그 이상)
✓ nginx (1.18 이상)
✓ /var/www/quant/ 디렉토리 존재 또는 생성 가능
✓ www-data 또는 유사 웹 서버 사용자
✓ sudo 권한 (webmaster 그룹)

---

📦 Step 2: Release 빌드

# 로컬에서 실행
cd /c/Temp/data_feed

# Release 빌드
dotnet publish -c Release \
  -o src/dotnet/QuantEngine.Web/publish

# 결과 확인
ls -lh src/dotnet/QuantEngine.Web/publish/

---

🚀 Step 3: 배포 스크립트 실행

방법 1: 자동 배포 스크립트 (권장)

# 스크립트에 실행 권한 부여
chmod +x deploy-manual.sh

# 배포 실행
./deploy-manual.sh 192.168.123.100
# 또는
./deploy-manual.sh 178.104.200.7

스크립트가 자동으로:

• ✓ SSH 연결 확인
• ✓ 원격 환경 파악
• ✓ 백업 생성
• ✓ 파일 전송 (rsync)
• ✓ 권한 설정
• ✓ nginx 재시작
• ✓ 헬스 체크

방법 2: 수동 배포 (단계별)

# 1. SSH 접속
ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100

# 원격 서버에서:
# ─────────────────────────────────────────────

# 2. 백업 생성
sudo mkdir -p /var/www/quant_backup
sudo cp -r /var/www/quant/publish \
  /var/www/quant_backup/quant_$(date +%Y%m%d_%H%M%S)
echo "✓ 백업 생성 완료"

# 3. 배포 디렉토리 준비
sudo mkdir -p /var/www/quant/publish
sudo chmod 777 /var/www/quant/publish

# 4. 권한 설정
sudo chown -R www-data:www-data /var/www/quant/publish
sudo chmod -R 755 /var/www/quant/publish

# 5. SSH 종료
exit

# 로컬에서: 파일 전송
rsync -avz --delete \
  -e "ssh -i ~/.ssh/id_ed25519" \
  src/dotnet/QuantEngine.Web/publish/ \
  kjh2064@192.168.123.100:/var/www/quant/publish/

# 다시 SSH 접속
ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100

# 원격 서버에서:
# ─────────────────────────────────────────────

# 6. nginx 재시작
sudo systemctl restart nginx

# 7. 상태 확인
sudo systemctl status nginx

# 종료
exit

---

✅ Step 4: 배포 검증

# 1. HTTP 상태 확인
curl -I http://178.104.200.7/quant/
# 또는
curl -I http://192.168.123.100/quant/

# 기대: HTTP/1.1 200 OK

# 2. MudBlazor 로드 확인
curl -s http://178.104.200.7/quant/ | grep -c "MudBlazor"
# 기대: > 0

# 3. 페이지 제목 확인
curl -s http://178.104.200.7/quant/ | grep -o "<title>.*</title>"
# 기대: <title>Quant Engine - Dashboard</title>

# 4. nginx 로그 확인
ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100 \
  'sudo tail -20 /var/log/nginx/error.log'

# 5. 브라우저 테스트
# http://178.104.200.7/quant/ 접속

---

🔄 롤백 (배포 실패 시)

ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100 << 'EOF'
# 최신 백업 확인
ls -lt /var/www/quant_backup/

# 최신 백업으로 복원
LATEST=$(ls -t /var/www/quant_backup | head -1)
echo "복원 중: $LATEST"

sudo cp -r /var/www/quant_backup/$LATEST/* /var/www/quant/publish/

# 권한 재설정
sudo chown -R www-data:www-data /var/www/quant/publish
sudo chmod -R 755 /var/www/quant/publish

# nginx 재시작
sudo systemctl restart nginx

echo "✅ 롤백 완료"
EOF

---

📊 배포 체크리스트

배포 전

[ ] SSH 키 설정 완료 (~/.ssh/id_ed25519)
[ ] SSH 연결 테스트 성공
[ ] Release 빌드 완료 (24MB)
[ ] 배포 스크립트 준비

배포 중

[ ] 환경 파악 완료
[ ] 백업 생성 완료
[ ] 파일 전송 완료
[ ] 권한 설정 완료
[ ] nginx 재시작 완료

배포 후

[ ] HTTP 200 OK 확인
[ ] MudBlazor 리소스 로드됨
[ ] 페이지 제목 확인
[ ] nginx 로그 에러 없음
[ ] 브라우저 접속 테스트

---

🆘 문제 해결

SSH 연결 타임아웃

# 원인: IP 주소 오류 또는 방화벽

# 해결:
1. IP 확인: 178.104.200.7 또는 192.168.123.100?
2. SSH 포트 확인: 22 (기본값)
3. 방화벽 규칙 확인
4. 공개 키 등록 재확인

권한 오류 (sudo 불가)

# 원인: sudo 권한 없음

# 확인:
sudo -l

# 해결: 관리자에게 webmaster 그룹 추가 요청

nginx 재시작 실패

# 로그 확인
sudo systemctl status nginx
sudo journalctl -u nginx -n 20

# 설정 테스트
sudo nginx -t

# 포트 충돌 확인
sudo netstat -tuln | grep :80

파일 권한 문제

# 현재 권한 확인
ls -la /var/www/quant/publish/

# 권한 수정
sudo chown -R www-data:www-data /var/www/quant/publish
sudo chmod -R 755 /var/www/quant/publish

---

📚 관련 파일

배포 스크립트:
├── deploy.sh (자동 배포, bash)
└── deploy-manual.sh (대화형 배포, 이 파일)

배포 가이드:
├── DEPLOYMENT_GUIDE.md (전체 가이드)
├── DEPLOYMENT_STEPS.md (단계별 지침)
├── DEPLOYMENT_CHECKLIST.md (운영 체크리스트)
└── DEPLOYMENT_SSH_GUIDE.md (이 파일)

CI/CD:
├── .gitea/workflows/deploy-prod.yml (자동화)
└── CI_CD_PIPELINE.md (CI/CD 문서)

---

⚡ 빠른 배포 명령어

한 번에 배포

chmod +x deploy-manual.sh && ./deploy-manual.sh 192.168.123.100

내부 IP 사용

# Gitea에서 배포할 때 (자동 CI/CD)
DEPLOY_HOST=192.168.123.100

외부 접속

# 사용자가 접속할 때
http://178.104.200.7/quant/

---

배포 준비 완료! 🚀

deploy-manual.sh 스크립트를 실행하거나, 위의 수동 단계를 따라 배포하세요.