kjh2064/QuantEngineByItz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(deploy): Update DEPLOYMENT_SSH_GUIDE.md with final environment configuration
WBS-9.3 - NULL Policy CI Gate / NULL Policy Validation (pull_request) Failing after 4s
Details
Quant Engine CI/CD Pipeline / validate-core (pull_request) Failing after 2m15s
Details
Quant Engine CI/CD Pipeline / validate-ui-and-storage (pull_request) Has been skipped
Details

Browse Source 
Complete rewrite with v9 production environment details:

Environment Configuration:
- Server: hz-prod-01
- Public IP: 178.104.200.7
- Internal IP: 172.17.0.1 (Docker gateway, internal access only)
- SSH user: kjh2064
- SSH endpoint: ssh kjh2064@178.104.200.7

Deployment Architecture:
- Nginx reverse proxy on port 80 (already configured)
- Location /quant/ → proxy_pass http://127.0.0.1:5000/
- Quantengine service runs on localhost:5000
- systemd service: /etc/systemd/system/quantengine.service

Deployment Paths:
- Active deployment: /home/kjh2064/quantengine_active
- Backup location: /home/kjh2064/quantengine_backup
- Nginx config: /etc/nginx/sites-available/gitea-ip.conf

Key Procedures:
1. SSH Setup: ssh-keygen, ssh-copy-id, key validation
2. Environment Check: System info, deployment paths, service status
3. Release Build: dotnet publish -c Release
4. Deployment Methods:
   - Auto: deploy-production.sh (recommended)
   - Auto: deploy-manual.sh (interactive)
   - Manual: Step-by-step SSH procedures
5. Verification: Health checks, logs, MudBlazor validation
6. Rollback: Automated backup restoration

Troubleshooting Guide:
- SSH connection failures
- Service startup issues
- Nginx proxy errors
- File permission problems

