QuantEngineByItz/docs/archive/CICD_ROADMAP.md

> **ARCHIVED (2026-07-30)**: 본 문서의 CI/CD 로드맵은 2026-07-11 이후 구현 완료되었습니다.  
> 현재 CI/CD 가이드는 [`docs/CICD_PIPELINE.md`](docs/CICD_PIPELINE.md) 및  
> [`docs/DEPLOYMENT_RUNBOOK.md`](docs/DEPLOYMENT_RUNBOOK.md)을 참고하세요.

# QuantEngine Gitea Actions CI/CD 개선 로드맵

**최종 목표**: 신뢰성 높은 자동화된 배포 파이프라인 구축

---

## ✅ Phase 1 완료 (2026-07-11 커밋: 0d8e3a6)

### 1.0 근본적 아키텍처 개선: SSH 제거 → 로컬 배포
- **문제점 (이전)**: Gitea Actions이 로컬 서버에서 실행되는데 같은 서버로 SSH 배포 ❌
- **해결책**: SSH 제거, 로컬 파일 시스템에 직접 배포 ✅
- **효과**:
  - 배포 시간 1-2분 단축
  - 네트워크 장애 영향 제거
  - 코드 복잡도 60줄 감소
  - 신뢰성 향상

**기술 변경**:
```bash
# 이전 (SSH)
ssh user@host "tar -xzf ... && systemctl restart"

# 현재 (로컬)
tar -xzf ... 
ln -sfn /deployments/new /active
systemctl restart quantengine
```

### 1.1 타임아웃 확대 (15분 → 30분)
- **효과**: 네트워크 지연 및 재시도 시 안정성 향상
- **변경**: `.gitea/workflows/deploy-prod.yml` line 28

### 1.2 자동 롤백 구현
- **효과**: 배포 실패 시 이전 버전으로 자동 복구
- **구현**:
  ```bash
  # 헬스체크 3회 연속 실패 → 이전 버전으로 자동 복구
  if [ $health_check_passed -eq 0 ]; then
    PREV_DEPLOY=$(ls -dt /home/kjh2064/deployments/quantengine_* | head -2 | tail -1)
    ln -sfn ${PREV_DEPLOY} /home/kjh2064/quantengine_active
    sudo systemctl restart quantengine
  fi
  ```
- **장점**:
  - 배포 실패 대응 자동화
  - 수동 개입 최소화
  - Telegram 알림 자동 발송

### 1.3 헬스체크 강화
- **데이터베이스 연결 검증** 추가
- **서비스 상태 확인** 강화
- **Favicon 검증** 경고로 변경 (선택사항)

### 1.4 배포 이력 추적
- **로그 파일**: `/home/kjh2064/.config/quantengine_deploy_history.log`
- **기록 내용**:
  ```
  TIMESTAMP=20260711_175640
  COMMIT=96cc7fc
  DEPLOY_PATH=/home/kjh2064/deployments/quantengine_20260711_175640
  PREV_VERSION=20260711_170421
  STATUS=success
  DEPLOYED_AT=2026-07-11T17:56:40Z
  ```
- **용도**: 배포 이력 추적, 빠른 롤백 결정

---

## 📋 Phase 2 계획 (빌드/배포 분리)

### 2.1 별도 빌드 워크플로우 생성 (**새로운 파일**: `.gitea/workflows/build.yml`)

**특징**:
- 빌드 결과를 Gitea Releases로 발행
- 빌드 메타데이터 (커밋, 타임스탐프) 포함
- 배포 시점에 빌드 재사용

**효과**:
```
이전 (현재):
  push → 빌드 → 테스트 → 배포 (한 번에)
  
개선 후:
  push → 빌드 (별도) → 배포 (독립적)
  └─ 같은 빌드를 여러 번 배포 가능
  └─ 빌드 아티팩트 재사용 → 속도 ↑
```

### 2.2 `appsettings.Production.json` 전략 변경

**현재 문제점**:
```yaml
# 현재 (deploy-prod.yml)
- name: Publish Release Package
  run: dotnet publish ... -o ./publish

- name: Prepare & Validate DB Env  # 배포 시점에 생성
  run: |
    cat > ./publish/appsettings.Production.json << EOF
    {
      "ConnectionStrings": {
        "DefaultConnection": "Host=127.0.0.1;Database=${{ env.QUANTENGINE_DB_NAME }};..."
      }
    }
    EOF
```

**문제**: 빌드와 배포 사이에 설정이 동적으로 변경됨

**개선 방향**:
```yaml
# 개선 후 (build.yml)
- name: Generate Configuration Template
  run: |
    cat > ./publish/appsettings.Production.json.template << EOF
    {
      "ConnectionStrings": {
        "DefaultConnection": "Host={DB_HOST};Database={DB_NAME};Username={DB_USER};..."
      }
    }
    EOF

# 배포 시점에 (deploy-prod.yml)
- name: Inject Secrets at Deploy Time
  run: |
    envsubst < appsettings.Production.json.template > appsettings.Production.json
```

**효과**:
- ✅ 빌드 시점 고정 (재현 가능)
- ✅ 배포 시점에만 secrets 주입
- ✅ "같은 빌드 → 같은 배포" 보장

### 2.3 배포 워크플로우 개선

**변경 사항**:
```yaml
# 현재 (deploy-prod.yml)
- name: Setup .NET
  ... (시간 낭비)

- name: Build Release
  ... (빌드 반복)

# 개선 후
- name: Download Build Artifact
  run: |
    curl -L -o quantengine.tar.gz \
      https://gitea.taxbaik.com/api/v1/repos/.../releases/download/build-${COMMIT}/quantengine-${COMMIT}.tar.gz
```

