ar ARCHITECTURE

Languages: English | العربية | Čeština | Deutsch | Español | فارسی | Français | हिन्दी | Bahasa Indonesia | Italiano | 日本語 | 한국어 | Nederlands | Polski | Português | Русский | Svenska | ไทย | Türkçe | Tiếng Việt | 中文

---

البنية

VDBackup هو وحدة WebUI تعمل بصلاحيات root. يتكوّن من ثلاث طبقات: WebUI (ما تراه)، والواجهة الخلفية الصدفية (ما ينفّذ العمل، بصلاحيات root)، والملفات الثنائية المرفقة (أدوات الأرشفة والنقل). كل شيء يعمل بصلاحيات root مسبقًا، لذا لا توجد مطالبة بالأذونات ولا تطبيق مصاحب للقدرات الأساسية.

   ┌──────────────────────────────────────────────────────────┐
   │  WebUI  (module/webroot, vanilla JS)                      │
   │    index.html · scripts.js · i18n.js · styles.css         │
   │    lang/en.js + 21 languages · config.json (CSP, no net)  │
   └───────────────┬──────────────────────────────────────────┘
                   │  ksu.exec("sh scripts/helper.sh <verb> <b64json>")
                   ▼
   ┌──────────────────────────────────────────────────────────┐
   │  scripts/helper.sh  (dispatcher, returns JSON)            │
   │    list-apps · config · dests · backup/restore/import ... │
   │    long ops -> setsid nohup scripts/worker.sh  (detached) │
   └───────────────┬───────────────────────────────┬──────────┘
                   │                               │ progress-<opid>.json (poll)
                   ▼                               ▼
   ┌────────────────────────────────────┐   ┌──────────────────────────┐
   │  scripts/worker.sh (root, detached)│   │  framework helper (opt.) │
   │   force-stop · tar|zstd|age        │   │  app_process + dex       │
   │   pm install · chown/chcon         │   │  perms/appops/ssaid/...  │
   │   transfer · notify                │   │  (dex primary, shell fb) │
   └───────────────┬────────────────────┘   └──────────────────────────┘
                   ▼
   ┌──────────────────────────────────────────────────────────┐
   │  bin/<abi>/  tar · zstd · lz4 · rclone · rsync · ssh · restic │
   └──────────────────────────────────────────────────────────┘
                   ▼
   Destinations: local · SFTP/SCP · SMB · WebDAV · FTP · S3 · 70+ (rclone)
                 rsync · restic repos · Google Drive (opt-in companion)

النقاط الرئيسية

• root مسبقًا. عملية الوحدة تعمل بصلاحيات root، لذا فإن المحرّك عبارة عن صدفة (shell) بسيطة. نحو 85% من العمل هو صدفة خالصة (tar/zstd/age/pm/am/chown/chcon/rclone/...).
• التنفيذ المنفصل. يعمل النسخ الاحتياطي/الاستعادة عبر setsid nohup كعملية root مستقلة. إغلاق الـ WebUI لا يقاطعها؛ وتعيد الواجهة الاتصال بقراءة logs/progress-<opid>.json.
• مساعد إطار العمل (~15%). تحتاج الأذونات الدقيقة وAppOps وSSAID وStorageStats والأيقونات وشبكة Wi-Fi ذات الامتياز إلى إطار عمل Android. يتولى ذلك ملف dex صغير يُشغَّل عبر app_process (بدون تطبيق مثبّت)، مع آلية احتياطية صدفية.
• قابلية النقل. صيغ قياسية فقط؛ النسخ الاحتياطية تُفتح على الحاسوب دون هذه الوحدة.
• الحالة تقيم في /data/adb/vdbackup/ (الإعدادات، المهام، الوجهات، بيانات الاعتماد المشفّرة، السجلات، التجهيز المؤقت). تُكتب النسخ الاحتياطية في تخزين مرئي للمستخدم ومشفّر ببيانات الاعتماد في /sdcard/VDBackup/ (/data/media/<user>/VDBackup، لكل مستخدم)، وليس في /data/adb (المشفّر على مستوى الجهاز والقابل للقراءة قبل أول فتح للقفل).

ضمان التوافق

يجب أن تظل النسخة الاحتياطية قابلة للاستعادة إلى الأبد. هذه قاعدة صارمة، وليست مجرد محاولة قدر الإمكان.

النطاق. يشمل الضمان النسخ الاحتياطية المكتوبة بإصدار v1.01 فصاعدًا (أول إصدار منشور رسميًا)، والإصدارات المنشورة والمُطلَقة رسميًا فقط. كان v1.00 بناءً للاختبار فحسب وهو خارج النطاق صراحةً؛ ولا تشمل التغطية إصدارات ما قبل الإطلاق وإصدارات التطوير. من أول إصدار عام فصاعدًا، يصبح الوعد التالي مطلقًا:

• صيغ قياسية فقط. كل أرشيف هو tar عادي مضغوط بـ zstd أو gzip أو lz4، ومغلّف اختياريًا بـ age. لا توجد حاوية خاصة، لذا يمكن فتح النسخة الاحتياطية على أي حاسوب بأدوات عادية حتى بدون هذه الوحدة (انظر etc/RECOVERY.md). صيغة لا يمكننا التخلي عنها.
• بيانات وصفية للإضافة فقط. يحمل manifest.json القيمة format_version. المخطّط ينمو فقط: يمكن إضافة الحقول، لكن لا تُزال أو يُعاد تسميتها أو يُعاد توظيفها أبدًا. تقرأ الاستعادة كل حقل بحذر دفاعي (الحقول الاختيارية المفقودة تعود إلى قيمة افتراضية)، وتثبّت ملفات APK وتستخرج الأرشيفات بحسب اسم الملف وامتداده، لا بافتراض شكل ثابت للـ manifest.
• استعادة متوافقة مع الأمام. لا ترفض الاستعادة نسخة احتياطية لكونها قديمة، وتتخطى نسخة VDBackup الأقدم بصمت أنواع العناصر التي لا تعرفها بدلًا من الفشل. لذلك تستعيد نسخة VDBackup الأحدث أي نسخة احتياطية أقدم، وتبقى أرشيفات الصيغ القياسية قابلة للاستعادة يدويًا على أي حال.

باختصار: أي شيء كتبته VDBackup يومًا ما، يمكن لكل نسخة VDBackup مستقبلية (وحاسوب عادي) استعادته. تغيير الصيغة بطريقة تعطّل نسخة احتياطية سابقة أمر غير مسموح؛ تُضاف القدرات الجديدة خلف format_version وحقول جديدة مضافة.

بخصوص التصميم التقني الكامل (صيغة الأرشيف، مخطط البيانات الوصفية، خطوط المعالجة، التشفير، الوجهات، أدوات الاستيراد) يحتفظ القائمون على الصيانة بملاحظات تصميم مفصّلة؛ هذا الملف هو نظرة عامة موجّهة للمساهمين.

أُنشئت هذه الوثائق بمساعدة Claude (Anthropic) ويتولى صيانتها VD171. التصحيحات والتحسينات مرحب بها - انظر CONTRIBUTING.md.