kt-event-marketing/deployment/container/EVENT-SERVICE-CONNECTION-GUIDE.md

# Event Service 외부 서비스 연결 가이드

## 📋 연결 설정 검토 결과

### ✅ 현재 설정 상태

Event Service는 다음 외부 서비스들과 연동됩니다:

1. **PostgreSQL** - 이벤트 데이터 저장
2. **Redis** - AI 생성 결과 및 이미지 캐싱
3. **Kafka** - 비동기 작업 큐 (AI 생성, 이미지 생성)
4. **Content Service** - 콘텐츠 생성 서비스 (선택)
5. **Distribution Service** - 배포 서비스 (선택)

### 📁 설정 파일

#### application.yml
모든 연결 정보는 환경변수를 통해 주입되도록 설정되어 있습니다:

```yaml
# PostgreSQL
spring.datasource.url: jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/${DB_NAME:eventdb}
spring.datasource.username: ${DB_USERNAME:eventuser}
spring.datasource.password: ${DB_PASSWORD:eventpass}

# Redis
spring.data.redis.host: ${REDIS_HOST:localhost}
spring.data.redis.port: ${REDIS_PORT:6379}
spring.data.redis.password: ${REDIS_PASSWORD:}

# Kafka
spring.kafka.bootstrap-servers: ${KAFKA_BOOTSTRAP_SERVERS:localhost:9092}

# JWT
jwt.secret: ${JWT_SECRET:default-jwt-secret-key-for-development-minimum-32-bytes-required}
```

## 🔧 필수 환경변수

### PostgreSQL (필수)
```bash
DB_HOST=your-postgresql-host        # PostgreSQL 호스트
DB_PORT=5432                        # PostgreSQL 포트
DB_NAME=eventdb                     # 데이터베이스 이름
DB_USERNAME=eventuser               # 데이터베이스 사용자
DB_PASSWORD=your-password           # 데이터베이스 비밀번호
DDL_AUTO=update                     # Hibernate DDL 모드
```

### Redis (필수)
```bash
REDIS_HOST=your-redis-host          # Redis 호스트
REDIS_PORT=6379                     # Redis 포트
REDIS_PASSWORD=your-password        # Redis 비밀번호 (없으면 빈 문자열)
```

### Kafka (필수)
```bash
KAFKA_BOOTSTRAP_SERVERS=kafka-host:9092   # Kafka 브로커 주소
```

### JWT (필수)
```bash
JWT_SECRET=your-jwt-secret-key      # 최소 32자 이상
```

### 마이크로서비스 연동 (선택)
```bash
CONTENT_SERVICE_URL=http://content-service:8083
DISTRIBUTION_SERVICE_URL=http://distribution-service:8086
```

## 🚀 배포 방법

### 방법 1: Docker Run

```bash
docker run -d \
  --name event-service \
  -p 8082:8082 \
  -e DB_HOST=your-postgresql-host \
  -e DB_PORT=5432 \
  -e DB_NAME=eventdb \
  -e DB_USERNAME=eventuser \
  -e DB_PASSWORD=your-password \
  -e REDIS_HOST=your-redis-host \
  -e REDIS_PORT=6379 \
  -e REDIS_PASSWORD=your-redis-password \
  -e KAFKA_BOOTSTRAP_SERVERS=your-kafka:9092 \
  -e JWT_SECRET=your-jwt-secret-minimum-32-chars \
  acrdigitalgarage01.azurecr.io/kt-event-marketing/event-service:latest
```

### 방법 2: Docker Compose

1. **환경변수 파일 생성**:
```bash
cp .env.event.example .env.event
vi .env.event  # 실제 값으로 수정
```

2. **컨테이너 실행**:
```bash
docker-compose --env-file .env.event -f docker-compose-event.yml up -d
```

3. **로그 확인**:
```bash
docker-compose -f docker-compose-event.yml logs -f event-service
```

### 방법 3: 스크립트 실행

```bash
# run-event-service.sh 파일 수정 후 실행
chmod +x run-event-service.sh
./run-event-service.sh
```

## 🔍 연결 상태 확인

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

**예상 응답**:
```json
{
  "status": "UP",
  "components": {
    "ping": {"status": "UP"},
    "db": {"status": "UP"},
    "redis": {"status": "UP"}
  }
}
```

### 개별 서비스 연결 확인

#### PostgreSQL 연결
```bash
docker logs event-service | grep -i "hikari"
```
성공 시: `HikariPool-1 - Start completed.`

#### Redis 연결
```bash
docker logs event-service | grep -i "redis"
```
성공 시: `Lettuce driver initialized`

#### Kafka 연결
```bash
docker logs event-service | grep -i "kafka"
```
성공 시: `Kafka version: ...`

