تتبع حالات فشل الاتصال بـ Collabora باستخدام سجلات coolwsd

بالنسبة لحاوية Collabora Online Development Edition (CODE)، ارفع coolwsdمستوى التسجيل إلى 0 debug، وتأكد من عدم تعطيل منطقتي Socketو ، ثم أعد إنتاج فشل فتح مستند واحد مع متابعة سجلات الحاوية. في Docker Compose، مرر الإعدادات عبر متغير بيئة صورة CODE وأعد إنشاء الخدمة. استخدم هذا الخيار فقط إذا لم يُظهر مُخرَج التصحيح مكان توقف الاتصال، ثم ارجع إلى المستوى السابق عند الانتهاء.WebSocketextra_paramstrace

تُناسب هذه الطريقة عمليات نشر Docker أو Compose حيث يُمكنك تحديث إعدادات الحاوية. أما تثبيت الحزمة الأصلي فيستخدم /etc/coolwsd/coolwsd.xmlمدير خدماته بدلاً من ذلك. يُضيف هذا الإعداد تفاصيل تشخيصية، ولكنه لا يُصلح مشكلة الوكيل أو مضيف WOPI أو الشهادة أو الشبكة تلقائيًا.

1. ابدأ بعملية تكاثر واحدة خاضعة للتحكم

اختر مستندًا واحدًا وسجّل وقت محاولة فتحه، وعنوان URL العام لـ Collabora، واسم الحاوية أو خدمة Compose. تجنّب تحديث عدة ملفات بشكل متكرر: فمحاولة واحدة تُسهّل عليك ربط أعراض المتصفح، وسجل الوكيل، وسجل خادم التكامل، وإدخالات coolwsd.

تأكد من أن الحاوية قيد التشغيل وحدد اسمها:

docker ps --format 'table {.Names}	{.Status}	{.Ports}'

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

docker logs --since 2m --follow --timestamps collabora

--followيُتيح هذا الخيار عرض المخرجات الجديدة، --sinceوتقييد سجل البيانات الأولي، --timestampsوإضافة طوابع زمنية خاصة بـ Docker. يوثّق Docker هذه الخيارات في مرجع سجلات الحاويات . في Compose، يمكنك استخدام docker compose logs --since=2m --follow collabora، حيث collaboraيُمثّل مفتاح الخدمة.

2. قم بتفعيل وضع تصحيح الأخطاء في coolwsd للاختبار

يدعم مخطط تكوين Collabora مستويات مُسماة تشمل warning، notice، information، debug، و trace. كما يُعرّف أيضًا disabled_areas؛ حيث يُعطّل الإعداد الافتراضي الموثق إخراج المعلومات التفصيلية من Socketو WebSocket، من بين أمور أخرى. هذا الأمر مهم لاستكشاف أخطاء الاتصال وإصلاحها: فقد يؤدي تغيير المستوى وحده إلى إخفاء أهم تفاصيل المصافحة. هذه الخيارات موثقة في قالب تكوين Collabora coolwsd ودليل Collabora Online SDK (قسم تكوين Docker؛ تمت مراجعته في أكتوبر 2026).

بالنسبة للصورة الرسمية collabora/code، أضف الخيارين إلى القيمة الحالية للخدمة extra_params. احتفظ بأي خيارات مطلوبة مسبقًا من قِبل عملية التثبيت، مثل إنهاء SSL أو اسم الخادم.

services:
  collabora:
    environment:
      extra_params: "--o:logging.level=debug --o:logging.disabled_areas=Admin,Pixel"

Socketيُبقي الخيار الثاني على WebSocketخيار التسجيل عالي التفصيل، مع إبقاء خياري التسجيل Adminوالتسجيل Pixelمُعطَّلين. لا تُضِف هذين الخيارين إلى قائمة الخيارات المُعطَّلة أثناء هذا الاختبار. تُوضِّح وثائق صورة CODE extra_paramsطريقة تمرير خيارات سطر الأوامر إلى coolwsd. إذا كان نظامك يستخدم ملف تكوين مُثبَّتًا أو صورة مُدارة من قِبل المورِّد، فاتبع طريقة التكوين الخاصة بهذا النظام.

قم بتطبيق تعديل Compose عن طريق إعادة إنشاء الخدمة:

docker compose up -d --force-recreate collabora

