نشر Git يربط مستودعًا بموقع بحيث تؤدي كل عملية push إلى الفرع المختار إلى استنساخ الشيفرة، وتشغيل عملية البناء، ونشر النتيجة. يغطي هذا الدليل الاتصال الأولي، والخطوتين من جانب المستودع اللتين تُكملان الإعداد، وقراءة سجل النشر، وآلية اكتشاف buildpack التي تحدد كيفية بناء تطبيق Node.js.
أين يقع نشر Git
افتح المواقع، ثم انقر على الموقع، ثم افتح مجموعة البيئة في القائمة اليسرى للموقع، واختر نشر Git. توجد صفحتان مرتبطتان بالقرب منها:
- عمليات النشر، سجل النشر الكامل لهذا الموقع، ضمن نفس مجموعة البيئة.
- Buildpack، استراتيجية البناء المكتشفة، في مواقع Node.js، ضمن مجموعة التطبيقات.
تصف صفحة نشر Git نفسها بوضوح: اربط مستودعًا وستؤدي كل عملية push إلى الفرع الذي قمت بتهيئته إلى تشغيل عملية بناء ونشر.
ربط مستودع
- اختر المزوّد: GitHub أو GitLab أو Bitbucket.
- أدخل عنوان URL للمستودع. الصيغة المطلوبة هي صيغة SSH، على سبيل المثال
git@github.com:user/repo.git. - اضبط الفرع الذي سيتم النشر منه. يبدأ الحقل بـ
main. - اختياريًا، حدد أمر البناء، على سبيل المثال
npm run build. - اختياريًا، حدد دليل الإخراج، على سبيل المثال
distأوpublic، أو.لمستودع تم بناؤه مسبقًا. - انقر على الاتصال بالمستودع.
اترك أمر البناء ودليل الإخراج فارغين إذا كان مستودعك قابلًا للنشر كما هو، وهو الوضع الشائع لموقع PHP بسيط أو موقع ثابت.
السكريبتات المتقدمة
يؤدي توسيع متقدم إلى إظهار حقلين إضافيين:
- سكريبت ما قبل النشر، الذي يعمل قبل البناء.
- سكريبت ما بعد النشر، الذي يعمل بعد النشر.
استخدم خطاف ما بعد النشر للأمور التي يجب أن تحدث بمجرد وضع الشيفرة الجديدة في مكانها: مسح ذاكرة التخزين المؤقت للتطبيق، تشغيل ترحيل لقاعدة البيانات، إعادة تشغيل عملية (worker).
النشر التلقائي عند الـ Push
يتحكم مفتاح التبديل أسفل البطاقة فيما إذا كانت عمليات الـ push تؤدي إلى النشر أصلًا. عند تفعيله، تؤدي كل عملية push إلى الفرع الذي تم تهيئته إلى تشغيل عملية نشر. وعند إيقافه، لا تعمل عمليات النشر إلا عند تشغيلها يدويًا باستخدام نشر الآن.
أوقف النشر التلقائي أثناء تجميد الشيفرة أو وقوع حادثة بدلًا من فصل المستودع. فصل المستودع يؤدي إلى التخلص من مفتاح النشر وسر الـ webhook، مما يعني أنك ستحتاج إلى إعادة تنفيذ كلتا الخطوتين من جانب المستودع لاحقًا.
إكمال الإعداد في مستودعك
ربط المستودع في KPanel ليس سوى الخطوة الأولى من ثلاث خطوات. وإلى أن يتم تشغيل عملية نشر، تعرض الصفحة شريطًا يقول إكمال الإعداد: خطوتان متبقيتان مع كل ما تحتاجه.
الخطوة 2: إضافة مفتاح النشر
تحتاج KapsuleHost إلى صلاحية قراءة لاستنساخ مستودعك. يعرض الشريط مفتاحًا عامًا مع زر نسخ المفتاح.
الصقه في إعدادات مفاتيح النشر في مستودعك. بالنسبة لـ GitHub، يوفر الشريط اختصار إضافة إلى GitHub الذي ينقلك مباشرة إلى صفحة الإعدادات الصحيحة. صلاحية القراءة كافية؛ لا تمنح صلاحية الكتابة.
الخطوة 3: إضافة الـ Webhook
الـ webhook هو ما يُعلم KapsuleHost بحدوث عملية push. يمنحك الشريط ثلاث قيم:
| الحقل | القيمة |
|---|---|
| عنوان URL للحمولة | عنوان URL ينتهي بـ /api/git-deploy/webhook/ بالإضافة إلى معرّف هذا الموقع |
| السر | سر توقيع تم توليده، مخفي حتى تنقر على أيقونة العين |
| نوع المحتوى | application/json |
انسخ كل قيمة إلى إعدادات الـ webhook في مستودعك. بالنسبة لـ GitHub، هناك اختصار إضافة webhook إلى GitHub. اضبط نوع المحتوى على JSON، وليس الصيغة الافتراضية المُرمّزة كنموذج، وإلا فلن يتم تحليل الحمولة.
تعامل مع سر الـ webhook كما تتعامل مع كلمة مرور. أي شخص يملكه، بالإضافة إلى عنوان URL للحمولة، يمكنه تشغيل عملية نشر لموقعك. كلتا القيمتين لا تُعرضان إلا لمن يملكون بالفعل صلاحية إدارة الموقع، ويبقى السر مخفيًا خلف أيقونة العين حتى تطلب إظهاره.
النشر يدويًا
انقر على نشر الآن في صفحة نشر Git لبناء ونشر أحدث إصدار من الفرع المهيأ دون الحاجة إلى push لأي commit. يعمل هذا سواء كان النشر التلقائي مفعلًا أم لا، وهذا ما يجعله الأداة المناسبة أثناء فترة التجميد: يتم تجاهل عمليات الـ push، لكن يمكنك مع ذلك نشر الإصلاح.
قراءة سجل النشر
افتح البيئة، ثم عمليات النشر. عنوان الصفحة هو سجل النشر وتسرد كل عملية نشر تم تشغيلها عبر webhook أو يدويًا، بدءًا بالأحدث.
يحمل كل صف:
- أيقونة حالة ورمز الـ commit المختصر (SHA)، مع الفرع كشارة.
- رسالة الـ commit، أو نشر يدوي إذا لم تكن هناك رسالة commit لعرضها.
- الكاتب، ومنذ متى تم التشغيل، والمدة التي استغرقها، وما الذي تسبب في تشغيله.
- شارة حالة.
الحالات هي قيد الانتظار، قيد البناء، قيد النشر، ناجح وفاشل. وطالما أن هناك عملية جارية، تُحدّث الصفحة نفسها كل خمس ثوانٍ وتعرض ملاحظة التحديث تلقائيًا أسفل الجدول، بحيث يمكنك تركها مفتوحة ومراقبة اكتمال عملية النشر.
عند فشل عملية النشر
يحصل الصف الفاشل على زر خطأ على الجانب الأيمن. انقر عليه لتوسيع مخرجات الخطأ المسجلة مباشرة ضمن الصفحة، دون الحاجة لمغادرتها. تلك المخرجات هي نص الخطأ الخاص بعملية البناء نفسها، لذا فهي عادة ما تحدد الملف أو الأمر الذي فشل.
اعمل على حل المشكلة بهذا الترتيب: اقرأ الخطأ، أعد إنتاج نفس أمر البناء محليًا، أصلح المشكلة، ثم نفّذ push. إذا نجح البناء محليًا ولكن ليس هنا، فالفرق يكاد يكون دائمًا متعلقًا بالبيئة، إما تبعية مفقودة مثبتة بشكل عام على جهازك، أو ملف موجود في دليل العمل لديك لكنه غير مُضمّن في الـ commit.
اكتشاف Buildpack
في مواقع Node.js، تُظهر صفحة Buildpack ضمن مجموعة التطبيقات كيف قررت KapsuleHost بناء تطبيقك. يعمل الاكتشاف على الملفات الموجودة في جذر مستودعك، ويفوز أول تطابق:
| المُكتشَف | المُحفِّز |
|---|---|
| Buildpack مخصص | kapsule.config.yaml أو kapsule.config.yml في الجذر |
| buildpack خاص بـ Dockerfile | Dockerfile في الجذر |
| Node.js | package.json مع سكريبت start أو build أو dev |
| Python | requirements.txt أو pyproject.toml |
| PHP | composer.json |
| ثابت (Static) | index.html في الجذر |
إذا لم يتطابق أي شيء، تُشير الصفحة إلى ذلك وتسرد المحفزات المدعومة. أضف Dockerfile أو kapsule.config.yaml للتحكم في عملية البناء صراحة.
تشغيل عملية بناء
انقر على تشغيل البناء لوضعها في قائمة الانتظار. تقوم الصفحة بالاستعلام كل ثلاث ثوانٍ أثناء تشغيل عملية ما، ويعرض جدول النسخ الأخيرة آخر عمليات التشغيل مع وقت البدء والنوع والحالة والمدة ومرجع الصورة الناتجة. انقر على صف لرؤية ذيل سجله.
يمكن تشغيل عملية بناء واحدة فقط في وقت واحد. محاولة تشغيل عملية ثانية بينما أخرى في قائمة الانتظار أو قيد التشغيل تُرفض برسالة البناء جاري بالفعل، وهذا أمر مقصود: قيام عمليتي بناء بالكتابة على نفس الإخراج في نفس الوقت هو السبب الشائع للحصول على موقع منشور جزئيًا.
قطع الاتصال
انقر على قطع الاتصال وأكّد ذلك. يوضح التأكيد بشكل صريح نطاق التأثير: تتم إزالة إعدادات نشر Git ومفتاح النشر، ولا تتأثر ملفات موقعك. يستمر الموقع في تقديم آخر نسخة تم نشرها.
رتّب الأمور بعد ذلك بحذف مفتاح النشر والـ webhook من إعدادات مستودعك. ستتوقف ببساطة عن العمل، لكن ترك مدخلات ميتة يجعل عملية التدقيق التالية أصعب.
استكشاف الأخطاء وإصلاحها
عمليات الـ push لا تُحفّز أي شيء. تحقق أولًا من مفتاح تبديل النشر التلقائي، ثم من الـ webhook في مستودعك. تعرض معظم المزودين عمليات التسليم الأخيرة ورموز استجابتها، مما يخبرك على الفور ما إذا كان الطلب قد غادر مستودعك أصلًا.
عملية الاستنساخ تفشل. مفتاح النشر مفقود، أو تم لصقه مع فاصل أسطر بداخله، أو تمت إضافته إلى المستودع الخاطئ. انسخه مجددًا باستخدام زر نسخ المفتاح بدلًا من تحديد النص يدويًا.
عملية النشر تنجح لكن الموقع لا يتغير. على الأرجح أن دليل الإخراج خاطئ. إذا كانت عملية البناء الخاصة بك تكتب إلى dist ودليل الإخراج فارغ، فإن الملفات المبنية لن تصل أبدًا إلى الجذر المنشور.
كل شيء يظهر بحالة قيد الانتظار ولا يتحرك أبدًا. تم وضع عملية النشر في قائمة الانتظار لكن لم يتم التقاطها أبدًا. شغّل نشر الآن يدويًا وتحقق من صفحة عمليات النشر بحثًا عن صف خطأ.
إلى أين تذهب بعد ذلك
- معاينة عمليات النشر لطلبات السحب يضيف عنوان URL خاصًا بكل طلب سحب فوق هذا الإعداد.
- تخزين أسرار التطبيق لموقع ما للحصول على بيانات الاعتماد التي يحتاجها البناء وبيئة التشغيل لديك.
- سجل نشاط الموقع يسجل التغييرات في الإعدادات التي تمت هنا.