كيفية تكوين إنهاء SSL لحاوية Collabora CODE

يُعدّ إنهاء SSL خيارًا مثاليًا لحاوية Collabora Online Development Edition (CODE) عند الرغبة في استخدام نقطة نهاية HTTPS عامة واحدة مع إدارة الشهادات عبر خادم وكيل عكسي مثل Nginx. في هذا التصميم، يتصل المتصفح بـ Nginx عبر HTTPS، ويقوم Nginx بفك تشفير البيانات، بينما يستقبل Collabora بيانات HTTP عادية على منفذه الداخلي. لا يقتصر معيار الجودة على مجرد تحميل الصفحة، بل يجب أن يتضمن النشر الناجح شهادة عامة صالحة، ونقطة نهاية WOPI قابلة للوصول، وتحديثات WebSocket فعّالة، وجلسة تحرير مستندات حقيقية متصلة باستمرار.

تصف وثائق بروكسي Collabora نمط تفريغ SSL هذا بأنه اتصال HTTP فقط بين البروكسي وCollabora، مع وجود ssl.enable=falseو ssl.termination=trueعلى جانب Collabora. راجع إعدادات بروكسي Collabora Online العكسي . تستخدم الأمثلة أدناه Nginx وDocker Compose، ولكن يمكن تحقيق النتيجة نفسها باستخدام بروكسيات عكسية أخرى إذا حافظت على سلوك المضيف وWebSocket المطلوب.

ما الذي يجب أن يحققه إعداد إنهاء SSL جيد؟

الخطوة 1: تأكيد حدود الشبكة قبل تغيير Collabora

حدد نقطة انتهاء بروتوكول TLS والخوادم التي يمكنها الوصول إلى المنفذ 9980. إذا كان Nginx يعمل على نفس الجهاز الذي يعمل عليه Docker، فإن ربط المنفذ المنشور به 127.0.0.1يُعد طريقة بسيطة لمنع الوصول المباشر إلى الإنترنت. تشير وثائق Docker إلى أن نشر منفذ إلى هذا المنفذ 127.0.0.1يجعله محليًا على الخادم المضيف؛ راجع وثائق نشر المنافذ الخاصة بـ Docker .

إذا كان Nginx يعمل في حاوية أخرى، فإن استخدام شبكة Docker خاصة مشتركة يكون عادةً أفضل من نشر المنفذ 9980 علنًا. المبدأ واحد: يجب على العملاء استخدام اسم مضيف خادم الوكيل العكسي HTTPS، وليس حاوية Collabora مباشرةً.

الخطوة 2: تشغيل الكود في وضع إنهاء SSL

لإنهاء اتصال TLS من جانب الخادم الوكيل، يجب أن تعرف منصة Collabora أن بروتوكول HTTPS هو البروتوكول الأصلي الذي يستخدمه العميل، حتى وإن كان اتصالها المباشر بالخادم الرئيسي يستخدم بروتوكول HTTP. الإعدادات الموثقة هي:

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

مثال بسيط لـ Compose يبدو كالتالي:

services:
  collabora:
    image: collabora/code:YOUR_TESTED_TAG
    restart: unless-stopped
    ports:
      - "127.0.0.1:9980:9980"
    environment:
      - "extra_params=--o:ssl.enable=false --o:ssl.termination=true"
      - "server_name=office.example.com"

استبدل YOUR_TESTED_TAGالإصدار الحالي بإصدار تم التحقق من صحته بدلاً من افتراض أنه latestآمن للاستخدام في بيئة إنتاجية. قم أيضاً بضبط إعدادات مضيف WOPI أو الاسم المستعار المناسبة لعملية التكامل؛ وتعتمد هذه القيم على ما إذا كنت تقوم بربط Nextcloud أو ownCloud أو مضيف WOPI آخر أو عملية تكامل مخصصة.

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

docker compose up -d
docker compose ps
docker logs --tail=100 collabora

ملاحظة الإصدار لعمليات النشر 26.04

لا تعتمد على علامتي SSL فقط عند استكشاف أخطاء صورة 26.04 الحالية وإصلاحها. في منتصف عام 2026، رصدت Collabora تراجعات في أداء صورة Docker التي لا تحتوي على توزيعة، بالإضافة إلى مشاكل في إعدادات تعطيل SSL. وثّقت إحدى المشكلات الرسمية على GitHub تراجعًا في بدء تشغيل صورة 26.04، وأفادت متابعة مجتمع Collabora بعودة سلوك إنهاء SSL المتأثر إلى العمل في صورة 26.04.2.4.1 اللاحقة. راجع المشكلة رقم 16019 على CollaboraOnline/online إذا تعطل إعداد إنهاء كان يعمل سابقًا مباشرةً بعد ترقية الصورة.

