docs: skill-rag-file 구축 완료 문서 정리

- Docker 빌드, SSHFS 볼륨, SQLAlchemy, ChromaDB 이슈 해결
- 77줄로 핵심 정보만 정리
- 서비스 정상 작동 확인

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

troubleshooting/250915_skill-rag-file_Docker_빌드_및_볼륨_마운트_문제.md

@@ -0,0 +1,77 @@
+# skill-rag-file 구축 완료
+
+## 작성일: 2025-09-15
+## 작성자: Claude & happybell80
+## 상태: ✅ 정상 작동 중
+
+## 1. 해결된 주요 이슈
+
+### Docker 빌드 - uv.lock 문제
+```dockerfile
+# 해결: uv.lock 없이 직접 설치
+RUN pip install --no-cache-dir uv && \
+    uv pip install --system --no-cache-dir .
+```
+
+### SSHFS 볼륨 충돌
+```yaml
+# 문제: Docker가 SSHFS 마운트 포인트에 mkdir 시도
+Error: mkdir /mnt/51123data: file exists
+
+# 해결: documents 볼륨 제거, network_mode: host로 직접 접근
+volumes:
+  - ./logs:/app/logs  # documents 볼륨 제거
+network_mode: host
+```
+
+### SQLAlchemy metadata 예약어
+```python
+# 변경: metadata → file_metadata
+file_metadata = Column(JSONB, default={})
+
+# Base.metadata.create_all() 제거 (테이블 이미 존재)
+```
+
+### ChromaDB 임베디드 모드
+```python
+# 변경 전: HttpClient (서버 모드, 포트 8000)
+self.client = chromadb.HttpClient(host, port)
+
+# 변경 후: PersistentClient (임베디드)
+self.client = chromadb.PersistentClient(path="./chroma_db")
+```
+
+## 2. 핵심 설정
+
+### pyproject.toml
+```toml
+chromadb==1.0.21  # 버전 업그레이드
+# readme = "README.md" 제거
+```
+
+### docker-compose.yml
+```yaml
+services:
+  skill-rag-file:
+    container_name: skill-rag-file
+    environment:
+      - PORT=8508
+      - DOCUMENT_BASE_PATH=/mnt/51123data/documents
+    volumes:
+      - ./logs:/app/logs
+      - ./.env:/app/.env:ro
+    network_mode: host
+```
+
+## 3. 서비스 정보
+- **포트**: 8508
+- **API 문서**: http://localhost:8508/docs
+- **파일 저장**: /mnt/51123data/documents (SSHFS → 51123 HDD)
+- **ChromaDB**: ./chroma_db (임베디드)
+- **PostgreSQL**: 51123 서버 team_document 테이블
+
+## 4. 최종 상태
+- ✅ 컨테이너 실행 중 (healthy)
+- ✅ 헬스체크 정상 (/healthz)
+- ✅ API 접근 가능
+- ✅ 파일 업로드/검색 준비 완료