التثبيت على خوادمك

يمكن تشغيل AppArch بالكامل على بنيتك التحتية الخاصة. يسلّم فريق AppArch حزمة التثبيت والترخيص ضمن نطاق عقدك.

ما تحتاجه قبل التثبيت

العنصر	فائدته
الترخيص	يحدّد حدود التثبيت ومدته، ويعمل على تثبيت واحد فقط. التثبيتات المتصلة بالإنترنت تجلبه تلقائيًا عند أول تشغيل باستخدام بيانات اعتماد التثبيت؛ أما التثبيتات المعزولة فتستلم ملف apparch.lic مرتبطًا برمز التثبيت الخاص بها - راجع ترخيص واحد، تثبيت واحد.
معرّف التثبيت	يُستخدم اسم مستخدم عند تسجيل الدخول إلى سجل صور AppArch.
مفتاح التثبيت	يُستخدم كلمة مرور في تسجيل الدخول نفسه. يُسلَّم مرة واحدة فقط.
حزمة التثبيت	ملفات الإعداد التي تشغّل الخدمات مع دليل خطوة بخطوة.

معرّف التثبيت ومفتاحه مرتبطان بترخيصك: الصور غير مدرجة للعموم ولا يمكن تنزيلها إلا بهذه البيانات.

docker login hub.apparch.io -u <معرّف-التثبيت> -p <مفتاح-التثبيت>

بعد نجاح تسجيل الدخول، اتبع خطوات حزمة التثبيت لتشغيل الخدمات.

ترخيص واحد، تثبيت واحد

لا يوجد ملف مفتاح يجب وضعه: المفتاح الذي يثبت أن الترخيص صادر عن AppArch مدمج في الصور.

يعمل الترخيص على تثبيت واحد فقط. أول تثبيت يجلبه عبر الإنترنت (معرّف التثبيت + مفتاح التثبيت) يربطه بنفسه؛ وأي تثبيت آخر يطلب الترخيص نفسه يُرفض برسالة “هذا الترخيص مستخدم بالفعل في تثبيت آخر”.

التثبيت هو كل ما يتشارك قاعدة بيانات واحدة: كل pod أو نسخة متماثلة تقرأ رمز التثبيت نفسه، لذا فإن توسيع الـ Api أو الواجهة إلى عدة pods يعمل بالترخيص نفسه ولا يتطلب شيئًا من AppArch.

تستلم التثبيتات المعزولة ملف ترخيص مرتبطًا برمز التثبيت الخاص بها:

1. شغّل الخدمات.
2. افتح خطوة الترخيص في معالج الإعداد واختر خيار لصق ملف الترخيص، أو انتقل في تثبيت مُعدّ مسبقًا إلى الإدارة ← الإعدادات ← الترخيص.
3. انسخ رمز التثبيت المعروض هناك وأرسله إلى AppArch.
4. ضع ملف .lic الذي تستلمه في ./license/apparch.lic، أو الصق محتواه في المعالج.

يعمل هذا الملف على ذلك التثبيت فقط.

الانتقال إلى خادم جديد: اطلب من AppArch تحرير الترخيص، ثم اجلبه مجددًا من الخادم الجديد.

الحفاظ على سريان الترخيص

