إصلاح خطأ "لا يمكن الاتصال بـ Kopano Core" في تطبيق Kopano WebApp

أسرع طريقة لإصلاح خطأ "تعذر الاتصال بـ Kopano Core" في تطبيق Kopano WebApp هي تحديد الطبقة المعطلة من بين ثلاث طبقات: Kopano Core نفسه ، أو نقطة اتصال WebApp بـ Core ، أو طبقة PHP-MAPI التي يستخدمها WebApp للتواصل مع Core. قد يبدو إعادة تشغيل كل شيء حلاً مؤقتًا للمشكلة، لكنه يخفي السبب الحقيقي، وقد يُصعّب تشخيص الأعطال المتكررة.

تُشير وثائق تطبيق الويب الرسمي لـ Kopano إلى أن تطبيق الويب يعتمد على Kopano Core php-mapi، وأن DEFAULT_SERVERإعداداته تتحكم في مكان اتصال تطبيق الويب بـ Kopano Core. تشمل الخيارات الموثقة مقبس Unix المحلي، وبروتوكول HTTP على المنفذ 236، وبروتوكول HTTPS على المنفذ 237. راجع وثائق تكوين تطبيق الويب لـ Kopano ودليل مسؤول Kopano Core .

ملاحظة هامة بخصوص الإصدار: أدلة إدارة Kopano العامة المتوفرة وقت كتابة هذا النص أقدم من العديد من توزيعات Linux الحالية. لذا، قد تختلف أسماء الحزم وإصدارات PHP وأغلفة الخدمات ومواقع السجلات في تثبيتك. يعتمد نموذج الاتصال وخيارات التكوين الموضحة أدناه على وثائق Kopano المنشورة، ولكن يُنصح بالتأكد من المسارات المحلية وإصدارات الحزم قبل إجراء أي تغييرات على خادم الإنتاج.

ما هو الحل الذي يجب أن تجربه أولاً؟

ابدأ بالعرض الذي يتناسب بشكل أفضل مع نظامك بدلاً من تطبيق كل تغيير دفعة واحدة.

1. هل يعمل برنامج Kopano Core بالفعل؟

تحقق من عملية الخادم قبل تعديل إعدادات تطبيق الويب. في التوزيعات التي تعتمد على systemd، استخدم ما يلي:

sudo systemctl status kopano-server

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

sudo journalctl -u kopano-server -n 100 --no-pager

ابحث عن أخطاء في اتصال قاعدة البيانات، أو فشل تحليل التكوين، أو مشاكل في الأذونات، أو ملفات مفقودة، أو أخطاء في بدء التشغيل. تشير وثائق Kopano Core إلى أن تغييرات التكوين تتطلب عادةً إعادة تشغيل المكون المتأثر، على سبيل المثال باستخدام الأمر `require` systemctl restart kopano-<component>. كما توثق هذه الوثائق /etc/kopano/server.cfgملف التكوين المعتاد لـ `require` kopano-server. راجع قسم "تكوين مكونات Kopano Core" .

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

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

2. هل يشير تطبيق الويب إلى نقطة نهاية Kopano Core الصحيحة؟

في تطبيق الويب، يوجد الإعداد الرئيسي DEFAULT_SERVERفي config.php. يوثق دليل تطبيق الويب الرسمي من كوبانو هذه الأمثلة:

define("DEFAULT_SERVER", "default:");
define("DEFAULT_SERVER", "file:///var/run/kopano/server.sock");
define("DEFAULT_SERVER", "http://localhost:236/kopano");
define("DEFAULT_SERVER", "https://localhost:237/kopano");