هذا سببٌ إضافي لتثبيت نسخة الصورة واختبارها. قد يبدو خطأ التكوين وتراجع صورة الحاوية متشابهين من Nginx: فكلاهما قد يظهر كاستجابة 502 أو فشل في الاتصال بالخادم.

الخطوة 3: تهيئة Nginx لإنهاء TLS وتوجيه مسارات Collabora

يحتاج Nginx إلى شهادة صالحة لاسم مضيف Collabora، ويجب عليه إعادة توجيه نقاط نهاية HTTP الخاصة بـ Collabora بالإضافة إلى حركة مرور WebSocket. يوضح دليل وكيل Collabora مواقع مخصصة لموارد المتصفح، والاكتشاف، والقدرات، واتصالات WebSocket الرئيسية، ومسارات التنزيل/التحميل، وWebSocket الخاص بالإدارة. يتبع التكوين التالي هذا الهيكل مع إضافة رؤوس إعادة التوجيه الشائعة:

server {
    listen 443 ssl;
    server_name office.example.com;

    ssl_certificate     /etc/letsencrypt/live/office.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;

    location ^~ /browser {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ~ ^/cool/(.*)/ws$ {
        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 $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /cool/adminws {
        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 $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }
}

رؤوس WebSocket ليست مجرد عناصر شكلية. توضح وثائق Nginx الرسمية أن `<webSocket>` Upgradeو` Connection<webSocket>` هما رؤوس خاصة بكل قفزة، ويجب تمريرهما صراحةً لبروتوكولات WebSocket التي تعمل عبر وكيل عكسي. راجع قسم "وكيل WebSocket في Nginx" . كما تغطي وثائق وحدة الوكيل القياسية ` <webSocket>` proxy_set_headerو` <webSocket> proxy_pass` و` <webSocket proxy_read_timeout>`: `ngx_http_proxy_module` .

الخطوة الرابعة: التحقق من صحة Nginx قبل إعادة التحميل

اختبر إعدادات Nginx قبل استبدال إعدادات تعمل بشكل سليم ومعروفة:

sudo nginx -t

أعد التحميل فقط إذا نجح اختبار بناء الجملة:

sudo systemctl reload nginx

ثم تأكد من أن Nginx نفسه قادر على الوصول إلى خادم Collabora المحلي. في حالة الإعداد على نفس المضيف، يُعد الفحص التالي مفيدًا:

curl -I http://127.0.0.1:9980/hosting/discovery

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

الخطوة 5: التحقق من نقطة نهاية HTTPS العامة

من عميل يقوم بحل اسم المضيف العام، اطلب نقطة نهاية الاكتشاف من خلال Nginx:

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

يجب أن يُعيد طلب المتصفح إلى https://office.example.com/hosting/discoveryالموقع ملف XML. يُعد هذا فحصًا وظيفيًا أفضل من الاعتماد على عنوان URL الرئيسي، لأن سلوك الصفحة الرئيسية ليس هو العقد الأساسي لـ WOPI، وقد يختلف باختلاف الإصدار.

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

الخطوة 6: اختبار مستند حقيقي و WebSocket

نجاح عملية الاكتشاف ضروري ولكنه غير كافٍ. افتح مستندًا من مضيف WOPI الخاص بك واتركه مفتوحًا لفترة كافية لاختبار الجلسة المباشرة. في أدوات مطوري المتصفح، يجب أن يتم تحديث طلب Collabora WebSocket بنجاح بدلًا من إعادة الاتصال بشكل متكرر أو إرجاع خطأ 400/502. يجب أن تسمح لك الجلسة السليمة بالكتابة والحفظ وإعادة فتح المستند.

إذا تم تحميل واجهة محرر النصوص ولكن فشل تحميل المستند بعد ذلك بوقت قصير، فاجعل مسار WebSocket، ومهلة الخادم الوكيل، وقائمة السماح لـ WOPI، وسلوك رأس المضيف من أولوياتك. إذا أظهرت سجلات Nginx خطأ في الاتصال بالخادم قبل إنشاء أي اتصال WebSocket، فافحص أولاً إصدار مستمع CODE وإصدار الصورة.

كيفية تشخيص أعطال الأجهزة الشائعة

502 مدخل غير صالح

عادةً ما يشير الخطأ 502 إلى أن Nginx لم يتمكن من الحصول على استجابة صحيحة من الخادم المُهيأ. تحقق مما إذا كان CODE يستمع بالفعل على المنفذ 9980 وما إذا كنت تستخدم بروتوكول الخادم الصحيح. في تصميم إنهاء SSL المُعتمد، تكون قفزة الخادم الوكيل إلى CODE عبر HTTP. إذا تسبب خلل في الصورة في استمرار CODE في استخدام HTTPS داخليًا رغم إعداداتك، curlستكشف السجلات واختبار مباشر عن هذا الخلل. لا تقم بالتبديل بشكل دائم إلى خادم HTTPS لمجرد إخفاء خلل غير مُفسر في الإعدادات؛ تحقق أولًا من سلوك صورة CODE التي تستخدمها.

يعمل برنامج الاكتشاف، لكن المستندات لا تفتح.

يشير هذا غالبًا إلى إعادة توجيه WebSocket أو مصادقة WOPI وليس إلى TLS نفسه. تحقق من /cool/.../wsالمسار، وعناوين الترقية، والمضيف الذي سمحت به كمصدر WOPI. قد يكون الوصول إلى Collabora ممكنًا تمامًا عبر HTTPS، ومع ذلك يتم رفض جلسة التحرير أو فشلها.

عناوين URL ذات محتوى مختلط أو مخطط غير صحيح

إذا رأى المتصفح صفحة HTTPS تشير إلى موارد HTTP، فتحقق من ssl.termination=trueعنوان بروتوكول إعادة التوجيه واسم الخادم. يجب أن يُعرّف الجانب العام من النشر نفسه باستمرار على أنه HTTPS حتى لو كانت نقطة الوصول الخاصة HTTP.

تشير تقارير الحاويات إلى أنها غير صحية على الرغم من أن التحرير يعمل

أدخلت الإصدارات الأخيرة من 26.04 سلوكًا جديدًا لفحص سلامة النظام، تغيّر خلال عملية الانتقال إلى الصور غير الموزعة. رصدت Collabora حالةً لم يلتزم فيها الفحص بإعدادات خادم HTTP الخلفي بعد إنهاء TLS. إذا اجتازت الاختبارات الوظيفية بنجاح، ولكن حالة Docker غير مستقرة (حمراء)، يُرجى مراجعة سجل المشكلات الخاص بالإصدار قبل إعادة تصميم وكيل عامل. راجع المشكلة رقم 16032 على CollaboraOnline/online .

متى يتم استخدام تصميم مختلف

يُعدّ إنهاء SSL من جانب الخادم الوكيل مناسبًا عندما يتواصل الخادم الوكيل العكسي وCollabora عبر واجهة محلية موثوقة أو شبكة خاصة معزولة. إذا كان تدفق البيانات بين Nginx وCODE يمر عبر شبكة غير موثوقة، فقد لا يفي استخدام HTTP العادي في المسار الداخلي بمتطلبات الأمان. في هذه الحالة، استخدم TLS للوصول إلى الواجهة الخلفية أيضًا، أو ضع كلا الخدمتين على شبكة محمية حيث لا يُمثّل اعتراض البيانات تهديدًا حقيقيًا.

وبالمثل، إذا كنت تدير بالفعل مدخلًا مُدارًا من قِبل المنصة ويتعامل مع الشهادات والتوجيه وWebSockets بشكل صحيح، فلا فائدة تُذكر من إضافة طبقة Nginx ثانية فقط من أجل Collabora. إن البنية الصحيحة هي التي توفر لك حدود TLS واحدة قابلة للمراقبة دون قفزات غير ضرورية.

قائمة التحقق النهائية للتحقق من الصحة

• يتم حل اسم مضيف Collabora إلى الخادم الوكيل العكسي.
• يعرض المنفذ 443 شهادة موثوقة لاسم المضيف هذا.
• لا يتم تعريض الكود للإنترنت العام على المنفذ 9980 دون داعٍ.
• ssl.enable=falseويتم ssl.termination=trueتطبيقها على تصميم الواجهة الخلفية لبروتوكول HTTP.
• يمكن لـ Nginx الوصول إلى CODE على عنوانه الخاص.
• /hosting/discoveryيستجيب عبر عنوان URL العام لبروتوكول HTTPS.
• تمت ترقية WebSocket /cool/.../wsبنجاح.
• يتم فتح المستند الحقيقي وتعديله وحفظه وإعادة فتحه.
• لقد قمت بتثبيت واختبار إصدار صورة CODE المحدد الذي تخطط لنشره.

إذا اجتازت جميع هذه الفحوصات بنجاح، فإن إنهاء بروتوكول SSL يؤدي وظيفته على أكمل وجه: حركة البيانات الخارجية محمية بواسطة HTTPS، ويتعرف Collabora على الاتصال العام على أنه آمن، ويظل مسار التحرير فعالاً. في حال فشل أحد الفحوصات، يُنصح بمعالجة المشكلة في تلك الطبقة بدلاً من تغيير أجزاء متعددة من النظام دفعة واحدة.