진단 도구
Elftia에는 문제 해결, 로그 수집, 캐시 관리, 데이터베이스 최적화를 돕는 완전한 내장 진단 도구 세트가 있습니다. 모든 진단 기능은 설정 → 시스템 페이지에 있습니다.
진단 정보 내보내기
진단 내보내기
Elftia 런타임에서 전체 진단 정보를 수집하고 공유 가능한 파일로 패키징합니다.
단계:
- 설정 → 시스템을 엽니다.
- "진단 및 캐시" 영역에서 진단 내보내기 버튼을 클릭합니다.
- 시스템이 정보 수집을 시작합니다(버튼에
Collecting...표시). - 수집이 완료되면 저장 위치를 선택합니다.
포함되는 정보:
| 콘텐츠 | 설명 |
|---|---|
| 앱 버전 | Elftia 버전, Electron 버전 |
| 운영 체제 | OS 유형, 버전, 아키텍처 |
| 런타임 환경 | Node.js 버전, 메모리 사용량, CPU 정보 |
| Provider 구성 | 구성된 providers 목록 및 상태(API Keys 제외) |
| MCP 서버 | 구성된 MCP 서버 목록 및 연결 상태 |
| 앱 설정 | 현재 앱 구성(민감 정보 제거됨) |
| 런타임 로그 | 최근 앱 런타임 로그 |
| 데이터베이스 상태 | 데이터베이스 크기, 테이블 통계 |
내보낸 진단 정보는 민감 정보가 제거되며 API Keys, 비밀번호 또는 기타 민감한 정보를 포함하지 않습니다. 진단 파일은 기술 지원이나 커뮤니티와 안전하게 공유할 수 있습니다.
내보내기 형식 옵션
진단 정보는 여러 내보내기 형식을 지원합니다.
| 형식 | 설명 | 권장 대상 |
|---|---|---|
| JSON | 단일 JSON 파일 | 빠른 공유, 온라인 보기 |
| ZIP | 전체 진단 패키지 | 상세 문제 해결을 위한 로그 파일 및 전체 정보 포함 |
진단 로그 복사
채팅이나 이슈 피드백에 빠르게 붙여넣을 수 있도록 진단 로그를 클립보드에 직접 복사합니다.
- 진단 로그 복사 버튼을 클릭합니다.
- 로그 내용이 클립보드에 복사됩니다.
- 필요한 곳에 붙여넣습니다.
진단 로그 보기
진단 내보내기 또는 진단 로그 복사 작업 후, 진단 결과가 페이지 아래쪽의 로그 영역에 초록색 고정폭 글꼴로 표시됩니다. 페이지에서 진단 정보를 직접 보고 검토할 수 있습니다.
캐시 관리
캐시 지우기
모델 목록 캐시, 검색 캐시 등을 포함한 Elftia의 로컬 캐시 데이터를 지웁니다.
단계:
- 캐시 지우기 버튼(빨간 위험 버튼)을 클릭합니다.
- 지우기가 완료될 때까지 기다립니다(버튼에
Clearing...표시). - 완료 후 페이지에 지우기 결과가 표시됩니다.
지워지는 콘텐츠:
- 모델 목록 캐시(다음 사용 시 다시 가져옵니다)
- 웹 검색 결과 캐시
- 파일 검색 인덱스 캐시
- 썸네일 캐시
- API Key 풀 런타임 캐시
지워지지 않는 콘텐츠:
- 채팅 기록
- 사용자 설정
- API Keys 및 provider 구성
- MCP 서버 구성
- 테마 설정
모델 목록이 업데이트되지 않거나 캐시 데이터가 오래된 것 같은 문제가 발생하면 보통 캐시를 지우면 해결됩니다. 캐시 지우기는 데이터와 구성에 영향을 주지 않습니다.
첨부 파일 정리
메시지와 연결되지 않은 고아 첨부 파일을 정리해 디스크 공간을 확보합니다.
단계:
- 첨부 파일 정리 버튼을 클릭합니다.
- 시스템이 모든 첨부 파일을 스캔하고 어떤 메시지에서도 참조되지 않는 고아 파일을 식별합니다.
- 고아 파일을 안전하게 삭제합니다.
- 정리 결과(삭제된 파일 수와 확보된 공간)를 표시합니다.
이 작업은 참조되지 않음이 확인된 첨부 파일만 정리하며 정상 채팅의 첨부 파일에는 영향을 주지 않습니다.
데이터베이스 유지 관리
데이터베이스 크기
페이지에는 현재 SQLite 데이터베이스 파일 크기가 표시됩니다. 채팅 기록이 늘어날수록 데이터베이스는 점차 커집니다.
VACUUM 최적화
SQLite는 데이터를 삭제한 뒤 디스크 공간을 자동으로 회수하지 않습니다. VACUUM 작업은 데이터베이스 파일을 다시 빌드해 삭제된 데이터가 차지하던 공간을 회수합니다.
단계:
- 데이터베이스 유지 관리 영역에서 VACUUM 버튼을 클릭합니다.
- 작업이 완료될 때까지 기다립니다(버튼이 진행 중 상태로 표시됨).
- 완료 후 최적화 결과와 새 데이터베이스 크기가 표시됩니다.
참고:
- VACUUM 작업은 일시적으로 데이터베이스 복사본을 생성하므로 디스크에 충분한 공간(데이터베이스 크기의 약 2배)이 있는지 확인하세요.
- 작업 중에는 애플리케이션을 닫지 마세요.
- 큰 데이터베이스의 VACUUM은 몇 초에서 수십 초가 걸릴 수 있습니다.
권장 빈도:
- 일반 사용: 한 달에 한 번.
- 채팅을 대량 삭제한 후: 즉시 실행하는 것을 권장합니다.
- 데이터베이스가 비정상적으로 큰 경우: 삭제되었지만 회수되지 않은 공간이 있을 수 있으며, VACUUM으로 크기를 크게 줄일 수 있습니다.
리소스 정리
고아 리소스 정리
안전하게 정리할 수 있는 고아 리소스 파일의 개수와 총 크기를 표시하고, 한 번의 클릭으로 정리할 수 있습니다.
단계:
- "정리 가능 개수"와 "정리 가능 크기"를 확인합니다.
- 리소스 정리 버튼을 클릭해 정리를 실행합니다.
- 완료 후 결과가 표시됩니다.
환경 감지
설정 → 일반 → 환경에 있습니다.
환경 감지는 시스템에서 개발 도구의 설치 상태를 스캔합니다.
| 도구 | 감지 | 표시 정보 |
|---|---|---|
| Node.js | node --version | 버전, 설치 경로 |
| Git | git --version | 버전, 설치 경로 |
| ripgrep | rg --version | 버전, 설치 경로 |
| uv | uv --version | 버전, 설치 경로 |
| uvx | uvx --version | 버전, 설치 경로 |
각 도구에는 상태 표시기가 있습니다.
- 초록색 점(설치됨): 버전과 설치 경로를 표시합니다.
- 빨간색 점(설치되지 않음): 자동 설치가 지원되는 경우 "설치" 버튼을 표시합니다.
자동 설치
일부 도구는 Elftia에서 직접 원클릭 설치를 지원합니다.
- 설치되지 않은 도구 옆의 설치 버튼을 클릭합니다.
- 버튼이 "Installing..."으로 바뀌고 설치 진행 상황을 표시합니다.
- 설치가 완료되면 상태가 자동으로 업데이트됩니다.
현재 자동 설치를 지원하는 도구: ripgrep, uv, uvx.
Node.js와 Git은 공식 웹사이트에서 수동으로 다운로드해 설치해야 합니다.
개발자 모드 진단
개발자 모드(설정 → 정보에서 버전 번호를 계속 클릭)를 활성화하면 추가 진단 기능을 사용할 수 있습니다.
DevTools
개발자 모드에서는 설정 → 정보에서 Electron DevTools를 열거나 닫을 수 있습니다.
- Console: 자세한 오류 메시지와 디버그 로그를 포함한 앱 JavaScript 로그를 봅니다.
- Network: 자세한 LLM API 호출 요청 및 응답을 포함한 모든 네트워크 요청을 봅니다.
- Elements: DOM 구조를 검사해 UI 문제를 찾습니다.
디버깅에 DevTools 사용하기
- 개발자 모드를 활성화합니다.
- 정보 페이지에서 Open DevTools 버튼을 클릭합니다.
- DevTools 창이 열린 후 Console 탭으로 전환합니다.
- 로그 출력을 관찰합니다. 오류 메시지는 보통 빨간색으로 표시됩니다.
- 네트워크 문제의 경우 Network 탭으로 전환해 실패한 요청을 확인합니다.
커뮤니티나 기술 지원에 문제를 보고할 때, 진단 내보내기 파일 외에도 DevTools Console의 오류 로그는 매우 유용한 문제 해결 정보입니다. Console에서 로그를 마우스 오른쪽 버튼으로 클릭하고 "Save as"를 선택해 전체 로그를 저장할 수 있습니다.
기타 진단 기능
첨부 파일 지표
시스템 탭에서 첨부 파일 관련 통계를 봅니다.
- 전체 첨부 파일 수
- 첨부 파일이 차지하는 디스크 공간
- 고아 첨부 파일의 수와 크기
캐시 지표
여러 캐시의 크기와 적중률을 봅니다.
- 파일 검색 캐시
- 모델 목록 캐시
- 썸네일 캐시
- 파일 트리 캐시
런타임 예산
애플리케이션의 리소스 소비를 이해할 수 있도록 리소스 사용량의 런타임 예산 개요를 봅니다.
데이터베이스 페이지네이션 지표
데이터베이스 관련 성능 문제를 진단하기 위해 데이터베이스 페이지네이션 쿼리의 성능 지표를 봅니다.
진단 문제 해결 흐름
문제가 발생하면 다음 순서로 문제를 해결하는 것을 권장합니다.
- 정보 수집: 진단 내보내기를 클릭해 진단 정보를 내보냅니다.
- 로그 검토: 진단 로그에서 오류 메시지를 검색합니다.
- 환경 확인: 환경 도구의 설치 상태를 확인합니다.
- 캐시 지우기: 캐시 지우기를 실행해 오래되었을 수 있는 캐시를 제거합니다.
- 데이터베이스 최적화: VACUUM을 실행해 데이터베이스를 최적화합니다.
- 앱 재시작: Elftia를 재시작해 문제가 해결되었는지 테스트합니다.
- DevTools 활성화: 위 단계로 해결되지 않으면 개발자 모드를 활성화해 DevTools로 심층 디버깅합니다.
진단 도구가 특정 오류 메시지를 표시하는 경우 일반적인 문제 또는 연결 오류를 참조해 해당 해결 방법을 찾으세요.