Claude-51124 22557e7132 docs: 오래된 트러블슈팅 아카이브 및 구조 정리

- 7-8월 초기 구축 문서 12개를 _archive/troubleshooting/2025_07-08_initial_setup/로 이동
- book/300_architecture/390_human_in_the_loop_intent_learning.md를 journey/research/intent_classification/로 이동 (개발 여정 문서)
- 빈 폴더 제거 (journey/assets/*)

2025-11-17 14:06:05 +09:00

3.3 KiB

Raw Blame History

uv 패키지 매니저 도입 및 CI/CD 빌드 속도 개선

날짜: 2025-07-31
작업자: happybell80 & Claude
관련 프로젝트: rb10508_test, file-graph-visualizer

오후 9시 30분

문제 상황

토크나이저 경고 분석:

ChromaDB의 SentenceTransformer 사용 시 토크나이저 병렬 처리 경고 발생
The current process just got forked. Disabling parallelism to avoid deadlocks...
FastAPI 같은 비동기 환경에서 fork() 시 데드락 가능성

해결:

docker-compose.yml에 TOKENIZERS_PARALLELISM=false 환경변수 추가
rb10508_test에만 먼저 적용 (테스트 우선 원칙)

오후 9시 45분

file-graph-visualizer 실행 문제

문제:

python visualize_refined.py 실행 시 모듈 없음 오류
가상환경 활성화 필요

uv 도입 결정:

Rust 기반 초고속 Python 패키지 매니저
pip보다 10-100배 빠른 설치 속도
가상환경 관리 통합

uv 설치:

curl -LsSf https://astral.sh/uv/install.sh | sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

오후 9시 50분

file-graph-visualizer에 uv 적용

실행 과정:

cd file-graph-visualizer
uv venv                    # 가상환경 생성 (.venv)
uv pip install -r requirements.txt  # 21개 패키지 0.3초만에 설치!
uv run python visualize_refined.py  # 가상환경 자동 활성화 후 실행

결과:

rb10508_test 분석 성공
31개 파일, 82개 함수 시각화
웹서버 http://localhost:3300 에서 확인 가능

오후 10시 00분

rb10508_test Docker 빌드에 uv 적용

Dockerfile 수정:

# 변경 전
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --upgrade -r requirements.txt

# 변경 후
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --upgrade pip uv && \
    uv pip install --system --upgrade -r requirements.txt

권한 고려사항:

curl로 직접 설치 대신 pip로 uv 설치 (권한 문제 방지)
--system 플래그로 시스템 전역 설치
베이스 이미지(chroma_vector:1.0)와 호환성 유지

오후 10시 05분

배포 및 성과 측정

Gitea Actions 빌드 시간:

Set up job: 1s
Checkout for validation: 1s
Basic file validation: 0s
Setup SSH: 0s
Test SSH Connection: 0s
Deploy to 51124 Server: 22s  ← 핵심 개선!
Cleanup: 0s
Final Summary: 0s
Complete job: 1s

성과:

Deploy 단계: 2-3분 → 22초 (90% 이상 단축)
전체 CI/CD 시간 대폭 감소
빠른 배포 → 빠른 테스트 사이클

교훈

uv의 강력한 성능
- Python 패키지 설치 병목 현상 해결
- 특히 CI/CD 환경에서 극적인 효과
- 로컬 개발과 배포 모두에서 생산성 향상
점진적 도입 전략
- 테스트 환경(rb10508_test)에서 먼저 검증
- 성공 확인 후 프로덕션(rb8001) 적용 예정
- 베이스 이미지에도 적용 가능성 검토
권한 문제 고려
- Docker 환경에서는 pip로 uv 설치가 안전
- --system 플래그로 가상환경 없이 설치
- 기존 베이스 이미지와의 호환성 유지
개발 환경 개선
- source venv/bin/activate 불필요
- uv run 명령으로 자동 가상환경 활성화
- 프로젝트별 독립성 유지하면서도 편의성 향상

3.3 KiB Raw Blame History