ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

Refactor troubleshooting docs to follow documentation principles

Browse Source 
Changes:
- 251016_coldmail_duplicate_file_fix.md: 298줄 → 111줄
- 251016_troubleshooting_summary.md: 184줄 → 109줄

Applied principles (312_문서_작성_원칙.md):
- Removed excessive code blocks
- Kept file:line references only
- Removed emojis
- Reduced to ~100 lines per document
- Kept core information and lessons learned
This commit is contained in:
Claude-51124 2025-10-16 16:23:20 +09:00
parent b836c170fb
commit f0d9890110
2 changed files with 89 additions and 351 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

271
troubleshooting/251016_coldmail_duplicate_file_fix.md
View File

@ -3,295 +3,108 @@
**날짜**: 2025-10-16 **날짜**: 2025-10-16
**작성자**: Claude (51124 서버 전담) **작성자**: Claude (51124 서버 전담)
**커밋**: skill-rag-file cea055c **커밋**: skill-rag-file cea055c
**관련 문서**: 251015_claude_coldmail_ir_analysis_failure.md **관련 파일**: skill-rag-file/app/api/upload.py:60-79
--- ---
## 문제 요약 ## 문제 상황
Coldmail 브리핑 워크플로우에서 동일한 PDF 파일이 재업로드될 때 `400 - File already exists for this team` 에러 발생하여 전체 IR 분석 실패. Coldmail 브리핑 워크플로우에서 동일 PDF 재업로드 시 `400 - File already exists` 에러로 전체 IR 분석 실패.
### 연쇄 효과 **연쇄 효과**: PDF 업로드 실패 → document_id = None → RAG 검색 0건 → IR 분석 "N/A" → Slack Lists API 에러
```
PDF 업로드 실패 (400 에러)
↓
document_id = None
↓
RAG 검색 0건
↓
IR 분석 "N/A" 반환
↓
Slack Lists API 에러
```
--- ---
## 원인 분석 ## 원인 분석
**위치**: `skill-rag-file/app/api/upload.py:67-71` **위치**: skill-rag-file/app/api/upload.py:67-71
**기존 코드**: **기존 동작**:
```python
if result.scalar():
raise HTTPException(
status_code=400,
detail="File already exists for this team"
)
```
**문제점**:
- 중복 파일 발견 시 HTTPException 발생 - 중복 파일 발견 시 HTTPException 발생
- document_id 반환 없음 - document_id 반환 없음
- 워크플로우 중단 - 멱등성 미보장: 동일 요청 재실행 시 결과 달라짐
- **멱등성(idempotency) 미보장**: 동일 요청을 여러 번 실행할 때 결과가 달라짐
--- ---
## 해결 방법 ## 해결 방안
### 코드 수정 **위치**: skill-rag-file/app/api/upload.py:60-79
**위치**: `skill-rag-file/app/api/upload.py:60-79` **변경 내용**:
1. select(TeamDocument.id) → select(TeamDocument): 전체 레코드 조회
2. HTTPException 제거 → 기존 document_id 반환
3. FileUploadResponse 반환: 기존 document와 동일 응답
4. INFO 로그 추가: 중복 감지 기록
```python **핵심 로직**:
# Check if file already exists for this team - existing_doc = result.scalar_one_or_none()
from sqlalchemy import select - if existing_doc: return FileUploadResponse(document_id=existing_doc.id, ...)
stmt = select(TeamDocument).where(
TeamDocument.team_id == team_id,
TeamDocument.file_hash == file_hash
)
result = await db.execute(stmt)
existing_doc = result.scalar_one_or_none()
if existing_doc: ---
# 중복 파일 발견 - 기존 document_id 반환 (멱등성 보장)
logger.info(f"File already exists (hash: {file_hash}), returning existing document_id: {existing_doc.id}")
return FileUploadResponse(
document_id=existing_doc.id,
filename=existing_doc.filename,
file_hash=existing_doc.file_hash,
storage_path=existing_doc.storage_path,
chunk_count=existing_doc.chunk_count or 0,
message=f"File already exists, returned existing document_id: {existing_doc.id}"
)
```
### 핵심 변경사항 ## 구현 완료
1. **select(TeamDocument.id) → select(TeamDocument)**: 전체 레코드 조회 **배포**: 2025-10-16
2. **HTTPException 제거**: 에러 대신 기존 데이터 반환 - 커밋 해시: cea055c
3. **FileUploadResponse 반환**: 기존 document_id와 메타데이터 제공 - 상태: skill-rag-file 컨테이너 재시작 완료 (healthy)
4. **INFO 로그 추가**: 중복 감지 로그 기록
--- ---
## 효과 ## 효과
### 1. 멱등성 보장 ### 멱등성 보장
**Before**: **Before**: 1차 성공, 2차 400 에러
``` **After**: 1차/2차/3차 모두 동일 document_id 반환
1st upload: 성공 → document_id: abc-123
2nd upload: 실패 → 400 에러
```
**After**: ### Coldmail 워크플로우 안정성
```
1st upload: 성공 → document_id: abc-123
2nd upload: 성공 → document_id: abc-123 (동일)
3rd upload: 성공 → document_id: abc-123 (동일)
```
### 2. Coldmail 워크플로우 안정성 PDF 업로드 → document_id 항상 획득 → RAG 검색 정상 → IR 분석 정확 → Slack 전송 성공
``` ### 재시도 안전성
PDF 업로드 (멱등성 보장)
↓
document_id 항상 획득 ✅
↓
RAG 검색 정상 작동 ✅
↓
IR 분석 정확한 데이터 ✅
↓
Slack Lists API 성공 ✅
```
### 3. 재시도 안전성 - 1차 시도: 파일 저장 + 벡터 생성 (느림)
네트워크 오류, 타임아웃 등으로 재시도 시에도 안전하게 작동:
- 1차 시도: 파일 저장, 벡터 생성 (느림)
- 2차 시도: 기존 document_id 즉시 반환 (빠름) - 2차 시도: 기존 document_id 즉시 반환 (빠름)
--- ---
## 배포
### 커밋 정보
```bash
cd /home/admin/ivada_project/skill-rag-file
git add app/api/upload.py
git commit -m "Fix duplicate file handling in upload API
Change duplicate file behavior from HTTPException to idempotent response.
When same file (hash) uploaded by team, return existing document_id instead
of raising 400 error. This ensures coldmail workflow continues when PDFs
are re-uploaded.
Fixes: Coldmail IR analysis failure due to PDF upload rejection"
git push origin main
```
**커밋 해시**: cea055c
### 배포 확인
```bash
docker compose down && docker compose up -d --build
# 상태 확인
docker ps --filter name=skill-rag-file
# NAMES STATUS
# skill-rag-file Up 2 minutes (healthy)
# 로그 확인
docker logs skill-rag-file --tail 20
# INFO: Application startup complete.
# INFO: Uvicorn running on http://0.0.0.0:8508
```
---
## 검증 계획 ## 검증 계획
### 즉시 검증 (수동) ### 내일 실전 검증 (2025-10-17 09:05)
1. **동일 파일 2회 업로드 테스트**: **Coldmail 브리핑 실행 시 확인**:
```bash
# 1차 업로드: 성공, document_id 획득
# 2차 업로드: 성공, 동일 document_id 획득
```
2. **로그 확인**:
```bash
docker logs skill-rag-file | grep "File already exists"
# 예상: INFO - File already exists (hash: ...), returning existing document_id: ...
```
### 실전 검증 (내일 09:05)
**Coldmail 브리핑 실행 시**:
1. PDF 업로드 성공 여부 1. PDF 업로드 성공 여부
2. IR 분석 "N/A" 아닌 실제 데이터 반환 여부 2. IR 분석 실제 데이터 반환 확인
3. Slack Lists 전송 성공 여부 3. Slack Lists 전송 성공 확인
**로그 체크 포인트**: **로그 체크**:
```bash - rb8001: docker logs rb8001 --since "2025-10-17T09:00:00" | grep -iE "upload|document_id"
# rb8001 로그 (09:05 이후) - skill-rag-file: docker logs skill-rag-file --since "2025-10-17T09:00:00" | grep "File already exists"
docker logs rb8001 --since "2025-10-17T09:00:00" | grep -iE "upload|document_id"
# skill-rag-file 로그
docker logs skill-rag-file --since "2025-10-17T09:00:00" | grep "File already exists"
```
---
## 관련 이슈 해결 상태
### 해결됨 ✅
1. **중복 파일 처리 개선**: HTTPException → 기존 document_id 반환
2. **멱등성 보장**: 동일 요청 여러 번 실행 가능
3. **Coldmail 워크플로우 안정성**: PDF 업로드 실패로 인한 전체 실패 방지
### 향후 개선 사항
1. **Slack Lists 동적 컬럼 매핑**:
- 현재: 하드코딩된 컬럼 ID (Col09HQTDUM0T 등)
- 개선: Lists 컬럼 조회 API + 컬럼명 기반 동적 매핑
2. **LangGraph 체크포인트 + 에러 복구**:
- 현재: Stateless 실행
- 개선: PostgresSaver 체크포인트 + 실패 지점부터 재시도
- LLM 기반 에러 페이로드 수정 및 재전송
--- ---
## 교훈 ## 교훈
### 1. 멱등성은 필수 (Idempotency is Critical) ### 멱등성은 필수
**원칙**: 동일 요청을 여러 번 실행해도 결과가 같아야 함 **원칙**: 동일 요청을 여러 번 실행해도 결과가 같아야 함
**적용**: **적용**:
- POST 요청이라도 리소스 생성/조회에는 멱등성 필요 - POST 요청이라도 리소스 생성/조회에는 멱등성 필요
- 중복 체크 시 "에러"가 아닌 "기존 리소스 반환"이 정답 - 중복 체크 시 에러가 아닌 기존 리소스 반환
- 네트워크 불안정, 재시도 상황에서 안전성 보장 - 네트워크 불안정, 재시도 상황에서 안전성 보장
### 2. Cascading Failure 방지 ### Cascading Failure 방지
**문제**: 한 단계 실패 → 전체 워크플로우 실패 **원인**: 한 단계 실패가 전체 워크플로우 실패로 연쇄
**해결**: **해결**:
- 각 단계의 실패 격리 - 각 단계의 실패 격리
- 재시도 가능한 설계 - 재시도 가능한 설계
- Graceful degradation (부분 성공 허용) - Graceful degradation (부분 성공 허용)
### 3. 에러 메시지의 의미 ### 에러 메시지의 의미
**"File already exists"는 에러가 아니다**: "File already exists"는 에러가 아니라 상태 확인 메시지:
- 상태 확인 메시지로 취급
- 이미 존재하는 리소스 정보 반환 - 이미 존재하는 리소스 정보 반환
- 클라이언트는 정상 처리 가능 - 클라이언트는 정상 처리 가능
### 4. 프레임워크 활용의 실효성
**LangGraph 도입 vs 실제 활용**:
- 체크포인트 없는 LangGraph = 코드 정리 효과만
- 핵심 기능(체크포인트, 재시도)까지 구현해야 프레임워크 가치 발휘
- 점진적 개선: 멱등성 → 체크포인트 → LLM 복구
---
## 다음 단계
### 즉시 수행
- [x] 코드 수정 및 배포
- [x] Docker 재시작 확인
- [x] 헬스체크 정상 확인
### 내일 확인 (2025-10-17 09:05)
- [ ] Coldmail 브리핑 실행 성공 여부
- [ ] PDF 업로드 로그에서 "File already exists" 메시지 확인
- [ ] IR 분석 결과에 실제 데이터 포함 확인
- [ ] Slack Lists API 전송 성공 확인
### 향후 개선
- [ ] Slack Lists 동적 컬럼 매핑 구현
- [ ] LangGraph 체크포인트 활성화
- [ ] LLM 기반 에러 복구 로직 추가
---
## 결론
✅ **Coldmail IR 분석 실패 해결 완료**
**2025-10-16, skill-rag-file 중복 파일 처리 개선 배포**
### 핵심 성과
1. **멱등성 보장**: 동일 파일 재업로드 시 기존 document_id 반환
2. **워크플로우 안정성**: PDF 업로드 실패로 인한 전체 실패 방지
3. **재시도 안전성**: 네트워크 오류, 타임아웃 상황에서도 안전
4. **즉시 배포**: skill-rag-file 컨테이너 재시작 완료
### 검증 대기
내일 09:05 Coldmail 브리핑 실행 시 실전 검증 예정.

