hgzero/docs/eventhub-setup-guide.md

EventHub 재설정 가이드

📋 개요

EventHub 공유 액세스 정책이 초기화되어 재설정이 필요합니다.

현재 EventHub 정보

• EventHub 이름: hgzero-eventhub-name
• 네임스페이스: hgzero-eventhub-ns.servicebus.windows.net
• 소비자 그룹: $Default
• 상태: 공유 액세스 정책 없음 (재생성 필요)

---

🔐 1단계: Azure Portal에서 공유 액세스 정책 생성

1.1 send-policy 생성 (STT 서비스용)

1. Azure Portal → EventHubs → hgzero-eventhub-ns → hgzero-eventhub-name
2. 좌측 메뉴에서 "공유 액세스 정책" 클릭
3. "+ 추가" 버튼 클릭
4. 다음 정보 입력:
   • 정책 이름: send-policy
   • 권한: ☑️ Send (보내기만 체크)
5. "만들기" 클릭

1.2 listen-policy 생성 (AI, Meeting 서비스용)

1. 동일한 공유 액세스 정책 화면에서 "+ 추가" 클릭
2. 다음 정보 입력:
   • 정책 이름: listen-policy
   • 권한: ☑️ Listen (수신 대기만 체크)
3. "만들기" 클릭

---

📝 2단계: 연결 문자열 복사

2.1 send-policy 연결 문자열

1. 생성된 send-policy 클릭
2. "연결 문자열-기본 키" 복사
3. ⚠️ 중요: EntityPath 제거 필요

원본:
Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=send-policy;SharedAccessKey=xxxxx;EntityPath=hgzero-eventhub-name

수정 후 (EntityPath 제거):
Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=send-policy;SharedAccessKey=xxxxx

2.2 listen-policy 연결 문자열

1. 생성된 listen-policy 클릭
2. "연결 문자열-기본 키" 복사
3. ⚠️ 중요: EntityPath 제거 필요

수정 후:
Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=listen-policy;SharedAccessKey=xxxxx

---

🔧 3단계: 서비스별 설정 업데이트

3.1 STT 서비스 (.env 파일)

파일: stt/src/main/resources/.env

# Azure Event Hub (send-policy - Send 권한, EntityPath 제거)
EVENTHUB_CONNECTION_STRING=Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=send-policy;SharedAccessKey=[YOUR_SEND_KEY]
EVENTHUB_NAME=hgzero-eventhub-name

3.2 AI-Python 서비스 (.env 파일)

파일: ai-python/.env

# Azure Event Hub (listen-policy - Listen 권한, EntityPath 제거)
EVENTHUB_CONNECTION_STRING=Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=listen-policy;SharedAccessKey=[YOUR_LISTEN_KEY]
EVENTHUB_NAME=hgzero-eventhub-name
EVENTHUB_CONSUMER_GROUP=$Default

3.3 Meeting 서비스 (IntelliJ 실행 프로파일)

파일: meeting/.run/MeetingApplication.run.xml

<option name="env"> 섹션에 다음 환경 변수 추가:

<env name="EVENTHUB_CONNECTION_STRING" value="Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=listen-policy;SharedAccessKey=[YOUR_LISTEN_KEY]" />
<env name="EVENTHUB_NAME" value="hgzero-eventhub-name" />

---

🚀 4단계: 서비스 재시작

4.1 STT 서비스

cd /Users/jominseo/HGZero/stt
./restart.sh

4.2 AI-Python 서비스

cd /Users/jominseo/HGZero/ai-python
./restart.sh

4.3 Meeting 서비스

IntelliJ에서 MeetingApplication 실행 프로파일 재시작

---

✅ 5단계: 연결 확인

5.1 STT 서비스 로그 확인

tail -f /Users/jominseo/HGZero/logs/stt-service.log | grep -i eventhub

성공 메시지 예시:

EventHub 연결 성공
EventHub Producer 초기화 완료

5.2 AI-Python 서비스 로그 확인

tail -f /Users/jominseo/HGZero/logs/ai-python.log | grep -i eventhub

성공 메시지 예시:

Event Hub 리스너 시작 성공
EventProcessor 연결 완료

실패 메시지 (이전):

AuthenticationError('CBS Token authentication failed')
Event Hub 리스너 오류: 'NoneType' object has no attribute 'eventhub_name'

5.3 Meeting 서비스 로그 확인

IntelliJ 콘솔에서 확인:

EventHub 연결 초기화 완료
EventHub Consumer 시작

---

🔍 트러블슈팅

문제 1: 인증 실패 (Authentication Error)

원인: 연결 문자열이 잘못되었거나 권한이 부족 해결:

1. 연결 문자열에 EntityPath가 포함되지 않았는지 확인
2. 정책 권한 확인 (STT: Send, AI/Meeting: Listen)
3. SharedAccessKey가 정확한지 확인

문제 2: EventHub 이름 오류

원인: EVENTHUB_NAME 환경 변수 누락 또는 오타 해결:

1. .env 파일 또는 실행 프로파일에 EVENTHUB_NAME=hgzero-eventhub-name 확인
2. 오타 체크: hgzero-eventhub-name (정확히 일치해야 함)

문제 3: 소비자 그룹 오류

원인: EVENTHUB_CONSUMER_GROUP 잘못 설정 해결:

# 올바른 형식 (작은따옴표 제거)
EVENTHUB_CONSUMER_GROUP=$Default

---

📌 체크리스트

• Azure Portal에서 send-policy 생성 (Send 권한)
• Azure Portal에서 listen-policy 생성 (Listen 권한)
• send-policy 연결 문자열 복사 (EntityPath 제거)
• listen-policy 연결 문자열 복사 (EntityPath 제거)
• STT 서비스 .env 파일 업데이트
• AI-Python 서비스 .env 파일 업데이트
• Meeting 서비스 실행 프로파일 업데이트
• STT 서비스 재시작
• AI-Python 서비스 재시작
• Meeting 서비스 재시작
• 모든 서비스 로그에서 EventHub 연결 성공 확인

---

🎯 다음 단계

설정 완료 후:

1. STT 테스트 페이지로 음성 녹음 테스트
2. AI 서비스가 EventHub에서 메시지 수신 확인
3. Meeting 서비스가 회의록 업데이트 수신 확인

---

작성일: 2025-10-29 작성자: 준호 (Backend Developer)