الإعدادات

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

متطلبات الخادم

الصور المثبّتة الإصدار

الملفات lab/distro-image.lock.json وlab/images.lock.json وlab/storage-image.lock.json وlab/realtime-image.lock.json وlab/functions-image.lock.json وlab/studio-image.lock.json تثبّت كل صورة من الأصل بوسمها وبصمتها. لا تغيّرها إلا عبر lab/pin_update.py، وانظر الترقيات.

المثبّت والخدمة

أوامر /usr/bin/python3 lab/install_server.py <command>:

يقبل deploy/server-acceptance.sh الخيارات --rehearse و--skip-install و--install-unit و--first-project و--bootstrap-file و--service-user و--home و--bun-dir و--docker-host و--console-timeout و--python. الوحدة المرفقة هي deploy/sbarbase.service. لا تعدّل نسخة مثبّتة منها يدويًا، بل ولّدها بالأمر supervise.

وكيل TLS

ينهي bun deploy/console-tls-proxy.ts اتصالات HTTPS أمام خادم الحلقة المحلية.

يضبط الأمر /usr/bin/python3 lab/studio_address.py plan|apply|verify DOMAIN العنوان العام لـStudio مرة واحدة: plan يعدّد سجل DNS الشامل والشهادة والإعداد المطلوب توفيرها، وapply (بصلاحية الجذر) يكتب SBARBASE_STUDIO_HOST في ملف systemd إضافي (drop-in) للوحة الإدارة (--service، وافتراضيه sbarbase) وللوكيل (--proxy-service، وافتراضيه sbarbase-proxy) ثم يعيد تشغيلهما، وverify يخبرك بالخطوة الناقصة (Studio).

ملف الإعداد الأولي للمشغّل

يسأل /usr/bin/python3 lab/operator_file.py PATH عن البيانات دون إظهار ما تكتبه، ثم يكتب ملف JSON بصلاحية 0600 فيه email وpassword وorganization فقط. الخيار --stdin يقرأ الكائن نفسه من الإدخال القياسي (بحد أقصى 8192 بايت) للأتمتة. مرّر الملف إلى install --bootstrap-file، أو شغّل lab/bootstrap.py تفاعليًا بدلًا منه. انظر إعداد المشغّل.

بريد كل بيئة

يُفعَّل بريد التطبيق (التأكيد والاستعادة) لبيئة واحدة بملف واحد هو .secrets/upstream/<runtime>-mail.json بصلاحية 0600. اكتبه أو اعرضه أو احذفه بالأمر lab/mail_config.py write|show|remove PATH، ولا تُطبع كلمة المرور أبدًا. المفاتيح: host وport وuser وpass وadmin_email وsender_name وreply_to وmax_frequency وotp_exp وotp_length وsecure_email_change وautoconfirm. يسري التغيير بمطابقة حاوية Auth لتلك البيئة. المخطط الكامل: بريد البيئة.

تنبيهات المشغّل

إذا وُجد الملف .lab/upstream/notifications.json، يرسل العامل أحداث المشغّل بالبريد، أو بخطاف ويب موقّع، أو عبر تيليجرام، أو بأي مزيج منها:

{
  "schema": 1,
  "email": {"enabled": true, "host": "smtp.example.invalid", "port": 587,
            "from": "sbarbase@example.invalid", "to": "operator@example.invalid", "tls": "starttls"},
  "webhook": {"enabled": true, "url": "https://hooks.example.invalid/sbarbase",
              "secretFile": ".secrets/upstream/notifier.json"},
  "telegram": {"enabled": true, "chatId": "-1001234567890",
               "tokenFile": ".secrets/upstream/telegram.json"}
}

قيمة tls واحدة من none أو starttls أو tls. سر توقيع خطاف الويب محفوظ في .secrets/upstream/notifier.json بالشكل {"schema": 1, "webhookSecret": "<64 hex characters>"}. لتيليجرام: أنشئ بوتًا عبر @BotFather، وأضفه إلى محادثتك، وضع رمزه في ملف خاص (صلاحياته 0600) بالشكل {"schema": 1, "botToken": "<token>"}. قيمة chatId هي رقم المحادثة، أو @channelname لقناة عامة. يُقرأ الرمز من هذا الملف فقط، ولا يظهر في أي رسالة. التصميم الكامل: تنبيهات المشغّل.

