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

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

# 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 (필수)

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 (필수)

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

Kafka (필수)

KAFKA_BOOTSTRAP_SERVERS=kafka-host:9092   # Kafka 브로커 주소

JWT (필수)

JWT_SECRET=your-jwt-secret-key      # 최소 32자 이상

마이크로서비스 연동 (선택)

CONTENT_SERVICE_URL=http://content-service:8083
DISTRIBUTION_SERVICE_URL=http://distribution-service:8086

🚀 배포 방법

방법 1: Docker Run

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. 환경변수 파일 생성:

cp .env.event.example .env.event
vi .env.event  # 실제 값으로 수정

2. 컨테이너 실행:

docker-compose --env-file .env.event -f docker-compose-event.yml up -d

3. 로그 확인:

docker-compose -f docker-compose-event.yml logs -f event-service

방법 3: 스크립트 실행

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

🔍 연결 상태 확인

헬스체크

curl http://localhost:8082/actuator/health

예상 응답:

{
  "status": "UP",
  "components": {
    "ping": {"status": "UP"},
    "db": {"status": "UP"},
    "redis": {"status": "UP"}
  }
}

개별 서비스 연결 확인

PostgreSQL 연결

docker logs event-service | grep -i "hikari"

성공 시: HikariPool-1 - Start completed.

Redis 연결

docker logs event-service | grep -i "redis"

성공 시: Lettuce driver initialized

Kafka 연결

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

해결:

# 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

해결:

# 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

해결:

# 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

해결:

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

📊 연결 풀 설정

HikariCP (PostgreSQL)

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

Lettuce (Redis)

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 컨테이너 이미지 빌드 가이드
• Docker Compose 설정
• 환경변수 템플릿
• 실행 스크립트
• IntelliJ 실행 프로파일