Portabilitas Data

Libre WebUI dapat mengekspor dan mengimpor arsip JSON berversi per pengguna dari Pengaturan → Pengelolaan Data. Arsip ini ditujukan untuk memindahkan data pribadi yang didukung antarinstalasi Libre WebUI atau memulihkan data tersebut ke sebuah akun. Arsip ini bukan cadangan server lengkap.

Arsip Versi 3

Format saat ini dikenali melalui:

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

Backend membuat ekspor dari kueri database yang terautentikasi dan dibatasi untuk pengguna. Isinya meliputi:

• preferensi pengguna, kecuali referensi profil suara yang dapat digunakan ulang;
• folder chat;
• sesi chat, pesan, cabang, penilaian, artefak, dan pengaturan per chat;
• Catatan mandiri, termasuk status sematnya;
• koleksi pengetahuan;
• konten dan metadata dokumen hasil ekstraksi, asosiasi sesi/koleksi, serta potongan teks.

Embedding dokumen tidak diekspor karena merupakan data turunan. Buat ulang embedding setelah impor jika pengambilan semantik diaktifkan. Arsip membawa teks hasil ekstraksi yang digunakan RAG, bukan byte berkas asli yang diunggah, sehingga arsip tidak dapat membuat ulang unggahan asli byte demi byte.

Setiap arsip menyertakan daftar exclusions. Versi 3 sengaja mengecualikan:

• akun, kata sandi, sesi login, dan keadaan OAuth;
• kredensial penyedia dan variabel plugin terenkripsi;
• rekaman serta transkrip referensi suara hasil kloning, yang merupakan data biometrik dan memerlukan penanganan terpisah yang memperhatikan persetujuan;
• persona dan memori persona;
• berkas pustaka gambar, audio, dan video yang dihasilkan;
• riwayat revisi serta lampiran catatan;
• tugas, proses, sandbox, dan volume Docker atau Kubernetes milik Work.

Kanal, pemberitahuan, kalender, dan otomatisasi juga berada di luar arsip portabel; semuanya merupakan keadaan instans/tim dan ikut berpindah melalui cadangan server lengkap.

Gunakan cadangan database/direktori data dengan ENCRYPTION_KEY yang sama untuk pemulihan server lengkap. Work juga memerlukan cadangan yang konsisten untuk volume bernamanya. Lihat migrasi dan pencadangan SQLite serta ruang kerja Work.

Integritas dan Validasi Ekspor

Versi 3 melindungi payload arsip dengan digest integritas SHA-256. Bentuk kanonis libre-json-sort-v1 menghilangkan kolom integrity tingkat teratas, mengurutkan kunci setiap objek JSON secara leksikografis, mempertahankan urutan array, lalu melakukan hash terhadap JSON ringkas yang dihasilkan sebagai UTF-8. Impor menolak arsip versi 3 yang digest-nya tidak cocok, sekalipun JSON-nya tetap valid secara sintaksis.

Digest ini mendeteksi kerusakan tidak disengaja dan perubahan setelah ekspor. Digest ini bukan tanda tangan digital, tidak mengautentikasi pembuat berkas, dan tidak menjaga kerahasiaan arsip. Perlakukan arsip seperti salinan lain dari chat dan Catatan privat milik pengguna.

Sebelum menawarkan unduhan, ekspor menjalankan pemeriksaan skema, ukuran kolom, ID, dan jumlah arsip yang sama dengan pemeriksaan impor. Ekspor juga memastikan JSON berformat rapi yang diunduh UI web tidak lebih besar dari batas unggahan 50 MiB. Alih-alih menawarkan berkas yang sudah diketahui tidak dapat dipulihkan Libre WebUI, ekspor mengembalikan kesalahan validasi yang tepat.

Batas arsip dan akun saat ini:

• 50 MiB per arsip yang diunggah atau dibuat;
• 100 folder chat;
• 5.000 sesi chat;
• 100.000 pesan chat;
• 100 Catatan, dengan judul hingga 200 karakter dan isi hingga 200.000 karakter;
• 5.000 koleksi pengetahuan;
• 5.000 dokumen;
• 100.000 potongan dokumen;
• kolom konten umum individual hingga 2.000.000 karakter dan ID hingga 256 karakter, dengan batas lebih sempit jika sumber daya runtime memberlakukannya.

