Khả chuyển dữ liệu

Libre WebUI có thể xuất và nhập kho lưu trữ JSON có phiên bản theo từng người dùng từ Cài đặt → Quản lý dữ liệu. Kho lưu trữ dùng để di chuyển dữ liệu cá nhân được hỗ trợ giữa các bản cài Libre WebUI hoặc khôi phục dữ liệu đó vào tài khoản. Đây không phải bản sao lưu máy chủ đầy đủ.

Kho lưu trữ phiên bản 3

Định dạng hiện tại được nhận diện bằng:

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

Backend tạo bản xuất từ các truy vấn cơ sở dữ liệu đã xác thực và giới hạn theo người dùng. Nội dung gồm:

• tùy chọn người dùng, trừ tham chiếu hồ sơ giọng tái sử dụng đã chọn;
• thư mục trò chuyện;
• phiên trò chuyện, tin nhắn, nhánh, đánh giá, tạo tác và cài đặt theo cuộc trò chuyện;
• Ghi chú độc lập, gồm trạng thái ghim;
• bộ sưu tập kiến thức;
• nội dung và siêu dữ liệu tài liệu đã trích xuất, liên kết phiên/bộ sưu tập và các đoạn văn bản.

Embedding tài liệu không được xuất vì là dữ liệu dẫn xuất. Hãy tạo lại embedding sau khi nhập nếu bật truy xuất ngữ nghĩa. Kho lưu trữ mang văn bản đã trích xuất dùng cho RAG, không phải byte tệp tải lên ban đầu, nên không thể tái tạo bản tải lên gốc theo từng byte.

Mỗi kho lưu trữ có danh sách exclusions. Phiên bản 3 chủ ý loại trừ:

• tài khoản, mật khẩu, phiên đăng nhập và trạng thái OAuth;
• thông tin xác thực nhà cung cấp và biến plugin đã mã hóa;
• bản ghi tham chiếu và bản chép lời giọng nhân bản, vốn là dữ liệu sinh trắc học và cần xử lý riêng có xét đến sự đồng ý;
• persona và bộ nhớ persona;
• tệp thư viện hình ảnh, âm thanh và video đã tạo;
• lịch sử phiên bản và tệp đính kèm ghi chú;
• tác vụ, lượt chạy, sandbox và volume Docker hoặc Kubernetes của Work.

Kênh, thông báo, lịch và tự động hóa cũng nằm ngoài kho lưu trữ di động; chúng là trạng thái phiên bản/nhóm và được chuyển cùng bản sao lưu máy chủ đầy đủ.

Để khôi phục máy chủ đầy đủ, hãy dùng bản sao lưu cơ sở dữ liệu/thư mục dữ liệu với cùng ENCRYPTION_KEY. Work cũng cần bản sao lưu nhất quán của các volume có tên. Xem Di chuyển và sao lưu SQLite và Không gian làm việc Work.

Tính toàn vẹn và xác thực bản xuất

Phiên bản 3 bảo vệ payload kho lưu trữ bằng digest toàn vẹn SHA-256. Dạng chuẩn libre-json-sort-v1 bỏ trường integrity cấp cao nhất, sắp xếp khóa của mọi đối tượng JSON theo thứ tự từ điển, giữ thứ tự mảng và băm JSON rút gọn thu được dưới dạng UTF-8. Quá trình nhập từ chối kho lưu trữ phiên bản 3 có digest không khớp, dù JSON vẫn đúng cú pháp.

Digest này phát hiện hỏng hóc vô tình và thay đổi sau khi xuất. Nó không phải chữ ký số, không xác thực người tạo tệp và không làm kho lưu trữ trở nên bí mật. Hãy bảo vệ kho lưu trữ như mọi bản sao khác của các cuộc trò chuyện và Ghi chú riêng tư của người dùng.

Trước khi cho tải xuống, quá trình xuất chạy cùng các kiểm tra lược đồ, kích thước trường, ID và số lượng kho lưu trữ như khi nhập. Nó cũng xác minh JSON được định dạng đẹp mà UI web tải xuống không lớn hơn giới hạn tải lên 50 MiB. Quá trình xuất trả lỗi xác thực chính xác thay vì cung cấp tệp mà Libre WebUI đã biết không thể khôi phục.

Giới hạn kho lưu trữ và tài khoản hiện tại:

• 50 MiB cho mỗi kho lưu trữ được tải lên hoặc tạo;
• 100 thư mục trò chuyện;
• 5.000 phiên trò chuyện;
• 100.000 tin nhắn trò chuyện;
• 100 Ghi chú, tiêu đề tối đa 200 ký tự và nội dung tối đa 200.000 ký tự;
• 5.000 bộ sưu tập kiến thức;
• 5.000 tài liệu;
• 100.000 đoạn tài liệu;
• mỗi trường nội dung chung tối đa 2.000.000 ký tự và ID tối đa 256 ký tự, với giới hạn hẹp hơn khi tài nguyên runtime quy định.