## ⚠️ 주의사항

### 1. localhost 주의
- Docker 컨테이너 내에서 `localhost`는 컨테이너 자신을 의미
- 호스트 머신의 서비스에 접근하려면:
  - Linux/Mac: `host.docker.internal` 사용
  - 또는 호스트 IP 직접 사용

### 2. JWT Secret
- 최소 32자 이상 필수
- 운영 환경에서는 강력한 랜덤 키 사용
- 예시: `kt-event-marketing-prod-jwt-secret-2025-secure-random-key`

### 3. DDL_AUTO 설정
- 개발: `update` (스키마 자동 업데이트)
- 운영: `validate` (스키마 검증만 수행)
- 초기 설치: `create` (스키마 생성, 주의: 기존 데이터 삭제)

### 4. Kafka 토픽
Event Service가 사용하는 토픽들이 미리 생성되어 있어야 합니다:
- `ai-event-generation-job`
- `image-generation-job`
- `event-created`

### 5. Redis 캐시 키
다음 키 프리픽스를 사용합니다:
- `ai:recommendation:*` - AI 추천 결과 (TTL: 24시간)
- `image:generation:*` - 이미지 생성 결과 (TTL: 7일)
- `job:status:*` - 작업 상태

## 🐛 트러블슈팅

### PostgreSQL 연결 실패
**증상**: `Connection refused` 또는 `Connection timeout`

**해결**:
```bash
# 1. PostgreSQL 서버 상태 확인
psql -h $DB_HOST -U $DB_USERNAME -d $DB_NAME

# 2. 방화벽 확인
telnet $DB_HOST 5432

# 3. 환경변수 확인
docker exec event-service env | grep DB_
```

### Redis 연결 실패
**증상**: `Unable to connect to Redis`

**해결**:
```bash
# 1. Redis 서버 상태 확인
redis-cli -h $REDIS_HOST -p $REDIS_PORT -a $REDIS_PASSWORD ping

# 2. 환경변수 확인
docker exec event-service env | grep REDIS_
```

### Kafka 연결 실패
**증상**: `Connection to node ... could not be established`

**해결**:
```bash
# 1. Kafka 서버 상태 확인
kafka-topics.sh --bootstrap-server $KAFKA_BOOTSTRAP_SERVERS --list

# 2. 토픽 존재 확인
kafka-topics.sh --bootstrap-server $KAFKA_BOOTSTRAP_SERVERS --describe --topic ai-event-generation-job

# 3. 환경변수 확인
docker exec event-service env | grep KAFKA_
```

### JWT 오류
**증상**: `JWT secret key must be at least 32 characters`

**해결**:
```bash
# JWT_SECRET 길이 확인 (32자 이상이어야 함)
docker exec event-service env | grep JWT_SECRET | awk -F'=' '{print length($2)}'
```

## 📊 연결 풀 설정

### HikariCP (PostgreSQL)
```yaml
maximum-pool-size: 5      # 최대 연결 수
minimum-idle: 2           # 최소 유휴 연결 수
connection-timeout: 30000 # 연결 타임아웃 (30초)
```

### Lettuce (Redis)
```yaml
max-active: 5             # 최대 활성 연결 수
max-idle: 3               # 최대 유휴 연결 수
min-idle: 1               # 최소 유휴 연결 수
```

## 🔐 보안 권장사항

1. **환경변수 보안**
   - `.env` 파일은 `.gitignore`에 추가
   - 운영 환경에서는 Kubernetes Secrets 또는 AWS Secrets Manager 사용

2. **네트워크 보안**
   - 프로덕션 환경에서는 전용 네트워크 사용
   - 불필요한 포트 노출 금지

3. **인증 정보 관리**
   - 비밀번호 정기적 변경
   - 강력한 비밀번호 사용

## 📝 체크리스트

배포 전 확인 사항:

- [ ] PostgreSQL 서버 준비 및 데이터베이스 생성
- [ ] Redis 서버 준비 및 연결 확인
- [ ] Kafka 클러스터 준비 및 토픽 생성
- [ ] JWT Secret 생성 (32자 이상)
- [ ] 환경변수 파일 작성 및 검증
- [ ] 네트워크 방화벽 설정 확인
- [ ] Docker 이미지 pull 권한 확인
- [ ] 헬스체크 엔드포인트 접근 가능 확인

## 📚 관련 문서

- [Event Service 컨테이너 이미지 빌드 가이드](build-image.md)
- [Docker Compose 설정](docker-compose-event.yml)
- [환경변수 템플릿](.env.event.example)
- [실행 스크립트](run-event-service.sh)
- [IntelliJ 실행 프로파일](../.run/EventServiceApplication.run.xml)