Переносність даних

Libre WebUI експортує й імпортує версійований JSON-архів користувача через Налаштування → Керування даними. Архів переносить підтримувані особисті дані між установленнями або відновлює їх в обліковому записі. Це не повна резервна копія сервера.

Архів версії 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 як UTF-8. Імпорт відхиляє архів із невідповідним дайджестом, навіть якщо JSON синтаксично правильний.

Дайджест виявляє випадкове пошкодження й зміни після експорту. Це не цифровий підпис, не підтверджує автора й не забезпечує конфіденційність. Захищайте архів як копію приватних чатів і Нотаток.

Перед завантаженням експорт виконує ті самі перевірки схеми, розмірів полів, ID й кількості, що імпорт. Також перевіряє, що форматований JSON не перевищує 50 MiB. Замість непридатного файлу повертається точна помилка перевірки.

Поточні ліміти:

• 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 детерміновано замінює його та всі включені посилання, ніколи не читаючи й не перезаписуючи чужий ресурс. Посилання на виключені або недоступні ресурси, як-от персона з іншого встановлення, є задокументованим винятком: попередня перевірка повідомляє про від’єднання сеансу.

Результат показує кількість створених, перезаписаних і пропущених папок, сеансів, Нотаток, колекцій і документів. Після успіху Libre перезавантажує уподобання, чати й папки та оновлює документи.

Старі архіви

Імпортер приймає версію 2 libre-webui-user-data і мігрує її до 3. Версія 2 не мала дайджесту й Нотаток, тому Libre не може перевірити походження або відновити неекспортовані Нотатки; це показано в попередженні.

Також приймається колишній формат libre-webui-export версії 1.0. Він містив уподобання й лише завантажені в браузері сеанси. Масив documents завжди був порожній, без папок, Нотаток, колекцій або фрагментів. Обмеження показуються до імпорту.

Кінцеві точки HTTP

Усі точки потребують bearer-токена або сеансу користувача:

Метод	Кінцева точка	Призначення
GET	/api/preferences/export	Створити поточний архів v3
POST	/api/preferences/import/preflight	Перевірити й спланувати без запису
POST	/api/preferences/import	Перевірити й імпортувати транзакційно

Вебінтерфейс надсилає архів полем archive у multipart/form-data, а політику — полем strategy. Ліміт 50 MiB. Для менших міграцій POST також приймає JSON:

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

strategy дорівнює skip або overwrite. Для сумісності старе mergeStrategy: "merge" відповідає skip, а mergeStrategy: "replace" — overwrite.