|
| 1 | +<div align="center"> |
| 2 | + |
| 3 | +# 🚍 Momen Platform |
| 4 | + |
| 5 | +**Spring Boot 기반 업무 & AI 통합 플랫폼** |
| 6 | + |
| 7 | +[](https://adoptium.net/) |
| 8 | +[](https://spring.io/projects/spring-boot) |
| 9 | +[](https://mariadb.org/) |
| 10 | +[](https://redis.io/) |
| 11 | +[](https://www.docker.com/) |
| 12 | +[](https://www.jenkins.io/) |
| 13 | +[](https://prometheus.io/) |
| 14 | +[](https://grafana.com/) |
| 15 | +[](https://resilience4j.readme.io/) |
| 16 | + |
| 17 | +</div> |
| 18 | + |
| 19 | +--- |
| 20 | + |
| 21 | +## ✨ 주요 기능 |
| 22 | + |
| 23 | +| | 기능 | |
| 24 | +|---|------| |
| 25 | +| 📌 | Spring Boot 기반 **업무 도메인 관리 API** | |
| 26 | +| 🔐 | **JWT 기반 인증·인가** 및 Spring Security 보안 구성 | |
| 27 | +| 🧠 | OpenAI · Gemini · Imagen 3 등 **생성형 AI 연동** | |
| 28 | +| ⚡ | Redis 캐시 & WebSocket 기반 **실시간 처리/알림** | |
| 29 | +| 📊 | Actuator · Prometheus · Grafana로 **메트릭 & 헬스 모니터링** | |
| 30 | +| 🛡 | Resilience4j, OWASP Dependency Check로 **탄력성 & 취약점 진단** | |
| 31 | +| 🐳 | Docker · docker-compose 기반 **컨테이너화된 배포 환경** | |
| 32 | +| ⚙️ | Jenkins 파이프라인을 활용한 **CI/CD 자동 배포** | |
| 33 | + |
| 34 | +--- |
| 35 | + |
| 36 | +## 🛠 기술 스택 |
| 37 | + |
| 38 | +<table> |
| 39 | +<tr> |
| 40 | +<td width="50%"> |
| 41 | + |
| 42 | +#### 💻 백엔드 |
| 43 | + |
| 44 | +| 기술 | 설명 | |
| 45 | +|------|------| |
| 46 | +|  | 런타임 (JDK 21, Gradle 기반) | |
| 47 | +|  | 애플리케이션 프레임워크 | |
| 48 | +|  | REST API, WebFlux(외부 연동) | |
| 49 | +|  | 인증/인가, JWT 보안 | |
| 50 | +|  | JPA 기반 데이터 접근 | |
| 51 | +|  | 세밀한 SQL 매핑 | |
| 52 | +|  | 타입 세이프 쿼리 | |
| 53 | +|  | 서버사이드 템플릿 | |
| 54 | +|  | 메인 데이터베이스 | |
| 55 | +|  | 캐시 · 세션 저장소 | |
| 56 | +|  | 배치 처리 인프라 | |
| 57 | + |
| 58 | +</td> |
| 59 | +<td width="50%"> |
| 60 | + |
| 61 | +#### 🏗 인프라 · 관측성 · 보안 |
| 62 | + |
| 63 | +| 기술 | 역할 | |
| 64 | +|------|------| |
| 65 | +|  | 애플리케이션 컨테이너 | |
| 66 | +|  | 앱·Redis 스택 구성 | |
| 67 | +|  | 빌드 & 배포 자동화 | |
| 68 | +|  | 메트릭 수집 (Actuator) | |
| 69 | +|  | 대시보드 시각화 | |
| 70 | +|  | 카카오 등 외부 API 탄력성 | |
| 71 | +|  | 분산 추적 연동용 라이브러리 | |
| 72 | +|  | 의존성 취약점 검사 | |
| 73 | +|  | 텍스트·임베딩 생성 | |
| 74 | +|  | LLM 연동 | |
| 75 | +|  | 이미지 생성 | |
| 76 | + |
| 77 | +</td> |
| 78 | +</tr> |
| 79 | +</table> |
| 80 | + |
| 81 | +--- |
| 82 | + |
| 83 | +## 🚀 시작하기 |
| 84 | + |
| 85 | +### 📋 사전 요구사항 |
| 86 | + |
| 87 | +- **Java 21** (JDK) |
| 88 | +- **Gradle** (Wrapper `./gradlew` 사용 권장) |
| 89 | +- **MariaDB** (로컬 또는 외부 인스턴스) |
| 90 | +- **Redis** (로컬 실행 시) |
| 91 | +- **Docker & Docker Compose** (배포/통합 실행 시) |
| 92 | + |
| 93 | +--- |
| 94 | + |
| 95 | +### ⚙️ Docker로 실행 (권장) |
| 96 | + |
| 97 | +```bash |
| 98 | +git clone <repository-url> |
| 99 | +cd blaybus |
| 100 | + |
| 101 | +# (선택) 환경 변수 예시 |
| 102 | +cp .env.example .env # 없다면 아래 예시를 참고해 직접 생성 |
| 103 | + |
| 104 | +# 애플리케이션 빌드 & 이미지 생성 |
| 105 | +./gradlew clean bootJar |
| 106 | +docker build -t momen . |
| 107 | + |
| 108 | +# 전체 스택 실행 (app + redis) |
| 109 | +docker-compose up -d |
| 110 | +``` |
| 111 | + |
| 112 | +#### 🔧 `.env` 예시 |
| 113 | + |
| 114 | +```bash |
| 115 | +DB_HOST=localhost |
| 116 | +DB_USERNAME=momen_user |
| 117 | +DB_PASSWORD=momen_password |
| 118 | +JWT_SECRET=your-jwt-secret |
| 119 | +OPENAI_API_KEY=sk-... |
| 120 | +GEMINI_API_KEY=your-gemini-key |
| 121 | +GEMINI_PROJECT_ID=your-gcp-project |
| 122 | +IMAGEN_PROJECT_ID=your-gcp-imagen-project |
| 123 | +MAIL_PASSWORD=your-mail-app-password |
| 124 | +TZ=Asia/Seoul |
| 125 | +``` |
| 126 | + |
| 127 | +`docker-compose.yml` 에서는 `DB_HOST`, `DB_USERNAME`, `DB_PASSWORD`, `JWT_SECRET`, `OPENAI_API_KEY`, `MAIL_PASSWORD` 등을 읽어 MariaDB 및 외부 API에 연결합니다. |
| 128 | + |
| 129 | +#### 🔗 서비스 접근 (Docker 실행 시) |
| 130 | + |
| 131 | +| 서비스 | URL | |
| 132 | +|--------|-----| |
| 133 | +| 🌐 애플리케이션 | `http://localhost:8089` | |
| 134 | +| 📚 Swagger UI | `http://localhost:8089/api/v1/swagger-ui.html` | |
| 135 | +| 🩺 Actuator Health | `http://localhost:8089/actuator/health` | |
| 136 | +| 📈 Prometheus Scrape | `http://localhost:8089/actuator/prometheus` | |
| 137 | + |
| 138 | +--- |
| 139 | + |
| 140 | +### 💻 로컬에서 실행 (Docker 없이) |
| 141 | + |
| 142 | +FastAPI 대신 **Spring Boot 애플리케이션만** 로컬에서 실행하는 방식입니다. Redis · Prometheus · Grafana 등은 별도 구성입니다. |
| 143 | + |
| 144 | +**필요 조건** |
| 145 | + |
| 146 | +- 로컬 MariaDB에 `momen` 데이터베이스 생성 |
| 147 | +- `application.properties` 또는 환경 변수로 DB 계정 정보 설정 |
| 148 | + |
| 149 | +#### 1) 데이터베이스 생성 |
| 150 | + |
| 151 | +```bash |
| 152 | +# 기본값 (storyg → 필요에 맞게 변경) |
| 153 | +chmod +x setup-database.sh |
| 154 | +./setup-database.sh |
| 155 | +``` |
| 156 | + |
| 157 | +또는 수동으로 MariaDB에서 데이터베이스 및 사용자를 생성한 뒤, `src/main/resources/application.properties` 의 `spring.datasource.*` 설정을 수정합니다. |
| 158 | + |
| 159 | +#### 2) 애플리케이션 실행 |
| 160 | + |
| 161 | +```bash |
| 162 | +# 프로젝트 루트에서 |
| 163 | +./gradlew clean bootRun |
| 164 | +``` |
| 165 | + |
| 166 | +| 항목 | 로컬 실행 시 | |
| 167 | +|------|--------------| |
| 168 | +| 앱 | `http://localhost:8080` | |
| 169 | +| Swagger UI | `http://localhost:8080/api/v1/swagger-ui.html` | |
| 170 | +| Actuator Health | `http://localhost:8080/actuator/health` | |
| 171 | + |
| 172 | +> ⚠️ MariaDB 및 (선택) Redis가 실행 중이 아니면 애플리케이션 기동에 실패할 수 있습니다. |
| 173 | +
|
| 174 | +--- |
| 175 | + |
| 176 | +## 🔌 API & 문서 |
| 177 | + |
| 178 | +### 📚 OpenAPI / Swagger |
| 179 | + |
| 180 | +`springdoc-openapi` 를 통해 자동 생성된 API 문서를 제공합니다. |
| 181 | + |
| 182 | +| 환경 | URL | |
| 183 | +|------|-----| |
| 184 | +| 로컬 | `http://localhost:8080/api/v1/swagger-ui.html` | |
| 185 | +| Docker | `http://localhost:8089/api/v1/swagger-ui.html` | |
| 186 | + |
| 187 | +### 🩺 Actuator 엔드포인트 |
| 188 | + |
| 189 | +`application.properties` 에서 다음 엔드포인트가 노출됩니다. |
| 190 | + |
| 191 | +| Endpoint | 설명 | |
| 192 | +|----------|------| |
| 193 | +| `/actuator/health` | 애플리케이션 헬스 체크 | |
| 194 | +| `/actuator/info` | 빌드/애플리케이션 정보 | |
| 195 | +| `/actuator/metrics` | JVM · HTTP 메트릭 | |
| 196 | +| `/actuator/prometheus` | Prometheus 스크랩용 메트릭 | |
| 197 | + |
| 198 | +Prometheus에서 `/actuator/prometheus` 를 스크랩 대상으로 등록하고, Grafana에서 Prometheus를 데이터 소스로 추가하면 JVM/HTTP/비즈니스 메트릭을 대시보드로 시각화할 수 있습니다. |
| 199 | + |
| 200 | +--- |
| 201 | + |
| 202 | +## 📁 프로젝트 구조 |
| 203 | + |
| 204 | +```bash |
| 205 | +├── src |
| 206 | +│ ├── main |
| 207 | +│ │ ├── java |
| 208 | +│ │ │ └── com/momen/ |
| 209 | +│ │ │ ├── MomenApplication.java # Spring Boot 진입점 |
| 210 | +│ │ │ ├── application/ # 애플리케이션 서비스 계층 |
| 211 | +│ │ │ ├── core/ # 공통 유틸·설정 |
| 212 | +│ │ │ ├── domain/ # 도메인 모델 & 비즈니스 로직 |
| 213 | +│ │ │ ├── infrastructure/ # DB/외부 시스템 연동 |
| 214 | +│ │ │ └── presentation/ # REST 컨트롤러 |
| 215 | +│ │ └── resources |
| 216 | +│ │ ├── application.properties # 기본 환경 설정 |
| 217 | +│ │ ├── application-*.properties # 프로필별 설정 |
| 218 | +│ │ ├── templates/ # Thymeleaf 템플릿 |
| 219 | +│ │ └── static/ # 정적 리소스 |
| 220 | +├── config/ |
| 221 | +│ └── dependency-check-suppressions.xml # OWASP Dependency Check 예외 규칙 |
| 222 | +├── docs/ |
| 223 | +│ ├── TECH_STACK_OBSERVABILITY_AND_SECURITY.md # 관측성·보안 상세 설명 |
| 224 | +│ └── JENKINS_DEPLOY.md # Jenkins 배포 가이드 |
| 225 | +├── docker-compose.yml # app + redis 스택 정의 |
| 226 | +├── Dockerfile # 애플리케이션 컨테이너 빌드 |
| 227 | +├── Jenkinsfile # CI/CD 파이프라인 정의 |
| 228 | +├── setup-database.sh # MariaDB 초기 설정 스크립트 |
| 229 | +└── build.gradle # Gradle 빌드 스크립트 |
| 230 | +``` |
| 231 | + |
| 232 | +--- |
| 233 | + |
| 234 | +## 📊 관측성 (Observability) |
| 235 | + |
| 236 | +| 영역 | 내용 | |
| 237 | +|------|------| |
| 238 | +| **메트릭** | Actuator + Micrometer + Prometheus를 통해 JVM, HTTP 요청, DB, Redis, 사용자 정의 메트릭 수집 | |
| 239 | +| **헬스 체크** | DB, Redis 등 의존성 상태를 `health` 엔드포인트로 노출, K8s Liveness/Readiness Probe에 활용 가능 | |
| 240 | +| **로깅** | `logs/Momen.log` 로 파일 로깅, 로그 패턴·레벨을 `application.properties` 에서 제어 | |
| 241 | +| **추적** | Brave/Zipkin 연동으로 분산 트레이싱 환경과 연계 가능 (스팬·트레이스 ID 기반 요청 추적) | |
| 242 | + |
| 243 | +자세한 내용은 `docs/TECH_STACK_OBSERVABILITY_AND_SECURITY.md` 를 참고하세요. |
| 244 | + |
| 245 | +--- |
| 246 | + |
| 247 | +## 🔒 보안 |
| 248 | + |
| 249 | +- **Spring Security + JWT** |
| 250 | + - 로그인 시 Access/Refresh Token 발급 |
| 251 | + - 토큰 만료 시간 (`jwt.access-token-validity`, `jwt.refresh-token-validity`) 설정 가능 |
| 252 | +- **OWASP Dependency Check** |
| 253 | + - Gradle 플러그인 `org.owasp.dependencycheck` 사용 |
| 254 | + - `./gradlew dependencyCheckAnalyze` 로 취약점 스캔 |
| 255 | + - `config/dependency-check-suppressions.xml` 로 허용할 CVE 관리 |
| 256 | +- **환경 변수 기반 비밀 관리** |
| 257 | + - DB 비밀번호, JWT 시크릿, OpenAI/Gemini/Imagen API Key, SMTP 비밀번호 등은 `.env` 또는 환경 변수 사용 권장 |
| 258 | +- **네트워크 & 접근 제어** |
| 259 | + - 프로파일(`local`, `dev`, `prod`) 별 설정으로 포트, 로깅, 보안 정책 분리 가능 |
| 260 | + |
| 261 | +--- |
| 262 | + |
| 263 | +## 🤝 기여하기 |
| 264 | + |
| 265 | +1. 저장소를 **Fork** 합니다. |
| 266 | +2. 기능 브랜치를 생성합니다. (`git checkout -b feature/amazing-feature`) |
| 267 | +3. 변경 사항을 커밋합니다. (`git commit -m 'Add some amazing feature'`) |
| 268 | +4. 브랜치를 원격 저장소에 푸시합니다. (`git push origin feature/amazing-feature`) |
| 269 | +5. Pull Request를 생성합니다. |
| 270 | + |
| 271 | +--- |
| 272 | + |
| 273 | +## 📄 라이선스 |
| 274 | + |
| 275 | +이 프로젝트의 라이선스는 **팀/조직 정책**에 따라 관리됩니다. |
| 276 | +외부 공개 또는 오픈소스 전환 시 별도의 `LICENSE` 파일로 공지될 예정입니다. |
| 277 | + |
| 278 | +--- |
| 279 | + |
| 280 | +## 📞 연락처 |
| 281 | + |
| 282 | +**프로젝트 관리자** — [dhxogns920@gmail.com](mailto:dhxogns920@gmail.com) |
| 283 | + |
0 commit comments