데이터 이동성

Libre WebUI는 설정 → 데이터 관리에서 버전이 지정된 사용자별 JSON 아카이브를 내보내고 가져올 수 있습니다. 이 아카이브는 지원되는 개인 데이터를 Libre WebUI 설치 간에 이동하거나 계정으로 복원하기 위한 것이며, 완전한 서버 백업이 아닙니다.

아카이브 버전 3

현재 형식은 다음으로 식별됩니다.

{
  "format": "libre-webui-user-data",
  "version": 3,
  "integrity": {
    "algorithm": "sha256",
    "canonicalization": "libre-json-sort-v1",
    "digest": "<64 lowercase hexadecimal characters>"
  }
}

백엔드는 인증된 사용자 범위 데이터베이스 쿼리에서 내보내기를 만듭니다. 다음이 포함됩니다.

• 선택한 재사용 음성 프로필 참조를 제외한 사용자 환경 설정.
• 채팅 폴더.
• 채팅 세션, 메시지, 분기, 평가, 아티팩트, 채팅별 설정.
• 고정 상태를 포함한 독립형 노트.
• 지식 컬렉션.
• 추출한 문서 콘텐츠와 메타데이터, 세션/컬렉션 연결, 텍스트 청크.

문서 임베딩은 파생 데이터이므로 내보내지 않습니다. 의미 검색이 활성화되어 있으면 가져온 뒤 임베딩을 다시 생성하세요. 아카이브에는 원본 업로드 파일 바이트가 아니라 RAG에서 사용하는 추출 텍스트가 들어 있으므로 원본 업로드를 바이트 단위로 재현할 수 없습니다.

각 아카이브에는 exclusions 목록이 있습니다. 버전 3은 다음을 의도적으로 제외합니다.

• 계정, 비밀번호, 로그인 세션, OAuth 상태.
• 제공자 자격 증명과 암호화된 플러그인 변수.
• 생체 데이터이며 별도 동의 처리가 필요한 복제 음성 참조 녹음과 전사.
• 페르소나와 페르소나 메모리.
• 생성된 이미지, 오디오, 동영상 라이브러리 파일.
• 노트 버전 기록과 첨부 파일.
• Work 작업, 실행, 샌드박스, Docker 또는 Kubernetes 볼륨.

채널, 알림, 캘린더, 자동화도 이동식 아카이브 외부의 인스턴스/팀 상태이며 전체 서버 백업과 함께 이동합니다.

전체 서버 복구에는 동일한 ENCRYPTION_KEY를 사용하는 데이터베이스/데이터 디렉터리 백업을 사용하세요. Work에는 이름 있는 볼륨의 일관된 백업도 필요합니다. SQLite 마이그레이션 및 백업과 Work 워크스페이스를 참조하세요.

무결성 및 내보내기 검증

버전 3은 SHA-256 무결성 다이제스트로 아카이브 페이로드를 보호합니다. libre-json-sort-v1 표준 형식은 최상위 integrity 필드를 생략하고, 모든 JSON 객체 키를 사전순으로 정렬하며, 배열 순서를 유지하고, 결과로 생성된 압축 JSON을 UTF-8로 해시합니다. JSON 문법이 유효하더라도 다이제스트가 일치하지 않는 버전 3 아카이브는 가져오기를 거부합니다.

이 다이제스트는 우발적 손상과 내보내기 후 변경을 감지합니다. 디지털 서명이 아니며 파일 생성자를 인증하지 않고 아카이브를 기밀로 만들지도 않습니다. 사용자의 비공개 채팅과 노트를 복사한 다른 파일처럼 취급하세요.

다운로드를 제공하기 전에 내보내기는 가져오기와 동일한 스키마, 필드 크기, ID, 아카이브 수 검사를 실행합니다. 웹 UI에서 내려받는 보기 좋게 출력된 JSON이 50 MiB 업로드 제한보다 크지 않은지도 확인합니다. Libre WebUI가 이미 복원할 수 없음을 아는 파일을 제공하지 않고 정확한 검증 오류를 반환합니다.

현재 아카이브 및 계정 제한:

• 업로드 또는 생성 아카이브당 50 MiB.
• 채팅 폴더 100개.
• 채팅 세션 5,000개.
• 채팅 메시지 100,000개.
• 노트 100개. 제목 최대 200자, 콘텐츠 최대 200,000자.
• 지식 컬렉션 5,000개.
• 문서 5,000개.
• 문서 청크 100,000개.
• 일반 콘텐츠 필드 각각 최대 2,000,000자, ID 최대 256자. 런타임 리소스의 제한이 더 좁으면 그 값을 적용.

