Mail Auth Flow

인턴십에서 메일 서버를 다뤄본 경험에서 영감을 받아, 회원가입 인증 메일 기능을 개인적으로 구현해 보았습니다.

1. 프로젝트 개요

이 프로젝트는 FastAPI와 PostgreSQL을 사용하여 구현한 범용적인 이메일 인증 시스템입니다. 회원가입, 로그인, 비밀번호 재설정 기능을 포함하며, 실제 이메일 발송을 통한 인증 프로세스를 제공합니다.

로그인: JWT 토큰 기반 인증 회원가입: 이메일 인증을 통한 사용자 등록 이메일 인증: 6자리 인증 코드를 통한 이메일 검증

시스템 메일 발송: 관리자용 시스템 메일 발송 기능 비밀번호 재설정: 이메일을 통한 안전한 비밀번호 변경 재설정 완료: 새로운 비밀번호 설정

■ 기술 스택

• Backend: FastAPI, SQLAlchemy, PostgreSQL
• Email: Mailgun, SMTP (Gmail 지원)
• Authentication: JWT, bcrypt
• Database: PostgreSQL
• Deployment: Docker

■ 시스템 아키텍처

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Database      │
│   (React)       │◄──►│   (FastAPI)     │◄──►│   (PostgreSQL)  │
│   Port: 3000    │    │   Port: 8000    │    │   Port: 5432    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Email Service │    │   Redis Cache   │    │   Celery Queue  │
│   (SMTP/Mailgun)│    │   (Session)     │    │   (Background)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

2. API 엔드포인트

■ 인증 관련

• POST /auth/register - 회원가입
• POST /auth/login - 로그인
• POST /auth/verify-email - 이메일 인증 코드 확인
• POST /auth/resend-verification - 인증 코드 재발송

■ 비밀번호 재설정

• POST /auth/forgot-password - 비밀번호 재설정 요청
• POST /auth/reset-password - 비밀번호 재설정

■ 사용자 정보

• GET /auth/me - 현재 사용자 정보 조회
• PUT /auth/profile - 사용자 정보 수정

3. 설치 및 실행

■ 프로젝트 클론 및 의존성 설치

1. 프로젝트 클론

# 프로젝트 클론
git clone <repository-url>
cd mail-auth-flow

2. 백엔드 의존성 설치 (로컬 개발용)

# Python 가상환경 생성 (권장)
python -m venv venv

# 가상환경 활성화
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

# 의존성 설치
pip install -r requirements.txt

■ 데이터베이스 초기화

# 데이터베이스 마이그레이션 실행
docker-compose exec app alembic upgrade head

■ 백엔드 (Docker) 실행

# Docker Compose로 백엔드 서비스 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f

■ 프론트엔드 (로컬) 실행

# 프론트엔드 디렉토리로 이동
cd frontend

# 의존성 설치 (최초 1회)
npm install

# 개발 서버 실행
npm run dev

■ 접속 정보

• 프론트엔드: http://localhost:3000 (Vite HMR 지원)
• 백엔드 API: http://localhost:8000
• API 문서: http://localhost:8000/docs

4. 환경 설정

■ 백엔드 환경 변수

1. .env.example 파일을 .env로 복사

cp .env.example .env

2. .env 파일을 편집하여 실제 값으로 설정

# 데이터베이스
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/mail_auth_db

# JWT 설정
SECRET_KEY=your-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# 이메일 서비스 선택
EMAIL_SERVICE=smtp  # 또는 mailgun

# SMTP 설정 (Gmail 예시)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password

# Mailgun 설정
MAILGUN_DOMAIN=your-domain.mailgun.org
MAILGUN_API_KEY=your-mailgun-api-key

# 이메일 발송자 정보
FROM_EMAIL=your-email@gmail.com
FROM_NAME=Mail Auth System
APP_NAME=Mail Auth Flow

■ 프론트엔드 환경 변수

mail-auth-flow/frontend/.env 파일:

VITE_API_BASE_URL=http://localhost:8000

5. 테스트 및 부하테스트

■ Mock 이메일 모드 설정

1. .env 파일에서 Mock 이메일 모드 활성화

# 테스트 설정
MOCK_EMAIL=True

2. Mock 모드에서는 실제 이메일이 발송되지 않고 콘솔에 로그만 출력됩니다.

■ 메일 비동기 발송 부하테스트 실행

1. 기본 이메일 인증 발송 테스트 (20개 이메일 동시 발송)

python async_mail_load_test.py

2. 사용자 정의 부하테스트

# 50개 이메일 동시 발송
python async_mail_load_test.py --emails 50

# 점진적 부하테스트 (10개부터 100개까지)
python async_mail_load_test.py --stress --max-emails 100

■ 테스트 결과 예시

📊 이메일 인증 발송 테스트 결과:
✅ 성공: 100개
❌ 실패: 0개
⏱️  총 소요시간: 0.92초
📈 평균 응답시간: 0.679초
⚡ 최고 응답시간: 0.916초
🐌 최저 응답시간: 0.153초
🚀 초당 처리량: 108.12 requests/sec

■ 주의사항

• Mock 모드에서는 실제 이메일이 발송되지 않습니다
• 대량 테스트 시 Celery Worker와 Redis 성능을 고려하세요
• Flower에서 http://localhost:5555로 실시간 태스크 모니터링 가능
• 프로덕션 환경에서는 Mock 모드를 비활성화하세요

6. 보안 고려사항

• 비밀번호는 bcrypt로 해시화하여 저장
• JWT 토큰을 사용한 인증
• 이메일 인증 코드는 10분 후 자동 만료
• SQL Injection 방지를 위한 SQLAlchemy ORM 사용
• CORS 설정을 통한 보안 강화

7. 향후 개선 및 확장 방향

■ 보안 강화

• 다단계 인증 (MFA) 지원
• 로그인 시도 제한 (Rate Limiting)
• 소셜 로그인 (Google, GitHub) 연동

■ 기능 확장

• 관리자 대시보드
• 이메일 템플릿 관리
• 사용자 프로필 관리

■ 기술적 개선

• 성능 최적화 (캐싱, 쿼리 최적화)
• 모니터링 시스템 구축
• 테스트 커버리지 확장