QuantEngineByItz/CICD_ROADMAP.md

QuantEngine Gitea Actions CI/CD 개선 로드맵

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

---

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

1.0 근본적 아키텍처 개선: SSH 제거 → 로컬 배포

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

기술 변경:

# 이전 (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 자동 롤백 구현

• 효과: 배포 실패 시 이전 버전으로 자동 복구
• 구현:

  # 헬스체크 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 전략 변경

현재 문제점:

# 현재 (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

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

개선 방향:

# 개선 후 (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 배포 워크플로우 개선

변경 사항:

# 현재 (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 테스트 추가

# 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 기능 테스트 추가

- 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시간

---

🔍 모니터링 및 추적

배포 이력 조회 (원격 서버)

ssh kjh2064@178.104.200.7
cat ~/.config/quantengine_deploy_history.log | tail -20

최근 배포 정보

ls -lt /home/kjh2064/deployments/ | head -5
readlink -f /home/kjh2064/quantengine_active

서비스 상태 확인

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 사용하도록 변경

테스트

# 수동 배포 트리거
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
• 현재 워크플로우:
  • .gitea/workflows/deploy-prod.yml (개선됨)
  • .gitea/workflows/ci.yml (기존 Python 검증)
• 배포 스크립트: tools/deploy_quantengine.sh (개선됨)

---

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