SQLite 저장소
Libre WebUI는 기본적으로 애플리케이션 데이터를 SQLite에 저장합니다. 저장소 계층은 채팅, 메시지, 사용자, 환경 설정, 문서, 문서 청크, 페르소나, 플러그인 자격 증명, 메모리와 관련 메타데이터를 하나의 로컬 데이터베이스에 보관합니다.
데이터베이스 위치
소스에서 실행할 때 다음 순서로 위치가 정해집니다.
DATA_DIR가 설정되어 있으면 사용합니다. 상대 경로는 백엔드 디렉터리를 기준으로 해석됩니다.- 설정되어 있지 않으면
backend/data를 사용합니다.
이전 버전과의 호환성을 위해, 소스 프로필에 설정이 없고 기존 영구 저장소가 backend/backend/data뿐이면 이 위치를 계속 사용합니다. 두 위치 모두에 상태가 있으면 시작할 때 명시적으로 하나를 선택해야 하며, 데이터를 복사하거나 병합하지 않습니다.
패키징된 npm/Homebrew 실행기는 기본적으로 ~/.libre-webui를 사용하며, 명시적으로 설정한 상대 DATA_DIR는 호출자의 작업 디렉터리를 기준으로 해석합니다. Docker와 Kubernetes 배포에서는 절대 컨테이너 경로를 제공합니다.
SQLite 파일 이름은 data.sqlite입니다.
예시:
DATA_DIR=/var/lib/libre-webui
SQLite에 저장되는 항목
- 사용자와 역할
- 세션과 메시지
- 환경 설정과 UI 설정
- 문서와 청크
- 페르소나와 페르소나 설정
- 페르소나 메모리와 변경 상태
- 플러그인 자격 증명 및 해당 라우팅/인증 바인딩, 변수, 사용자별 활성화, 쓰기 가능한 정의의 승인, 검색된 모델 카탈로그
- 시스템 설정
- Work 작업 소유권, 모델/공급자 라우팅, 실행, 메시지, 도구 활동, 상태와 Docker 리소스 식별자
민감한 값은 암호화 저장소 도우미를 통과할 때 애플리케이션 계층에서 암호화됩니다.
분리된 Work 저장소
Work 대화와 작업 메타데이터는 SQLite에 저장되지만 Work 파일은 그렇지 않습니다. 각 작업에는 /workspace에 마운트되는 전용 Docker 명명 볼륨이 제공됩니다. 컨테이너는 교체할 수 있는 실행 상태이고, 명명 볼륨은 작업의 영구 파일 시스템입니다.
따라서 데이터베이스 백업만으로는 Work를 완전히 백업할 수 없습니다. Docker 호스트의 볼륨 백업 절차를 사용해 해당 Docker 볼륨도 백업하세요. Libre WebUI가 관리하는 Work 볼륨에는 ai.libre-webui.managed=true와 소유 작업 ID가 레이블로 지정됩니다.
Work 작업을 삭제하면 SQLite 레코드와 관리되는 명명 볼륨이 영구적으로 제거됩니다. 실행 취소, 미리 보기 중지 또는 백엔드 재시작으로는 파일이 삭제되지 않습니다.
JSON 호환성
이전 Libre WebUI 설치에서는 일부 데이터에 JSON 파일을 사용했습니다. 현재 빌드는 SQLite를 기본 저장 경로로 사용하고 저장소 접근을 서비스/모델 계층 뒤에 두므로, 나머지 앱은 영구 저장 형식을 알 필요가 없습니다.
이전 설치를 업그레이드한다면 새 백엔드를 시작하기 전에 전체 데이터 디렉터리를 백업하세요.
.status.json의 기존 플러그인 활성화 상태는 업그레이드 당시 존재하는 계정의 사용자별 SQLite 행으로 한 번만 마이그레이션되지만, 정확한 해시로 고정된 번들 정의에만 적용됩니다. 기존 사용자 정의 정의와 섀도 정의는 관리자가 다시 가져올 때까지 격리되며, 승인해도 이전 활성화 행은 복원되지 않습니다. 나중에 생성된 계정은 활성 플러그인이 없는 상태로 시작하며, 각 계정의 활성화 변경 사항은 독립적입니다.
백업
데이터베이스를 복사하기 전에 백엔드를 중지합니다.
cp -R backend/data backend/data.backup
DATA_DIR를 사용하는 배포의 경우:
cp -R "$DATA_DIR" "$DATA_DIR.backup"
인스턴스에서 Work를 사용한다면 백엔드가 중지된 동안 관리되는 모든 Work 명명 볼륨도 백업하세요. 데이터베이스, 암호화 키, Work 볼륨 백업은 동일한 시점의 것으로 보관해야 합니다.
복원
백엔드를 중지하고 데이터 디렉터리를 백업으로 교체한 다음 다시 시작합니다. 동일한 ENCRYPTION_KEY를 유지하세요. 다른 키로는 암호화된 값을 복호화할 수 없습니다.
Work의 경우 백엔드를 시작하기 전에 복원된 데이터베이스에 기록된 정확한 이름으로 명명 볼륨을 복원합니다. Libre WebUI는 작업 컨테이너를 다시 만들 수 있지만 누락된 워크스페이스 파일을 대화 기록에서 재구성할 수는 없습니다.
운영 참고 사항
- SQLite는 동시 읽기 성능을 높이기 위해 WAL을 활성화해 실행됩니다.
- 백엔드 프로세스가 데이터 디렉터리에 쓸 수 있어야 합니다.
- Docker와 Kubernetes에서는
DATA_DIR를 영구 저장소에 두세요. - 데이터베이스와 함께
ENCRYPTION_KEY도 백업하세요. - 저장소 크기를 측정하거나 마이그레이션 또는 복원할 때 Work 명명 볼륨은 별도로 계산하세요.