وثائق صباربيز
صباربيز يشغّل مشاريع Supabase كثيرة على خادم واحد، ويوفر إجراءات للنسخ الاحتياطي والاستعادة والترقية، لكل منها نطاق تحقق وحدود موثقة. قسّمنا الوثائق بحسب ما تحتاجه الآن. ابدأ بصفحة لماذا إن كنت جديدًا، أو بصفحة الحالة إن أردت معرفة ما يعمل.
أربعة أقسام، لكل منها غرض واحد، وتحتها الدفتر الهندسي.
كلمات تتكرر في كل الصفحات: العميل (يسمّى منظمة في الكود) يملك مشاريع، ولكل مشروع بيئات مثل الإنتاج والتجربة. و"خادمك" هو ما يسمّيه الكود التثبيت. البيئة هي وحدة العزل والنقل والاستعادة. المصطلحات غير المألوفة في المسرد.
الشروح: لماذا يعمل بهذه الطريقة
اقرأ هذه الصفحات لتفهم التصميم. لكل صفحة الشكل نفسه: ما هو، ولماذا، وكيف بنيناه، وحدوده، وأين تتعمق أكثر.
- لماذا صباربيز: المشكلة، والبدائل الموجودة، وما المختلف هنا.
- البنية: مسار الطلب، وما هو مشترك وما هو منفصل.
- الهرمية: العملاء والمشاريع والبيئات، ولماذا تنفصل الملكية عن مكان التشغيل.
- العزل والثقة: ما الذي يشكّل نقطة فشل مشتركة، ومن الموثوق.
- نموذج التهديد: الأصول، والمهاجمون، وحدود الثقة، والفحص وراء كل إجراء وقائي، والثغرات المعروفة.
- الاستعادة: السياج، ثم التصدير، ثم الاستعادة، ثم التحقق، ثم التحويل.
- التجهيز: لماذا لا يؤدي الانهيار أبدًا إلى تنفيذ العمل مرتين.
الأدلة العملية: كيف تنفّذ مهمة
- التثبيت عبر Docker: طريقة التثبيت الأساسية، من جهاز Ubuntu 26.04 فارغ حتى تعمل لوحة الإدارة، كما جُرّبت في آلة افتراضية محلية.
- البداية السريعة: التثبيت دون Docker، من خادم فارغ إلى استدعاء supabase-js، كما جُرّب في آلة افتراضية محلية.
- اختيار خادم: ماذا تشتري، وماذا تعطيك الخيارات المجانية فعلًا.
- المختبر المحلي: شغّل الحزمة على جهازك لتقييمها.
- إعداد المشغّل: أنشئ المشغّل الأول والعميل الأول.
- النشر على خادم: دليل تشغيل الخادم وثغراته المعروفة.
- Realtime: تغييرات قاعدة البيانات والبث والحضور لكل بيئة.
- النقل من Supabase: انسخ مشروع Supabase ومستخدميه وملفاته إلى بيئة جديدة بأمر واحد.
- الوصول إلى قاعدة البيانات: سلسلة اتصال PostgreSQL لكل بيئة للترحيلات وpsql وأدوات ORM.
- وكلاء الذكاء الاصطناعي والواجهة البرمجية: رموز الوصول ونقطة MCP والواجهة المتوافقة مع Supabase، ليستطيع Claude Code أو Cursor أو Codex النشر هنا.
- مفاتيح API: مفاتيح عامة للتطبيقات، ومفاتيح سرية (
service_role) للخوادم والوكلاء. - مفتاح التوقيع: غيّر مفتاح توقيع JWT لبيئة متى احتمل أنه تسرّب.
- Edge Functions: انشر مجلد دوال Supabase إلى بيئة واستدعِه عبر supabase-js.
- السجلات والمقاييس: الطلبات والأخطاء وأزمنة الاستجابة وسجلات الخدمات لكل بيئة.
- إعدادات تسجيل الدخول: عنوان الموقع وعناوين إعادة التوجيه ومزوّدو OAuth (Google وGitHub وApple وغيرها) لكل بيئة.
- Supabase Studio: افتح Studio الأصلي لبيئة واحدة، من خلف تسجيل الدخول إلى الواجهة، عبر نفق SSH أو على عنوانه العام.
- النسخ الاحتياطي والاستعادة: النسخ اليومي والاستعادة والنسخ المشفّرة خارج الخادم وحدود كل إجراء.
- إيقاف الكتابة: إيقاف كتابات التطبيقات في بيئة واحدة قبل أي عمل يكون طريق العودة منه استعادة نسخة احتياطية.
- الترقيات: التحديث من لوحة الإدارة، والتحديث التلقائي الاختياري، وسطر الأوامر، مع عودة تلقائية إن فشل.
- الأمر sbarbase: الحالة والنسخ الاحتياطية والاستعادة والبيئات والمفاتيح والترقية وStudio والسجلات من أمر واحد.
المرجع: حقائق تبحث عنها
الحالة: المكان الوحيد لما يعمل ولكل رقم، مع التواريخ والأوامر.
المسرد: كل مصطلح داخلي في جملة أو جملتين.
الإعدادات: الملفات والخيارات ومتغيرات البيئة التي يتعامل معها المشغّل.
واجهة API: مسارات الإدارة والبوابة.
جاهزية النشر: مصفوفة جاهزية الخادم بندًا بندًا.
تصميم لوحة الإدارة: رموز تصميم Supabase في لوحة الإدارة، والتنقل فيها، ولقطة الخادم.
هيكل المستودع: مجلدات الكود والوثائق والفحوص، وما يرجع إليه العمل الحالي.
اتجاه العمل الآن
يعتمد المشروع على خدمات Supabase الأصلية، ويهدف إلى تسهيل تشغيلها وإدارتها وتخصيصها على Linux عبر Docker. العمل النشط هو خطة مواكبة الإصدارات الأصلية، ويعمل الفرع الرئيسي على خادم حقيقي (الحالة). تسجّل أهداف المشروع المتطلبات، وتحدد خطة المنتج وقابلية التشغيل الأولويات. وتربط طريقة التنفيذ والتحقق كل نتيجة بنطاقها، مع عقد مكان التشغيل الأصلي وسجل الأدلة.
القرارات
- سجل القرارات: كل اختيار، والبديل عنه، وشروط إعادة النظر فيه.
الدفتر الهندسي
يضم docs/engineering الملاحظات المفصلة التي كُتبت أثناء بناء كل آلية: التصاميم، واختبارات الانهيار، والمراجعات، والخطط، ونقاط التحقق بترتيبها الزمني. هي دقيقة ومؤرخة، وبعضها حلّت محله ملاحظات لاحقة. اقرأها حين تحيلك إليها صفحة شرح، أو قبل أن تغيّر ذلك الجزء من النظام. ملاحظات الوكلاء البرمجيين الذين يكملون العمل في engineering/handoff.
ونحتفظ هنا أيضًا بـالأدلة (ملفات JSON تكتبها الفحوص الحية وتستشهد بها صفحة الحالة)، والرسوم التوضيحية، وسجل تصميم لوحة الإدارة.