إصلاح مشكلة "انقطاع اتصال المقبس بشكل غير متوقع" في Collabora Online: فحوصات WebSocket والبروكسي

قد يبدو Collabora Online سليمًا للوهلة الأولى، ولكنه قد يتعطل بمجرد محاولة المحرر إنشاء اتصال WebSocket مباشر. تتمثل الأعراض الشائعة في بدء تحميل المستند ثم ظهور رسالة تفيد بإغلاق اتصال WebSocket بشكل غير متوقع، مصحوبة أحيانًا بفشل wss://الطلب في المتصفح. في إصدار 2026، ثمة سبب خاص بهذا الإصدار يستدعي التحقق قبل إجراء أي تغييرات أخرى: فقد قدم فرع 26.04 عنوان URL أكثر اختصارًا لـ WebSocket، وقد تتعارض قواعد الوكيل العكسي القديمة معه.

تشير ملاحظات إصدار CODE 26.04 الرسمية من Collabora إلى أن الإصدار 26.04.1، الصادر في 8 يونيو 2026، كان يتطلب من مستخدمي خادم Apache2 العكسي تغيير قاعدة ProxyPass الخاصة بهم لتتوافق مع عنوان URL الجديد المُختصر لـ WebSocket. وتشير ملاحظات الإصدار 26.04.2.x اللاحقة إلى أن CODE يمكنه الرجوع إلى عنوان URL القديم في حال تعذر استخدام المسار الجديد، ويُصدر تحذيرًا يُوجه المسؤولين إلى توصيات الوكيل الحالية. كما أن فرع Collabora Online 26.04 الخاص بالمؤسسات مُحدّث حتى عام 2026، لذا ينبغي على المسؤولين مقارنة أي إعدادات وكيل منسوخة من دليل الإصدار 24.04 أو 25.04 الأقدم مع أحدث وثائق المورّد قبل اعتبار المشكلة عطلًا عشوائيًا في الشبكة.

ما يعنيه الخطأ فعلياً

لا تُحدد الرسالة سببًا جذريًا واحدًا. هذا يعني أن اتصال WebSocket بين المتصفح وCollabora إما لم يُحدَّث بنجاح أبدًا، أو أنه تم إنشاؤه ثم توقف بشكل غير متوقع. هذا التمييز مهم لأن الحلول تختلف.

1. تحقق مما إذا كان العطل قد بدأ بعد الترقية إلى الإصدار 26.04

إذا ظهرت المشكلة مباشرةً بعد الترقية من الإصدار 25.04 أو إصدار أقدم من CODE إلى الإصدار 26.04، فاعتبر الخادم الوكيل العكسي هو السبب الرئيسي. هذا ليس مجرد تخمين، فقد وثّقت شركة Collabora تغيير عنوان URL المُختصر لبروتوكول WebSocket في ملاحظات الإصدار 26.04، كما أبلغت إحدى المشكلات الرسمية في المشروع عن فشل بروتوكولات WebSocket بعد الترقية إلى الإصدار 26.04.1 إلى حين تعديل قواعد خادم Apache الوكيل.

لا تحلّ هذه المشكلة بالرجوع إلى إصدار أقدم دون تعديل الخادم الوكيل القديم. قد يكون الرجوع إلى الإصدار السابق إجراءً مؤقتًا، لكن الحل الدائم هو مواءمة الخادم الوكيل مع الإصدار الذي تنوي تشغيله. بالنسبة إلى Apache، استخدم إعدادات خادم Collabora Online الوكيل الحالية بدلاً من نسخة أقدم من الإصدار 26.04. يُوثّق سجل مشكلات WebSocket الخاص بـ Collabora (الإصدار 26.04) حالةً تم فيها استعادة التشغيل بعد تحديث قواعد Apache.

2. أثبت ما إذا كان بروتوكول HTTP يعمل بينما يفشل بروتوكول WebSocket

اختبر نقاط نهاية Collabora العادية أولاً:

curl -I https://office.example.com/hosting/discovery
curl -I https://office.example.com/hosting/capabilities

تُثبت الاستجابة الناجحة إمكانية الوصول إلى نظام أسماء النطاقات (DNS) وبروتوكول أمان طبقة النقل (TLS) وخادم الوكيل الأمامي وجزء على الأقل من خدمة Collabora. لكنها لا تُثبت عمل خاصية تحرير المستندات، إذ يعتمد المحرر على مسار WebSocket ضمن نطاق معين /cool/، والذي يتطلب متطلبات مختلفة لخادم الوكيل.

بعد ذلك، افتح أدوات مطوري المتصفح، وكرر الخطأ، وافحص لوحة الشبكة باستخدام مُرشِّح WS. عادةً ما تُحسِّن عملية المصافحة الناجحة لـ WebSocket اتصال HTTP؛ ويُعرِّف RFC 6455 استجابة الخادم بأنها حالة HTTP 101 عند نجاح التحسين. إذا رأيت بدلاً من ذلك 400 أو 404 أو 405 أو 502، أو طلبًا فاشلاً فوريًا، فاربط الطابع الزمني لهذا الحدث بسجلات الخادم الوكيل العكسي وcoolwsd.