Perilaku Impor yang Aman

Saat berkas dipilih, backend langsung diminta melakukan pemeriksaan awal. Sebelum mengaktifkan tindakan Impor terakhir, Pengaturan menampilkan jumlah masuk, perkiraan jumlah pembuatan/penimpaan/pelewatan, pemetaan ulang ID, dan peringatan migrasi. Mengubah kebijakan konflik akan menghitung dan menampilkan pratinjau baru.

Pemeriksaan awal memverifikasi digest integritas jika tersedia, memigrasikan format lama yang didukung, memvalidasi seluruh skema, jumlah sumber daya, ID unik, stempel waktu, batas konten, serta relasi yang disertakan, lalu merencanakan konflik dan pemetaan ulang referensi tanpa menulis data. Asosiasi folder, koleksi, induk pesan, atau dokumen yang menggantung ditolak, bukan dibuang diam-diam. Backend mengulangi validasi dan perencanaan konflik untuk impor sebenarnya. Semua penulisan berlangsung dalam satu transaksi database pada backend SQLite maupun PostgreSQL yang didukung; kesalahan mengembalikan preferensi, folder, sesi/pesan, Catatan, koleksi, dokumen, dan potongan secara bersamaan.

Tersedia dua kebijakan konflik:

• Lewati duplikat mempertahankan rekaman dengan ID yang cocok dan mengimpor rekaman baru. Preferensi digabungkan dengan preferensi akun saat ini.
• Timpa yang ada mengganti rekaman dengan ID yang cocok. Preferensi menggantikan nilai bawaan Libre WebUI. Rekaman yang tidak ada dalam arsip tidak pernah dihapus.

Kedua kebijakan bersifat idempoten untuk rekaman dengan ID yang cocok. Jika sebuah ID sudah dimiliki akun lain pada server tujuan, Libre WebUI memetakan ulang ID tersebut dan setiap referensi yang disertakan secara deterministik. Libre WebUI tidak pernah menimpa atau membaca sumber daya pengguna lain. Referensi ke sumber daya yang dikecualikan atau tidak tersedia, seperti persona dari instalasi lain, tetap menjadi pengecualian terdokumentasi: pemeriksaan awal melaporkan bahwa sesi akan dilepaskan sebelum impor.

Hasil di Pengaturan melaporkan jumlah yang dibuat, ditimpa, dan dilewati untuk folder, sesi, Catatan, koleksi, serta dokumen. Setelah impor berhasil, Libre memuat ulang preferensi, chat, dan folder lalu menyegarkan dokumen.

Arsip Lama

Pengimpor menerima arsip libre-webui-user-data versi 2 dan memigrasikannya ke versi 3 selama validasi. Versi 2 tidak memiliki digest integritas dan tidak memuat Catatan, sehingga Libre tidak dapat memverifikasi asalnya atau memulihkan Catatan yang tidak pernah diekspor. Pratinjau pemeriksaan awal menyatakan kedua batasan tersebut.

Pengimpor juga menerima bentuk lama libre-webui-export versi 1.0. Format yang dibuat peramban tersebut memuat preferensi dan hanya sesi yang dimuat dalam peramban itu. Array documents selalu kosong, dan format tersebut tidak memuat folder, Catatan, koleksi pengetahuan, atau potongan dokumen. Libre melaporkan keterbatasan migrasi ini sebelum impor.

Endpoint HTTP

Semua endpoint memerlukan token bearer atau sesi pengguna yang terautentikasi:

Metode	Endpoint	Tujuan
GET	/api/preferences/export	Membuat arsip v3 pengguna saat ini
POST	/api/preferences/import/preflight	Memvalidasi dan merencanakan tanpa menulis
POST	/api/preferences/import	Memvalidasi dan mengimpor secara transaksional

UI web mengirim arsip sebagai kolom multipart/form-data bernama archive dan kebijakan konflik sebagai kolom strategy. Batas unggahan adalah 50 MiB. Untuk migrasi berbasis API yang lebih kecil, kedua endpoint POST juga menerima JSON:

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

strategy dapat berupa skip atau overwrite. Demi kompatibilitas dengan klien lama yang hanya menangani preferensi, mergeStrategy: "merge" dipetakan ke skip dan mergeStrategy: "replace" dipetakan ke overwrite.