DOCS/troubleshooting/251016_troubleshooting_summary.md

트러블슈팅 이슈 해결 요약

날짜: 2025-10-16 작성자: Claude (51124 서버 전담) 작업 기간: 16:06 - 16:12 KST

---

완료된 이슈

1. Coldmail IR 분석 실패 - 중복 파일 처리 개선 ✅

문제: 동일 PDF 재업로드 시 400 - File already exists 에러로 전체 IR 분석 실패

해결:

• 위치: skill-rag-file/app/api/upload.py:60-79
• HTTPException 제거 → 기존 document_id 반환 (멱등성 보장)
• 커밋: cea055c
• 상태: 배포 완료, skill-rag-file 컨테이너 정상 작동

효과:

• 동일 파일 여러 번 업로드 가능
• Coldmail 워크플로우 안정성 확보
• 네트워크 재시도 시 안전

문서: 251016_coldmail_duplicate_file_fix.md

---

2. NaverWorks Briefing 'system' UUID 오류 ✅

문제: 시스템 메시지의 user_id="system"이 UUID 타입 불일치로 emotion_readings 저장 실패

해결:

• 위치: rb8001/app/state/database.py:145-155
• "system" user_id 발견 시 저장 skip (return True)
• 커밋: 2f767b3
• 상태: 배포 완료, rb8001 컨테이너 정상 작동

효과:

• NaverWorks Briefing 정상 작동 (감정 저장 제외)
• ERROR 로그 제거
• 기능 영향 없음

향후 개선: 전용 시스템 UUID 생성 또는 emotion_readings.user_id nullable 변경 (51123 서버 작업 필요)

---

3. gRPC + uvloop BlockingIOError 로그 노이즈 억제 ✅

문제: gRPC (Vertex AI 호출)와 uvloop 이벤트 루프 경합으로 BlockingIOError 로그 노이즈 발생

해결:

• 위치: rb8001/app/core/logger.py:41-44
• gRPC 로거 레벨 → CRITICAL
• asyncio 로거 레벨 → WARNING
• 커밋: adae74c
• 상태: 배포 완료, rb8001 컨테이너 정상 작동

효과:

• BlockingIOError 로그 숨김
• 실제 오류 추적 용이
• 기능 영향 없음 (로그만 억제)

---

미해결 이슈 (51123 서버 작업 필요)

4. Slack 봇 설치 workspace_id 컬럼 오류 ⏸️

문제: auth-server의 workspace_member 테이블에 workspace_id 컬럼 없음

위치: auth-server/app/providers/slack.py:408-418

해결 방법:

• workspace_member.workspace_id → user.team_id 변경
• 또는 workspace_member 테이블에 workspace_id 컬럼 추가

상태: 51123 서버 작업 필요 (auth-server)

---

배포 상태

skill-rag-file

• 커밋: cea055c
• 상태: Up (healthy)
• 변경: 중복 파일 멱등성 보장

rb8001

• 커밋: adae74c
• 상태: Up (healthy)
• 변경: system UUID 처리 + gRPC 로그 억제

---

검증 계획

즉시 확인 ✅

• skill-rag-file 컨테이너 정상 작동
• rb8001 컨테이너 정상 작동
• 헬스체크 통과

내일 검증 (2025-10-17)

• 09:00 NaverWorks Briefing: system UUID 오류 로그 사라짐 확인
• 09:00 NaverWorks Briefing: gRPC BlockingIOError 로그 사라짐 확인
• 09:05 Coldmail Briefing: PDF 업로드 성공 확인
• 09:05 Coldmail Briefing: IR 분석 실제 데이터 반환 확인
• 09:05 Coldmail Briefing: Slack Lists 전송 성공 확인

로그 체크 포인트

# NaverWorks Briefing (09:00)
docker logs rb8001 --since "2025-10-17T09:00:00" | grep -iE "system|grpc|blocking"

# Coldmail Briefing (09:05)
docker logs rb8001 --since "2025-10-17T09:05:00" | grep -iE "upload|document_id"
docker logs skill-rag-file --since "2025-10-17T09:05:00" | grep "File already exists"

---

교훈

1. 멱등성 설계 (Idempotency)

원칙: 동일 요청을 여러 번 실행해도 결과가 같아야 함

적용: 중복 체크 시 "에러"가 아닌 "기존 리소스 반환"

2. 시스템 사용자 처리 정책

문제: 사용자가 아닌 시스템 작업의 user_id 처리 미정의

해결:

• 단기: 시스템 user_id 감지 후 skip
• 장기: 전용 시스템 UUID 생성

3. 로그 레벨 관리

원칙: 외부 라이브러리 로그는 필요 시 레벨 조정

적용: gRPC, asyncio 로거 레벨 상향 조정

4. Cascading Failure 방지

원칙: 한 단계 실패가 전체 워크플로우 실패로 이어지지 않도록

적용:

• PDF 업로드 실패 → IR 분석 실패 → Slack 전송 실패 (연쇄)
• 멱등성으로 PDF 업로드 안정화

---

다음 단계

51124 서버 (완료)

• Coldmail 중복 파일 처리 개선
• NaverWorks system UUID 오류 해결
• gRPC 로그 노이즈 억제

51123 서버 (향후)

• Slack 봇 설치 workspace_id 오류 수정 (auth-server)
• emotion_readings.user_id nullable 또는 시스템 UUID 생성

---

결론

✅ 51124 서버 트러블슈팅 완료 (3/4 이슈 해결)

2025-10-16, 트러블슈팅 이슈 3건 해결 배포

핵심 성과

1. Coldmail IR 분석 안정화: 중복 파일 멱등성 보장
2. NaverWorks Briefing 정상화: system UUID 오류 해결
3. 로그 품질 개선: gRPC 노이즈 억제로 실제 오류 추적 용이
4. 즉시 배포: skill-rag-file + rb8001 재시작 완료

검증 대기

내일 09:00-09:10 브리핑 실행 시 실전 검증 예정.