KArtSell.Aegis/docs/CI_CD_AUTO_DEPLOYMENT_SETUP.md

CI/CD 자동 배포 설정 가이드

K-ArtSell Aegis v16.0 - Gitea CI/CD 자동 배포

---

📋 개요

Gitea Actions 워크플로우가 자동 배포를 처리합니다.

Git Push (main) 
  → Build Stage (backend + frontend)
  → Deploy Stage (production server)
  → Verify Stage (health checks)
  → LIVE ✅

총 소요: ~8분 (완전 자동)

---

🔐 Step 1: SSH 키 생성

프로덕션 서버에 SSH로 배포하기 위해 SSH 키 쌍을 생성합니다.

로컬에서 (개발 머신)

ssh-keygen -t ed25519 -f kartsell-deploy -N ""

결과:

• kartsell-deploy (private key)
• kartsell-deploy.pub (public key)

프로덕션 서버에 공개 키 등록

# 프로덕션 서버에 SSH로 접속
ssh user@production-server.com

# ~/.ssh 디렉토리 확인
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# 공개 키 추가
cat >> ~/.ssh/authorized_keys << 'EOF'
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... (kartsell-deploy.pub 내용)
EOF

chmod 600 ~/.ssh/authorized_keys

---

🔑 Step 2: Gitea Secrets 설정

저장소 Settings → Actions Secrets에 다음을 추가합니다:

1. DEPLOY_HOST

프로덕션 서버 호스트명

production-server.com
또는
192.168.1.100

2. DEPLOY_USER

배포 사용자명

deploy
또는 다른 ssh 사용자

3. DEPLOY_SSH_KEY

SSH 개인 키 (전체 내용)

-----BEGIN OPENSSH PRIVATE KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC...
(kartsell-deploy 파일의 전체 내용)
-----END OPENSSH PRIVATE KEY-----

Gitea에서 설정하기

1. 저장소 페이지 접속
2. Settings → Actions (또는 CI/CD)
3. Secrets 탭
4. Add Secret 클릭
5. 위 3개 값 추가

---

🖥️ Step 3: 프로덕션 서버 준비

디렉토리 생성

sudo mkdir -p /opt/kartsell
sudo mkdir -p /var/www/kartsell/frontend
sudo mkdir -p /var/log/nginx

sudo chown kartsell:kartsell /opt/kartsell
sudo chown www-data:www-data /var/www/kartsell/frontend

Systemd 서비스 파일

파일: /etc/systemd/system/kartsell-api.service

[Unit]
Description=K-ArtSell API Service
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=kartsell
Group=kartsell
WorkingDirectory=/opt/kartsell/
ExecStart=/opt/kartsell/KArtSell.Host
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

# Environment
Environment="ASPNETCORE_ENVIRONMENT=Production"
Environment="ASPNETCORE_URLS=http://localhost:5002"
Environment="KARTSELL_POSTGRES=Host=db.internal;Port=5432;Database=kartsell;Username=kartsell;Password=kartsell"

[Install]
WantedBy=multi-user.target

Systemd 활성화

sudo systemctl daemon-reload
sudo systemctl enable kartsell-api.service
sudo systemctl status kartsell-api.service

SSL/TLS 인증서 준비

Let's Encrypt 또는 다른 CA에서 인증서를 발급받습니다:

# Let's Encrypt (Certbot 사용)
sudo apt install certbot python3-certbot-nginx
sudo certbot certonly --nginx -d kartsell.taxbaik.com

# 인증서 위치 확인
ls -la /etc/letsencrypt/live/kartsell.taxbaik.com/

---

🚀 Step 4: 워크플로우 확인

1. 워크플로우 파일 확인

cat .gitea/workflows/deploy.yml

2. main 브랜치에 push

git add .
git commit -m "Ready for auto-deployment"
git push origin main

3. Gitea Actions에서 모니터링

저장소 → Actions 탭에서 진행 상황 확인

Workflow: Auto Deploy to Production
├─ Build (backend + frontend) ✅
├─ Deploy (SSH to production) ✅
├─ Verify (health checks) ✅
└─ Monitor (Phase 1 status) ✅

---

📊 워크플로우 상세

Build Stage

1. .NET 10 SDK 설정
2. Backend 빌드 (Release mode)
3. Backend 테스트 (217/217)
4. Backend 퍼블리시 → /publish/
5. Node.js + pnpm 설정
6. Frontend 빌드 (Production)
7. Frontend 테스트 (40/40)
8. Frontend 빌드 → /frontend/dist/
9. 아티팩트 업로드

예상 시간: 3-5분

Deploy Stage

