# Java-Service-Tree-Framework-All-In-One

* Spring Security 와 Keycloak 을 연동한 인증 인가 시스템 적용 ( Spring security 설정과 동작을 분리 )
* Spring OAuth2RestTemplate 을 활용한 연관 시스템간의 통신 적용 완료 ( 사용자 베이스 통신 동작을 분리 )
* Docker file 을 자동으로 구성하도록 설정
* Artifact Version 을 자동으로 구성하도록 설정
* ZuulProxy 를 활용한 MSA Gateway 구성
* Zipkin 을 활용한 Request Flow 추적

## Java Service Tree Framework By 313DEVGRP ##

    * 313 DEV GRP는 2010년 12월에 출범한 자바 개발자 그룹입니다.
    * TSF(jsTree Service Framework)는 MIT License로 배포됩니다.
    * 개인, 기업, 정부에서 무료로 사용이 가능합니다.

### Java Service Tree Framework란: ###

MVC패턴을 구현한 다양한 프레임워크를 대상으로 ( EgovFramework 기반한 ) 서비스레이어의 도메인 객체를 Tree Base Object로 간주하여 서비스 - DAO - DTO - DB를 정형화한 기반 구현체를 제공하는 프레임워크 입니다.

특장점 :

    * 중앙집중형 아키텍쳐
    * 확장(extend)을 염두해 둔 객체지향 개발 방식
    * 안정성
    * Speeeeeeeeeeed~!

### Java Service Tree Framework에서 사용한 기술 ###

> Part              | Detail Skill
> -------------     | -------------
> View Part 	    | html+css, Bootstrap, RequireJS, Bower, Grunt, AngularJS, jQuery, Qunit, Flex, Json, xml, BlazeDS
> Server Part	    | Apache(modjk), Nginx, Tomcat, Resin, Jetty, SiteMash, Tiles, FreeMarker, Velocity
> Framework Part    | Struts, Spring, iBatis, Hibernate, Spring-integration, Spring-security, Spring-Boot, Spring-DW, Spring-WebFlow, Spring-Data(JPA), Spring-Batch, Spring-WebServices, Spring-Mobile, Spring-MVC
> Tool Part         | Quartz, Ehcache, MemCache, Redis, Apache-Commons, EgovFramework(Component)
> CI Part           | Junit, Maven, Hudson, Jenkins, Bamboo, Nexus, Jira, Fisheye, Crucible, Confluence, Sonar
> Database Part     | MySql, Oracle, MS-sql, postgres, Hadoop, Storm, Spark, Cassandra, MongoDB
> Mobile Part       | Android, PhoneGap
> Search Engine Part| Lucene, Elastic Search, Kibana, Logstash, Beats
> Management Part   | PMBOK, MicroService, CBD, PLE, Prototype, PMS, ALM
> Virtual Image Part| Docker
> Microservice Part | Netty - Zookeeper - Finagle


### jsTree Service Framework을 지속적으로 성장시키는 툴 ###