يُشير الإعداد الافتراضي الموثق إلى المقبس المحلي file:///var/run/kopano/server.sock. يُعد هذا الخيار الأبسط عادةً عند تشغيل تطبيق الويب والنظام الأساسي على نفس الجهاز. أما إذا كانا يعملان على جهازين منفصلين، فلن يعمل مقبس يونكس المحلي؛ بل ستحتاج إلى نقطة نهاية HTTP أو HTTPS قابلة للوصول. توضح وثائق تحسين أداء Kopano كيفية اتصال مضيف تطبيق الويب بخادم Kopano منفصل عبر المنفذ 236، أو المنفذ 237 لبروتوكول SSL. راجع قسم تحسين أداء Kopano وتكوين الخادم المنفصل .

مقبس يونكس المحلي: يُعدّ عمومًا الخيار الأقل استهلاكًا للموارد على مضيف واحد، ويتجنّب تعريض خدمة TCP لمجرد الوصول إلى تطبيق الويب المحلي. لكنّ ثمن ذلك يكمن في ضرورة وجود المقبس وإمكانية استخدامه من قِبل عملية خادم الويب.

بروتوكول HTTP على المنفذ 236: يسهل اختباره على مختلف الأجهزة، وهو مناسب للشبكات الداخلية الموثوقة عندما تسمح بنية الأمان بذلك. لكن يعيبه أن حركة البيانات لا تُشفّر في طبقة نقل Kopano.

استخدام بروتوكول HTTPS على المنفذ 237: يُعدّ مناسبًا عند الحاجة إلى نقل بيانات مشفر بين تطبيق الويب والنظام الأساسي. ويتطلب ذلك إعداد الشهادات والتحقق منها. توضح وثائق التكوين الخاصة بـ Kopano استخدام تطبيق الويب لبروتوكول HTTPS DEFAULT_SERVER، وفي بعض الحالات، شهادات العميل. راجع تكوينات Kopano الخاصة بالنظام الأساسي .

3. إذا كنت تستخدم مقبس يونكس، فهل هو موجود وهل يمكن لخادم الويب الوصول إليه؟

بالنسبة لعملية النشر على نفس المضيف، تحقق من المقبس نفسه:

ls -l /var/run/kopano/server.sock
file /var/run/kopano/server.sock
ss -xl | grep kopano

إذا كان الملف مفقودًا، فلا تقم بإنشاء ملف عادي بهذا الاسم. يتم إنشاء المقبس بواسطة خادم Kopano قيد التشغيل. لذا، يشير فقدان المقبس عادةً إلى بدء تشغيل Core، أو تغيير مسار المقبس، أو عدم تطابق في الإعدادات.

إذا كان المقبس موجودًا، فتحقق من ملكيته ووضعه. يجب أن يتمكن مستخدم خادم الويب من الوصول إلى المقبس عبر مسار الدليل الخاص به. اعتمادًا على توزيعتك، قد يكون حساب خادم الويب هو `/user/` www-dataأو apache`/user/` أو مستخدم آخر خاص بالخدمة. تجنب حل أخطاء الأذونات باستخدام أوضاع عامة مثل `/user/` chmod 777؛ لأن ذلك يزيد من احتمالية حدوث أخطاء وقد يتم استبدالها في المرة القادمة التي تعيد فيها الخدمة إنشاء المقبس.

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

4. ماذا لو كان النظام الأساسي سليمًا ولكن تطبيق الويب لا يزال يقول إنه لا يستطيع الاتصال؟

تحقق من PHP-MAPI بعد ذلك. يذكر Kopano صراحةً أن WebApp يعتمد عليه php-mapi. يمكن لفحص إعدادات WebApp أيضًا اختبار توفر PHP وPHP-MAPI. راجع توثيق WebApp Config.php .

إليك طريقة سريعة للتحقق من واجهة سطر الأوامر:

php -m | grep -i mapi

مع ذلك، ينطوي هذا الاختبار على قيدٍ هام: قد لا تستخدم واجهة سطر أوامر PHP نفس إعدادات Apache PHP أو PHP-FPM أو أي تكامل آخر لخادم الويب. وتُثبت نتيجة واجهة سطر الأوامر الإيجابية فقط أن بيئة سطر الأوامر تتعرف على الوحدة.