3. قم بإصلاح مسار ورؤوس Nginx WebSocket

بالنسبة لـ Nginx، فإن الخصائص المهمة واضحة: يجب أن يصل الطلب إلى /cool/مسار Collabora، ويجب أن يستخدم الوكيل HTTP/1.1 لتدفق ترقية WebSocket الكلاسيكي، ويجب إعادة توجيه Upgradeالرؤوس Connection، ويجب الحفاظ على المضيف الأصلي، ويجب أن تكون مهلة القراءة طويلة بما يكفي لجلسة التحرير.

لطالما أظهر دليل Collabora SDK موقعًا مخصصًا لبروتوكول WebSocket مع Upgradeو Connectionو Hostو و proxy_read_timeout. كما أشارت إحدى وثائق مشروع Collabora الرسمية إلى ضرورة وجود رؤوس WebSocket على /coolالمسار الأوسع. النمط الأمثل المتوافق مع الإصدار 26.04 هو:

location ^~ /cool/ {
    proxy_pass http://127.0.0.1:9980;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 3600s;
}

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

لماذا تُعدّ قيم المهلة الزمنية مهمة؟

جلسات التحرير عبر WebSocket طويلة الأمد. توضح قيم Helm الحالية لمشروع Collabora هذا الأمر صراحةً، وتستخدم مهلة طويلة لخادم Nginx الوكيل المدمج. إذا قام موازن التحميل الطرفي، أو مدخل Kubernetes، أو شبكة توصيل المحتوى (CDN)، أو جدار الحماية، أو الخادم الوكيل العكسي بإغلاق الاتصالات الخاملة قبل الموعد المتوقع للتطبيق، فسيتمكن المستخدمون من التحرير بشكل طبيعي لفترة من الوقت، ثم يتم قطع اتصالهم على فترات منتظمة.

عندما يحدث العطل بعد عدد متقارب من الثواني في كل مرة، يتم فحص كل وسيط في المسار بدلاً من زيادة مهلة Nginx فقط. يتم اعتماد أقصر مهلة.

4. اجعل إنهاء بروتوكول TLS متسقًا

في عملية النشر الشائعة، يتم إنهاء بروتوكول HTTPS عند Nginx أو Apache أو HAProxy أو Traefik أو وحدة تحكم الدخول، ثم يتم توجيه بروتوكول HTTP العادي إلى Collabora على المنفذ 9980. في هذا التصميم، يتطلب التكوين الرسمي لـ Collabora أن يعرف النظام الخلفي أن بروتوكول TLS يتم إنهاؤه بواسطة الوكيل. ssl.enable=falseويوثق دليل SDK ssl.termination=trueهذا النموذج.

بالنسبة لنشر Docker، يتم التعبير عن ذلك عادةً من خلال المعلمات الإضافية لـ Collabora:

--o:ssl.enable=false --o:ssl.termination=true

استخدم هذه الخيارات فقط عندما يتم إنهاء بروتوكول TLS فعليًا في الخادم الرئيسي. إذا كان الخادم الوكيل يتصل بـ Collabora عبر HTTPS، فقم بضبط هذه البنية بشكل متسق بدلاً من دمج النموذجين. قد يؤدي عدم التوافق إلى ظهور مخططات خاطئة، أو عناوين URL غير صحيحة لـ WebSocket، أو فشل في الشهادات، أو عمليات إعادة توجيه تُعطّل عملية الترقية.

5. تحقق من عدم تطابق المضيف والمصدر في سجلات coolwsd

يتحقق Collabora من مصادر WebSocket. إذا احتوى السجل على عبارات مثل " Rejecting WebSocket upgradeمُتبوع بمصدر ومضيف متوقع"، فقم بتصحيح علاقة اسم المضيف/المنفذ الخارجي بدلاً من إضافة رؤوس مُتساهلة بشكل عشوائي. يحتوي نظام تتبع المشكلات الرسمي لـ Collabora على مثال موثق حيث :443لم يتطابق اسم الخادم المُكوّن، بما في ذلك، مع مصدر المتصفح بدون هذا المنفذ الصريح.

تعتمد الأوامر المفيدة على نظام التثبيت الخاص بك:

docker logs collabora --tail 200
journalctl -u coolwsd --since "10 minutes ago"
nginx -t
apachectl configtest

ابحث عن الخطأ الأول بالتزامن مع فشل طلب خدمة الويب. الرسائل المتعلقة بالترقيات المرفوضة، أو بنية عنوان URI غير الصحيحة، أو مضيف غير متوقع، أو مصدر غير متاح، تُعدّ أكثر فعالية من نافذة المتصفح المنبثقة العامة.