Complete deployment flow diagrams and examples for all scenarios.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
김재현
2026-06-25 18:24:01 +09:00
parent a2acaa70d8
commit d0bbb779c0
1 changed files with 246 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DEPLOYMENT_SSH_GUIDE.md
+245 -142
View File
@@ -1,7 +1,7 @@
# 🔐 SSH 배포 가이드 # 🔐 SSH 배포 가이드 (v9)
**목표**: SSH로 원격 서버에 직접 접속하여 환경을 파악한 후 배포 **목표**: SSH로 원격 서버에 직접 접속하여 배포
**대상**: 178.104.200.7 (공인 IP) / 192.168.123.100 (내부 IP) **환경**: hz-prod-01 (공인 IP 178.104.200.7 / 내부 IP 172.17.0.1)
--- ---
@@ -17,61 +17,84 @@ ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
#### 1.2 공개 키를 원격 서버에 등록 #### 1.2 공개 키를 원격 서버에 등록
```bash ```bash
ssh-copy-id -i ~/.ssh/id_ed25519.pub kjh2064@178.104.200.7 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 연결 테스트 #### 1.3 SSH 연결 테스트
```bash ```bash
ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100 "echo '✅ 연결 성공'" ssh -i ~/.ssh/id_ed25519 kjh2064@178.104.200.7 "echo '✅ 연결 성공'"
``` ```
--- ---
## 🔍 Step 1: 환경 파악 ## 🔍 Step 1: 환경 파악
### 시스템 정보 확인 ### 원격 서버 정보 확인
```bash ```bash
# SSH 접속 ssh kjh2064@178.104.200.7 << 'EOF'
ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100
# 원격 서버에서 실행:
# ─────────────────────────────────────────────
# 1. 시스템 정보 # 1. 시스템 정보
echo "=== 시스템 정보 ==="
hostname
uname -a uname -a
lsb_release -a lsb_release -a
# 2. 디스크 상태 # 2. 배포 경로
echo -e "\n=== 배포 경로 ==="
ls -la /home/kjh2064/quantengine_active/ || echo "아직 없음 (첫 배포)"
ls -la /home/kjh2064/quantengine_backup/
# 3. 서비스 상태
echo -e "\n=== quantengine 서비스 ==="
sudo systemctl status quantengine --no-pager
# 4. Nginx 설정
echo -e "\n=== Nginx /quant 설정 ==="
cat /etc/nginx/sites-available/gitea-ip.conf | grep -A 10 "location /quant"
# 5. 포트 상태
echo -e "\n=== 포트 상태 ==="
sudo netstat -tuln | grep -E ":80|:443|:5000"
# 6. 디스크 상태
echo -e "\n=== 디스크 ==="
df -h df -h
# 3. 웹 서버 상태 EOF
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 또는 그 이상) ✓ Linux (Ubuntu 20.04+)
✓ nginx (1.18 이상) ✓ nginx 1.28.3 (reverse proxy)
✓ /var/www/quant/ 디렉토리 존재 또는 생성 가능 ✓ /home/kjh2064/quantengine_active/ 배포 경로
✓ www-data 또는 유사 웹 서버 사용자 ✓ quantengine systemd 서비스
✓ sudo 권한 (webmaster 그룹) ✓ 포트 5000에서 .NET 앱 실행
✓ sudo 권한 (quantengine 서비스 제어)
```
---
## 🏗️ 배포 아키텍처
```
┌────────────────────────────────────────────────────┐
│ 사용자 (외부 인터넷) │
│ http://178.104.200.7/quant/ │
└─────────────────────┬────────────────────────────────┘
│ 공인 IP (포트 80)
┌─────────────────────▼────────────────────────────────┐
│ Nginx (reverse proxy) │
│ /etc/nginx/sites-available/gitea-ip.conf │
│ location /quant/ → proxy_pass http://127.0.0.1:5000/
└─────────────────────┬────────────────────────────────┘
│ localhost:5000
┌─────────────────────▼────────────────────────────────┐
│ quantengine (systemd 서비스) │
│ /home/kjh2064/quantengine_active/ │
│ QuantEngine.Web.dll (실행 중) │
└────────────────────────────────────────────────────┘
``` ```
--- ---
@@ -79,7 +102,7 @@ sudo -l
## 📦 Step 2: Release 빌드 ## 📦 Step 2: Release 빌드
```bash ```bash
# 로컬에서 실행 # 로컬 개발 머신에서 실행
cd /c/Temp/data_feed cd /c/Temp/data_feed
# Release 빌드 # Release 빌드
@@ -88,20 +111,21 @@ dotnet publish -c Release \
# 결과 확인 # 결과 확인
ls -lh src/dotnet/QuantEngine.Web/publish/ ls -lh src/dotnet/QuantEngine.Web/publish/
du -sh src/dotnet/QuantEngine.Web/publish/
``` ```
--- ---
## 🚀 Step 3: 배포 스크립트 실행 ## 🚀 Step 3: 배포 방법
### 방법 1: 자동 배포 스크립트 (권장) ### 방법 1: 자동 배포 스크립트 (권장)
```bash ```bash
# 스크립트에 실행 권한 부여 # 스크립트에 실행 권한 부여
chmod +x deploy-manual.sh chmod +x deploy-production.sh
# 배포 실행 # 배포 실행
./deploy-manual.sh 192.168.123.100 ./deploy-production.sh
# 또는 # 또는
./deploy-manual.sh 178.104.200.7 ./deploy-manual.sh 178.104.200.7
``` ```
@@ -109,115 +133,180 @@ chmod +x deploy-manual.sh
**스크립트가 자동으로:** **스크립트가 자동으로:**
- ✓ SSH 연결 확인 - ✓ SSH 연결 확인
- ✓ 원격 환경 파악 - ✓ 원격 환경 파악
- ✓ 서비스 중지
- ✓ 백업 생성 - ✓ 백업 생성
- ✓ 파일 전송 (rsync) - ✓ 파일 전송 (rsync)
- ✓ 권한 설정 - ✓ 파일 검증
- ✓ nginx 재시작 - ✓ 서비스 시작
- ✓ 헬스 체크 - ✓ 헬스 체크
### 방법 2: 수동 배포 (단계별) ### 방법 2: 수동 배포 (단계별)
#### Step 2-1: SSH 접속
```bash ```bash
# 1. SSH 접속 ssh -i ~/.ssh/id_ed25519 kjh2064@178.104.200.7
ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100 ```
# 원격 서버에서: #### Step 2-2: 서비스 중지 및 백업
# ─────────────────────────────────────────────
# 2. 백업 생성 ```bash
sudo mkdir -p /var/www/quant_backup # 원격 서버에서 실행:
sudo cp -r /var/www/quant/publish \ set -e
/var/www/quant_backup/quant_$(date +%Y%m%d_%H%M%S)
echo "✓ 백업 생성 완료"
# 3. 배포 디렉토리 준비 SERVICE_NAME="quantengine"
sudo mkdir -p /var/www/quant/publish DEPLOY_PATH="/home/kjh2064/quantengine_active"
sudo chmod 777 /var/www/quant/publish BACKUP_PATH="/home/kjh2064/quantengine_backup"
BACKUP_NAME="quantengine_$(date +%Y%m%d_%H%M%S)"
# 4. 권한 설정 # 서비스 중지
sudo chown -R www-data:www-data /var/www/quant/publish sudo systemctl stop $SERVICE_NAME
sudo chmod -R 755 /var/www/quant/publish sleep 2
echo "✓ 서비스 중지"
# 5. SSH 종료 # 백업 생성
mkdir -p $BACKUP_PATH
if [ -d $DEPLOY_PATH ]; then
cp -r $DEPLOY_PATH "$BACKUP_PATH/$BACKUP_NAME"
echo "✓ 백업: $BACKUP_PATH/$BACKUP_NAME"
else
mkdir -p $DEPLOY_PATH
echo "⚠️ 첫 배포"
fi
```
#### Step 2-3: SSH 종료
```bash
exit exit
``` ```
#### Step 2-4: 파일 전송 (로컬에서)
```bash ```bash
# 로컬에서: 파일 전송
rsync -avz --delete \ rsync -avz --delete \
-e "ssh -i ~/.ssh/id_ed25519" \ -e "ssh -i ~/.ssh/id_ed25519" \
src/dotnet/QuantEngine.Web/publish/ \ src/dotnet/QuantEngine.Web/publish/ \
kjh2064@192.168.123.100:/var/www/quant/publish/ kjh2064@178.104.200.7:/home/kjh2064/quantengine_active/
``` ```
#### Step 2-5: 서비스 시작
```bash ```bash
# 다시 SSH 접속 ssh -i ~/.ssh/id_ed25519 kjh2064@178.104.200.7 << 'EOF'
ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100
# 원격 서버에서: SERVICE_NAME="quantengine"
# ───────────────────────────────────────────── DEPLOY_PATH="/home/kjh2064/quantengine_active"
# 6. nginx 재시작 # 파일 검증
sudo systemctl restart nginx if [ -f $DEPLOY_PATH/QuantEngine.Web.dll ]; then
echo "✓ 파일 확인됨"
else
echo "❌ 파일 없음"
exit 1
fi
# 7. 상태 확인 # 서비스 시작
sudo systemctl status nginx sudo systemctl start $SERVICE_NAME
sleep 3
# 종료 # 상태 확인
exit if sudo systemctl is-active --quiet $SERVICE_NAME; then
echo "✓ 서비스 시작됨"
else
echo "❌ 서비스 시작 실패"
exit 1
fi
EOF
``` ```
--- ---
## ✅ Step 4: 배포 검증 ## ✅ Step 4: 배포 검증
```bash ### HTTP 상태 확인
# 1. HTTP 상태 확인
curl -I http://178.104.200.7/quant/
# 또는
curl -I http://192.168.123.100/quant/
```bash
# 공인 IP로 접근 (외부 사용자 기준)
curl -I http://178.104.200.7/quant/
# 기대: HTTP/1.1 200 OK # 기대: HTTP/1.1 200 OK
# 2. MudBlazor 로드 확인 # localhost:5000 직접 확인 (서버에서)
ssh kjh2064@178.104.200.7 'curl -I http://127.0.0.1:5000/'
# 기대: HTTP/1.1 200 OK
```
### MudBlazor 리소스 확인
```bash
curl -s http://178.104.200.7/quant/ | grep -c "MudBlazor" curl -s http://178.104.200.7/quant/ | grep -c "MudBlazor"
# 기대: > 0 # 기대: > 0
```
# 3. 페이지 제목 확인 ### 페이지 제목 확인
```bash
curl -s http://178.104.200.7/quant/ | grep -o "<title>.*</title>" curl -s http://178.104.200.7/quant/ | grep -o "<title>.*</title>"
# 기대: <title>Quant Engine - Dashboard</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. 브라우저 테스트 ```bash
# http://178.104.200.7/quant/ 접속 # 서비스 로그
ssh kjh2064@178.104.200.7 'sudo journalctl -u quantengine -n 50'
# Nginx 에러 로그
ssh kjh2064@178.104.200.7 'sudo tail -f /var/log/nginx/error.log'
# 실시간 모니터링
ssh kjh2064@178.104.200.7 'sudo journalctl -u quantengine -f'
```
### 브라우저 테스트
```
http://178.104.200.7/quant/
``` ```
--- ---
## 🔄 롤백 (배포 실패 시) ## 🔄 롤백 (배포 실패 시)
### 자동 롤백 스크립트
```bash ```bash
ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100 << 'EOF' ssh kjh2064@178.104.200.7 << 'EOF'
# 최신 백업 확인 set -e
ls -lt /var/www/quant_backup/
# 최신 백업으로 복원 SERVICE_NAME="quantengine"
LATEST=$(ls -t /var/www/quant_backup | head -1) DEPLOY_PATH="/home/kjh2064/quantengine_active"
echo "복원 중: $LATEST" BACKUP_PATH="/home/kjh2064/quantengine_backup"
sudo cp -r /var/www/quant_backup/$LATEST/* /var/www/quant/publish/ echo "🔄 최신 백업 찾는 중..."
LATEST=$(ls -t $BACKUP_PATH | head -1)
echo "롤백 대상: $LATEST"
# 권한 재설정 # 서비스 중지
sudo chown -R www-data:www-data /var/www/quant/publish sudo systemctl stop $SERVICE_NAME
sudo chmod -R 755 /var/www/quant/publish sleep 2
# nginx 재시작 # 백업 복원
sudo systemctl restart nginx cp -r "$BACKUP_PATH/$LATEST"/* "$DEPLOY_PATH/"
echo "✓ 백업 복원 완료"
# 서비스 시작
sudo systemctl start $SERVICE_NAME
sleep 3
# 확인
if sudo systemctl is-active --quiet $SERVICE_NAME; then
echo "✅ 롤백 완료" echo "✅ 롤백 완료"
else
echo "❌ 롤백 실패"
exit 1
fi
EOF EOF
``` ```
@@ -229,26 +318,28 @@ EOF
``` ```
[ ] SSH 키 설정 완료 (~/.ssh/id_ed25519) [ ] SSH 키 설정 완료 (~/.ssh/id_ed25519)
[ ] SSH 연결 테스트 성공 [ ] SSH 연결 테스트 성공
[ ] Release 빌드 완료 (24MB) [ ] Release 빌드 완료 (24MB+)
[ ] 배포 스크립트 준비 [ ] 배포 스크립트 준비
``` ```
### 배포 중 ### 배포 중
``` ```
[ ] 환경 파악 완료 [ ] 환경 파악 완료
[ ] 백업 생성 완료 [ ] 서비스 중지 확인
[ ] 파일 전송 완료 [ ] 백업 생성 확인
[ ] 권한 설정 완료 [ ] 파일 전송 완료 (rsync)
[ ] nginx 재시작 완료 [ ] 파일 검증 완료
[ ] 서비스 시작 완료
``` ```
### 배포 후 ### 배포 후
``` ```
[ ] HTTP 200 OK 확인 [ ] HTTP 200 OK 확인
[ ] localhost:5000 응답 확인
[ ] MudBlazor 리소스 로드됨 [ ] MudBlazor 리소스 로드됨
[ ] 페이지 제목 확인 [ ] Nginx 에러 로그 확인
[ ] nginx 로그 에러 없음
[ ] 브라우저 접속 테스트 [ ] 브라우저 접속 테스트
[ ] 페이지 로드 시간 < 2s
``` ```
--- ---
@@ -257,46 +348,47 @@ EOF
### SSH 연결 타임아웃 ### SSH 연결 타임아웃
```bash ```bash
# 원인: IP 주소 오류 또는 방화벽 # 확인:
1. IP 주소: 178.104.200.7 또는 172.17.0.1?
2. SSH 포트: 22 (기본값)
3. 방화벽 규칙
4. 공개 키 등록 확인
# 해결: # 해결:
1. IP 확인: 178.104.200.7 또는 192.168.123.100? ssh-copy-id -i ~/.ssh/id_ed25519.pub kjh2064@178.104.200.7
2. SSH 포트 확인: 22 (기본값)
3. 방화벽 규칙 확인
4. 공개 키 등록 재확인
``` ```
### 권한 오류 (sudo 불가) ### 서비스 시작 실패
```bash
# 원인: sudo 권한 없음
# 확인:
sudo -l
# 해결: 관리자에게 webmaster 그룹 추가 요청
```
### nginx 재시작 실패
```bash ```bash
# 로그 확인 # 로그 확인
sudo systemctl status nginx ssh kjh2064@178.104.200.7 'sudo journalctl -u quantengine -n 50'
sudo journalctl -u nginx -n 20
# 설정 테스트 # 설정 확인
sudo nginx -t ssh kjh2064@178.104.200.7 'cat /etc/systemd/system/quantengine.service'
# 포트 충돌 확인 # 파일 검증
sudo netstat -tuln | grep :80 ssh kjh2064@178.104.200.7 'ls -la /home/kjh2064/quantengine_active/'
```
### Nginx 프록시 오류
```bash
# Nginx 설정 테스트
ssh kjh2064@178.104.200.7 'sudo nginx -t'
# 설정 파일 확인
ssh kjh2064@178.104.200.7 'cat /etc/nginx/sites-available/gitea-ip.conf'
# 포트 확인
ssh kjh2064@178.104.200.7 'sudo netstat -tuln | grep 5000'
``` ```
### 파일 권한 문제 ### 파일 권한 문제
```bash ```bash
# 현재 권한 확인 # 현재 권한 확인
ls -la /var/www/quant/publish/ ssh kjh2064@178.104.200.7 'ls -la /home/kjh2064/quantengine_active/'
# 권한 수정 # 권한 설정 (필요시)
sudo chown -R www-data:www-data /var/www/quant/publish ssh kjh2064@178.104.200.7 'chmod +x /home/kjh2064/quantengine_active/QuantEngine.Web.dll'
sudo chmod -R 755 /var/www/quant/publish
``` ```
--- ---
@@ -305,18 +397,21 @@ sudo chmod -R 755 /var/www/quant/publish
``` ```
배포 스크립트: 배포 스크립트:
├── deploy.sh (자동 배포, bash) ├── deploy-production.sh (권장)
└── deploy-manual.sh (대화형 배포, 이 파일) └── deploy-manual.sh (대화형)
배포 가이드: 배포 문서:
├── DEPLOYMENT_GUIDE.md (전체 가이드) ├── DEPLOYMENT_GUIDE.md (전체)
├── DEPLOYMENT_STEPS.md (단계별 지침) ├── DEPLOYMENT_STEPS.md (단계별)
├── DEPLOYMENT_CHECKLIST.md (운영 체크리스트) ├── DEPLOYMENT_SSH_GUIDE.md (이 파일)
└── DEPLOYMENT_SSH_GUIDE.md (이 파일) └── DEPLOYMENT_CHECKLIST.md (체크리스트)
CI/CD: CI/CD:
├── .gitea/workflows/deploy-prod.yml (자동화) ├── .gitea/workflows/deploy-prod.yml
└── CI_CD_PIPELINE.md (CI/CD 문서) └── CI_CD_PIPELINE.md
환경:
└── ENVIRONMENT_DIAGNOSIS.md
``` ```
--- ---
@@ -325,23 +420,31 @@ CI/CD:
### 한 번에 배포 ### 한 번에 배포
```bash ```bash
chmod +x deploy-manual.sh && ./deploy-manual.sh 192.168.123.100 chmod +x deploy-production.sh && ./deploy-production.sh
``` ```
### 내부 IP 사용 ### 내부 IP 사용 (선택)
```bash ```bash
# Gitea에서 배포할 때 (자동 CI/CD) ./deploy-manual.sh 172.17.0.1
DEPLOY_HOST=192.168.123.100
``` ```
### 외부 접속 ### 공인 IP 사용 (권장)
```bash ```bash
# 사용자가 접속할 때 ./deploy-manual.sh 178.104.200.7
http://178.104.200.7/quant/ ```
### 상태 확인
```bash
ssh kjh2064@178.104.200.7 'sudo systemctl status quantengine'
```
### 로그 모니터링
```bash
ssh kjh2064@178.104.200.7 'sudo journalctl -u quantengine -f'
``` ```
--- ---
**배포 준비 완료!** 🚀 **배포 준비 완료!** 🚀
deploy-manual.sh 스크립트를 실행하거나, 위의 수동 단계를 따라 배포하세요. `deploy-production.sh` 또는 `deploy-manual.sh` 스크립트를 실행하거나, 위의 수동 단계를 따라 배포하세요.