كيفية إعداد Collabora Online خلف Nginx

ما ينبغي أن يفعله خادم وكيل عكسي فعال

يُتيح نشر Collabora Online بشكل سليم خلف Nginx للمستخدمين عنوان HTTPS عامًا واحدًا للمحرر، مع الحفاظ على خدمة Collabora على شبكة خاصة. يجب أن يقوم المحرر بتحميل موارد المتصفح، واكتشاف إمكانيات Office، وفتح مستند عبر منصة التخزين المتصلة، والحفاظ على اتصال WebSocket نشطًا أثناء التحرير. ولا يكفي التحقق من صحة بنية Nginx وحدها لإثبات عمل هذه المسارات.

يفترض هذا المثال أن خادم Collabora مستقل أو حاوية CODE يستمع على المنفذ 9980، وأن Nginx يُشغّل الخدمة office.example.com، وأن بروتوكول TLS ينتهي عند Nginx. استبدل اسم المضيف ومسارات الشهادات بمساراتك الخاصة. ينطبق عنوان الواجهة الخلفية 127.0.0.1:9980فقط عندما يتشارك Nginx وCollabora نفس المضيف وتكون الخدمة مرتبطة بشبكة محلية. بالنسبة للحاويات المنفصلة، ​​استخدم اسم خدمة Collabora على شبكة Docker خاصة، مثل http://collabora:9980.

قبل تغيير Nginx

تأكد من أن اسم DNS العام يُشير إلى الخادم الوكيل، وأن شهادة TLS تُغطي هذا الاسم تحديدًا، وأن Nginx قادر على الوصول إلى Collabora عبر عنوانه الداخلي. إذا كنت تستخدم Docker، فقم بربط كلا الخدمتين بشبكة مُعرّفة من قِبل المستخدم، ولا تنشر منفذ Collabora علنًا. إذا كان Nginx يعمل على المضيف، فاربط منفذ الحاوية بشبكة محلية (loopback)، على سبيل المثال 127.0.0.1:9980:9980. يجب أن يُعرّض جدار الحماية منافذ الويب العامة التي تنوي استخدامها، وليس منفذ Collabora الخلفي.

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

قم بتعيين خيارات TLS الخاصة بـ Collabora التي تدعم استخدام البروكسي

coolwsdلإنهاء اتصال TLS، قم بتهيئة خدمة Collabora باستخدام ssl.enable=falseالقيمتين ssl.termination=true`<T>` و`<T>`. تعتمد طريقة ضبط هذه القيم على كيفية تثبيت Collabora: إما تعديل coolwsd.xmlالإعدادات المدعومة أو استخدام الخيارات الموثقة لحزمتك أو حاويتك. مع صورة CODE Docker، عادةً ما تُمرر الخيارات كـ `<T>` extra_params؛ راجع توثيق الصورة لمعرفة إصدارك، وتأكد من وضع الوسائط بين علامتي اقتباس بشكل صحيح في Compose. أعد تشغيل خدمة Collabora أو أنشئها من جديد بعد تغيير إعداداتها.

تُخبر هذه الإعدادات برنامج Collabora بأن الاتصال الخارجي محمي بواسطة الخادم الوكيل، حتى وإن كان مسار الاتصال بين الخادم الوكيل والخادم الخلفي يستخدم بروتوكول HTTP. ولا تُثبّت هذه الإعدادات شهادة عامة، ولا تُهيئ نظام أسماء النطاقات (DNS)، ولا تُخوّل خادم التخزين باستخدام Collabora. يُرجى ضبط قائمة السماح لمضيفي WOPI أو إعدادات التكامل بشكل منفصل وفقًا لمنصة التخزين الخاصة بك.

قم بتهيئة Nginx لإعادة توجيه مسارات المحرر

يجب أن يجتاز Nginx عملية اكتشاف الموارد وموارد المتصفح، وأن يحافظ على ترقية WebSocket المستخدمة في التحرير التفاعلي. فيما يلي مثال لخادم واحد. عرّفها mapفي سياق Nginx http، مثل السياق الرئيسي nginx.conf، وليس داخل المضيف الظاهري.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

ضع كتلة الخادم في إعدادات الموقع المضمنة في Nginx. هذا يفترض أن شهادات TLS مثبتة بالفعل وأن اتصال الوكيل بـ Collabora هو HTTP:

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;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    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 $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
    }
}

تحمل المسارات التي تبدأ بـ /coolطلبات WebSocket الرئيسية وطلبات المحرر؛ ويتضمن النمط أيضًا /loolمسارات قديمة لضمان التوافق. يتطلب توجيه WebSocket في Nginx رؤوس ترقية HTTP/1.1 لأنها Upgradeرؤوس Connectionخاصة بكل قفزة. يساعد مهلة القراءة الطويلة على تجنب إغلاق اتصال التحرير النشط بسبب مهلة قصيرة عادية للوكيل. راجع وثائق وكيل WebSocket في Nginx ومرجع وحدة الوكيل .