Cách nhập an toàn

Khi chọn tệp, backend lập tức được yêu cầu kiểm tra sơ bộ. Cài đặt hiển thị tổng số đầu vào, số lượng dự kiến tạo/ghi đè/bỏ qua, ánh xạ lại ID và cảnh báo di chuyển trước khi bật hành động Nhập cuối cùng. Đổi chính sách xung đột sẽ tính và hiển thị bản xem trước mới.

Kiểm tra sơ bộ xác minh digest toàn vẹn nếu có, di chuyển định dạng cũ được hỗ trợ, xác thực toàn bộ lược đồ, số lượng tài nguyên, ID duy nhất, dấu thời gian, giới hạn nội dung và quan hệ đi kèm, đồng thời lập kế hoạch xử lý xung đột và ánh xạ lại tham chiếu mà không ghi dữ liệu. Liên kết thư mục, bộ sưu tập, cha tin nhắn hoặc tài liệu bị treo sẽ bị từ chối thay vì âm thầm bỏ. Backend lặp lại việc xác thực và lập kế hoạch xung đột cho lần nhập thực tế. Mọi thao tác ghi diễn ra trong một giao dịch cơ sở dữ liệu trên cả backend SQLite và PostgreSQL được hỗ trợ; nếu có lỗi, tùy chọn, thư mục, phiên/tin nhắn, Ghi chú, bộ sưu tập, tài liệu và đoạn đều được rollback cùng nhau.

Có hai chính sách xung đột:

• Bỏ qua bản trùng giữ các bản ghi có ID khớp và nhập bản ghi mới. Tùy chọn được hợp nhất với tùy chọn hiện tại của tài khoản.
• Ghi đè bản hiện có thay thế các bản ghi có ID khớp. Tùy chọn thay thế giá trị mặc định của Libre WebUI. Bản ghi không có trong kho lưu trữ không bao giờ bị xóa.

Cả hai chính sách đều có tính lũy đẳng với bản ghi có ID khớp. Nếu một ID đã thuộc tài khoản khác trên máy chủ đích, Libre WebUI ánh xạ lại nó và mọi tham chiếu đi kèm một cách xác định. Libre WebUI không bao giờ ghi đè hoặc đọc tài nguyên người dùng khác. Tham chiếu đến tài nguyên bị loại trừ hoặc không khả dụng, như persona từ bản cài khác, vẫn là ngoại lệ được ghi rõ: kiểm tra sơ bộ báo rằng phiên sẽ được tách trước khi nhập.

Kết quả trong Cài đặt báo số lượng đã tạo, ghi đè và bỏ qua cho thư mục, phiên, Ghi chú, bộ sưu tập và tài liệu. Sau khi nhập thành công, Libre nạp lại tùy chọn, trò chuyện và thư mục rồi làm mới tài liệu.

Kho lưu trữ cũ

Trình nhập chấp nhận kho lưu trữ libre-webui-user-data phiên bản 2 và di chuyển sang phiên bản 3 trong quá trình xác thực. Phiên bản 2 không có digest toàn vẹn và không chứa Ghi chú, nên Libre không thể xác minh nguồn gốc hoặc khôi phục Ghi chú chưa từng được xuất. Bản xem trước kiểm tra sơ bộ nêu rõ cả hai giới hạn.

Trình nhập cũng chấp nhận cấu trúc libre-webui-export phiên bản 1.0 trước đây. Định dạng do trình duyệt tạo chỉ chứa tùy chọn và các phiên được nạp trong trình duyệt đó. Mảng documents luôn trống và không chứa thư mục, Ghi chú, bộ sưu tập kiến thức hay đoạn tài liệu. Libre báo các giới hạn di chuyển này trước khi nhập.

Endpoint HTTP

Mọi endpoint đều yêu cầu token bearer hoặc phiên của người dùng đã xác thực:

Phương thức	Endpoint	Mục đích
GET	/api/preferences/export	Tạo kho lưu trữ v3 của người dùng hiện tại
POST	/api/preferences/import/preflight	Xác thực và lập kế hoạch không ghi
POST	/api/preferences/import	Xác thực và nhập theo giao dịch

UI web gửi kho lưu trữ dưới dạng trường multipart/form-data tên archive và chính sách xung đột dưới dạng trường strategy. Giới hạn tải lên là 50 MiB. Với di chuyển nhỏ hơn qua API, hai endpoint POST cũng chấp nhận JSON:

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

strategy là skip hoặc overwrite. Để tương thích với máy khách cũ chỉ xử lý tùy chọn, mergeStrategy: "merge" ánh xạ sang skip và mergeStrategy: "replace" ánh xạ sang overwrite.