6. إذا فشلت المتصفحات المبنية على Chromium فقط، فافحص معالجة HTTP/2 أو HTTP/3

هذه حالة محدودة، لكن يجدر التحقق منها قبل إعادة بناء الخادم. وثّق مشروع Collabora حالةً متعلقةً بمتصفح Chromium حيث مرّر خادم وسيط طلب HTTP/2 CONNECT WebSocket مباشرةً إلى coolwsd، فاستقبل الخطأ 405 (الطريقة غير مسموحة). كما سجّلت مشكلة أخرى حالات فشل تحميل المستندات المتعلقة ببروتوكول HTTP/3/QUIC في مسار خادم وسيط مُحدد. لا تعني هذه التقارير ضرورة تعطيل HTTP/2 أو HTTP/3 دائمًا، بل تعني أن على الوسيط ترجمة سلوك العميل إلى اتصال WebSocket يدعمه Collabora.

إذا كان متصفح فايرفوكس يعمل بينما يفشل متصفح كروم على نفس الحساب والمستند، فقم بتسجيل البروتوكول ورمز الحالة عند الخادم الوكيل. يُفضّل تصحيح سلوك الخادم الوكيل/الوصول بدلاً من تعطيل البروتوكولات الحديثة بشكل عام، إلا إذا لم يكن لديك بديل متوافق في بيئتك.

7. أعد التشغيل فقط بعد التحقق من صحة الإعدادات

اختبر بنية الخادم الوكيل أولاً. ثم أعد تحميله بدلاً من إعادة تشغيله بشكل متكرر دون فهم.

sudo nginx -t && sudo systemctl reload nginx
sudo apachectl configtest && sudo systemctl reload apache2

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

كيفية التحقق من الإصلاح بنفسك

استخدم سلسلة تحقق قصيرة بدلاً من الاعتماد على فتح مستند واحد ناجح:

• /hosting/discoveryيمكن الوصول إلى هذه المعلومات /hosting/capabilitiesمن خلال نفس اسم المضيف العام الذي يستخدمه المستخدمون.
• افتح مستندًا وتأكد من أن طلب خدمة الويب للمتصفح قد تمت ترقيته بنجاح بدلاً من إرجاع رمز الخطأ 4xx/5xx.
• قم بإجراء عدة تعديلات، وانتظر لفترة أطول من فترة الفشل السابقة، وتأكد من أن الاتصال لا يزال مستقرًا.
• احفظ المستند وأغلقه، ثم أعد فتحه للتأكد من أن عملية نقل البيانات ذهابًا وإيابًا عبر WOPI سليمة.
• تحقق من سجلات coolwsd والوكيل بحثًا عن ترقيات WebSocket المرفوضة، أو أخطاء تحليل URI، أو حلقات إعادة الاتصال المتكررة.
• إذا كان النشر الخاص بك يحتوي على موازن تحميل أو مدخل، فكرر الاختبار من خلال مسار الإنتاج الحقيقي بدلاً من الاتصال مباشرة بالمنفذ 9980.

أي حل يجب أن تختار؟

إذا قمتَ بالترقية إلى الإصدار 26.04 وتستخدم Apache، فإن تحديث قواعد البروكسي هو الإجراء ذو ​​الأولوية القصوى لأن Collabora وثّقت هذا التغيير بشكلٍ صريح. إذا حدث انقطاع الاتصال بعد فترة زمنية محددة، فركّز على إعدادات مهلة الاتصال في جميع نقاط الشبكة. إذا كان العطل فوريًا على جميع المتصفحات، فتحقق من /cool/التوجيه، وتحديث الرؤوس، وتناسق المضيف/الأصل، وإنهاء TLS. إذا تعطلت مجموعة متصفحات واحدة فقط، فقارن معالجة بروتوكول HTTP قبل إجراء أي تغييرات على Collabora نفسها.

يكمن الحل في تجنب اعتبار رسالة "انقطاع اتصال المقبس بشكل غير متوقع" بمثابة عطل في تطبيق Collabora بشكل افتراضي. في العديد من عمليات النشر، يكون كل من المحرر ونقطة نهاية الاكتشاف ومضيف WOPI سليمين، بينما يُسيء الخادم الوكيل العكسي التعامل مع نوع الاتصال الأكثر أهمية للتحرير المباشر: اتصال WebSocket طويل الأمد.

المراجع الرسمية

• ملاحظات إصدار Collabora CODE 26.04
• ملاحظات إصدار Collabora Online 26.04
• إعدادات بروكسي Collabora Online SDK
• مشكلة رقم 15918 في CollaboraOnline/online: فشل WebSocket بعد الترقية إلى الإصدار 26.04
• مشكلة CollaboraOnline/online رقم 13751: رؤوس WebSocket في وثائق الوكيل
• الإعدادات الافتراضية لمهلة وكيل Helm في Collabora Online
• RFC 6455: بروتوكول WebSocket