docs(deploy): Update DEPLOYMENT_SSH_GUIDE.md with final environment configuration

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>
2026-06-25 18:24:01 +09:00
parent a2acaa70d8
commit d0bbb779c0
1 changed files with 246 additions and 143 deletions
@@ -1,7 +1,7 @@
-# 🔐 SSH 배포 가이드
+# 🔐 SSH 배포 가이드 (v9)

-**목표**: SSH로 원격 서버에 직접 접속하여 환경을 파악한 후 배포  
-**대상**: 178.104.200.7 (공인 IP) / 192.168.123.100 (내부 IP)
+**목표**: SSH로 원격 서버에 직접 접속하여 배포  
+**환경**: 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 공개 키를 원격 서버에 등록
 ```bash
 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 연결 테스트
 ```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: 환경 파악

-### 시스템 정보 확인
+### 원격 서버 정보 확인

 ```bash
-# SSH 접속
-ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100
-
-# 원격 서버에서 실행:
-# ─────────────────────────────────────────────
+ssh kjh2064@178.104.200.7 << 'EOF'

 # 1. 시스템 정보
+echo "=== 시스템 정보 ==="
+hostname
 uname -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

-# 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
+EOF
 ```

 ### 예상 환경

 ```
-✓ Linux (Ubuntu 20.04 또는 그 이상)
-✓ nginx (1.18 이상)
-✓ /var/www/quant/ 디렉토리 존재 또는 생성 가능
-✓ www-data 또는 유사 웹 서버 사용자
-✓ sudo 권한 (webmaster 그룹)
+✓ Linux (Ubuntu 20.04+)
+✓ nginx 1.28.3 (reverse proxy)
+✓ /home/kjh2064/quantengine_active/ 배포 경로
+✓ quantengine systemd 서비스
+✓ 포트 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 빌드

 ```bash
-# 로컬에서 실행
+# 로컬 개발 머신에서 실행
 cd /c/Temp/data_feed

 # Release 빌드
@@ -88,20 +111,21 @@ dotnet publish -c Release \

 # 결과 확인
 ls -lh src/dotnet/QuantEngine.Web/publish/
+du -sh src/dotnet/QuantEngine.Web/publish/
 ```

 ---

-## 🚀 Step 3: 배포 스크립트 실행
+## 🚀 Step 3: 배포 방법

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

 ```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
 ```
@@ -109,115 +133,180 @@ chmod +x deploy-manual.sh
 **스크립트가 자동으로:**
 - ✓ SSH 연결 확인
 - ✓ 원격 환경 파악
+- ✓ 서비스 중지
 - ✓ 백업 생성
 - ✓ 파일 전송 (rsync)
- ✓ 권한 설정
- ✓ nginx 재시작
+- ✓ 파일 검증
+- ✓ 서비스 시작
 - ✓ 헬스 체크

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

+#### Step 2-1: SSH 접속
+
 ```bash
-# 1. SSH 접속
-ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100
+ssh -i ~/.ssh/id_ed25519 kjh2064@178.104.200.7
+```

-# 원격 서버에서:
-# ─────────────────────────────────────────────
+#### Step 2-2: 서비스 중지 및 백업

-# 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 "✓ 백업 생성 완료"
+```bash
+# 원격 서버에서 실행:
+set -e

-# 3. 배포 디렉토리 준비
-sudo mkdir -p /var/www/quant/publish
-sudo chmod 777 /var/www/quant/publish
+SERVICE_NAME="quantengine"
+DEPLOY_PATH="/home/kjh2064/quantengine_active"
+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 chmod -R 755 /var/www/quant/publish
+# 서비스 중지
+sudo systemctl stop $SERVICE_NAME
+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
 ```

+#### Step 2-4: 파일 전송 (로컬에서)
+
 ```bash
-# 로컬에서: 파일 전송
 rsync -avz --delete \
  -e "ssh -i ~/.ssh/id_ed25519" \
  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
-# 다시 SSH 접속
-ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100
+ssh -i ~/.ssh/id_ed25519 kjh2064@178.104.200.7 << 'EOF'

-# 원격 서버에서:
-# ─────────────────────────────────────────────
+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: 배포 검증

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

+```bash
+# 공인 IP로 접근 (외부 사용자 기준)
+curl -I http://178.104.200.7/quant/
 # 기대: 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"
 # 기대: > 0
+```

-# 3. 페이지 제목 확인
+### 페이지 제목 확인
+
+```bash
 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/ 접속
+```bash
+# 서비스 로그
+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
-ssh -i ~/.ssh/id_ed25519 kjh2064@192.168.123.100 << 'EOF'
-# 최신 백업 확인
-ls -lt /var/www/quant_backup/
+ssh kjh2064@178.104.200.7 << 'EOF'
+set -e