1. 아티팩트 다운로드
2. SSH 키 설정
3. Backend 파일 복사 → /opt/kartsell/
4. Frontend 파일 복사 → /var/www/kartsell/frontend/
5. Nginx 설정 자동 생성
6. Nginx 재로드
7. 서비스 재시작
8. 헬스 체크 (frontend + API)

예상 시간: 2-3분

---

✅ 배포 후 확인

프로덕션 서버에서

# 서비스 상태
sudo systemctl status kartsell-api.service

# 로그 확인
sudo journalctl -u kartsell-api.service -f

# Nginx 상태
sudo systemctl status nginx

클라이언트에서

# Frontend
curl https://kartsell.taxbaik.com/
# Expected: 200 OK (HTML)

# API
curl https://kartsell.taxbaik.com/api/health
# Expected: 200 OK (JSON)

# Full API
curl https://kartsell.taxbaik.com/api/internal/v1/model-operations/plan
# Expected: 200 OK (data)

---

🔄 롤백 절차

만약 배포 후 문제가 발생하면:

1. 이전 버전 복원

# 프로덕션 서버에서
cd /opt/kartsell/

# 백업에서 복원 (또는 이전 릴리스 다운로드)
git clone <repo-url> --branch <previous-tag> ./previous-release

cp -r ./previous-release/* ./
sudo systemctl restart kartsell-api.service

2. 데이터베이스 마이그레이션 롤백

# 필요한 경우만
dotnet run --project src/KArtSell.DbMigrator -- --rollback

3. 다시 배포

git push origin main  # 수정된 코드 push
# 워크플로우가 자동으로 다시 배포

---

🛡️ 보안 최고 사례

✅ 안전한 관행

• SSH 키는 절대 코드에 저장하지 않음
• Secrets는 마스킹됨 (로그에 표시 안 됨)
• 최소 권한 원칙 (deploy 사용자는 필요한 디렉토리만 접근)
• 헬스 체크로 나쁜 배포 방지

✅ 구성 관리

• 환경 변수는 systemd 서비스 파일에서 관리
• 민감 정보는 secrets 저장소 사용
• SSL 인증서는 자동 갱신 설정 (Certbot)

✅ 모니터링

• 배포 후 헬스 체크
• Nginx 및 API 로그 모니터링
• 서비스 자동 재시작 (systemd Restart=on-failure)

---

🔧 문제 해결

SSH 접속 실패

# 1. 공개 키 확인
cat kartsell-deploy.pub

# 2. 프로덕션 서버에서 authorized_keys 확인
grep -i "ssh-ed25519" ~/.ssh/authorized_keys

# 3. 권한 확인
ls -la ~/.ssh/
# authorized_keys: 600
# .ssh: 700

배포 실패 (NGINX 설정)

# 프로덕션 서버에서
sudo nginx -t
sudo systemctl reload nginx

# 로그 확인
sudo tail -f /var/log/nginx/error.log

서비스 시작 실패

# 프로덕션 서버에서
sudo systemctl status kartsell-api.service
sudo journalctl -u kartsell-api.service -n 50

포트 충돌

# 포트 5002 확인
sudo netstat -tulpn | grep 5002

# 기존 프로세스 종료
sudo lsof -i :5002
sudo kill -9 <PID>

---

📅 배포 일정

자동 배포 트리거

• push to main: 자동 배포
• PR merge to main: 자동 배포
• Manual trigger: Actions에서 "Run workflow" 클릭

배포 스케줄 (선택사항)

# .gitea/workflows/deploy.yml에 추가
schedule:
  - cron: '0 2 * * *'  # 매일 02:00 UTC에 배포

---

🎯 다음 단계

즉시 (지금)

1. ✅ SSH 키 생성
2. ✅ Gitea Secrets 설정
3. ✅ 프로덕션 서버 준비
4. ✅ main에 push (배포 시작)

배포 후

1. ✅ Actions 탭에서 진행 상황 모니터링
2. ✅ ~8분 후 서비스 LIVE
3. ✅ 헬스 체크 확인
4. ✅ Phase 1 자동 모니터링 계속

진행 중

• Phase 1: 자동 실행 (50-90일)
• Phase 2: 배포 완료 ✅
• Phase 3-4: Phase 1 완료 후 자동 트리거

---

📞 지원

Gitea Actions 문서

• https://docs.gitea.com/usage/actions/

SSH 키 생성 문서

• https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent

Systemd 서비스 문서

• https://www.freedesktop.org/software/systemd/man/systemd.service.html

---

CI/CD 자동 배포 설정 완료!

다음 push에서 자동 배포가 시작됩니다. 🚀