안전한 가져오기 동작

파일을 선택하면 백엔드가 즉시 사전 점검합니다. 최종 가져오기 작업을 활성화하기 전에 설정에 들어오는 합계, 예상 생성/덮어쓰기/건너뛰기 수, ID 재매핑, 마이그레이션 경고를 표시합니다. 충돌 정책을 바꾸면 새 미리보기를 계산해 표시합니다.

사전 점검은 가능한 경우 무결성 다이제스트를 확인하고, 지원되는 이전 형식을 마이그레이션하며, 전체 스키마, 리소스 수, 고유 ID, 타임스탬프, 콘텐츠 범위, 포함된 관계를 검증하고, 데이터를 쓰지 않고 충돌과 참조 재매핑을 계획합니다. 연결이 끊긴 폴더, 컬렉션, 메시지 부모, 문서 연결은 조용히 버리지 않고 거부합니다. 실제 가져오기에서도 검증과 충돌 계획을 반복합니다. 지원되는 SQLite 및 PostgreSQL 백엔드 모두에서 모든 쓰기가 하나의 데이터베이스 트랜잭션으로 이루어집니다. 오류가 발생하면 환경 설정, 폴더, 세션/메시지, 노트, 컬렉션, 문서, 청크를 함께 롤백합니다.

두 가지 충돌 정책을 사용할 수 있습니다.

• 중복 건너뛰기는 ID가 일치하는 레코드를 유지하고 새 레코드를 가져옵니다. 환경 설정은 계정의 현재 설정과 병합합니다.
• 기존 항목 덮어쓰기는 ID가 일치하는 레코드를 바꿉니다. 환경 설정은 Libre WebUI 기본값 위에 덮어씁니다. 아카이브에 없는 레코드는 삭제하지 않습니다.

두 정책 모두 ID가 일치하는 레코드에 대해 멱등적입니다. 대상 서버에서 ID를 다른 계정이 이미 소유하면 Libre WebUI는 결정적으로 해당 ID와 포함된 모든 참조를 재매핑합니다. 다른 사용자의 리소스를 덮어쓰거나 읽지 않습니다. 다른 설치의 페르소나처럼 제외되거나 사용할 수 없는 리소스 참조는 문서화된 예외로 남습니다. 사전 점검은 가져오기 전에 세션이 분리된다고 보고합니다.

설정에 표시되는 결과는 폴더, 세션, 노트, 컬렉션, 문서의 생성·덮어쓰기·건너뛰기 수를 보고합니다. 가져오기에 성공하면 Libre가 환경 설정, 채팅, 폴더를 다시 불러오고 문서를 새로 고칩니다.

이전 아카이브

가져오기는 버전 2 libre-webui-user-data 아카이브를 받아 검증 중 버전 3으로 마이그레이션합니다. 버전 2에는 무결성 다이제스트와 노트가 없었으므로 Libre는 출처를 검증하거나 내보내지 않은 노트를 복구할 수 없습니다. 사전 점검 미리보기에 두 제한이 모두 표시됩니다.

이전 libre-webui-export 버전 1.0 형식도 지원합니다. 브라우저가 생성한 이 형식에는 환경 설정과 해당 브라우저에 불러온 세션만 있었습니다. documents 배열은 항상 비어 있었고 폴더, 노트, 지식 컬렉션, 문서 청크도 없었습니다. Libre는 가져오기 전에 이러한 마이그레이션 제한을 보고합니다.

HTTP 엔드포인트

모든 엔드포인트에는 인증된 사용자의 Bearer 토큰 또는 세션이 필요합니다.

메서드	엔드포인트	용도
GET	/api/preferences/export	현재 사용자의 v3 아카이브 생성
POST	/api/preferences/import/preflight	쓰지 않고 검증 및 계획
POST	/api/preferences/import	검증 후 트랜잭션으로 가져오기

웹 UI는 아카이브를 archive라는 multipart/form-data 필드로, 충돌 정책을 strategy 필드로 보냅니다. 업로드 제한은 50 MiB입니다. 작은 API 기반 마이그레이션에서는 두 POST 엔드포인트가 JSON도 받습니다.

{
  "data": { "format": "libre-webui-user-data", "version": 3 },
  "strategy": "skip"
}

strategy는 skip 또는 overwrite입니다. 이전 환경 설정 전용 클라이언트와의 호환성을 위해 mergeStrategy: "merge"는 skip에, mergeStrategy: "replace"는 overwrite에 매핑됩니다.