ci: 프론트 자동 배포 구현 (Nginx 정적호스팅, main push)

- deploy.yaml: dist 빌드 → SSH(tar)로 웹 루트 교체 → nginx reload
- deploy/nginx-sb-front.conf: SPA 폴백 + /api 프록시 샘플
- deploy/README.md: 시크릿·서버 준비 안내

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitea/workflows/deploy.yaml

@@ -1,12 +1,17 @@
-name: Deploy (manual)
+name: Deploy
 
-# 배포 대상이 정해지면 아래 단계의 주석을 풀고 시크릿을 등록하세요.
+# main 푸시 시 자동 배포: dist 빌드 → 서버 Nginx 루트로 업로드 → nginx reload
-# 저장소 Settings > Actions > Secrets 에 등록 필요:
+#
-#   DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_KEY, DEPLOY_PATH
+# 저장소 Settings > Actions > Secrets 에 등록:
+#   DEPLOY_HOST     배포 서버 호스트/IP
+#   DEPLOY_USER     SSH 계정 (nginx reload 무비밀번호 sudo 필요 — deploy/README.md 참고)
+#   DEPLOY_SSH_KEY  SSH 개인키 (PEM 전체)
+#   DEPLOY_PATH     Nginx 웹 루트 (예: /var/www/sb-front)
+#   DEPLOY_PORT     SSH 포트 (선택, 기본 22)
 on:
+  push:
+    branches: [main]
   workflow_dispatch: {}
-  # push:
-  #   tags: ['v*']
 
 jobs:
   deploy:
@@ -26,17 +31,31 @@ jobs:
           npm ci
           npm run build
 
-      # ===== 배포 예시 (택1) — 사용 시 주석 해제 =====
+      - name: Deploy to Nginx (SSH)
-      # 1) 정적 파일을 원격 서버로 rsync (Nginx 등 정적 호스팅)
+        env:
-      # - name: Deploy via SSH/rsync
+          DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
-      #   uses: appleboy/scp-action@v0.1.7
+          DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
-      #   with:
+          DEPLOY_PORT: ${{ secrets.DEPLOY_PORT }}
-      #     host: ${{ secrets.DEPLOY_HOST }}
+          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
-      #     username: ${{ secrets.DEPLOY_USER }}
+          DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
-      #     key: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
-      #     source: "dist/*"
+          set -euo pipefail
-      #     target: ${{ secrets.DEPLOY_PATH }}
+          PORT="${DEPLOY_PORT:-22}"
-      #     strip_components: 1
+          DEST="${DEPLOY_PATH:-}"
+          if [ -z "$DEST" ] || [ "$DEST" = "/" ]; then
+            echo "::error::DEPLOY_PATH 시크릿이 비어 있거나 잘못되었습니다."; exit 1
+          fi
 
-      - name: Notice
+          mkdir -p ~/.ssh && chmod 700 ~/.ssh
-        run: echo "dist 빌드 완료. 배포 대상 지정 후 위 단계를 활성화하세요."
+          printf '%s\n' "$DEPLOY_SSH_KEY" > ~/.ssh/id_deploy
+          chmod 600 ~/.ssh/id_deploy
+          ssh-keyscan -p "$PORT" "$DEPLOY_HOST" >> ~/.ssh/known_hosts 2>/dev/null
+          SSH="ssh -p $PORT -i $HOME/.ssh/id_deploy -o StrictHostKeyChecking=yes"
+
+          echo "Deploy dist/ -> $DEPLOY_USER@$DEPLOY_HOST:$DEST"
+          $SSH "$DEPLOY_USER@$DEPLOY_HOST" "mkdir -p '$DEST'"
+          # 기존 파일 정리 후 새 빌드 업로드 (tar 파이프 — 추가 의존성 없음)
+          tar -czf - -C dist . | $SSH "$DEPLOY_USER@$DEPLOY_HOST" "find '$DEST' -mindepth 1 -delete && tar -xzf - -C '$DEST'"
+          # Nginx 설정 검증 후 reload (실패해도 배포 자체는 유지)
+          $SSH "$DEPLOY_USER@$DEPLOY_HOST" "sudo nginx -t && sudo nginx -s reload" || echo "nginx reload 생략됨"
+          echo "✅ 배포 완료"

deploy/README.md

@@ -0,0 +1,39 @@
+# 프론트엔드 배포 (Nginx 정적 호스팅)
+
+`main` 푸시 시 [.gitea/workflows/deploy.yaml](../.gitea/workflows/deploy.yaml) 가
+`dist` 를 빌드해 서버 Nginx 웹 루트로 업로드하고 nginx 를 reload 합니다.
+
+## 1. Gitea 저장소 시크릿 (Settings → Actions → Secrets)
+| 시크릿 | 설명 | 예시 |
+|---|---|---|
+| `DEPLOY_HOST` | 서버 호스트/IP | `10.0.0.5` |
+| `DEPLOY_USER` | SSH 계정 | `deploy` |
+| `DEPLOY_SSH_KEY` | SSH 개인키(PEM 전체) | `-----BEGIN OPENSSH PRIVATE KEY-----...` |
+| `DEPLOY_PATH` | Nginx 웹 루트 | `/var/www/sb-front` |
+| `DEPLOY_PORT` | SSH 포트(선택) | `22` |
+
+## 2. 서버 1회 준비
+```bash
+sudo apt-get install -y nginx
+sudo mkdir -p /var/www/sb-front && sudo chown deploy:deploy /var/www/sb-front
+
+# Nginx 서버블록 설치 (deploy/nginx-sb-front.conf 참고)
+sudo cp deploy/nginx-sb-front.conf /etc/nginx/sites-available/sb-front
+sudo ln -sf /etc/nginx/sites-available/sb-front /etc/nginx/sites-enabled/sb-front
+sudo nginx -t && sudo systemctl reload nginx
+
+# deploy 계정에 nginx 검증/reload 무비밀번호 sudo 허용
+echo 'deploy ALL=(root) NOPASSWD: /usr/sbin/nginx -t, /usr/sbin/nginx -s reload' \
+  | sudo tee /etc/sudoers.d/sb-front
+
+# 러너 공개키를 deploy 계정 authorized_keys 에 등록 (백엔드와 동일 키 사용 가능)
+```
+
+## 3. 동작
+- main 푸시 → CI(빌드) + Deploy(빌드·업로드·reload) 가 각각 실행
+- 업로드는 웹 루트를 비우고 새 `dist` 로 교체 (해시 자산명이라 안전)
+- 수동 배포: 저장소 Actions → Deploy → Run workflow
+
+## 참고
+- API 는 같은 도메인의 `/api/` 로 Nginx 가 백엔드(8080)에 프록시합니다.
+  별도 도메인/포트로 띄운다면 빌드시 `VITE_API_BASE_URL` 환경변수를 지정하세요.

deploy/nginx-sb-front.conf

@@ -0,0 +1,28 @@
+# /etc/nginx/sites-available/sb-front  (심볼릭 링크로 sites-enabled 에 연결)
+server {
+    listen 80;
+    server_name _;            # 도메인으로 교체
+
+    root /var/www/sb-front;   # DEPLOY_PATH 와 동일
+    index index.html;
+
+    # SPA: 새로고침/직접 진입 시 index.html 로 폴백 (vue-router history 모드)
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # 해시 자산 장기 캐시
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # API 프록시 → 백엔드(8080)
+    location /api/ {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}