🚀 [프로젝트 배포 후기] Next.js + FastAPI + MySQL 멀티 환경 배포 설계 & 장애 대응 기록
안녕하세요.
이번 글에서는 Aura AI 프로젝트를 실제 운영 가능한 구조로 배포하면서 설계한 아키텍처와, 배포 중 발생한 장애를 해결한 과정을 실무 관점에서 정리했습니다.
단순히 *“배포 성공”*이 아니라,
- 어떤 구조를 선택했는지
- 왜 그 선택이 합리적이었는지
- 실제 어떤 문제가 발생했는지
- 어떻게 해결했는지
위 4가지를 중심으로 작성했습니다.
👉 실서비스 운영을 가정한 배포/운영/장애 대응 경험 기록이라고 보시면 됩니다.
1️⃣ 배포 구조 개요 (실무 기준 아키텍처)
📌 사용 스택
Frontend
- Next.js
- NextAuth.js
- 배포: Vercel
Backend
- FastAPI + Uvicorn
- 배포: Amazon Web Services EC2 (Ubuntu)
Database
- MySQL
- EC2 내부 localhost 운영
📌 전체 아키텍처
Browser
↓
Vercel (Next.js)
↓
Proxy API (/api/proxy)
↓
EC2 FastAPI
↓
MySQL (localhost)
📌 이 구조를 선택한 이유
단순히 “편해서”가 아니라 운영 관점에서 다음 기준을 만족시키기 위해 선택했습니다.
✅ Vercel
- HTTPS 기본 제공
- CI/CD 자동화
- 프론트 배포 속도 빠름
✅ EC2
- 장시간 실행되는 백엔드/DB 운영에 적합
- 서버 리소스 직접 제어 가능
- 서버리스 대비 안정적
✅ 프론트/백엔드 분리
- 확장성 ↑
- 장애 격리 가능
- 유지보수 편리
👉 실무에서 가장 흔히 사용하는 “프론트 서버리스 + 백엔드 서버 분리” 구조를 그대로 채택했습니다.
2️⃣ 실제 배포 중 발생한 핵심 문제 & 해결 과정
문제 1️⃣ Mixed Content 오류
❌ 증상
- 로그인은 성공
- 그러나 사용자 정보 API 호출 실패
- 브라우저 콘솔: Mixed Content 에러
❌ 원인
Vercel → HTTPS
EC2 → HTTP
브라우저 정책상
👉 HTTPS 페이지에서 HTTP 요청은 보안상 차단됩니다.
✅ 해결 방법
Vercel 내부 Proxy API 도입
/api/proxy/*
구조 변경:
Browser → HTTPS → Vercel → HTTP → EC2
브라우저는 HTTPS만 인식하고,
Vercel이 내부에서 백엔드로 요청을 전달하도록 설계했습니다.
✅ 결과
✔ Mixed Content 완전 해결
✔ 프론트 API 주소 통일
✔ 서버 주소 변경 시 프록시만 수정하면 됨
👉 보안 + 유지보수성 동시 개선
문제 2️⃣ Vercel에서 MySQL 직접 접속 실패
❌ 증상
ECONNREFUSED 127.0.0.1:3306
NextAuth 로그인 실패
❌ 원인
Vercel은 서버리스 환경이므로
- 장기 DB 커넥션 유지 불가
- 내부 네트워크 접근 불가
- 로컬 MySQL 직접 연결 불가
즉, 구조적으로 DB 직결이 불가능
✅ 해결 방법
역할 재설계
담당역할
| Vercel | 인증/프록시 |
| FastAPI | DB 작업 전담 |
회원가입/유저 CRUD를 전부 백엔드로 이동했습니다.
✅ 결과
✔ 로그인/회원가입 정상 동작
✔ DB 접근 로직 백엔드 집중
✔ 보안/확장성/유지보수성 개선
👉 아키텍처 분리의 필요성을 체감한 케이스
문제 3️⃣ EC2 SSH 접속 불능
❌ 증상
SSH 접속 후 화면 멈춤
❌ 원인
- SSH 데몬 응답 불가
- 네트워크 일시 장애
✅ 해결
EC2 콘솔 → Reboot
필요 시:
systemctl restart ssh
✅ 결과
즉시 복구
👉 운영 환경에서 재부팅은 가장 빠른 해결책이라는 점을 경험
3️⃣ 배포 안정성 확보 — systemd 도입
초기에는 다음 방식으로 실행했습니다.
nohup uvicorn ...
문제점
- 터미널 종료 시 불안정
- 재부팅 시 자동 실행 안 됨
- 운영 환경에 부적합
✅ 개선 → systemd 서비스 등록
- 서버 부팅 시 자동 실행
- 장애 시 자동 재시작
- SSH 종료와 무관
👉 운영 서버 필수 설정
효과
✔ 항상 실행 상태 유지
✔ 다운타임 최소화
✔ 실서비스 수준 안정성 확보
4️⃣ 배포 과정에서 수정한 핵심 코드
✅ 프록시 라우트 (route.ts)
- Mixed Content 해결
- 서버측 통신 브릿지
✅ apiClient.ts
- API 주소 /api/proxy 통일
- FormData 업로드 자동 처리
✅ 회원가입 API
- Vercel → FastAPI 프록시 구조
✅ Swagger docs 대응
- openapi.json 프록시 처리
👉 “프론트는 통신만, 비즈니스 로직은 백엔드” 원칙 확립
5️⃣ 최종 배포 체크리스트
Vercel
NEXT_PUBLIC_API_BASE_URL=/api/proxy
EC2
systemctl status aura-api → active
ss -tlnp | grep 8000 → LISTEN
기능 테스트
- 회원가입
- 소셜 로그인
- 사용자 정보 조회
- 채팅 API
✅ 마무리 — 실무 관점에서 배운 점
이번 배포에서 가장 중요했던 것은 **“단순 실행”이 아니라 “운영 가능한 구조 설계”**였습니다.
✔ 핵심 개선 사항
- Mixed Content 해결
- 서버리스 ↔ DB 구조 분리
- systemd 자동 실행
- 장애 복구 프로세스 확보
🎯 결론
👉 단순 구현이 아닌
👉 실서비스 운영을 고려한 배포/아키텍처 설계 경험을 쌓을 수 있었습니다.
개인 프로젝트였지만,
실무 환경과 동일한 방식으로 설계/운영/장애 대응까지 진행했다는 점이 가장 큰 성과라고 생각합니다.
'코디챗봇 프로젝트' 카테고리의 다른 글
| [Aura_AI] [7편] GPT 호출 안정화 및 토큰 사용량 제한 설계 (0) | 2026.02.27 |
|---|---|
| [Aura_Ai] [7편] 서버오류 해결 (0) | 2026.02.25 |
| [Aura_Ai] [5편] 데이터 가공으로 UX 개선하기 (0) | 2026.02.02 |
| [Aura_Ai] [4편] GPT API를 활용한 서비스 설계 (0) | 2026.02.01 |
| [Aura_AI] [3편] OAuth만으로는 부족해서 자체 회원가입을 추가한 이유 (0) | 2026.01.23 |