تشمل عمليات المتابعة المفيدة ما يلي:

php --ini
php -i | grep -i mapi

ثم قارن ذلك بإعدادات PHP المستخدمة من قِبل خادم الويب أو مجموعة FPM. إذا كانت الحزمة مفقودة أو كانت الإصدارات غير متوافقة، فقم بتثبيت مجموعة حزم Kopano Core/PHP-MAPI المطابقة من المستودع المخصص لتوزيعتك وإصدار Kopano الخاص بك. لا تقم بدمج إصدارات PHP-MAPI غير ذات الصلة لمجرد إظهار الامتداد في ملف التكوين php -m.

اختر هذا المسار عندما: kopano-server يكون النظام سليمًا، وتكون نقطة النهاية صحيحة ويمكن الوصول إليها، ولكن تطبيق الويب يفشل أثناء عمليات التحقق من الاتصال أو التكوين من جانب PHP.

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

هل يجب إعادة تشغيل خادم Apache أو PHP-FPM أو Kopano؟

أعد تشغيل المكون الذي تم تغيير تكوينه أو وحدته النمطية بالفعل.

• إذا قمت بالتغيير /etc/kopano/server.cfg، فأعد التشغيل kopano-server.
• إذا قمت بتثبيت أو تمكين ملحق PHP، فأعد تشغيل طبقة خدمة PHP المستخدمة بواسطة WebApp، مثل Apache أو خدمة PHP-FPM ذات الصلة.
• إذا قمت فقط بتغيير ملف تكوين PHP الخاص بتطبيق الويب، فعادةً ما تكون إعادة تشغيل Kopano Core بالكامل غير ضرورية ما لم تتغير نقطة نهاية Core نفسها أيضًا.

يختلف أمر خدمة الويب باختلاف توزيعة PHP وحزمة PHP المستخدمة. على سبيل المثال systemctl restart apache2، قد يكون الأمر systemctl restart httpd`/etc/web-service` أو `/etc/web-service` أو وحدة PHP-FPM ذات إصدار محدد. استخدم اسم الخدمة الموجود على خادمك بدلاً من نسخ الأمر دون تدقيق.

ماذا عن خوادم Core البعيدة وجدران الحماية؟

إذا كان تطبيق الويب وKopano Core منفصلين، فتحقق أولاً من التوجيه والمستمع المُهيأ قبل إلقاء اللوم على تطبيق الويب. توضح وثائق Kopano الوصول عبر HTTP على المنفذ 236 والوصول عبر SSL على المنفذ 237. وبالتالي، يُضيف النشر عن بُعد عدة أنماط فشل لا توجد في النشر المحلي باستخدام مقابس Unix، مثل: قواعد جدار الحماية، وربط المستمع، ونظام أسماء النطاقات (DNS)، وشهادات TLS، والخوادم الوكيلة العكسية، وسياسة الشبكة الوسيطة.

بالنسبة لنقطة نهاية HTTP، يمكنك على الأقل التحقق مما إذا كان مستمع TCP قابلاً للوصول من مضيف تطبيق الويب:

nc -vz core.example.net 236

بالنسبة لبروتوكول HTTPS، تحقق من نقطة نهاية TLS بشكل منفصل باستخدام أداة مناسبة لسياسة الشهادات الخاصة بك. لا يضمن نجاح اتصال TCP نجاح مصادقة تطبيق الويب أو عمليات MAPI، ولكن فشل الاتصال يثبت أن PHP-MAPI لا يمكنه الوصول إلى الخدمة المُكوّنة عبر هذا العنوان والمنفذ.

إذا كنت تستخدم خادم وكيل عكسي، فتذكر أن وثائق Kopano تشترط أن يكون مسار الوكيل وتعيين الواجهة الخلفية متوافقين مع عنوان URL الذي يستخدمه تطبيق الويب. كما يشير الدليل الرسمي لـ Kopano Core إلى اعتبارات HTTP/1.1 لتوجيه حركة مرور Kopano. راجع قسم تكوين مكونات Kopano Core .

