From 285c7c0a5ff627e19c75512fa6ede80f09d84a50 Mon Sep 17 00:00:00 2001
From: happybell80 <goeun2dcc@gmail.com>
Date: Thu, 31 Jul 2025 22:08:14 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20uv=20=ED=8C=A8=ED=82=A4=EC=A7=80=20?=
 =?UTF-8?q?=EB=A7=A4=EB=8B=88=EC=A0=80=20=EB=8F=84=EC=9E=85=20=ED=8A=B8?=
 =?UTF-8?q?=EB=9F=AC=EB=B8=94=EC=8A=88=ED=8C=85=20=EB=AC=B8=EC=84=9C=20?=
 =?UTF-8?q?=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 토크나이저 경고 해결 과정
- file-graph-visualizer에 uv 적용
- Docker 빌드 속도 90% 개선 성과
- CI/CD 배포 시간 단축 (2-3분 → 22초)
---
 ..._happybell80_uv패키지매니저도입.md | 120 ++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 troubleshooting/250731_happybell80_uv패키지매니저도입.md

diff --git a/troubleshooting/250731_happybell80_uv패키지매니저도입.md b/troubleshooting/250731_happybell80_uv패키지매니저도입.md
new file mode 100644
index 0000000..0ac1b62
--- /dev/null
+++ b/troubleshooting/250731_happybell80_uv패키지매니저도입.md
@@ -0,0 +1,120 @@
+# 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 설치**:
+```bash
+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 적용
+
+**실행 과정**:
+```bash
+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 수정**:
+```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 시간 대폭 감소
+- 빠른 배포 → 빠른 테스트 사이클
+
+## 교훈
+
+1. **uv의 강력한 성능**
+   - Python 패키지 설치 병목 현상 해결
+   - 특히 CI/CD 환경에서 극적인 효과
+   - 로컬 개발과 배포 모두에서 생산성 향상
+
+2. **점진적 도입 전략**
+   - 테스트 환경(rb10508_test)에서 먼저 검증
+   - 성공 확인 후 프로덕션(rb8001) 적용 예정
+   - 베이스 이미지에도 적용 가능성 검토
+
+3. **권한 문제 고려**
+   - Docker 환경에서는 pip로 uv 설치가 안전
+   - `--system` 플래그로 가상환경 없이 설치
+   - 기존 베이스 이미지와의 호환성 유지
+
+4. **개발 환경 개선**
+   - `source venv/bin/activate` 불필요
+   - `uv run` 명령으로 자동 가상환경 활성화
+   - 프로젝트별 독립성 유지하면서도 편의성 향상
\ No newline at end of file