# إعداد المشغّل

أنشئ حساب المشغّل الأول والعميل الأول (المنظمة) على خادمك. تحققنا من هذه الخطوات بتاريخ 2026-09-20 على جهاز التطوير. هذه تهيئة أولية تجريبية ومحلية. على خادم، اتبع [البدء السريع](https://base.sbarah.com/docs/guides/quickstart/) أو [التثبيت عبر Docker](https://base.sbarah.com/docs/guides/docker/) (`deploy/compose.sh bootstrap`) بدل هذه الصفحة، ودليل النشر على خادم موجود في [SERVER-DEPLOYMENT](https://base.sbarah.com/docs/guides/server-deployment/). المثبّت هو `lab/install_server.py` (`check` و`plan` و`install` و`images` و`smoke` و`supervise` و`wait-console`).

## شرط التوافق الحالي

التثبيتات الجديدة مدعومة، وكذلك التثبيتات المحفوظة التي يحمل مصدرها وهدف استعادتها الحالي تثبيت جيل HBA متطابقًا. أما القواعد القديمة المحفوظة التي لا تحمل هذا التثبيت فتحتاج تبنّيًا صريحًا (`lab/adopt-retained.py source|target`)، ويرفض تشغيلها قبل كتابة أي بيانات اعتماد أو تشغيل أي خدمة. القاعدتان المحفوظتان في نسخة المستودع هذه متبنّاتان منذ 2026-09-20. لا تُعد إنشاء حاوياتهما ولا تحذف الحالة لتتجاوز هذا الشرط. انظر [تكامل HBA في المصدر](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/SOURCE-HBA-INTEGRATION.md) و[كتّاب HBA في هدف الاستعادة](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/engineering/TARGET-HBA-WRITERS.md).

## التشغيل

1. شغّل بيئة التشغيل الأصلية المملوكة: `/usr/bin/python3 lab/durable_runtime.py up`.
2. شغّل في الطرفية `/usr/bin/python3 lab/bootstrap.py`. أدخل بريدًا إلكترونيًا واسم المنظمة وكلمة مرور من 12 حرفًا على الأقل. لا تظهر كلمة المرور أثناء كتابتها، ويُطلب منك تأكيدها. لا تضع بيانات الاعتماد في الوسائط.
3. شغّل `bun lab/upstream-server.ts` لتبدأ واجهة API المحلية. نقطة الإدارة لحزمة Supabase هي العنوان الأساسي الذي يطبعه الأمر مضافًا إليه `/management`؛ ومفتاح التوجيه العام هو `sb_publishable_sbarbase_local_management`. افتح العنوان الأساسي المطبوع لتصل إلى واجهة الدخول. شغّل `bun run build:ui` قبل تشغيل الخادم.
4. بعد الدخول، يسرد `GET /management/v1/organizations` عضويات المستخدم الحالية، مع معرّف المنظمة واسمها والدور. وتعمل بعدها واجهات المشاريع والبيئات الموجودة داخل تلك المنظمة.

للأتمتة، يقرأ `bootstrap.py --stdin` ما لا يزيد على 8192 بايت من JSON فيه الحقول `email` و`password` و`organization` بالضبط. مرّرها عبر قناة stdin خاصة، لا عبر أمر shell يحمل بيانات الاعتماد في سطره. لا يطبع الأمر إلا حالة الاكتمال ومعرّفَي الهوية والمنظمة الناتجين.

أمر الإعداد مخصص للمشغّل الموثوق الذي يملك أصلًا وصولًا إلى أسرار التثبيت. ليس نقطة HTTP. يبقى التسجيل العام في Auth معطّلًا، وطلب POST إلى اكتشاف المنظمات ليس عملية تهيئة. إنشاء مالك المنظمة الأولى لا يمنح وصولًا عابرًا للمنظمات، ولا يكشف واجهة المدير الخاصة في Auth.

## الانقطاع وإعادة المحاولة

قبل إنشاء مستخدم Auth، يُكتب سجل نية خاص خالٍ من كلمات المرور، كتابة ذرّية مع fsync. يسجّل معرّف عملية عشوائيًا والبريد والمنظمة، ثم معرّف الهوية بعد تأكيده. وتحدد علامة عملية في `app_metadata`، لا يتحكم بها إلا المدير، مستخدم Auth نفسه إذا توقف الإعداد قبل تسجيل معرّفه. لا تُستخدم أبدًا البيانات الوصفية التي يعدّلها المستخدم لادعاء هذه الهوية.

أعد المحاولة بالبريد والمنظمة وكلمة المرور الأصلية. يتحقق الإعداد من كلمة المرور الموجودة مقابل Auth الخاص بالإدارة، ولا يعيد تعيينها بصمت أبدًا. ويستخدم معاملة واحدة في الفهرس للمنظمة وعضوية المالك وسجل التهيئة وقيد التدقيق. تكرار عملية مكتملة يعيد المعرّفات نفسها. لا يمكنه إنشاء منظمات مكررة، ولا إعادة ملكية سُحبت لاحقًا.

يمسك الغلاف قفل ملف من نظام التشغيل طوال العملية الفرعية. محاولات الإعداد المتزامنة تفشل بدل أن تتسابق. ويفرض الفهرس أيضًا سجل إعداد أوليًا واحدًا. إن غاب سجل النية بعد التهيئة، يرفض الإعداد أي عملية جديدة. وإن اختفت هوية Auth مسجّلة، يرفض استبدالها. الإصلاح اليدوي لهاتين الحالتين إجراء استعادة منفصل للمشغّل، لم يُكتب بعد.

لا يُحفظ في هذا السجل أي كلمة مرور لـAuth أو رمز JWT. وضع ملفه 0600 تحت `.secrets/upstream` المستثنى. تحفظ خدمة Auth كلمة المرور بطريقتها المعتادة. لا يرسل أمر الإعداد دعوة بالبريد؛ فإنشاء المدير الخاص يؤكد صراحة البريد الذي أدخله المشغّل.

## الأدلة والحدود

يتحقق [18 فحصًا حيًا](https://github.com/M7MMAD-OMAR/sbarbase/blob/main/docs/evidence/bootstrap-checks.json) من إنشاء مستخدم حقيقي في Auth الخاص بالإدارة، ومن الانقطاع بعد إنشاء Auth، والانقطاع بعد إيداع الفهرس، ورفض كلمة المرور الخاطئة، وإعادة استخدام الهوية والمنظمة، وخصوصية السجل، والدخول عبر الحزمة. وتثبت أيضًا اكتشاف المنظمات، وإنشاء أول مشروع، ورفض الاكتشاف دون مصادقة، ورفض الوصول إلى منظمة غير ذات صلة.

يستخدم الفحص الحي نواة التهيئة نفسها ومحوّل Auth نفسه وسجل الملفات نفسه التي يستخدمها سطر الأوامر، مع فهرس مؤقت معزول. وفُحص الغلاف نفسه أمام المدخلات المشوّهة، والضعيفة أو غير الصالحة، والكبيرة جدًا، ورفض القفل المتزامن. لم يُؤتمت إدخال كلمة المرور التفاعلي. لم يُحتفظ بأي حساب مالك فعلي ولم يُسلَّم؛ فقد حذف الفحص الهوية التي ولّدها وملفاته الخاصة.

تغطي اختبارات الوحدات أربع نقاط انقطاع دائمة، والتحقق من كلمة المرور قبل منح الصلاحية، والملكية المسحوبة، والاكتشاف المحصور بالعضوية. مجاميع الاختبارات الحالية مسجّلة في [الحالة](https://base.sbarah.com/docs/reference/status/)؛ ولا تثبت الجاهزية للإنتاج.

منذ كُتبت هذه الصفحة أول مرة صار متاحًا: الدعوات، وعوامل الدخول الإضافية (MFA) وحدود معدل الدخول في لوحة الإدارة، وHTTPS عبر وكيل TLS المرجعي ([النشر على خادم](https://base.sbarah.com/docs/guides/server-deployment/))، والنسخ الاحتياطية المشفّرة خارج الخادم ([النسخ الاحتياطي والاستعادة](https://base.sbarah.com/docs/guides/backup-and-restore/))، وإعادة تعيين كلمة المرور من سطر أوامر الخادم (أدناه). وما زال ينقص: إصلاح مدعوم لحالتَي الرفض المذكورتين أعلاه (سجل نية مفقود، وهوية اختفت)، وتهيئة موجّهة عند أول تشغيل في لوحة الإدارة، وتقسيم صفحات قوائم المنظمات الكبيرة جدًا، ومثبّت كامل قابل للتوزيع. يبحث الإعداد عن هوية التهيئة في واجهة Auth الخاصة صفحة بصفحة، ويتوقف بخطأ بعد 10,000 مستخدم بدل أن يفترض بصمت عدم وجود تطابق. احفظ كلمة المرور الأصلية بأمان بنفسك.

## نسيت كلمة المرور

لا يوجد في لوحة الإدارة رابط «نسيت كلمة المرور»، لأن تسجيل دخول الإدارة لا يرسل بريدًا من تلقاء نفسه. من يملك صلاحية الدخول إلى الخادم يضع كلمة جديدة:

```bash
sudo -u sbarbase /opt/sbarbase/deploy/sbarbase reset-password you@example.com
```

يطلب الأمر كلمة المرور الجديدة مرتين دون أن تظهر (12 حرفًا على الأقل)، ويستبدلها عبر خدمة تسجيل دخول الإدارة، وينهي كل جلسات اللوحة وStudio التي كانت مفتوحة لهذا الحساب، فتتوقف فورًا أي جلسة فُتحت بالكلمة القديمة. ويبقى تطبيق المصادقة الذي يستخدمه الحساب كما هو. ويُسجَّل التغيير في سجل التدقيق باسم `management.password_reset`. يقرأ الأمر سر خدمة الإدارة من `.secrets/upstream/runtime.json`، ولهذا لا يعمل إلا على الخادم، بحساب الخدمة.

المصادر: [Supabase admin createUser](https://supabase.com/docs/reference/javascript/auth-admin-createuser)، و[admin listUsers](https://supabase.com/docs/reference/javascript/auth-admin-listusers)، وخدمة Auth الأصلية المثبّتة الإصدار التي شُغّلت محليًا.