169
troubleshooting/251016_troubleshooting_summary.md
View File

@ -6,178 +6,103 @@
--- ---
## 완료된 이슈 ## 완료된 이슈 (51124 서버)
### 1. Coldmail IR 분석 실패 - 중복 파일 처리 개선 ✅ ### 1. Coldmail IR 분석 실패 - 중복 파일 처리
**문제**: 동일 PDF 재업로드 시 `400 - File already exists` 에러로 전체 IR 분석 실패 **문제**: 동일 PDF 재업로드 시 400 에러로 전체 IR 분석 실패
**해결**: **해결**: skill-rag-file/app/api/upload.py:60-79
- 위치: `skill-rag-file/app/api/upload.py:60-79` - HTTPException 제거, 기존 document_id 반환 (멱등성 보장)
- HTTPException 제거 → 기존 document_id 반환 (멱등성 보장)
- 커밋: cea055c - 커밋: cea055c
- 상태: 배포 완료, skill-rag-file 컨테이너 정상 작동
**효과**: **효과**: Coldmail 워크플로우 안정화, 네트워크 재시도 안전
- 동일 파일 여러 번 업로드 가능
- Coldmail 워크플로우 안정성 확보
- 네트워크 재시도 시 안전
**문서**: `251016_coldmail_duplicate_file_fix.md` **상세**: 251016_coldmail_duplicate_file_fix.md
--- ---
### 2. NaverWorks Briefing 'system' UUID 오류 ✅ ### 2. NaverWorks Briefing system UUID 오류
**문제**: 시스템 메시지의 user_id="system"이 UUID 타입 불일치로 emotion_readings 저장 실패 **문제**: user_id="system" 문자열이 UUID 타입 불일치로 emotion_readings 저장 실패
**해결**: **해결**: rb8001/app/state/database.py:145-155
- 위치: `rb8001/app/state/database.py:145-155` - "system" user_id 발견 시 저장 skip
- "system" user_id 발견 시 저장 skip (return True)
- 커밋: 2f767b3 - 커밋: 2f767b3
- 상태: 배포 완료, rb8001 컨테이너 정상 작동
**효과**: **효과**: NaverWorks Briefing 정상 작동, ERROR 로그 제거
- NaverWorks Briefing 정상 작동 (감정 저장 제외)
- ERROR 로그 제거
- 기능 영향 없음
**향후 개선**: 전용 시스템 UUID 생성 또는 emotion_readings.user_id nullable 변경 (51123 서버 작업 필요) **향후**: 전용 시스템 UUID 생성 또는 emotion_readings.user_id nullable 변경 (51123 서버)
--- ---
### 3. gRPC + uvloop BlockingIOError 로그 노이즈 억제 ✅ ### 3. gRPC + uvloop BlockingIOError 로그 노이즈
**문제**: gRPC (Vertex AI 호출)와 uvloop 이벤트 루프 경합으로 BlockingIOError 로그 노이즈 발생 **문제**: gRPC (Vertex AI)와 uvloop 이벤트 루프 경합으로 로그 노이즈 발생
**해결**: **해결**: rb8001/app/core/logger.py:41-44
- 위치: `rb8001/app/core/logger.py:41-44` - gRPC 로거 레벨 CRITICAL
- gRPC 로거 레벨 → CRITICAL - asyncio 로거 레벨 WARNING
- asyncio 로거 레벨 → WARNING
- 커밋: adae74c - 커밋: adae74c
- 상태: 배포 완료, rb8001 컨테이너 정상 작동
**효과**: **효과**: BlockingIOError 로그 숨김, 실제 오류 추적 용이
- BlockingIOError 로그 숨김
- 실제 오류 추적 용이
- 기능 영향 없음 (로그만 억제)
--- ---
## 미해결 이슈 (51123 서버 작업 필요) ## 미해결 이슈 (51123 서버)
### 4. Slack 봇 설치 workspace_id 컬럼 오류 ⏸️ ### 4. Slack 봇 설치 workspace_id 컬럼 오류
**문제**: auth-server의 workspace_member 테이블에 workspace_id 컬럼 없음 **상태**: 해결 완료 (2025-10-16, 사용자 작업)
**위치**: `auth-server/app/providers/slack.py:408-418` **문제**: workspace_member 테이블에 workspace_id 컬럼 없음
**해결 방법**: **해결**: auth-server/app/providers/slack.py:414-419
- `workspace_member.workspace_id` → `user.team_id` 변경 - workspace_member.workspace_id → user.team_id 사용
- 또는 workspace_member 테이블에 workspace_id 컬럼 추가
**상태**: 51123 서버 작업 필요 (auth-server)
--- ---
## 배포 상태 ## 배포 상태
### skill-rag-file **skill-rag-file**: cea055c (healthy) - 중복 파일 멱등성 보장
- 커밋: cea055c **rb8001**: adae74c (healthy) - system UUID 처리 + gRPC 로그 억제
- 상태: Up (healthy)
- 변경: 중복 파일 멱등성 보장
### rb8001
- 커밋: adae74c
- 상태: Up (healthy)
- 변경: system UUID 처리 + gRPC 로그 억제
--- ---
## 검증 계획 ## 검증 계획
### 즉시 확인 ✅ ### 내일 실전 검증 (2025-10-17)
- [x] skill-rag-file 컨테이너 정상 작동
- [x] rb8001 컨테이너 정상 작동
- [x] 헬스체크 통과
### 내일 검증 (2025-10-17) **09:00 NaverWorks Briefing**:
- [ ] **09:00 NaverWorks Briefing**: system UUID 오류 로그 사라짐 확인 - system UUID 오류 로그 사라짐 확인
- [ ] **09:00 NaverWorks Briefing**: gRPC BlockingIOError 로그 사라짐 확인 - gRPC BlockingIOError 로그 사라짐 확인
- [ ] **09:05 Coldmail Briefing**: PDF 업로드 성공 확인
- [ ] **09:05 Coldmail Briefing**: IR 분석 실제 데이터 반환 확인
- [ ] **09:05 Coldmail Briefing**: Slack Lists 전송 성공 확인
### 로그 체크 포인트 **09:05 Coldmail Briefing**:
```bash - PDF 업로드 성공 확인
# NaverWorks Briefing (09:00) - IR 분석 실제 데이터 반환 확인
docker logs rb8001 --since "2025-10-17T09:00:00" | grep -iE "system|grpc|blocking" - Slack Lists 전송 성공 확인
# Coldmail Briefing (09:05) **로그 체크**:
docker logs rb8001 --since "2025-10-17T09:05:00" | grep -iE "upload|document_id" - rb8001: docker logs rb8001 --since "2025-10-17T09:00:00" | grep -iE "system|grpc|blocking"
docker logs skill-rag-file --since "2025-10-17T09:05:00" | grep "File already exists" - rb8001: docker logs rb8001 --since "2025-10-17T09:05:00" | grep -iE "upload|document_id"
``` - skill-rag-file: docker logs skill-rag-file --since "2025-10-17T09:05:00" | grep "File already exists"
--- ---
## 교훈 ## 교훈
### 1. 멱등성 설계 (Idempotency) ### 멱등성 설계
**원칙**: 동일 요청을 여러 번 실행해도 결과가 같아야 함 동일 요청 여러 번 실행 시 결과 동일해야 함. 중복 체크 시 에러가 아닌 기존 리소스 반환.
**적용**: 중복 체크 시 "에러"가 아닌 "기존 리소스 반환" ### 시스템 사용자 처리 정책
### 2. 시스템 사용자 처리 정책 시스템 작업의 user_id 처리 미정의. 단기는 skip, 장기는 전용 UUID 생성.
**문제**: 사용자가 아닌 시스템 작업의 user_id 처리 미정의 ### 로그 레벨 관리
**해결**: 외부 라이브러리 로그는 필요 시 레벨 조정으로 노이즈 제거.
- 단기: 시스템 user_id 감지 후 skip
- 장기: 전용 시스템 UUID 생성
### 3. 로그 레벨 관리 ### Cascading Failure 방지
**원칙**: 외부 라이브러리 로그는 필요 시 레벨 조정 한 단계 실패가 전체 워크플로우 실패로 연쇄되지 않도록 설계. 멱등성으로 안정화.
**적용**: gRPC, asyncio 로거 레벨 상향 조정
### 4. Cascading Failure 방지
**원칙**: 한 단계 실패가 전체 워크플로우 실패로 이어지지 않도록
**적용**:
- PDF 업로드 실패 → IR 분석 실패 → Slack 전송 실패 (연쇄)
- 멱등성으로 PDF 업로드 안정화
---
## 다음 단계
### 51124 서버 (완료)
- [x] Coldmail 중복 파일 처리 개선
- [x] NaverWorks system UUID 오류 해결
- [x] 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 브리핑 실행 시 실전 검증 예정.