ترتيب تشخيصي عملي يقلل من التغييرات غير الضرورية

1. تحقق من kopano-serverالحالة. إذا كانت العملية فاشلة، فقم بإصلاح النظام الأساسي أولاً.
2. اقرأ سجلات النظام الأساسية. يجب حل مشكلات قاعدة البيانات أو التكوين قبل أن يتمكن تطبيق الويب من الاتصال.
3. تحقق DEFAULT_SERVER. تأكد من مطابقته لمقبس محلي أو نقطة نهاية HTTP/HTTPS البعيدة الصحيحة.
4. اختبر المقبس أو مستمع الشبكة الفعلي. هذا يفصل بين أعطال النقل ومشاكل PHP.
5. تحقق من PHP-MAPI في بيئة تشغيل الويب. لا تعتمد فقط على بيئة سطر الأوامر PHP.
6. أعد تشغيل الخدمات المتأثرة فقط. ثم أعد اختبار تطبيق الويب وراجع السجلات إذا استمر الخطأ.

يُعدّ هذا الترتيب أكثر أمانًا من البدء بإعادة تثبيت الحزم، لأنه يحافظ على الأدلة ويجعل كل اختبار ذا مغزى. كما أنه يتجنب الخطأ المعاكس: إعادة تشغيل تطبيق الويب أو خادم Apache بشكل متكرر عندما يتعذر على Kopano Core نفسه بدء التشغيل.

متى يكون تغيير DEFAULT_SERVER حلاً خاطئاً؟

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

على سبيل المثال، لا يُعدّ الاستبدال default:ترقيةً http://localhost:236/kopanoبالضرورة. فهو يُغيّر بروتوكول النقل من المقبس الافتراضي المحلي الموثّق إلى بروتوكول TCP. قد يكون ذلك مفيدًا لتصحيح الأخطاء أو في بنية الشبكة التي تتطلب TCP، ولكنه يُغيّر أيضًا مستوى الأمان وواجهة التشغيل. في حالة إعداد نفس المضيف، غالبًا ما يكون إصلاح المقبس المفقود أو غير القابل للوصول أسهل من فتح مستمع آخر.

ماذا يجب عليك فعله إذا استمر الخطأ؟

عند هذه النقطة، اجمع الأدلة من كلا طرفي العلاقة:

• القيمة الدقيقة DEFAULT_SERVER، مع إزالة بيانات الاعتماد أو الأسرار؛
• systemctl status kopano-serverوإدخالات سجل خادم كوبانو الأخيرة؛
• معلومات ملكية المقبس أو معلومات المستمع البعيد؛
• إصدار PHP وامتداد MAPI المحمل في وقت تشغيل خدمة الويب؛
• سجل أخطاء تطبيق الويب/PHP المتعلق بمحاولة تسجيل دخول فاشلة.

تُشير وثائق تطبيق الويب الخاص بـ Kopano إلى أن تسجيل أخطاء PHP مُفعّل من خلال إعدادات PHP، config.phpوتحذر من عرض الأخطاء مباشرةً لأن ذلك قد يُؤدي إلى تلف استجابات JSON. لذا، تُعد سجلات جانب الخادم المصدر التشخيصي الأفضل. يُرجى الرجوع إلى إعدادات تسجيل تطبيق الويب الرسمية قبل زيادة مستوى التفصيل.

بمجرد تحديد ما إذا كان العطل ناتجًا عن بدء تشغيل Kopano Core، أو النقل، أو الأذونات، أو PHP-MAPI، أو الشبكات البعيدة، قم بتطبيق أصغر حل يُعالج تلك الطبقة. هذا أكثر موثوقية من التعامل مع رسالة "لا يمكن الاتصال بـ Kopano Core" كخطأ واحد بحل واحد شامل.