ربط تيليجرام من لوحة الإدارة. يستطيع مالك التثبيت ربط تيليجرام دون تعديل أي ملف: من التنبيهات في قائمة التثبيت. الصق رمز البوت الذي أخذته من @BotFather، فيتحقق منه صباربيز مع تيليجرام، ويحفظه في .secrets/upstream/telegram.json (صلاحياته 0600)، ولا يعرضه بعدها أبدًا، بل آخر أربعة أحرف منه فقط. ثم افتح الرابط الذي تعطيك إياه الصفحة واضغط Start في تيليجرام: لا تُربط إلا المحادثة التي تفتح هذا الرابط، وهو يعمل مرة واحدة ويبقى صالحًا 30 دقيقة، وتصلها رسالة تأكيد. ومن الصفحة نفسها ترسل رسالة تجريبية، أو تفصل القناة فينسى صباربيز الرمز. تبقى القنوات الأخرى في notifications.json كما هي، ويسري أي تغيير على التثبيت العامل خلال ثانية دون إعادة تشغيل. يرى مدراء التثبيت حالة القناة، ولا يغيّرها إلا المالكون، ويُسجَّل كل تغيير في سجل التدقيق. إذا انكشف الرمز يومًا، أرسل /revoke إلى @BotFather والصق الرمز الجديد.

امتلاء القرص وتوقف الخدمات. يفحص المشرف مرة كل دقيقة. إذا قلّ المتاح في نظام ملفات يكتب فيه (مجلد التثبيت، ومجلد بيانات Docker) عن 10% أو 5 غيغابايت يصلك تحذير، وإذا قلّ عن 5% أو 2 غيغابايت يصلك تنبيه حرج. وإذا بقيت حاوية قاعدة البيانات أو Storage أو تسجيل دخول الإدارة، أو حاوية Auth أو REST أو Realtime لإحدى البيئات، متوقفة خمس دقائق يصلك تنبيه حرج. لا تُراقب Edge Functions، لأنها تبقى متوقفة عمدًا ما دامت البيئة موقوفة عن الكتابة.

الفحص من الخارج. الخادم المتوقف لا يستطيع أن يبلّغ عن نفسه. في deploy/uptime-worker/ عامل Cloudflare (Worker) يسأل مسار /health العام كل خمس دقائق: فشلان متتاليان يرسلان رسالة واحدة على تيليجرام، وأول جواب سليم بعدها يرسل رسالة أخرى. انسخ هناك wrangler.example.toml إلى wrangler.toml (يتجاهله git)، واضبط فيه HEALTH_URL ومعرّف مساحة KV لحفظ حالته (bunx wrangler kv namespace create sbarbase-uptime)، ثم انشره بالأمر bunx wrangler deploy -c deploy/uptime-worker/wrangler.toml، وأعطه رمز البوت ورقم المحادثة سرّين بالأمرين bunx wrangler secret put TELEGRAM_TOKEN وbunx wrangler secret put CHAT_ID (مع -c نفسه)؛ لا يُكتب أيّ منهما في ملف. رقم المحادثة هو chatId الذي كتبته لوحة الإدارة في .lab/upstream/notifications.json.

من بين الأحداث: بيئة ظلت تحتاج أكثر من حصتها. تضمن البوابة لكل بيئة 8 طلبات في الوقت نفسه، وتسمح للمزدحمة أن تستعير حتى 24 من 64 (8 لكل واحدة من البيئات الثماني التي يتسع لها التثبيت)، مع إبقاء الحصة غير المستخدمة لكل مشروع نشط في الدقيقة الأخيرة فارغة (8 على الأقل). الاستعارة وحدها لا تُبلَّغ أبدًا. إذا بقيت البيئة 15 دقيقة متتالية تُرفض عند حدها، أو تزاحم جارة لها، يصلك تنبيه واحد عنها مع ما يجب فعله: ارفع حصتها (صفحة البيئة في لوحة الإدارة، قسم حصة البوابة، لمشغّلي التثبيت وحدهم)، أو انقلها إلى محرك قاعدة بيانات خاص بها، أو كبّر الخادم. لا تُرفع الحصة إلا إذا بقيت حصص كل البيئات الجاهزة ضمن الـ64 التي تملكها البوابة، فإن لم تتسع فاخفض حصة بيئة أخرى أولًا. التصميم: الحصة العادلة.