-# 최신 백업으로 복원
-LATEST=$(ls -t /var/www/quant_backup | head -1)
-echo "복원 중: $LATEST"
+SERVICE_NAME="quantengine"
+DEPLOY_PATH="/home/kjh2064/quantengine_active"
+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 chmod -R 755 /var/www/quant/publish
+# 서비스 중지
+sudo systemctl stop $SERVICE_NAME
+sleep 2

-# nginx 재시작
-sudo systemctl restart nginx
+# 백업 복원
+cp -r "$BACKUP_PATH/$LATEST"/* "$DEPLOY_PATH/"
+echo "✓ 백업 복원 완료"

-echo "✅ 롤백 완료"
+# 서비스 시작
+sudo systemctl start $SERVICE_NAME
+sleep 3
+
+# 확인
+if sudo systemctl is-active --quiet $SERVICE_NAME; then
+  echo "✅ 롤백 완료"
+else
+  echo "❌ 롤백 실패"
+  exit 1
+fi
 EOF
 ```

@@ -229,26 +318,28 @@ EOF
 ```
 [ ] SSH 키 설정 완료 (~/.ssh/id_ed25519)
 [ ] SSH 연결 테스트 성공
-[ ] Release 빌드 완료 (24MB)
+[ ] Release 빌드 완료 (24MB+)
 [ ] 배포 스크립트 준비
 ```

 ### 배포 중
 ```
 [ ] 환경 파악 완료
-[ ] 백업 생성 완료
-[ ] 파일 전송 완료
-[ ] 권한 설정 완료
-[ ] nginx 재시작 완료
+[ ] 서비스 중지 확인
+[ ] 백업 생성 확인
+[ ] 파일 전송 완료 (rsync)
+[ ] 파일 검증 완료
+[ ] 서비스 시작 완료
 ```

 ### 배포 후
 ```
 [ ] HTTP 200 OK 확인
+[ ] localhost:5000 응답 확인
 [ ] MudBlazor 리소스 로드됨
-[ ] 페이지 제목 확인
-[ ] nginx 로그 에러 없음
+[ ] Nginx 에러 로그 확인
 [ ] 브라우저 접속 테스트
+[ ] 페이지 로드 시간 < 2s
 ```

 ---
@@ -257,46 +348,47 @@ EOF

 ### SSH 연결 타임아웃
 ```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?
-2. SSH 포트 확인: 22 (기본값)
-3. 방화벽 규칙 확인
-4. 공개 키 등록 재확인
+ssh-copy-id -i ~/.ssh/id_ed25519.pub kjh2064@178.104.200.7
 ```

-### 권한 오류 (sudo 불가)
-```bash
-# 원인: sudo 권한 없음
-
-# 확인:
-sudo -l
-
-# 해결: 관리자에게 webmaster 그룹 추가 요청
-```
-
-### nginx 재시작 실패
+### 서비스 시작 실패
 ```bash
 # 로그 확인
-sudo systemctl status nginx
-sudo journalctl -u nginx -n 20
+ssh kjh2064@178.104.200.7 'sudo journalctl -u quantengine -n 50'

-# 설정 테스트
-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
 # 현재 권한 확인
-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
-sudo chmod -R 755 /var/www/quant/publish
+# 권한 설정 (필요시)
+ssh kjh2064@178.104.200.7 'chmod +x /home/kjh2064/quantengine_active/QuantEngine.Web.dll'
 ```

 ---
@@ -305,18 +397,21 @@ sudo chmod -R 755 /var/www/quant/publish

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

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

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

 ---
@@ -325,23 +420,31 @@ CI/CD:

 ### 한 번에 배포
 ```bash
-chmod +x deploy-manual.sh && ./deploy-manual.sh 192.168.123.100
+chmod +x deploy-production.sh && ./deploy-production.sh
 ```

-### 내부 IP 사용
+### 내부 IP 사용 (선택)
 ```bash
-# Gitea에서 배포할 때 (자동 CI/CD)
-DEPLOY_HOST=192.168.123.100
+./deploy-manual.sh 172.17.0.1
 ```

-### 외부 접속
+### 공인 IP 사용 (권장)
 ```bash
-# 사용자가 접속할 때
-http://178.104.200.7/quant/
+./deploy-manual.sh 178.104.200.7
+```
+
+### 상태 확인
+```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` 스크립트를 실행하거나, 위의 수동 단계를 따라 배포하세요.