증상 및 재현 조건
아래 순서로 100% 재현됩니다. 신규 구축 환경에서 특히 자주 발생합니다.
Dify Docker Compose 신규 구축
langgenius/dify-web:1.14.1 이미지 기준으로 재현됨
지식베이스 파일 업로드 및 인덱싱 완료
Qdrant 벡터화까지 정상 완료 — 백엔드 worker 로그에서도 정상 확인됨
검색 테스트 실행 → 렌더링 오류 발생
“이 컴포넌트를 렌더링하는 동안 예기치 않은 오류가 발생했습니다” 표시
검색 결과 클릭 → 동일 오류 재발생
상세 모달을 열 때도 동일한 버그 — 두 개의 컴포넌트에 각각 존재
at 0zbj41-miu3gf.js:1:21957
문서를 삭제하고 다시 올려도 동일하게 발생합니다. 데이터 문제가 아니라 프론트엔드 코드의 null 방어 처리 누락이 원인입니다.
원인 분석
브라우저 콘솔 오류와 GitHub 이슈 #12564를 분석한 결과, 두 개의 프론트엔드 컴포넌트에서 동일한 패턴의 버그가 확인됐습니다. 검색 API 반환 결과 중 document.name이 null인 항목이 있을 때 .split()을 호출하면서 TypeError가 발생하고 React 렌더링 전체가 중단됩니다.
문제 파일 1 — 검색 결과 목록
web/app/components/datasets/hit-testing/components/result-item.tsx// ❌ 수정 전 - const extension = document.name.split('.').slice(-1)[0] as FileAppearanceTypeEnum // ✅ 수정 후 + const extension = (document?.name?.split('.').slice(-1)[0] ?? '') as FileAppearanceTypeEnum
문제 파일 2 — 검색 결과 상세 모달
web/app/components/datasets/hit-testing/components/chunk-detail-modal.tsx// ❌ 수정 전 - const extension = document.name.split('.').slice(-1)[0] as FileAppearanceTypeEnum // ✅ 수정 후 + const extension = (document?.name?.split('.').slice(-1)[0] ?? '') as FileAppearanceTypeEnum
result-item.tsx만 고치면 검색 결과 클릭 시 chunk-detail-modal.tsx에서 동일한 오류가 다시 발생합니다.
⚠️ 빌드 전 필수 — 데이터 손실 방지
Docker 빌드 시 build context가 전체 프로젝트 폴더를 읽습니다. docker/volumes/에 PostgreSQL·Redis·Qdrant 데이터가 있는데, 권한 문제가 발생한 상태에서 컨테이너를 재시작하면 DB가 초기화되어 모든 데이터가 사라질 수 있습니다. 실제로 이 과정에서 데이터가 손실된 사례가 있습니다.
조치 1 — .dockerignore에 volumes 제외 추가
# .dockerignore에 추가 echo "docker/volumes" >> .dockerignore # 확인 cat .dockerignore
조치 2 — 권한 오류 발생 시 volumes 임시 이동 절차
volumes가 제자리에 없는 상태에서 docker compose up을 실행하면 DB가 신규 초기화됩니다. volumes 복원 전에는 절대로 docker compose up을 실행하지 마세요.
# 1. 컨테이너 중지 (down이 아닌 stop) docker compose stop # 2. volumes 임시 이동 (삭제 절대 아님) sudo mv docker/volumes /tmp/dify-volumes-backup # 3. 빌드 실행 docker build -t langgenius/dify-web:1.14.1-patched -f web/Dockerfile . # 4. 빌드 완료 즉시 복원 — 절대 빠뜨리지 마세요 sudo mv /tmp/dify-volumes-backup docker/volumes # 5. 복원 확인 후 시작 ls docker/volumes/db/data/ docker compose up -d
핵심 원칙: volumes 이동 → 빌드 → volumes 즉시 복원 → 시작 순서를 반드시 지켜야 합니다. 빌드와 복원 사이에 컨테이너를 시작하면 데이터가 손실됩니다.
단계별 해결 방법
1단계 — 소스 클론 및 버전 체크아웃
git clone https://github.com/langgenius/dify.git cd dify git checkout 1.14.1
2단계 — result-item.tsx 패치
# 33번 라인 삭제 후 수정본 입력 vi web/app/components/datasets/hit-testing/components/result-item.tsx # :33 → dd → i → 아래 코드 입력 → Esc → :wq const extension = (document?.name?.split('.').slice(-1)[0] ?? '') as FileAppearanceTypeEnum # 수정 확인 grep -n "document.*name.*split" \ web/app/components/datasets/hit-testing/components/result-item.tsx
3단계 — chunk-detail-modal.tsx 패치
# 35번 라인 삭제 후 수정본 입력 vi web/app/components/datasets/hit-testing/components/chunk-detail-modal.tsx # :35 → dd → i → 아래 코드 입력 → Esc → :wq const extension = (document?.name?.split('.').slice(-1)[0] ?? '') as FileAppearanceTypeEnum # 수정 확인 grep -n "document.*name.*split" \ web/app/components/datasets/hit-testing/components/chunk-detail-modal.tsx
4단계 — 빌드 및 재시작
# 빌드 docker build -t langgenius/dify-web:1.14.1-patched -f web/Dockerfile . # docker-compose.yaml 이미지명 변경 sed -i 's|langgenius/dify-web:1.14.1|langgenius/dify-web:1.14.1-patched|g' docker/docker-compose.yaml # 재시작 cd docker && docker compose down && docker compose up -d # 확인 docker ps | grep dify-web
docker ps | grep dify-web 결과에 1.14.1-patched가 표시되면 정상 적용된 것입니다.
빌드 후 검증 방법
Ctrl+Shift+R (Mac: Cmd+Shift+R)로 캐시를 초기화한 후 테스트하세요.
- ✓지식베이스 파일 업로드 — Knowledge → Create Knowledge → 파일 업로드 → 인덱싱 완료 확인
- ✓검색 테스트 실행 — Hit Testing 탭에서 검색어 입력 후 결과가 정상 표시되는지 확인
- ✓검색 결과 클릭 — 결과 카드 클릭 시 상세 모달이 정상적으로 열리는지 확인
- ✓챗봇 RAG 테스트 — 지식베이스를 연결한 앱에서 문서 내용을 질문하여 정상 답변 확인
- !콘솔 확인 — F12 → Console 탭에서 TypeError가 더 이상 발생하지 않는지 확인
추천 LLM · Embedding 모델 (Ollama 기준)
Dify 셀프호스팅 환경에서 Ollama와 연동해 완전 로컬로 운용할 때 추천하는 모델 조합입니다.
LLM 모델 비교
| 모델 | VRAM | 한국어 | 영어 논문 | Function Call | Context |
|---|---|---|---|---|---|
qwen2.5:14b-instruct-q4_K_M | ~9GB | 최우수 | 우수 | 지원 | 128K |
mistral-nemo:12b | ~7GB | 보통 | 우수 | 지원 | 128K |
qwen2.5:7b | ~5GB | 우수 | 양호 | 지원 | 128K |
gemma4:e4b | ~10GB | 양호 | 우수 | 지원 | 128K |
Embedding 모델 비교
한국어 포함 100개+ 언어 지원. 다국어 RAG 환경 최적. VRAM ~1.2GB. Max tokens 8192, Dimensions 1024.
영어 특화, 매우 가볍고 빠름(274MB). 영어 전용 문서 처리 시 적합. Dimensions 768.
Settings → Model Provider → Ollama. Docker 환경에서 http://host.docker.internal:11434, Linux에서는 http://172.17.0.1:11434를 사용합니다.
정리 및 교훈
| 항목 | 내용 |
|---|---|
| 버그 위치 | result-item.tsx, chunk-detail-modal.tsx 각 1곳 |
| 원인 | document.name이 null일 때 .split() 호출로 TypeError 발생 |
| 수정 방법 | Optional chaining(?.) + Nullish coalescing(??) 적용 |
| 빌드 방법 | 소스 패치 후 docker build -f web/Dockerfile . |
| 가장 중요한 것 | 빌드 전 .dockerignore에 docker/volumes 제외 필수 |
| 공식 수정 여부 | GitHub PR #12612 머지됨, 차기 버전에 반영 예정 |
Dify 버전 업그레이드 시 docker-compose.yaml의 web 이미지가 원래 버전으로 덮어씌워질 수 있습니다. 업그레이드 전에 해당 버그가 공식 반영됐는지 GitHub 릴리즈 노트를 확인하세요.