نسخ احتياطية خارج الخادم

إذا وُجد الملف .lab/upstream/backup-offsite.json يُشفَّر كل تشغيل يومي للنسخ الاحتياطي ويُنسخ إلى مخزن واحد متوافق مع S3 (bucket):

{
  "schema": 1,
  "s3": {"endpoint": "https://s3.eu-central-1.amazonaws.com", "region": "eu-central-1",
         "bucket": "example-backups", "prefix": "sbarbase/",
         "credentialsFile": ".secrets/upstream/offsite-s3.json"},
  "keyFile": ".secrets/upstream/offsite-key.json"
}

يجب أن يكون endpoint بعنوان https (ويُقبل http العادي على الحلقة المحلية فقط). تقبل prefix الحروف والأرقام و. و_ و- و/. الحقل credentialsFile ملف بصلاحية 0600 بالشكل {"schema": 1, "accessKeyId": "...", "secretAccessKey": "..."}. والحقل keyFile ملف بصلاحية 0600 بالشكل {"schema": 1, "key": "<64 hex characters>"}، لا يُنشأ إلا بطلب صريح عبر python3 lab/backup.py offsite-key PATH. يُرفض الملفان إذا كانا رابطًا رمزيًا أو مقروءين للمجموعة أو لغيرها. يتبع الاحتفاظ SBARBASE_BACKUP_KEEP. الإعداد والحدود في النسخ الاحتياطي والاستعادة.

قناة التحديث

تقع إعدادات التحديث وطلباته وسجل الترقية في .lab/upgrades/، خاصة بحساب الخدمة: المجلد 0700، وملفات JSON بصلاحية 0600، ويُستبدل كل منها دفعة واحدة. لا تكتب لوحة الإدارة إلا settings.json وrequest.json، ويكتب المشرف وlab/upgrade.py الباقي (الترقيات).

يحدد SBARBASE_RELEASE_SOURCE مستودع Git الذي يقرأه فحص الإصدارات (عنوان أو مسار)، والافتراضي المستودع الرسمي عبر HTTPS. أيًا كان المصدر، يُتحقق من التواقيع مقابل deploy/release-signers في نسخة المستودع التي تعمل. ويضبط TZ المنطقة الزمنية التي تُقرأ بها نافذة الصيانة؛ ويمرر compose.yaml كليهما إلى الحاوية (انظر إعدادات المشغّل).

مجلدات الحالة

يتجاهل Git المجلدين كليهما. لا تطبع محتوى .secrets/ أبدًا، ولا تحذف أيًّا منهما لتتجاوز رفضًا.

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

اضبطها في compose.yaml (مع Docker) أو في أسطر Environment= لخدمة systemd.

ومع Docker يقرأ deploy/compose.sh هذه أيضًا. ويرفض إن غاب المقبس أو مجلد بيانات Docker، أو إن لم يكن SBARBASE_ROOT هو نسخة المستودع هذه:

متغيرات البيئة الداخلية

باقي المتغيرات التي تبدأ بـSBARBASE_* (مثل SBARBASE_WORKER_FD وSBARBASE_EFFECT_TOKEN، وSBARBASE_DOCKER_PROFILE وSBARBASE_CONTAINER اللذين يضبطهما compose.yaml) تنقل واصفات الأقفال والرموز بين عمليات صباربيز نفسها. ليست إعدادات للمشغّل، فلا تضبطها يدويًا.

ما لا يمكن ضبطه بعد

فئات الموارد وعتبات القبول ثابتة في الكود (lab/resource_policy.py، lab/pressure_admission.py). حدود التزامن في البوابة ومهلها قيم افتراضية في المُنشئ داخل src/gateway/concurrency.ts.

عدّل على GitHub