**효과**:
- 빌드 시간 제거 (5-10분 단축)
- 배포 속도 ↑↑

---

## 🎯 Phase 3 계획 (E2E 검증 강화)

### 3.1 로그인 기능 E2E 테스트 추가

```bash
# deploy-prod.yml에 추가
- name: E2E Login Test
  run: |
    # 1. 로그인 시도
    LOGIN_RESULT=$(curl -s -c /tmp/cookies.txt \
      -X POST "https://quant.taxbaik.com/Account/Login" \
      -d "username=${{ secrets.ADMIN_USERNAME }}" \
      -d "password=${{ secrets.ADMIN_PASSWORD }}" \
      -o /dev/null -w "%{http_code}")

    # 2. 성공 확인
    if [ "$LOGIN_RESULT" = "302" ] || [ "$LOGIN_RESULT" = "200" ]; then
      echo "✓ Login test passed"
    else
      echo "❌ Login test failed: $LOGIN_RESULT"
      exit 1
    fi

    # 3. 인증 상태 확인
    DASHBOARD=$(curl -s -b /tmp/cookies.txt \
      "https://quant.taxbaik.com/Admin/Dashboard" \
      -o /dev/null -w "%{http_code}")

    if [ "$DASHBOARD" = "200" ]; then
      echo "✓ Dashboard accessible"
    else
      echo "❌ Dashboard access failed: $DASHBOARD"
      exit 1
    fi
```

### 3.2 API 기능 테스트 추가

```bash
- name: E2E API Test
  run: |
    # Collection API 상태 확인
    API_RESULT=$(curl -s -b /tmp/cookies.txt \
      "https://quant.taxbaik.com/api/collection/state" \
      -H "Content-Type: application/json" \
      -o /dev/null -w "%{http_code}")

    if [ "$API_RESULT" = "200" ]; then
      echo "✓ API endpoint responding"
    else
      echo "❌ API test failed: $API_RESULT"
      exit 1
    fi
```

---

## 📊 구현 우선순위 및 영향도

| 우선 | Phase | 항목 | 난이도 | 효과 | 예상 소요 |
|------|-------|------|--------|------|----------|
| 1️⃣ | 1 | 타임아웃 확대 | ⭐ | 즉시 안정성 ↑ | 5분 |
| 2️⃣ | 1 | 자동 롤백 | ⭐⭐ | 배포 실패 대응 | 30분 |
| 3️⃣ | 1 | 헬스체크 강화 | ⭐⭐ | 검증 확실성 | 20분 |
| 4️⃣ | 1 | 배포 이력 추적 | ⭐⭐ | 운영 가시성 | 15분 |
| 5️⃣ | 2 | 빌드 분리 | ⭐⭐⭐ | 속도 ↑↑ + 일관성 | 2시간 |
| 6️⃣ | 3 | 로그인 E2E | ⭐⭐⭐ | 기능 검증 | 1시간 |

---

## 🔍 모니터링 및 추적

### 배포 이력 조회 (원격 서버)
```bash
ssh kjh2064@178.104.200.7
cat ~/.config/quantengine_deploy_history.log | tail -20
```

### 최근 배포 정보
```bash
ls -lt /home/kjh2064/deployments/ | head -5
readlink -f /home/kjh2064/quantengine_active
```

### 서비스 상태 확인
```bash
sudo systemctl status quantengine
sudo journalctl -u quantengine -f
```

---

## ✨ 기대 효과

### 배포 신뢰성 향상
- **이전**: 배포 실패 시 수동 대응 (15-30분 소요)
- **현재**: 자동 롤백 + 알림 (1-2분)

### 배포 속도 개선 (Phase 2)
- **이전**: 빌드 5-10분 + 배포 2-3분 = 7-13분
- **현재**: 빌드 분리 + 아티팩트 재사용 = 2-3분

### 운영 가시성 향상
- **배포 이력 추적**: 언제, 어떤 버전, 누가 배포했는지
- **빠른 롤백**: 이전 버전으로 즉시 복구 가능
- **근본 원인 분석**: 로그를 통한 배포 실패 원인 파악

---

## 다음 액션 (사용자)

### Phase 2 적용하기
1. `.gitea/workflows/build.yml` 파일 검토 및 조정
2. `deploy-prod.yml` 수정하여 빌드 아티팩트 다운로드 로직 추가
3. GitHub Releases API 대신 Gitea Releases API 사용하도록 변경

### 테스트
```bash
# 수동 배포 트리거
curl -X POST https://gitea.taxbaik.com/api/v1/repos/kjh2064/QuantEngineByItz/actions/workflows/deploy-prod.yml/dispatches \
  -H "Authorization: token ${GITEA_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"ref":"main", "inputs":{"release_tag":"build-96cc7fc"}}'
```

### 모니터링
- Telegram 알림 확인
- 배포 이력 로그 검증
- 이전 버전 롤백 테스트 (스테이징 환경)

---

## 참고 자료

- **분석 문서**: [gitea_cicd_analysis.md](https://claude.ai/code/artifact/9b62fb29-6438-4cd3-80a4-3593c7057eb5)
- **현재 워크플로우**:
  - `.gitea/workflows/deploy-prod.yml` (개선됨)
  - `.gitea/workflows/ci.yml` (기존 Python 검증)
- **배포 스크립트**: `tools/deploy_quantengine.sh` (개선됨)

---

**작성일**: 2026-07-11  
**상태**: Phase 1 ✅ 완료, Phase 2 📋 계획 중, Phase 3 📋 계획 중