قابلية نقل البيانات
يستطيع 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>"
}
}
ينشئ الخادم الخلفي التصدير من استعلامات قاعدة بيانات موثقة ومقصورة على المستخدم. ويحتوي على:
- تفضيلات المستخدم، باستثناء مرجع ملف صوت قابل لإعادة الاستخدام محدد؛
- مجلدات المحادثة؛
- جلسات المحادثة ورسائلها وفروعها وتقييماتها وعناصرها المنشأة وإعدادات كل محادثة؛
- Notes المستقلة، بما فيها حالة التثبيت؛
- مجموعات المعرفة؛
- محتوى المستندات المستخرج وبياناته الوصفية، وارتباطات الجلسات/المجموعات، ومقاطع النص.
لا تُصدر تضمينات المستندات لأنها بيانات مشتقة. أعد إنشاءها بعد الاستيراد عند تفعيل الاسترجاع الدلالي. يحمل الأرشيف النص المستخرج الذي يستخدمه RAG، لا بايتات الملف الأصلي، ولذلك لا يمكنه إعادة إنشاء الملف المرفوع بايتًا ببايت.
يتضمن كل أرشيف قائمة exclusions. ويستبعد الإصدار 3 عمدًا:
- الحسابات وكلمات المرور وجلسات الدخول وحالة OAuth؛
- بيانات اعتماد المزوّدين ومتغيرات المكونات المشفرة؛
- تسجيلات الأصوات المستنسخة المرجعية ونصوصها، لأنها بيانات حيوية تتطلب معالجة مستقلة تراعي الموافقة؛
- الشخصيات وذاكرتها؛
- ملفات مكتبة الصور والصوت والفيديو المولّدة؛
- سجل مراجعات الملاحظات ومرفقاتها؛
- مهام Work وتشغيلاتها وبيئاتها المعزولة ووحدات Docker أو Kubernetes.
كما تقع القنوات والإشعارات والتقاويم والأتمتة خارج الأرشيف المحمول؛ فهي حالة مثيل/فريق وتنتقل مع نسخة احتياطية كاملة للخادم.
لاستعادة الخادم كاملة، استخدم نسخة احتياطية من قاعدة البيانات/دليل البيانات مع ENCRYPTION_KEY نفسه. ويتطلب Work نسخة متسقة من وحداته المسماة. راجع ترحيل SQLite والنسخ الاحتياطي ومساحات عمل Work.
سلامة الأرشيف والتحقق من التصدير
يحمي الإصدار 3 حمولة الأرشيف ببصمة سلامة SHA-256. يحذف الشكل القياسي libre-json-sort-v1 حقل integrity العلوي، ويرتب مفاتيح كل كائن JSON معجميًا، ويحافظ على ترتيب المصفوفات، ويجزّئ JSON المضغوط الناتج بترميز UTF-8. ويرفض الاستيراد أرشيف إصدار 3 لا تطابق بصمته، حتى لو ظل JSON صالحًا نحويًا.
تكشف البصمة التلف العرضي والتغييرات اللاحقة للتصدير. وهي ليست توقيعًا رقميًا، ولا تثبت منشئ الملف، ولا تجعل الأرشيف سريًا. تعامل معه مثل أي نسخة أخرى من محادثات المستخدم وNotes الخاصة.
قبل إتاحة التنزيل، يجري التصدير فحوص المخطط وحجم الحقول والمعرفات وعدد عناصر الأرشيف نفسها التي يستخدمها الاستيراد. ويتحقق أيضًا من ألا يتجاوز JSON المنسق الذي تنزله الواجهة حد الرفع 50 MiB. ويعيد خطأ تحقق دقيقًا بدلًا من تقديم ملف يعلم Libre WebUI أنه لا يستطيع استعادته.
الحدود الحالية للأرشيف والحساب:
- 50 MiB لكل أرشيف مرفوع أو مولّد؛
- 100 مجلد محادثة؛
- 5,000 جلسة محادثة؛
- 100,000 رسالة محادثة؛
- 100 Notes، بعناوين حتى 200 حرف ومحتوى حتى 200,000 حرف؛
- 5,000 مجموعة معرفة؛
- 5,000 مستند؛
- 100,000 مقطع مستند؛
- حقول المحتوى العام حتى 2,000,000 حرف والمعرفات حتى 256 حرفًا، مع حدود أضيق حيث تفرضها موارد التشغيل.
سلوك الاستيراد الآمن
يطلب تحديد الملف من الخادم فحصه مبدئيًا فورًا. تعرض الإعدادات الإجماليات الواردة وأعداد الإنشاء/الاستبدال/التجاوز المتوقعة وإعادة تعيين المعرفات وتحذيرات الترحيل قبل تمكين إجراء الاستيراد النهائي. ويؤدي تغيير سياسة التعارض إلى حساب معاينة جديدة.
يتحقق الفحص المبدئي من بصمة السلامة إن وُجدت، ويرحّل التنسيقات القديمة المدعومة، ويفحص المخطط الكامل وأعداد الموارد والمعرفات الفريدة والطوابع الزمنية وحدود المحتوى والعلاقات، ويخطط للتعارضات وإعادة ربط المراجع بلا كتابة. وتُرفض ارتباطات المجلد أو المجموعة أو أصل الرسالة أو المستند المعلّقة بدلًا من حذفها بصمت. ويكرر الخادم التحقق والتخطيط للاستيراد الفعلي. تتم كل الكتابات في معاملة قاعدة بيانات واحدة على SQLite وPostgreSQL؛ وأي خطأ يتراجع عن التفضيلات والمجلدات والجلسات/الرسائل وNotes والمجموعات والمستندات والمقاطع معًا.
تتوفر سياستان للتعارض:
- تجاوز المكررات يحتفظ بالسجلات ذات المعرفات المطابقة ويستورد الجديدة. وتُدمج التفضيلات مع تفضيلات الحساب الحالية.
- الكتابة فوق الموجود تستبدل السجلات ذات المعرفات المطابقة. وتحل التفضيلات محل قيم Libre WebUI الافتراضية. ولا تُحذف السجلات الغائبة عن الأرشيف.
كلتا السياستين متكررة النتائج للسجلات ذات المعرفات المطابقة. وإذا كان معرف مملوكًا لحساب آخر على الخادم الهدف، يعيد Libre WebUI تعيينه وكل مرجع مضمن إليه بصورة حتمية. ولا يكتب فوق مورد مستخدم آخر أو يقرأه. وتظل المراجع إلى موارد مستبعدة أو غير متاحة، مثل شخصية من تثبيت آخر، استثناءً موثقًا؛ إذ يبلغ الفحص أن الجلسة ستُفصل قبل الاستيراد.
تعرض النتيجة في الإعدادات أعداد المجلدات والجلسات وNotes والمجموعات والمستندات المنشأة والمستبدلة والمتجاوزة. وبعد نجاح الاستيراد، يعيد Libre تحميل التفضيلات والمحادثات والمجلدات ويحدّث المستندات.
الأرشيفات القديمة
يقبل المستورد أرشيفات libre-webui-user-data بالإصدار 2 ويرحّلها إلى الإصدار 3 أثناء التحقق. لم يتضمن الإصدار 2 بصمة سلامة أو Notes، لذلك لا يستطيع Libre التحقق من مصدره أو استعادة Notes لم تُصدّر أصلًا. وتوضح المعاينة القيدين.
ويقبل أيضًا شكل libre-webui-export القديم بالإصدار 1.0. كان هذا التنسيق المنشأ في المتصفح يحتوي التفضيلات والجلسات المحملة في ذلك المتصفح فقط. وكانت مصفوفة documents فارغة دائمًا، ولم يحتوِ مجلدات أو Notes أو مجموعات معرفة أو مقاطع مستندات. ويبلغ Libre عن هذه القيود قبل الاستيراد.
نقاط نهاية HTTP
تتطلب جميع النقاط رمز Bearer أو جلسة المستخدم الموثق:
| الطريقة | نقطة النهاية | الغرض |
|---|---|---|
GET | /api/preferences/export | إنشاء أرشيف v3 للمستخدم الحالي |
POST | /api/preferences/import/preflight | التحقق والتخطيط بلا كتابة |
POST | /api/preferences/import | التحقق والاستيراد ضمن معاملة |
ترسل الواجهة الأرشيف في حقل multipart/form-data باسم archive وسياسة التعارض في حقل 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.