f53d55e712
- 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>
173 lines
4.1 KiB
Markdown
173 lines
4.1 KiB
Markdown
# 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 초과 모니터링 |