works/oauth/docs/apisix-guide.md

APISIX API Gateway 가이드

개요

Apache APISIX는 고성능 API Gateway로 OAuth 시스템의 모든 API 트래픽을 관리합니다.

주요 기능

1. API 라우팅

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 인증

jwt-auth:
  key: "user-key"
  secret: "my-secret-key"
  algorithm: "HS256"

IP 제한 (관리자 API)

ip-restriction:
  whitelist:
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16

CORS 설정

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

curl http://localhost:9080/health

2. 인증 API

# 로그인
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 토큰 필요)

curl -X GET http://localhost:9080/api/v1/users/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

4. 관리자 API (IP 제한 + JWT)

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 연결 실패

# etcd 상태 확인
docker-compose exec etcd etcdctl endpoint health

# etcd 로그 확인
docker-compose logs etcd

2. 라우트가 작동하지 않음

# APISIX Admin API로 라우트 확인
curl http://localhost:9092/apisix/admin/routes

3. Rate Limiting 디버깅

# Rate limit 헤더 확인
curl -i http://localhost:9080/api/v1/auth/login
# X-RateLimit-Limit, X-RateLimit-Remaining 헤더 확인

성능 최적화

1. 연결 풀 설정

upstream:
  keepalive: 320
  keepalive_requests: 10000
  keepalive_timeout: 60s

2. 캐시 최적화

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 초과 모니터링