لتفعيل بروتوكول HTTPS على الخادم، غيّر عناوين URL للخادم الخلفي، https://وقم بضبط التحقق من شهادة الخادم وسلسلة الشهادات الموثوقة في Nginx بشكل مناسب. تجنب تعطيل التحقق من الشهادة كحل دائم. إذا كان Nginx موجودًا في حاوية أخرى، فاستبدل عنوان الاسترجاع باسم خدمة Collabora؛ 127.0.0.1حيث يشير عنوان الاسترجاع داخل حاوية الوكيل إلى تلك الحاوية.

عند استخدام بادئة URI بدلاً /collabora/من اسم مضيف مخصص، يتطلب التكوين وعناوين URL للاكتشاف التي يُنشئها Collabora معالجة إضافية للمسار. ابدأ باسم مضيف مخصص ما لم تدعم منصتك صراحةً نشر المسار الفرعي. لا يؤدي وجود كتلة خادم تُعيد توجيه الطلبات في الجذر إلى جعل عناوين URL المُنشأة للاكتشاف تعمل تلقائيًا ضمن بادئة.

أعد تحميل كل طبقة وتحقق منها

تحقق من صحة إعدادات Nginx قبل تطبيقها، ثم أعد تحميل الخدمة:

sudo nginx -t
sudo systemctl reload nginx

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

curl -fsS https://office.example.com/hosting/discovery | head
curl -fsS https://office.example.com/hosting/capabilities

يجب أن تُعيد نقطة نهاية الاكتشاف ملف XML بدلاً من صفحة خطأ 404 من Nginx أو صفحة تسجيل الدخول؛ ويجب أن تُعيد الإمكانيات استجابة من Collabora. تفحّص عناوين URL الخاصة بمحرر ملف XML للاكتشاف: يجب أن تستخدم اسم مضيف HTTPS العام والمسارات التي يمكن الوصول إليها، وليس اسم حاوية أو عنوانًا داخليًا فقط. تُظهر الصورة أدناه أنواع الاستجابات التي يجب البحث عنها؛ القيم المعروضة فيها توضيحية فقط، وليست ناتجًا من خادم مباشر.

أخيرًا، قم بتهيئة منصة المستندات الخاصة بك لاستخدامها https://office.example.comكخادم Collabora، ثم افتح مستندًا تجريبيًا. من علامات النجاح المفيدة تحميل المحرر واستمرار استجابته أثناء الكتابة والحفظ وإعادة فتح المستند. في أدوات مطوري المتصفح، /cool/يجب أن تتم ترقية طلب WebSocket بنجاح؛ حالة HTTP 101 Switching Protocolsهي نتيجة مصافحة WebSocket المتوقعة. لا تعتبر حالة المثال المرسومة دليلًا على أن خادمك قد اجتاز هذا الاختبار.

اقرأ حالات الفشل من خلال أعراضها

• خطأ 502: بوابة غير صالحة: يتعذر على Nginx الوصول إلى الخادم الرئيسي. تحقق من اسم الخدمة، والمنفذ، وشبكة الحاوية، والمستمع، والسجلات. إذا كانت الحاويات منفصلة، ​​فلا تستخدم عنوان الاسترجاع الخاص بحاوية الوكيل.
• خطأ 404 في اكتشاف المواقع أو موارد المتصفح: تأكد من وصول الطلب إلى المضيف الظاهري الصحيح، وأن الموقع يُعيد توجيه المسار دون إعادة كتابة غير مقصودة لعنوان URI. اختبر عنوان URL العام، وليس فقط عنوان URL الخاص بالخادم.
• يتم تحميل المحرر ولكنه يتوقف أو ينقطع الاتصال: افحص /cool/.../wsالطلب. قد يؤدي نقص رؤوس الترقية، أو استخدام اتصال HTTP/1.0 من المصدر، أو مهلة قصيرة، أو وجود خادم وكيل يقوم بتخزين الاتصال مؤقتًا، إلى انقطاع التحرير. تأكد من ترقية الطلب وبقاءه مفتوحًا أثناء تفعيل المستند.
• مضيف WOPI غير مصرح به: قد يكون الخادم الوكيل سليمًا بينما يرفض Collabora منصة التخزين. تحقق من اسم مضيف WOPI الفعلي مقابل قائمة السماح في Collabora وإعدادات موصل المنصة. لا تحل هذه المشكلة بفتح الواجهة الخلفية للإنترنت العام.
• تحذير بشأن المحتوى المختلط أو الشهادة: تأكد من أن عنوان URL الخاص بالمحرر العام وعناوين URL في الاكتشاف تستخدم بروتوكول HTTPS وأن الشهادة مطابقة لاسم المضيف. إذا كنت تُنهي اتصال TLS على خادم Nginx، فتحقق أيضًا من إعدادات إنهاء Collabora.

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

المصادر وملاحظات الإصدار

تمت مراجعة تفاصيل التكوين بالرجوع إلى وثائق بروكسي Collabora ودليل SDK 25.04، بالإضافة إلى مراجع WebSocket ووحدة البروكسي في Nginx، بتاريخ 6 أكتوبر 2026. قد تختلف خيارات الحزمة والحاوية باختلاف إصدار Collabora؛ لذا يُرجى التأكد من أسماء الإعدادات للإصدار الذي تستخدمه قبل تطبيقها. لا تفترض هذه المقالة استخدام منصة تخزين محددة، ولا تُثبت وجود عملية نشر فعلية.