يتصل التثبيت المتصل بالإنترنت بـ AppArch كل ساعة (https://gateway.apparch.io، اتصال HTTPS صادر). كل اتصال يجدد ترخيصه؛ لا يلزمك فعل شيء يدويًا، لكن يجب أن يتمكن الخادم من الوصول إلى هذا العنوان.

• يستمر الترخيص الذي له تاريخ انتهاء في العمل أسبوعين دون اتصال ناجح، فلا يوقف تغيير في جدار الحماية أو انقطاعٌ أيَّ شيء على الفور. وإذا مر أسبوعان دون اتصال، يتوقف التثبيت إلى أن يتمكن من الوصول إلى AppArch مجددًا.
• الترخيص الذي ليس له تاريخ انتهاء لا يعتمد على هذا الاتصال.
• التثبيتات المعزولة عن الشبكة لا تتصل أبدًا: يعمل ملف ترخيصها حتى تاريخ انتهائه.

عندما يتوقف التثبيت - إذا أُلغي الترخيص، أو فشل الاتصال لمدة أسبوعين، أو انتهى الترخيص منذ أكثر من 14 يومًا - تعرض كل الشاشات عدا الإدارة رسالة “هذا التثبيت متوقف” مع السبب، ولا يُحلَّل أو يُسجَّل أي شيء. لا تفشل خطوات CI: يطبع الـ collector تحذيرًا وينجح، فلا يعطل الترخيص طلبات الدمج أبدًا. يؤدي تثبيت ترخيص صالح من الإدارة ← الإعدادات ← الترخيص إلى رفع التوقف فورًا دون إعادة تشغيل.

الحدود الشهرية. قد يحدد ترخيصك عدد تقارير ArchScan وعمليات ArchSecurity وتعليقات ArchPilot لكل شهر ميلادي، للتثبيت كله. لا يُحفظ التقرير الذي يتجاوز الحد وينجح الـ collector مع تحذير؛ ويواصل ArchPilot تسجيل المراجعات لكنه يتوقف عن نشر التعليقات على طلبات الدمج. تُصفَّر الحدود في اليوم الأول من كل شهر، ويظهر الاستخدام الحالي في الإدارة ← الإعدادات ← الترخيص.

الميزات المرخصة. ثلاث ميزات تعتمد على ترخيصك: تسجيل الدخول الموحد (الدخول عبر LDAP)، وسجل التدقيق (عرض الإدارة ← التدقيق؛ تُسجَّل الإجراءات دائمًا)، والتقارير المتقدمة (تصدير التقارير ورسائل التقارير المجدولة). تعرض صفحة الترخيص نفسها الميزات التي يتضمنها ترخيصك.

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

• Docker Engine 24+ مع إضافة compose
• PostgreSQL وRedis (مضمّنان في حزمة التثبيت)
• عنوان HTTP(S) يصل إليه مستخدموك
• للتثبيتات المتصلة بالإنترنت: اتصال HTTPS صادر إلى gateway.apparch.io (فحص الترخيص كل ساعة) وhub.apparch.io (الصور)

بعد التثبيت

• عند أول تشغيل يظهر معالج الإعداد لإنشاء حساب المسؤول.
• يُحدَّث مخطط قاعدة البيانات تلقائيًا مع كل تشغيل، فلا حاجة لتنفيذ SQL يدويًا.
• يُدار البريد (SMTP أو Postmark) وتسجيل الدخول عبر LDAP وتجديد الترخيص من قسم الإدارة داخل التطبيق.

ملاحظة

إذا تسرّب مفتاح التثبيت، أبلغنا: نستبدله ويتوقف القديم فورًا عن العمل، دون أي تأثير على الخدمات العاملة لديك.

نصيحة

في التثبيتات المعزولة عن الإنترنت تُسلَّم الصور كملفات، فلا حاجة لتسجيل الدخول إلى السجل.

يتولى فريق المبيعات ترخيص التثبيت الخاص والأسعار: apparch.io.

مراقبة الإقلاع

تسرد الواجهة البرمجية إقلاعها في سجل الحاوية (docker compose logs -f api): الاتصال بقاعدة البيانات (المضيف والمنفذ - لا بيانات اعتماد أبدا)، وقفل التمهيد، وتطبيق الترحيلات المعلقة، وبذر البيانات المرجعية، وتحميل الترخيص، وأخيرا Boot complete - accepting requests. إذا أخفق الإقلاع، يسمي سطر واحد فوق أثر المكدس المرحلة التي ماتت.

نقاط الصحة

تعرض الحاويتان مجسات غير موثقة:

النقطة	المعنى
GET /health/live	العملية تخدم HTTP. بلا فحص اعتماديات.
GET /health/ready	جاهز للحركة - الواجهة تفحص PostgreSQL وRedis، وواجهة المستخدم تفحص الواجهة البرمجية.

ملف docker-compose.yml المرفق يصلها كفحوص صحة للحاويات (واجهة المستخدم تنتظر واجهة برمجية سليمة لا مجرد مقلعة). على Kubernetes: وجه livenessProbe إلى /health/live وreadinessProbe إلى /health/ready، وامنح الواجهة نافذة إقلاع سخية - الإقلاع الأول يشغل الترحيلات والبذر.

فحوصات التقارير

• التحقق من الالتزام. كل تقرير ArchScan وArchSecurity وSmartScan يذكر الالتزام (commit) الخاص به، وتبحث عنه API في مستودع المشروع باستخدام بيانات اعتماد المشروع. الالتزام الذي لا يملكه المستودع قطعًا يُرفض بـ 422 report_commit_not_found وتفشل خطوة CI: رمز المشروع مستخدم في خط مستودع آخر أو على عمل لم يُدفع قط. وإذا تعذّر التحقق (لا بيانات اعتماد، المزوّد غير متاح) يُحفظ التقرير. COMMIT_VERIFICATION=Record يسجّل فقط، وOff يتخطى التحقق.
• تقارير مضغوطة. ترسل المجمّعات الحالية التقارير مضغوطة بـ gzip (يصغر التقرير الكبير نحو ثماني مرات)؛ لا شيء لضبطه.

الترقيات

وجه وسوم الصور إلى الإصدار الجديد ثم docker compose pull && docker compose up -d. تطبق الترحيلات المعلقة بالترتيب، واحدة واحدة، مهما بلغ عدد الإصدارات المتخطاة - تنصيب 1.0.0 المنتقل إلى 1.0.12 يطبق الاثنتي عشرة كلها في الإقلاع الأول، تحت قفل قاعدة بيانات يمنع تصادم النسخ المتوازية. خذ نسخة احتياطية قبل الترقية؛ الترحيلات لا تعرف إلا الأمام.

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

APPARCH_API_IMAGE=hub.apparch.io/apparch/api:<new-version> docker compose run --rm --no-deps api --check-license

ينتهي الفحص بـ Result: safe to upgrade. (رمز الخروج 0) أو Result: do not upgrade yet. (رمز الخروج 1) ويذكر ما ينقص: التنصيب المتصل يحتاج معرّف التنصيب ومفتاحه وإمكانية الوصول إلى AppArch؛ والتنصيب المعزول يحتاج ملف ترخيص مرتبطًا برمز تنصيبه في license/apparch.lic. لا ترقِّ إلا بعد نجاح الفحص.