diff --git a/README.md b/README.md index c47a16e..dbc6a0e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,390 @@ -# works +# OAuth 2.0 인증 시스템 프로젝트 -aimond.io 에서 서비스할 대상 시스템의 프로토타입을 구성해 봅니다. \ No newline at end of file +> aimond.io 에서 서비스할 대상 시스템의 프로토타입을 구성합니다. + +## 📋 목차 +- [프로젝트 개요](#프로젝트-개요) +- [시스템 아키텍처](#시스템-아키텍처) +- [기술 스택](#기술-스택) +- [서비스 구성](#서비스-구성) +- [빠른 시작](#빠른-시작) +- [개발 가이드](#개발-가이드) +- [API 문서](#api-문서) +- [배포 가이드](#배포-가이드) +- [문서](#문서) + +## 🎯 프로젝트 개요 + +엔터프라이즈급 OAuth 2.0 기반 중앙 인증 시스템으로, 멀티 테넌트 환경에서 동적 테마 적용 및 세분화된 권한 관리를 제공합니다. + +### 주요 특징 +- ✅ **OAuth 2.0 표준 준수**: 완벽한 OAuth 2.0 플로우 구현 +- ✅ **동적 테마 시스템**: 애플리케이션별 맞춤형 인증 페이지 +- ✅ **3단계 권한 체계**: System Admin, Group Admin, User +- ✅ **API Gateway**: Apache APISIX를 통한 트래픽 관리 +- ✅ **마이크로서비스 아키텍처**: 확장 가능한 서비스 구조 +- ✅ **컨테이너 기반**: Docker를 통한 일관된 개발/운영 환경 + +## 🏗️ 시스템 아키텍처 + +```mermaid +graph TB + subgraph "Client Layer" + Browser[사용자 브라우저] + Mobile[모바일 앱] + API[API 클라이언트] + end + + subgraph "API Gateway Layer" + APISIX[Apache APISIX
Rate Limiting
Authentication
Load Balancing] + etcd[etcd
Service Discovery] + end + + subgraph "Application Services" + OAuth[OAuth Service
FastAPI] + Frontend[Web Frontend
React + Vite] + end + + subgraph "Data Layer" + MongoDB[(MongoDB
Users/Apps/History)] + Redis[(Redis
Cache/Session)] + end + + Browser --> APISIX + Mobile --> APISIX + API --> APISIX + APISIX <--> etcd + APISIX --> OAuth + APISIX --> Frontend + OAuth --> MongoDB + OAuth --> Redis +``` + +## 🛠️ 기술 스택 + +### API Gateway +- **Apache APISIX 3.8.0**: 고성능 API Gateway +- **etcd 3.5**: 서비스 디스커버리 및 설정 관리 + +### Backend +- **Python 3.11**: 메인 프로그래밍 언어 +- **FastAPI**: 고성능 웹 프레임워크 +- **Motor**: MongoDB 비동기 드라이버 +- **Authlib**: OAuth 2.0 구현 +- **Celery**: 비동기 작업 처리 + +### Frontend +- **React 18**: UI 라이브러리 +- **Vite**: 빌드 도구 +- **TypeScript**: 타입 안정성 +- **shadcn/ui**: UI 컴포넌트 +- **Tailwind CSS**: 유틸리티 CSS +- **Zustand**: 상태 관리 +- **React Query**: 서버 상태 관리 + +### Database & Cache +- **MongoDB 7.0**: 메인 데이터베이스 +- **Redis 7**: 캐싱 및 세션 관리 + +### DevOps +- **Docker & Docker Compose**: 컨테이너화 +- **Kubernetes**: 프로덕션 오케스트레이션 +- **Nexus**: 아티팩트 저장소 + +## 📦 서비스 구성 + +### 1. OAuth 인증 서비스 (`/oauth`) + +#### 백엔드 (`/oauth/backend`) +FastAPI 기반 OAuth 2.0 인증 서버 + +**주요 기능:** +- OAuth 2.0 Authorization Code Flow +- JWT 토큰 발급 및 검증 +- 사용자 인증 및 권한 관리 +- 애플리케이션 등록 및 관리 +- 인증 히스토리 추적 + +**디렉토리 구조:** +``` +oauth/backend/ +├── app/ +│ ├── api/ # API 엔드포인트 +│ ├── core/ # 핵심 설정 및 유틸리티 +│ ├── models/ # 데이터 모델 +│ ├── services/ # 비즈니스 로직 +│ └── main.py # 애플리케이션 진입점 +├── tests/ # 테스트 코드 +├── requirements.txt # Python 의존성 +└── Dockerfile # 컨테이너 이미지 +``` + +#### 프론트엔드 (`/oauth/frontend`) +React + TypeScript 기반 인증 UI + +**주요 기능:** +- 동적 테마 적용 로그인 페이지 +- 사용자 프로필 관리 +- 애플리케이션 관리 대시보드 +- 권한 설정 인터페이스 +- 인증 히스토리 뷰어 + +**디렉토리 구조:** +``` +oauth/frontend/ +├── src/ +│ ├── components/ # React 컴포넌트 +│ ├── pages/ # 페이지 컴포넌트 +│ ├── hooks/ # Custom Hooks +│ ├── services/ # API 서비스 +│ ├── stores/ # 상태 관리 +│ └── utils/ # 유틸리티 함수 +├── public/ # 정적 파일 +└── package.json # Node.js 의존성 +``` + +### 2. API Gateway (`/apisix`) + +Apache APISIX 설정 및 라우팅 규칙 + +**주요 설정:** +- 라우팅 규칙 (`routes.yaml`) +- Rate Limiting 정책 +- JWT 인증 플러그인 +- CORS 설정 +- 캐싱 전략 + +**트래픽 제한:** +| 엔드포인트 | Rate Limit | Burst | +|-----------|------------|-------| +| /api/v1/auth/* | 10 req/s | 20 | +| /api/v1/users/* | 100 req/s | 50 | +| /api/v1/applications/* | 50 req/s | 25 | +| /api/v1/admin/* | 200 req/s | 100 | + +### 3. 향후 추가될 서비스 (`/services`) + +이 디렉토리에는 OAuth 인증을 사용할 서비스들이 추가됩니다. + +## 🚀 빠른 시작 + +### 사전 요구사항 +- Docker & Docker Compose +- Git +- Make (선택사항) + +### 1. 저장소 클론 +```bash +git clone http://gitea.yakenator.io/aimond/works.git +cd works +``` + +### 2. 환경 변수 설정 +```bash +# 백엔드 환경 변수 +cp oauth/backend/.env.example oauth/backend/.env +# .env 파일을 열어 필요한 값 수정 +``` + +### 3. Docker Compose로 실행 + +#### Makefile 사용 (권장) +```bash +# 모든 서비스 시작 +make up + +# 백그라운드 실행 +make up-d + +# 로그 확인 +make logs + +# 서비스 중지 +make down +``` + +#### Docker Compose 직접 사용 +```bash +# 모든 서비스 시작 +docker-compose up --build + +# 백그라운드 실행 +docker-compose up -d --build + +# 로그 확인 +docker-compose logs -f + +# 서비스 중지 +docker-compose down +``` + +### 4. 서비스 접속 +- **API Gateway**: http://localhost:9080 +- **APISIX Dashboard**: http://localhost:9000 (admin/admin123) +- **Frontend**: http://localhost:5173 +- **API Documentation**: http://localhost:9080/api/v1/docs + +## 💻 개발 가이드 + +### 개발 환경 규칙 +- 모든 개발은 Docker 컨테이너 환경에서 진행 +- 서비스 간 의존성은 healthcheck로 관리 +- Hot reload 지원 (백엔드/프론트엔드) + +### 코드 스타일 +- **Python**: Black + Ruff +- **TypeScript**: ESLint + Prettier +- **Commit**: Conventional Commits + +### 테스트 +```bash +# 백엔드 테스트 +make test-backend + +# 프론트엔드 테스트 +make test-frontend +``` + +### 디버깅 +```bash +# 백엔드 컨테이너 접속 +make exec-backend + +# MongoDB 쉘 접속 +make exec-mongo + +# Redis CLI 접속 +make exec-redis +``` + +## 📚 API 문서 + +### 주요 엔드포인트 + +#### 인증 +- `POST /api/v1/auth/login`: 로그인 +- `POST /api/v1/auth/logout`: 로그아웃 +- `POST /api/v1/auth/refresh`: 토큰 갱신 +- `GET /api/v1/auth/authorize`: OAuth 인증 +- `POST /api/v1/auth/token`: 토큰 발급 + +#### 사용자 +- `GET /api/v1/users/me`: 현재 사용자 정보 +- `PUT /api/v1/users/me`: 사용자 정보 수정 +- `POST /api/v1/users/me/password`: 패스워드 변경 + +#### 애플리케이션 +- `GET /api/v1/applications`: 애플리케이션 목록 +- `POST /api/v1/applications`: 애플리케이션 등록 +- `PUT /api/v1/applications/{id}`: 애플리케이션 수정 +- `DELETE /api/v1/applications/{id}`: 애플리케이션 삭제 + +상세 API 문서는 [oauth/docs/api-specification.md](oauth/docs/api-specification.md) 참조 + +## 🚢 배포 가이드 + +### 환경별 배포 + +#### 개발 환경 (dev) +```bash +docker-compose up -d +``` + +#### 검증 환경 (vei) +```bash +cd oauth/configs/vei +docker-compose -f docker-compose.yml up -d +``` + +#### 운영 환경 (prod) +```bash +kubectl apply -f .k8s/ +``` + +### 백업 및 복구 + +#### 자동 백업 +- 매일 새벽 3시 자동 백업 +- 1개월 이상 데이터는 압축 아카이빙 + +#### 수동 백업 +```bash +# MongoDB 백업 +docker-compose exec mongodb mongodump --out /backup + +# Redis 백업 +docker-compose exec redis redis-cli BGSAVE +``` + +## 📖 문서 + +### 핵심 문서 +- [CLAUDE.md](CLAUDE.md): 프로젝트 규칙 및 가이드 +- [Architecture](oauth/docs/architecture.md): 시스템 아키텍처 +- [API Specification](oauth/docs/api-specification.md): API 명세 +- [APISIX Guide](oauth/docs/apisix-guide.md): API Gateway 가이드 + +### 개발 문서 +- Frontend 개발 가이드 (작성 예정) +- Backend 개발 가이드 (작성 예정) +- 테스트 가이드 (작성 예정) + +### 운영 문서 +- 모니터링 가이드 (작성 예정) +- 트러블슈팅 가이드 (작성 예정) +- 성능 튜닝 가이드 (작성 예정) + +## 🔐 보안 + +### 보안 기능 +- JWT 기반 인증 +- Rate Limiting +- IP 제한 (관리자 API) +- CORS 정책 +- SQL Injection 방지 +- XSS/CSRF 방지 + +### 보안 체크리스트 +- [ ] 환경별 Secret Key 분리 +- [ ] HTTPS 적용 +- [ ] WAF 설정 +- [ ] 정기 보안 감사 +- [ ] 취약점 스캔 + +## 🤝 기여 + +### Git 협업 규칙 +- **원격 저장소**: http://gitea.yakenator.io/aimond/works.git +- **브랜치 전략**: + - `main`: 프로덕션 + - `develop`: 개발 + - `feature/*`: 기능 개발 +- **커밋 규칙**: 모든 작업 세션은 git commit으로 마무리 + +### 개발 프로세스 +1. Feature 브랜치 생성 +2. 개발 및 테스트 +3. Pull Request 생성 +4. 코드 리뷰 +5. Merge + +## 📝 라이선스 + +[LICENSE](LICENSE) 파일 참조 + +## 👥 팀 + +- 개발: Claude AI Assistant +- 기획/관리: 사용자 + +## 🔗 관련 링크 + +- [Gitea Repository](http://gitea.yakenator.io/aimond/works.git) +- [APISIX Documentation](https://apisix.apache.org/) +- [FastAPI Documentation](https://fastapi.tiangolo.com/) +- [React Documentation](https://react.dev/) + +--- + +**Last Updated**: 2024-12-31 +**Version**: 1.0.0 \ No newline at end of file