From 39000278ecf6330fa6e8dee8b74234ef3f04a6a6 Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Fri, 24 Jul 2026 16:00:41 +0900 Subject: [PATCH] docs: add comprehensive deployment guide in Korean MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 실제 파라미터와 정확한 절차를 한글로 설명: 1단계: Release 생성 (prepare-release.yml) - 파라미터: version (비워두기 또는 버전명 입력) - 결과: Release와 아티팩트 생성 2단계: 배포 실행 (deploy-prod.yml) - 파라미터: release (비워두기 또는 Release 버전 입력) - 결과: 운영 서버에 배포 + 자동 헬스 체크 롤백, 확인, 예시 시나리오 포함 Co-Authored-By: Claude Haiku 4.5 --- 배포_가이드.md | 182 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 배포_가이드.md diff --git a/배포_가이드.md b/배포_가이드.md new file mode 100644 index 00000000..e79ed7f3 --- /dev/null +++ b/배포_가이드.md @@ -0,0 +1,182 @@ +# QuantEngine 배포 가이드 (한글) + +## 현재 상태 +- ✅ 코드: 모두 커밋됨 +- ✅ 테스트: 214/214 통과 +- ✅ 워크플로우: 준비 완료 + +--- + +## 배포 방법 (2단계) + +### 📍 1단계: Release 생성 (prepare-release.yml) + +**목적:** 코드를 빌드하고 Release 버전을 만드는 단계 + +**URL 이동:** +``` +https://gitea.taxbaik.com/kjh2064/QuantEngineByItz/actions +``` + +**작업 절차:** +1. 위 URL에 접속 +2. 왼쪽 목록에서 "Prepare Release" 클릭 +3. 오른쪽 상단 "Run workflow" 버튼 클릭 +4. 팝업에서 파라미터 입력: + + **파라미터: version (버전 이름)** + - **의미:** 이 Release의 이름 + - **입력값:** + - **비워두기** (추천): 자동으로 `quant_20260724.0.xxxxx` 형태로 생성 + - **직접 입력**: `v0.1.20260724` 같이 원하는 이름 입력 + - **기본값:** (비어있음 = 자동 생성) + +5. "Run workflow" 클릭 +6. 실행 완료 대기 (약 5-10분) + +**완료 후:** +- ✅ 빌드 성공 +- ✅ Release 생성됨 +- ✅ Git 태그 생성됨 +- ✅ 아티팩트 업로드됨 + +--- + +### 📍 2단계: 배포 실행 (deploy-prod.yml) + +**목적:** 생성된 Release를 운영 서버에 배포하는 단계 + +**URL 이동:** +``` +https://gitea.taxbaik.com/kjh2064/QuantEngineByItz/actions +``` + +**작업 절차:** +1. 위 URL에 접속 +2. 왼쪽 목록에서 "Deploy to Production" 클릭 +3. 오른쪽 상단 "Run workflow" 버튼 클릭 +4. 팝업에서 파라미터 입력: + + **파라미터: release (배포할 Release 선택)** + - **의미:** 1단계에서 만든 Release 중 어떤 것을 배포할지 선택 + - **입력값:** + - **비워두기** (추천): 가장 최신 Release를 자동으로 배포 + - **직접 입력**: 1단계에서 생성된 버전명 + - 예: `v0.1.20260724` + - 예: `quant_20260724.0.abc1234` + - **기본값:** (비어있음 = 최신 Release 배포) + +5. "Run workflow" 클릭 +6. 실행 완료 대기 (약 3-5분) + +**자동으로 진행되는 작업:** +1. Release 아티팩트 다운로드 +2. SSH로 서버에 전송 +3. 서버에서 압축 해제 +4. 기존 서비스 중지 +5. 새 버전 배포 +6. 서비스 시작 +7. 자동 헬스 체크 (6가지 항목 검증) + +--- + +## 배포 후 확인 + +**웹에서 확인:** +``` +http://178.104.200.7/quantengine/Account/Login +계정: admin +암호: quant123! +``` + +**SSH로 상태 확인:** +```bash +ssh kjh2064@178.104.200.7 + +# 서비스 상태 확인 +systemctl status quantengine + +# 최근 로그 보기 (실시간) +journalctl -u quantengine -f + +# 배포된 버전 확인 +readlink ~/quantengine_active +``` + +--- + +## 문제 발생 시 롤백 + +**이전 버전으로 되돌리기:** + +```bash +ssh kjh2064@178.104.200.7 + +# 백업에서 복구 +ln -sfn $(readlink ~/quantengine_active_backup) ~/quantengine_active + +# 서비스 재시작 +sudo systemctl restart quantengine + +# 확인 +systemctl status quantengine +``` + +--- + +## 예시 시나리오 + +### ✅ 시나리오 1: 기본 배포 (추천) + +**1단계:** +- "Prepare Release" 실행 +- version 파라미터: **비워두기** ← 자동 생성 +- 대기 + +**2단계:** +- "Deploy to Production" 실행 +- release 파라미터: **비워두기** ← 최신 Release 배포 +- 대기 + +**결과:** 최신 코드가 운영 서버에 배포됨 + +### ✅ 시나리오 2: 특정 버전 배포 + +**1단계:** +- "Prepare Release" 실행 +- version 파라미터: `v0.1.20260724` 입력 +- 대기 → Release "v0.1.20260724" 생성됨 + +**2단계:** +- "Deploy to Production" 실행 +- release 파라미터: `v0.1.20260724` 입력 ← 위에서 생성한 버전 +- 대기 + +**결과:** 지정된 버전이 운영 서버에 배포됨 + +--- + +## 주의사항 + +⚠️ **반드시 순서대로!** +- 1단계(Prepare Release) 없이 2단계를 할 수 없음 +- 1단계 완료 후 2단계 실행 + +⚠️ **파라미터 입력** +- 오타 없이 정확히 입력 +- 존재하지 않는 버전을 입력하면 오류 발생 + +⚠️ **배포 중 중단 금지** +- 실행 중에는 중단하지 말 것 +- 전체 프로세스는 3-5분 소요 + +--- + +## 빠른 참조 + +| 단계 | Workflow | 파라미터 | 권장값 | +|------|----------|---------|-------| +| 1 | Prepare Release | version | (비워두기) | +| 2 | Deploy to Production | release | (비워두기) | + +**총 소요 시간:** 10-15분