> [ -> 형상관리 바로가기](https://github.com/jstree) : https://github.com/jstree
>
> [ -> 이슈관리 바로가기](http://www.313.co.kr/jira) : http://www.313.co.kr/jira
>
> [ -> 문서관리 바로가기](http://www.313.co.kr/confluence) : http://www.313.co.kr/confluence
>
> [ -> 리뷰관리 바로가기](http://www.313.co.kr/fecru) : http://www.313.co.kr/fecru
>
> [ -> 빌드관리 바로가기](http://www.313.co.kr/bamboo) : http://www.313.co.kr/bamboo
>
> [ -> 품질관리 바로가기](http://www.313.co.kr/sonar) : http://www.313.co.kr/sonar
>
> [ -> 아티팩트관리 바로가기](http://www.313.co.kr/nexus) : http://www.313.co.kr/nexus
>
> [ -> jsTree Service Framework 관리 샘플 사이트](http://www.313.co.kr/index.do) : http://www.313.co.kr/index.do
>
> [ -> jsTree Service Framework 사용 샘플 사이트](http://www.313.co.kr/) : http://www.313.co.kr




### Those who support us! ###
![YourKit](https://www.yourkit.com/images/yklogo.png)
> YourKit, LCC is the creator of [YourKit Java Profiler](https://www.yourkit.com/java/profiler/) and [YourKit .NET Profiler](https://www.yourkit.com/.net/profiler/),
> innovative and intelligent tools for profiling Java and .NET applications.

### 실행 방법

1. GitHub에서 프로젝트를 클론하였습니다.
   ```bash
   git clone https://github.com/313DEVGRP/Java-Service-Tree-Framework-Global-Config
   ```
2. Java 11 버전을 사용하도록 환경 설정
    - Project Sturcture 에서 Java 11 버전 설정을 했습니다.

3. 프로젝트를 빌드하고 실행을 시도했습니다.

4. 실행 중 다음과 같은 에러가 발생하였습니다.
   ```
   No spring.config.import property has been defined
   ```

5. 다음과 같이 해결하였습니다.
    - Run/Debug Configurations 메뉴에서 `Active profiles` 항목에 `dev`를 설정했습니다.
    - 다시 실행하니 정상적으로 작동했습니다.

윈도우 11 환경에서 인텔리제이를 사용하여 실행을 하였습니다.



# 🌍 Java-Service-Tree-Framework-Global-Config

> A-RMS 마이크로서비스 생태계의 중앙 설정 관리 서버

[![Java](https://img.shields.io/badge/Java-11-orange.svg)](https://openjdk.java.net/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.5.5-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Spring Cloud](https://img.shields.io/badge/Spring%20Cloud-2021.0.0-blue.svg)](https://spring.io/projects/spring-cloud)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

## 📋 목차

- [프로젝트 개요](#-프로젝트-개요)
- [주요 기능](#-주요-기능)
- [기술 스택](#-기술-스택)
- [시스템 아키텍처](#-시스템-아키텍처)
- [프로젝트 구조](#-프로젝트-구조)
- [시작하기](#-시작하기)
- [설정 가이드](#-설정-가이드)
- [API 문서](#-api-문서)
- [배포](#-배포)
- [문제 해결](#-문제-해결)

---

## 🎯 프로젝트 개요

**Global-Config**는 Spring Cloud Config Server를 기반으로 A-RMS의 모든 마이크로서비스 설정을 중앙에서 관리하고 배포하는 핵심 인프라 서비스입니다.

### 핵심 역할

- 🔧 **중앙 설정 관리**: Git 기반 설정 파일 관리
- 🔄 **동적 설정 변경**: 재시작 없이 설정 업데이트
- 🌐 **환경별 설정 분리**: dev, stg, live 환경 관리
- 📡 **Webhook 자동 갱신**: Git push 시 자동으로 클라이언트에 알림

### 마이크로서비스 아키텍처

```
                [Gitea Repository - Configuration Files]
                              ↓
                    [Global-Config Server] ⭐
                    (Spring Cloud Config Server)
                              ↓
        ┌─────────────────────┼─────────────────────┐
        ↓                     ↓                     ↓
   [Backend-Core]      [Engine-Fire]        [Middleware-Proxy]
   (Config Client)     (Config Client)      (Config Client)
```

---

## ✨ 주요 기능

### 1. Spring Cloud Config Server

**Git 저장소 기반 설정 관리**

```yaml
spring:
  cloud:
    config:
      server:
        git:
          uri: http://www.313.co.kr/gitea/root/ARMS
          username: root
          password: ${GIT_PASSWORD}
          default-label: main
          token: ${GIT_TOKEN}
```

**설정 파일 URL 패턴:**
```
/{application}/{profile}
/{application}-{profile}.yml
/{label}/{application}-{profile}.yml
```

**예시:**
```
http://www.313.co.kr:33133/javaServiceTreeFrameworkBackendCore/dev
http://www.313.co.kr:33133/javaServiceTreeFrameworkEngineFire/live
http://www.313.co.kr:33133/javaServiceTreeFrameworkMiddleProxy/stg
```

### 2. Webhook 기반 자동 갱신

**Git Push → 자동 서비스 갱신**

```
1. Git Push → Gitea Webhook 발동
2. POST /api/config-server/config-changed
3. 변경된 설정 파일 분석
4. 해당 서비스 /actuator/refresh 호출
5. 서비스가 재시작 없이 설정 갱신 ✓
```

**지원 파일명 패턴:**
```
javaServiceTreeFrameworkBackendCore-dev.yml    → backend-core
javaServiceTreeFrameworkEngineFire-live.yml    → engine-fire
javaServiceTreeFrameworkMiddleProxy-stg.yml    → middle-proxy
```

### 3. 환경별 설정 관리

**Dev / Staging / Live 환경 분리**

```yaml
# application-dev.yml (개발 환경)
arms:
  backend-core:
    url: http://127.0.0.1:31313
  engine-fire:
    url: http://127.0.0.1:33333

# application-live.yml (운영 환경)
arms:
  backend-core:
    url: http://www.313.co.kr:31313
  engine-fire:
    url: http://www.313.co.kr:33333
```

### 4. Gitea 통합

**Gitea API를 통한 설정 파일 관리**

```yaml
gitea:
  owner: root
  base-url: http://www.313.co.kr/gitea
  system-info: http://www.313.co.kr/gitea/api/v1/repos/root/SystemInfo/contents/
  schedule-config: http://www.313.co.kr/gitea/api/v1/repos/root/schedule-config/contents/
  language-config: http://www.313.co.kr/gitea/api/v1/repos/root/language-config/contents/
```

### 5. 다국어 설정 관리

- 언어팩 중앙 관리
- Gitea 저장소 기반 다국어 파일 배포
- 실시간 언어팩 업데이트

### 6. 동적 스케줄러

- 런타임 스케줄 작업 추가/제거
- Cron 표현식 기반 스케줄링
- 스케줄 설정 중앙 관리

---

## 🔧 기술 스택

### 핵심 프레임워크

| 카테고리 | 기술 | 버전 |
|---------|------|------|
| **Language** | Java | 11 |
| **Framework** | Spring Boot | 2.5.5 |
| **Cloud Config** | Spring Cloud Config | 2021.0.0 |
| **Build Tool** | Gradle | 6.9.1 |
| **Container** | Docker | Latest |
| **Git** | Gitea | Latest |

### 주요 라이브러리

#### Spring Cloud
```gradle
// Config Server
implementation 'org.springframework.cloud:spring-cloud-config-server'
implementation 'org.springframework.cloud:spring-cloud-starter-config'

// OpenFeign for MSA Communication
implementation 'org.springframework.cloud:spring-cloud-starter-openfeign'
```

#### Spring Boot
```gradle
// WebFlux for Reactive HTTP
implementation 'org.springframework.boot:spring-boot-starter-webflux'

// Actuator for Management
implementation 'org.springframework.boot:spring-boot-starter-actuator:2.5.5'

// AOP
implementation 'org.springframework.boot:spring-boot-starter-aop'
```

#### 문서화 & 알림
```gradle
// Swagger
implementation 'io.springfox:springfox-boot-starter:3.0.0'

// Slack API
implementation 'com.slack.api:slack-api-client:1.25.1'

// Lombok
compileOnly 'org.projectlombok:lombok'
```

---

## 🏗️ 시스템 아키텍처

### 설정 갱신 워크플로우

#### 방법 1: Git Push → Webhook (자동)

```
┌─────────────┐
│  Developer  │
└──────┬──────┘
       │ 1. Edit config file
       ↓
┌─────────────┐
│   Gitea     │
│ Repository  │
└──────┬──────┘
       │ 2. Git Push
       ↓
┌─────────────┐
│   Gitea     │
│  Webhook    │
└──────┬──────┘
       │ 3. POST /config-changed
       ↓
┌─────────────┐
│   Global    │
│   Config    │
└──────┬──────┘
       │ 4. Analyze changed files
       │ 5. Call /actuator/refresh
       ↓
┌─────────────┬─────────────┬─────────────┐
│ Backend-Core│ Engine-Fire │ Middle-Proxy│
│             │             │             │
│ ✓ Refreshed │ ✓ Refreshed │ ✓ Refreshed │
└─────────────┴─────────────┴─────────────┘
```

#### 방법 2: 수동 Refresh

```bash
# Config Server 갱신
curl -X POST http://localhost:33133/actuator/refresh

# Config Client 갱신
curl -X POST http://localhost:31313/actuator/refresh
```

### Config Server - Client 통신

```
┌──────────────────┐
│  Config Server   │
│  Port: 33133     │
└────────┬─────────┘
         │
         │ HTTP GET /{app}/{profile}
         │
    ┌────┴────┬────────┬──────────┐
    ↓         ↓        ↓          ↓
┌────────┐┌────────┐┌────────┐┌────────┐
│Backend ││Engine  ││Middle  ││Other   │
│Core    ││Fire    ││Proxy   ││Service │
│:31313  ││:33333  ││:13131  ││        │
└────────┘└────────┘└────────┘└────────┘
```

---

## 📂 프로젝트 구조

```
src/main/java/com/arms/
├── Application.java                    # @EnableConfigServer
│
├── api/
│   ├── configserver/                   # ⭐ Config Server 핵심
│   │   ├── controller/
│   │   │   └── ConfigServerWebhookController.java
│   │   └── model/
│   │       └── ArmsApplicationProperties.java
│   │
│   ├── systeminfo/                     # 시스템 정보 관리
│   │   ├── controller/
│   │   ├── model/
│   │   └── service/
│   │
│   ├── languageconfig/                 # 다국어 설정 관리
│   │   ├── controller/
│   │   ├── model/
│   │   └── service/
│   │
│   ├── schedule/                       # 스케줄 관리
│   │   ├── controller/
│   │   └── model/
│   │
│   └── util/                           # 유틸리티
│
├── config/                             # 설정 클래스
│   ├── DynamicSchedulerConfig.java     # 동적 스케줄러
│   ├── FeignResponseDecoderConfig.java # Feign 응답 디코더
│   ├── GiteaUserConfig.java            # Gitea 연동
│   ├── OpenFeignConfig.java            # OpenFeign 클라이언트
│   ├── SlackConfig.java                # Slack 알림
│   ├── Swagger2Config.java             # API 문서
│   └── ThreadPoolConfig.java           # 스레드 풀
│
├── license/                            # 라이선스 관리
│   ├── GenerateKeyPair.java            # RSA 키 생성
│   └── LicenseSigner.java              # 디지털 서명
│
└── egovframework/                      # 전자정부 프레임워크

src/main/resources/
├── application.yml                     # 공통 설정
├── application-dev.yml                 # 개발 환경
├── application-stg.yml                 # 스테이징 환경
├── application-live.yml                # 운영 환경
└── logback/                            # 로그 설정
    ├── console-appender.xml
    ├── logback-dev.xml
    ├── logback-stg.xml
    └── logback-live.xml
```

---

## 🚀 시작하기

### 필수 요구사항

- ☕ **Java 11** 이상
- 🐘 **Gradle 6.9.1** 이상
- 🌿 **Gitea** (Git 저장소)
- 🐳 **Docker** (선택사항)

### 1. Repository Clone

```bash
git clone https://github.com/313DEVGRP/Java-Service-Tree-Framework-Global-Config
cd Java-Service-Tree-Framework-Global-Config
```

### 2. Gitea 저장소 준비

#### Gitea에 ARMS 저장소 생성

```
Repository: http://www.313.co.kr/gitea/root/ARMS
```

#### 설정 파일 구조

```
ARMS/
├── javaServiceTreeFrameworkBackendCore-dev.yml
├── javaServiceTreeFrameworkBackendCore-stg.yml
├── javaServiceTreeFrameworkBackendCore-live.yml
├── javaServiceTreeFrameworkEngineFire-dev.yml
├── javaServiceTreeFrameworkEngineFire-stg.yml
├── javaServiceTreeFrameworkEngineFire-live.yml
├── javaServiceTreeFrameworkMiddleProxy-dev.yml
├── javaServiceTreeFrameworkMiddleProxy-stg.yml
└── javaServiceTreeFrameworkMiddleProxy-live.yml
```

### 3. 환경 설정

#### IntelliJ IDEA

1. **Run/Debug Configurations**
2. **Active profiles**: `dev` 입력
3. **Apply** → **OK**

#### 커맨드라인

```bash
# 환경 변수 설정
export SPRING_PROFILES_ACTIVE=dev

# VM Options
-Dspring.profiles.active=dev
```

### 4. 빌드

```bash
# Gradle Wrapper 권한 부여 (Linux/Mac)
chmod +x gradlew

# 빌드
./gradlew clean build

# 테스트 제외 빌드
./gradlew clean build -x test
```

### 5. 실행

#### 로컬 실행

```bash
# Gradle로 실행
./gradlew bootRun

# JAR로 실행
java -jar build/libs/Java-Service-Tree-Framework-Global-Config-25.11.x.jar
```

#### Docker로 실행

```bash
# Docker 이미지 빌드
./gradlew docker

# Docker 컨테이너 실행
docker run -d \
  -p 33133:33133 \
  --name global-config \
  -e SPRING_PROFILES_ACTIVE=dev \
  313.co.kr:5550/313devgrp/java-service-tree-framework-global-config:25.11.x
```

### 6. 헬스 체크

```bash
# 서버 상태 확인
curl http://localhost:33133/actuator/health

# 응답 예시
{
  "status": "UP",
  "components": {
    "configServer": {
      "status": "UP"
    }
  }
}
```

---

## ⚙️ 설정 가이드

### Config Server 설정

#### application-dev.yml

```yaml
spring:
  cloud:
    config:
      server:
        git:
          uri: http://www.313.co.kr/gitea/root/ARMS
          username: root
          password: ${GIT_PASSWORD}
          default-label: main
          token: ${GIT_TOKEN}

gitea:
  owner: root
  base-url: http://www.313.co.kr/gitea
  
clients:
  urls:
    backend-core:
      url: http://127.0.0.1:31313
    engine-fire:
      url: http://127.0.0.1:33333
    middle-proxy:
      url: http://127.0.0.1:13131
```

### Config Client 설정 (예시: Backend-Core)

#### bootstrap.yml

```yaml
spring:
  application:
    name: javaServiceTreeFrameworkBackendCore
  cloud:
    config:
      uri: http://localhost:33133
      profile: dev
      label: main
      fail-fast: true
```

#### build.gradle

```gradle
dependencies {
    implementation 'org.springframework.cloud:spring-cloud-starter-config'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}
```

#### @RefreshScope 사용

```java
@RestController
@RefreshScope
public class DynamicConfigController {
    
    @Value("${custom.property}")
    private String customProperty;
    
    @GetMapping("/config")
    public String getConfig() {
        return customProperty;
    }
}
```

### Gitea Webhook 설정

#### 1. Webhook 생성

```
1. Gitea 저장소 → Settings → Webhooks
2. Add Webhook → Gitea
3. Payload URL: http://www.313.co.kr:33133/api/config-server/config-changed
4. Content Type: application/json
5. Trigger: Push events
6. Active: ✓
```

#### 2. Webhook Payload 예시

```json
{
  "commits": [
    {
      "id": "abc123",
      "message": "Update database config",
      "added": [],
      "modified": [
        "javaServiceTreeFrameworkBackendCore-dev.yml"
      ],
      "removed": []
    }
  ]
}
```

---

## 📖 API 문서

### Config Server 엔드포인트

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/{application}/{profile}` | 설정 조회 |
| GET | `/{application}/{profile}/{label}` | 라벨별 설정 조회 |
| GET | `/{label}/{application}-{profile}.yml` | 파일 직접 조회 |
| POST | `/api/config-server/config-changed` | Webhook 수신 |

### 설정 조회 예시

```bash
# Backend-Core의 dev 설정 조회
curl http://localhost:33133/javaServiceTreeFrameworkBackendCore/dev

# Engine-Fire의 live 설정 조회
curl http://localhost:33133/javaServiceTreeFrameworkEngineFire/live

# 특정 브랜치의 설정 조회
curl http://localhost:33133/main/javaServiceTreeFrameworkMiddleProxy-stg.yml
```

### Actuator 엔드포인트

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/actuator/health` | 헬스 체크 |
| POST | `/actuator/refresh` | 설정 갱신 |
| POST | `/actuator/shutdown` | 서버 종료 |
| GET | `/actuator/env` | 환경 변수 확인 |
| GET | `/actuator/info` | 애플리케이션 정보 |

### Swagger UI

```
http://localhost:33133/global-config-api/swagger-ui/
```

---

## 📋 설정 파일 예시

### Backend-Core 설정

#### javaServiceTreeFrameworkBackendCore-dev.yml

```yaml
server:
  port: 31313

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/arms_dev
    username: arms_user
    password: ${MYSQL_PASSWORD}
    driver-class-name: com.mysql.cj.jdbc.Driver
  
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: true

# OpenSearch 설정
elasticsearch:
  url: localhost:9200

# Jira 설정
jira:
  server-url: https://jira.313.co.kr
  username: admin
  api-token: ${JIRA_API_TOKEN}

# 커스텀 설정
custom:
  property: "dev-value"
  
logging:
  level:
    com.arms: DEBUG
```

### Engine-Fire 설정

#### javaServiceTreeFrameworkEngineFire-dev.yml

```yaml
server:
  port: 33333

spring:
  cloud:
    config:
      uri: http://localhost:33133

# Kafka 설정
kafka:
  bootstrap-servers: localhost:9092
  topic: arm-events

# Redmine 설정
redmine:
  server-url: http://redmine.313.co.kr
  api-key: ${REDMINE_API_KEY}

logging:
  level:
    com.arms: DEBUG
```

### Middleware-Proxy 설정

#### javaServiceTreeFrameworkMiddleProxy-dev.yml

```yaml
server:
  port: 13131

spring:
  cloud:
    gateway:
      routes:
        - id: backend-core
          uri: http://localhost:31313
          predicates:
            - Path=/api/backend/**
        - id: engine-fire
          uri: http://localhost:33333
          predicates:
            - Path=/api/engine/**

# 라우팅 설정
routes:
  backend-core: http://localhost:31313
  engine-fire: http://localhost:33333

logging:
  level:
    org.springframework.cloud.gateway: DEBUG
```

---

## 🐳 배포

### Docker 배포

#### 1. 이미지 빌드

```bash
# Gradle Task로 빌드
./gradlew docker

# 또는 Docker 직접 빌드
docker build -t 313devgrp/java-service-tree-framework-global-config:25.11.x .
```

#### 2. 이미지 푸시

```bash
# Private Registry에 푸시
docker push 313.co.kr:5550/313devgrp/java-service-tree-framework-global-config:25.11.x
```

#### 3. Docker Compose

```yaml
version: '3.8'

services:
  global-config:
    image: 313.co.kr:5550/313devgrp/java-service-tree-framework-global-config:25.11.x
    container_name: global-config
    ports:
      - "33133:33133"
    environment:
      - SPRING_PROFILES_ACTIVE=dev
      - JAVA_OPTS=-Xms512m -Xmx1024m
    volumes:
      - ./logs:/logs
    networks:
      - arms-network
    restart: unless-stopped

networks:
  arms-network:
    driver: bridge
```

```bash
# Docker Compose 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f global-config
```

### Maven Repository 배포

```bash
# Maven 저장소에 배포
./gradlew publish

# 버전 확인
./gradlew printVersion
```

**배포 정보:**
- **Repository**: http://www.313.co.kr/nexus/repository/ple-releases/
- **GroupId**: 313devgrp
- **ArtifactId**: Java-Service-Tree-Framework-Global-Config
- **Version**: 25.11.x (자동 증가)

### 버전 관리

```gradle
ext {
    majorVersion = 25  // 수동 관리
    minorVersion = 11  // 수동 관리
    // patchVersion은 Nexus에서 자동 증가
}
```

---

## 🔍 문제 해결

### 자주 발생하는 문제

#### 1. Config Server 연결 실패

**증상:**
```
Could not resolve placeholder 'some.property'
```

**원인:**
- Config Server가 실행되지 않음
- Config Client가 잘못된 URI로 연결 시도
- 네트워크 문제

**해결:**
```bash
# Config Server 상태 확인
curl http://localhost:33133/actuator/health

# 설정 조회 테스트
curl http://localhost:33133/javaServiceTreeFrameworkBackendCore/dev

# Config Client의 bootstrap.yml 확인
spring:
  cloud:
    config:
      uri: http://localhost:33133  # 올바른 URI 확인
```

#### 2. Git 저장소 접근 실패

**증상:**
```
Failed to clone repository: Authentication failed
```

**원인:**
- Git 인증 정보 오류
- Git 저장소 URL 오류
- 네트워크 방화벽

**해결:**
```yaml
# application-dev.yml 확인
spring:
  cloud:
    config:
      server:
        git:
          uri: http://www.313.co.kr/gitea/root/ARMS
          username: root
          password: ${GIT_PASSWORD}  # 환경 변수 확인
          token: ${GIT_TOKEN}        # Personal Access Token 확인
```

```bash
# 환경 변수 설정
export GIT_PASSWORD="your_password"
export GIT_TOKEN="your_token"

# 직접 Git 접근 테스트
git clone http://www.313.co.kr/gitea/root/ARMS
```

#### 3. Webhook이 동작하지 않음

**증상:**
```
설정 파일 변경 후에도 서비스에 반영되지 않음
```

**원인:**
- Webhook URL 오류
- Webhook이 비활성화됨
- 파일명 패턴 불일치

**해결:**
```bash
# 1. Webhook 로그 확인
docker logs -f global-config

# 2. 수동 Refresh 시도
curl -X POST http://localhost:31313/actuator/refresh

# 3. Webhook Payload 테스트
curl -X POST http://localhost:33133/api/config-server/config-changed \
  -H "Content-Type: application/json" \
  -d '{
    "commits": [{
      "modified": ["javaServiceTreeFrameworkBackendCore-dev.yml"]
    }]
  }'
```

#### 4. 설정이 갱신되지 않음

**증상:**
```
/actuator/refresh 호출했는데 설정이 변경되지 않음
```

**원인:**
- @RefreshScope 어노테이션 누락
- Config Server의 Git 캐시

**해결:**
```java
// @RefreshScope 추가
@RestController
@RefreshScope  // ← 필수!
public class MyController {
    @Value("${my.property}")
    private String myProperty;
}
```

```bash
# Config Server Git 캐시 삭제
rm -rf /tmp/config-repo-*

# Config Server 재시작
./gradlew bootRun
```

#### 5. Port 충돌

**증상:**
```
Port 33133 is already in use
```

**해결:**
```bash
# 포트 사용 프로세스 확인 (Linux/Mac)
lsof -i :33133

# 포트 사용 프로세스 확인 (Windows)
netstat -ano | findstr :33133

# 프로세스 종료
kill -9 <PID>

# 또는 다른 포트 사용
server:
  port: 33134
```

---

## 📈 모니터링

### 로그 확인

#### Docker 환경

```bash
# 실시간 로그
docker logs -f global-config

# 최근 100줄
docker logs --tail 100 global-config

# 특정 시간 이후 로그
docker logs --since 1h global-config
```

#### 로컬 환경

```bash
# 로그 파일 확인
tail -f logs/application.log

# 에러 로그만 필터링
tail -f logs/application.log | grep ERROR

# 특정 클래스 로그만 확인
tail -f logs/application.log | grep "ConfigServerWebhookController"
```

### Health Check

```bash
# 헬스 체크
curl http://localhost:33133/actuator/health

# 상세 헬스 정보
curl http://localhost:33133/actuator/health | jq

# 응답 예시
{
  "status": "UP",
  "components": {
    "configServer": {
      "status": "UP",
      "details": {
        "repositories": [
          {
            "name": "ARMS",
            "profiles": ["dev", "stg", "live"]
          }
        ]
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 500000000000,
        "free": 250000000000
      }
    }
  }
}
```

### 환경 변수 확인

```bash
# 현재 환경 변수 조회
curl http://localhost:33133/actuator/env

# 특정 속성 조회
curl http://localhost:33133/actuator/env/spring.cloud.config.server.git.uri
```

---

## 🎨 특장점

### ✅ 중앙집중형 관리
- 모든 마이크로서비스 설정을 한 곳에서 관리
- 설정 변경 이력을 Git으로 추적
- 팀 협업이 용이한 구조

### ✅ 동적 설정 변경
- 서비스 재시작 없이 설정 갱신
- 다운타임 제로 설정 업데이트
- Webhook 기반 자동화

### ✅ 환경별 분리
- dev/stg/live 환경 독립 관리
- 환경별 다른 설정 적용 가능
- 프로파일 기반 세밀한 제어

### ✅ Git 기반 버전 관리
- 설정 변경 이력 자동 추적
- 롤백 가능
- 브랜치/태그 지원

### ✅ 보안
- 민감 정보 암호화 지원
- Git 인증 토큰 사용
- Actuator 엔드포인트 보안

---

## 🔐 보안 권장 사항

### 1. Actuator 보안

**개발 환경:**
```yaml
management:
  endpoints:
    web:
      exposure:
        include: "*"  # 모든 엔드포인트 노출
```

**운영 환경:**
```yaml
management:
  endpoints:
    web:
      exposure:
        include: health,info,refresh  # 필수 엔드포인트만 노출
  endpoint:
    health:
      show-details: when-authorized  # 인증된 사용자에게만 상세 정보
```

### 2. Git 인증 정보 보호

```yaml
# 환경 변수 사용
spring:
  cloud:
    config:
      server:
        git:
          username: ${GIT_USERNAME}
          password: ${GIT_PASSWORD}
          token: ${GIT_TOKEN}
```

```bash
# 환경 변수 설정
export GIT_USERNAME="your_username"
export GIT_PASSWORD="your_password"
export GIT_TOKEN="your_token"
```

### 3. 설정 파일 암호화

```yaml
# 암호화된 값 사용
spring:
  datasource:
    password: '{cipher}AQA...'  # Spring Cloud Config Encryption
```

---

## 📝 개선 권장 사항

### 1. 보안 강화
- [ ] Spring Security 통합
- [ ] Actuator 엔드포인트 인증/인가
- [ ] Git 자격 증명 암호화
- [ ] Spring Cloud Config Encryption 활성화

### 2. 고가용성
- [ ] Config Server 다중화 (클러스터링)
- [ ] Load Balancer 구성
- [ ] Redis/RabbitMQ 기반 설정 갱신

### 3. 모니터링 강화
- [ ] Prometheus + Grafana 통합
- [ ] Elastic APM 연동
- [ ] 설정 변경 알림 (Slack/Email)

### 4. 기능 추가
- [ ] Vault 통합 (민감 정보 관리)
- [ ] 설정 변경 승인 워크플로우
- [ ] A/B 테스트 지원

---

## 🤝 기여 가이드

### 브랜치 전략

- `main`: 프로덕션 릴리즈
- `dev`: 개발 통합 브랜치
- `feature/*`: 기능 개발
- `bugfix/*`: 버그 수정
- `hotfix/*`: 긴급 수정

### Pull Request 프로세스

1. `dev` 브랜치에서 feature 브랜치 생성
2. 기능 개발 및 테스트
3. PR 생성 (dev ← feature)
4. 코드 리뷰
5. 머지

### 커밋 메시지 컨벤션

```
feat: 새로운 기능 추가
fix: 버그 수정
docs: 문서 수정
style: 코드 포맷팅
refactor: 코드 리팩토링
test: 테스트 코드
chore: 빌드 업무, 패키지 매니저 설정
```

---

## 📝 변경 이력

### v25.11.x (2025-11-03)
- ✨ Webhook 기반 자동 갱신 기능 추가
- ✨ Gitea 통합 강화
- 🐛 설정 파일 패턴 매칭 개선
- 📝 API 문서 업데이트

### v25.10.x (2025-10-15)
- ✨ 다국어 설정 관리 기능 추가
- ✨ 동적 스케줄러 지원
- 🔧 OpenFeign HTTP Client 5 적용
- 📊 모니터링 개선

### v25.9.x (2025-09-20)
- 🎉 Initial Release
- ✨ Spring Cloud Config Server 구축
- ✨ 환경별 설정 분리
- ✨ Actuator 통합

---

## 📞 연락처

- **Maintainer**: 313DEVGRP
- **Email**: 313@313.co.kr
- **Website**: http://www.313.co.kr
- **Jira**: http://www.313.co.kr/jira
- **Confluence**: http://www.313.co.kr/confluence

---

## 📄 라이선스

Copyright © 2025 313DEVGRP. All rights reserved.

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 감사의 글

이 프로젝트는 다음 오픈소스 프로젝트를 사용합니다:

- [Spring Boot](https://spring.io/projects/spring-boot)
- [Spring Cloud Config](https://spring.io/projects/spring-cloud-config)
- [Spring Cloud](https://spring.io/projects/spring-cloud)
- [Gitea](https://gitea.io/)
- [Gradle](https://gradle.org/)

---

## 🔗 관련 프로젝트

- [Java-Service-Tree-Framework-Backend-Core](http://www.313.co.kr/gitea/313DEVGRP/Java-Service-Tree-Framework-Backend-Core)
- [Java-Service-Tree-Framework-Engine-Fire](http://www.313.co.kr/gitea/313DEVGRP/Java-Service-Tree-Framework-Engine-Fire)
- [Java-Service-Tree-Framework-Middleware-Proxy](http://www.313.co.kr/gitea/313DEVGRP/Java-Service-Tree-Framework-Middleware-Proxy)
- [Java-Service-Tree-Framework-Frontend-Web](http://www.313.co.kr/gitea/313DEVGRP/Java-Service-Tree-Framework-Frontend-Web)

---

**Made with ❤️ by 313DEVGRP**

> Global-Config는 A-RMS 마이크로서비스 생태계의 **중추 신경계** 역할을 하는 핵심 인프라 서비스입니다!