استخدم اسم خدمة Compose الفعلي. بالنسبة للحاوية قصيرة العمر التي تم تشغيلها باستخدام docker run، قم بتحديث إعدادات التشغيل الخاصة بها وأعد إنشائها بنفس وحدات التخزين والشبكات والمنافذ والخيارات الأخرى. يشير دليل CODE إلى أن الصورة تقبل extra_paramsعند بدء التشغيل؛ لا تفترض أن تغيير بيئة حاوية تم إنشاؤها مسبقًا سيؤثر على عملية coolwsd قيد التشغيل.

3. اقرأ الاتصال بالترتيب

أعد إنتاج الخطأ مرة واحدة، ثم راجع تلك الفترة الزمنية فقط. ابحث في المخرجات عن مصطلحات مثل WebSocketو WOPIو ERRو و WRN، ثم قارن الطوابع الزمنية. تختلف الصياغة الدقيقة ومناطق السجلات باختلاف إصدار Collabora، لذا تعامل معها كفئات للفحص وليست رسائل حرفية مضمونة.

• لم تُسجّل أيّ إدخالات جديدة في coolwsd وقت الاختبار: قد لا يصل الطلب إلى هذه الحاوية. يُرجى التحقق من عنوان URL العام المُكوّن، ونظام أسماء النطاقات (DNS)، وموازن الأحمال، وسجلات الوصول/الأخطاء الخاصة بالخادم الوكيل العكسي، والتأكد من أنك تراقب النسخة المتماثلة الصحيحة.
• يصل المتصفح إلى الخدمة، لكن اتصال WebSocket لا يبقى مفتوحًا: راجع معالجة الوكيل لترقية WebSocket، والمضيف المُعاد توجيهه والبروتوكول، وإنهاء TLS، وتوجيه المسار، ومهلات الخمول. قارن ذلك مع وحدة تحكم مطور المتصفح وسجلات الوكيل؛ لا يستطيع coolwsd تفسير طلب لم يُعِد الوكيل توجيهه.
• يظهر طلب WOPI ويفشل: تحقق من عنوان URL الخاص بخادم التكامل لبروتوكول WOPI، وقائمة السماح للمضيفين أو إعدادات الاسم المستعار، وإمكانية الوصول من حاوية Collabora، واستجابة خادم التكامل. يُعد خطأ WOPI مرحلة منفصلة عن اتصال WebSocket بين المتصفح وCollabora.
• تنجح عملية WOPI، لكن المتصفح لا يزال ينقطع الاتصال: ركّز الآن على مسار WebSocket وأخطاء الاتصال من جانب المتصفح. هذا التسلسل يُضيّق نطاق البحث، لكنه لا يُثبت أي إعدادات الوكيل أو الشبكة خاطئة.

إذا لم يُظهر Docker أي مخرجات رغم أن الخدمة نشطة، فتحقق من إعدادات التسجيل داخل الحاوية. يقرأ أمر التسجيل في Docker مخرجات الحاوية القياسية وتدفقات الأخطاء؛ قد يستخدم التثبيت المُهيأ للكتابة إلى ملف مسارًا مثل `//` /var/log/coolwsd.log، كما هو مُحدد في إعداداته. افحص الملف الفعلي بدلًا من افتراض هذا المسار.

docker exec collabora sh -c 'grep -n -A25 "<logging>" /etc/coolwsd/coolwsd.xml'

في حال تفعيل تسجيل الملفات، استخدم المسار المُكوّن، على سبيل المثال:

docker exec collabora sh -c 'tail -n 200 /var/log/coolwsd.log'

4. تحقق من النتيجة واستعد التسجيل الطبيعي

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

docker logs --since 5m --timestamps collabora

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

docker logs --since 5m collabora | grep -Ei 'coolwsd|WOPI|WebSocket|ERR|WRN'

logging.levelاستعد القيم السابقة disabled_areas، ثم أعد إنشاء الخدمة. قد تُنتج مستويات التصحيح والتتبع بيانات أكثر بكثير، وقد تتضمن تفاصيل تشغيلية حساسة. قبل مشاركة السجلات، احجب رموز الوصول، وأسماء المستندات، ومعرّفات المستخدمين، وأسماء المضيفين، والعناوين الداخلية. إذا لم تكن الخدمة هي صورة CODE الرسمية، فتأكد من مسار تكوينها والمعلمات المدعومة مع مسؤول تلك الصورة.