Initial commit: OAuth 2.0 인증 시스템 with APISIX API Gateway

- FastAPI 백엔드 + MongoDB + Redis 구성 - React + Vite + TypeScript + shadcn/ui 프론트엔드 - Apache APISIX API Gateway 통합 - Docker Compose 기반 개발 환경 - 3단계 권한 체계 (System Admin, Group Admin, User) - 동적 테마 지원 - 환경별 설정 (dev/vei/prod) 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-31 10:16:41 +09:00
commit f53d55e712
55 changed files with 6798 additions and 0 deletions
--- a/oauth/docs/apisix-guide.md
+++ b/oauth/docs/apisix-guide.md
@ -0,0 +1,173 @@
+# APISIX API Gateway 가이드
+
+## 개요
+Apache APISIX는 고성능 API Gateway로 OAuth 시스템의 모든 API 트래픽을 관리합니다.
+
+## 주요 기능
+
+### 1. API 라우팅
+```mermaid
+graph LR
+    Client[클라이언트] --> APISIX[APISIX Gateway]
+    APISIX --> |/api/v1/auth/*| Auth[인증 서비스]
+    APISIX --> |/api/v1/users/*| Users[사용자 서비스]
+    APISIX --> |/api/v1/applications/*| Apps[애플리케이션 서비스]
+    APISIX --> |/api/v1/admin/*| Admin[관리자 서비스]
+    APISIX --> |/*| Frontend[프론트엔드]
+```
+
+### 2. Rate Limiting 정책
+- **인증 API**: 10 req/s (burst: 20)
+- **사용자 API**: 100 req/s (burst: 50)
+- **애플리케이션 API**: 50 req/s (burst: 25)
+- **관리자 API**: 200 req/s (burst: 100)
+- **Health Check**: 1000 req/s (burst: 500)
+
+### 3. 보안 플러그인
+
+#### JWT 인증
+```yaml
+jwt-auth:
+  key: "user-key"
+  secret: "my-secret-key"
+  algorithm: "HS256"
+```
+
+#### IP 제한 (관리자 API)
+```yaml
+ip-restriction:
+  whitelist:
+    - 10.0.0.0/8
+    - 172.16.0.0/12
+    - 192.168.0.0/16
+```
+
+#### CORS 설정
+```yaml
+cors:
+  allow_origins: "*"
+  allow_methods: "GET,POST,PUT,DELETE,OPTIONS"
+  allow_headers: "*"
+  expose_headers: "*"
+```
+
+### 4. 캐싱 전략
+프론트엔드 정적 리소스에 대한 캐싱:
+- 캐시 크기: 메모리 50MB, 디스크 1GB
+- 캐시 TTL: 300초
+- 캐시 대상: GET, HEAD 요청
+- 캐시 상태 코드: 200, 301, 404
+
+## APISIX 대시보드
+
+### 접속 정보
+- URL: http://localhost:9000
+- 계정: admin / admin123
+
+### 주요 기능
+1. **라우트 관리**: API 라우팅 규칙 설정
+2. **업스트림 관리**: 백엔드 서비스 설정
+3. **플러그인 설정**: 보안, 캐싱, 모니터링 플러그인
+4. **모니터링**: 실시간 트래픽 모니터링
+
+## API 호출 예시
+
+### 1. Health Check
+```bash
+curl http://localhost:9080/health
+```
+
+### 2. 인증 API
+```bash
+# 로그인
+curl -X POST http://localhost:9080/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"password123"}'
+```
+
+### 3. 사용자 API (JWT 토큰 필요)
+```bash
+curl -X GET http://localhost:9080/api/v1/users/me \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+```
+
+### 4. 관리자 API (IP 제한 + JWT)
+```bash
+curl -X GET http://localhost:9080/api/v1/admin/users \
+  -H "Authorization: Bearer ADMIN_JWT_TOKEN"
+```
+
+## 프로메테우스 메트릭
+APISIX는 Prometheus 메트릭을 제공합니다:
+- Endpoint: http://localhost:9091/metrics
+- 주요 메트릭:
+  - `apisix_http_status`: HTTP 상태 코드별 요청 수
+  - `apisix_http_latency`: 요청 지연 시간
+  - `apisix_bandwidth`: 대역폭 사용량
+
+## 트러블슈팅
+
+### 1. etcd 연결 실패
+```bash
+# etcd 상태 확인
+docker-compose exec etcd etcdctl endpoint health
+
+# etcd 로그 확인
+docker-compose logs etcd
+```
+
+### 2. 라우트가 작동하지 않음
+```bash
+# APISIX Admin API로 라우트 확인
+curl http://localhost:9092/apisix/admin/routes
+```
+
+### 3. Rate Limiting 디버깅
+```bash
+# Rate limit 헤더 확인
+curl -i http://localhost:9080/api/v1/auth/login
+# X-RateLimit-Limit, X-RateLimit-Remaining 헤더 확인
+```
+
+## 성능 최적화
+
+### 1. 연결 풀 설정
+```yaml
+upstream:
+  keepalive: 320
+  keepalive_requests: 10000
+  keepalive_timeout: 60s
+```
+
+### 2. 캐시 최적화
+```yaml
+proxy-cache:
+  cache_zone:
+    memory_size: 100m  # 메모리 캐시 증가
+    disk_size: 5G      # 디스크 캐시 증가
+```
+
+### 3. 로드 밸런싱 알고리즘
+- `roundrobin`: 기본 라운드 로빈
+- `chash`: 일관된 해싱
+- `ewma`: 지수 가중 이동 평균
+
+## 보안 Best Practices
+
+1. **Admin API 보호**
+   - 프로덕션에서는 Admin API를 내부 네트워크에서만 접근 가능하도록 설정
+   - Admin Key를 환경 변수로 관리
+
+2. **SSL/TLS 설정**
+   - 프로덕션에서는 반드시 HTTPS 사용
+   - Let's Encrypt 또는 상용 인증서 적용
+
+3. **WAF 플러그인 활용**
+   - SQL Injection 방지
+   - XSS 공격 방지
+   - CSRF 토큰 검증
+
+4. **로그 모니터링**
+   - 비정상적인 트래픽 패턴 감지
+   - 실패한 인증 시도 추적
+   - Rate limit 초과 모니터링