قم بتثبيت Collabora خلف Nginx دون التأثير على WebSockets

ضع Collabora على اسم مضيف HTTPS مخصص في Nginx، وقم بتوجيه مسارات المحرر والاكتشاف الخاصة به إلى coolwsd، وقم بتمرير رؤوس ترقية WebSocket بشكل صريح على مسارات المقبس المباشر. بالنسبة لمضيف واحد، يمكن لـ Nginx إنهاء TLS العام وإرسال HTTP إلى Collabora على واجهة خاصة؛ إذا كان Nginx وCollabora يعملان في حاويات مختلفة، فاستخدم اسم خدمة Collabora على شبكتهما المشتركة بدلاً من 127.0.0.1.

يفترض هذا المثال أن المستخدمين يفتحون الموقع https://office.example.comوأن Nginx يتولى معالجة شهادته. منفذ الاستماع الافتراضي لـ Collabora هو 9980؛ استخدم المنفذ المتاح في بيئة النشر الخاصة بك. https://example.com/collabora/يتطلب استخدام بادئة عنوان URL مثل `<اسم_العنوان>` مسارًا منسقًا وإعدادات جذر الخدمة، لذا لن يتم تطبيق تكوين المضيف الجذر هذا دون تغيير.

1. حدد خريطة اتصال المصدر وWebSocket

في سياق Nginx http، أضف اسمًا للخادم Collabora وخريطة تُعيّن رأس الاتصال upgradeفقط عندما يطلب العميل اتصال WebSocket. ضع هذا الجزء خارج أي serverجزء آخر. استبدل العنوان إذا وصل Nginx إلى Collabora بطريقة أخرى.

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

upstream coolwsd {
    server 127.0.0.1:9980;
}

إذا كان Nginx نفسه حاوية، 127.0.0.1فإن الإشارة هنا تشير إلى حاوية Nginx هذه، وليس إلى حاوية Collabora. أما في شبكة Docker مشتركة، فيمكن server collabora:9980;استخدام اسم الخدمة الذي يتم حله في تلك الشبكة.

2. أضف المضيف الظاهري HTTPS ومسارات Collabora

serverداخل قسم HTTPS office.example.com، قم بتوجيه موارد المتصفح، ونقاط نهاية الاكتشاف، واتصالات WebSocket، ومسارات Collabora المتبقية. تتبع المواقع إرشادات وكيل Collabora. احتفظ بمواقع المقابس المحددة أعلى مسار cool/ الأوسع loolنطاقًا حتى يطبق Nginx رؤوس WebSocket بشكل صحيح.

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

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/private-key.pem;

    location ^~ /browser {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ^~ /cool/adminws {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

استبدل مسارات الشهادات بملفات مضيفك. إذا لم تستخدم لوحة تحكم الإدارة في تثبيتك، /cool/adminwsفقد لا تحتاج إلى الموقع لتحرير المستندات؛ /cool/.../wsالمسار الرئيسي ضروري. proxy_read_timeoutالمدة المذكورة هنا هي ساعة واحدة كمثال فقط، وليست شرطًا عامًا. مهلة قراءة الوكيل الافتراضية في Nginx هي 60 ثانية بين كل قراءة وأخرى. اختر قيمة أطول من فترات الخمول التي تحتاجها جلساتك، أو اعتمد على حركة مرور WebSocket ping المناسبة حيثما كان ذلك مدعومًا.

3. قم بمطابقة وضع TLS الخاص بـ Collabora مع قفزة الوكيل

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

استخدم بروتوكول HTTP فقط على شبكة خاصة موثوقة، وامنع الوصول العام إلى المنفذ 9980. إذا كانت السياسة تتطلب التشفير بين Nginx وCollabora، فاستخدم بروتوكول HTTPS وقم بضبط التحقق من الشهادة بشكل صحيح؛ لا تعطل التحقق لإخفاء عدم تطابق الشهادة. توضح وثائق إعدادات وكيل Collabora الفرق بين SSL على الوكيل وSSL بين الوكيل والخادم coolwsd.

قم أيضًا بتعيين عنوان URL الخاص بـ Collabora في تكامل التخزين إلى اسم مضيف HTTPS العام. بالنسبة إلى Nextcloud، يتطلب دليل الإدارة أن يكون المتصفح وكلا الخادمين قادرين على الوصول إلى بعضهما البعض عبر HTTP(S)، باستخدام بروتوكولات خارجية متطابقة. قم بتقييد قائمة السماح لـ WOPI لتقتصر على مضيف التخزين وعنوان Collabora المتوقعين؛ ولا توسع نطاقها بشكل كبير لحل خطأ في توجيه الوكيل.

4. اختبر التكوين من كلا الجانبين

تحقق من صيغة Nginx قبل إعادة تحميله:

sudo nginx -t
sudo systemctl reload nginx

إذا كان Nginx يعمل داخل حاوية، فاستخدم إجراءات التحقق وإعادة التحميل الخاصة بتلك الحاوية. من مضيف Nextcloud، اختبر نقاط نهاية Collabora العامة باستخدام اسم المضيف الفعلي.

curl -fsS https://office.example.com/hosting/discovery -o /dev/null
curl -fsS https://office.example.com/hosting/capabilities -o /dev/null

افتح عناوين HTTPS هذه من متصفح المستخدم أيضًا. تتحقق هذه العناوين من إمكانية الوصول، ولكن استجابة الاكتشاف الناجحة وحدها لا تثبت نجاح تحرير المستند. افتح مستندًا واستخدم لوحة الشبكة في المتصفح للتأكد من تحميل الملفات واستمرار الاتصال /cool/.../wsمفتوحًا. عادةً ما يُظهر اتصال WebSocket الناجح عبر HTTP/1.1 رمز الاستجابة 405 101 Switching Protocols؛ وقد يختلف العرض الدقيق باختلاف المتصفح وبروتوكول النقل. إذا نجح هذا الإعداد القياسي في Firefox ولكنه فشل في Chromium، فافحص طريقة الطلب والبروتوكول. يُوثّق تقرير مشكلة Collabora المُنشأ للإصدار 25.04 اتصال WebSocket في Chromium عبر HTTP/2 باستخدام رمز CONNECTالاستجابة 405 واستقباله؛ ويبقى مفتوحًا كما تم التحقق منه في 9 أكتوبر 2026. هذا تقرير خاص بالإصدار، وليس سلوكًا عامًا. قارن إصدارات Collabora وNginx والمتصفح قبل تغيير إعدادات HTTP/2. راجع مشكلة Collabora رقم 12155 .

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

يشرح دليل Nginx WebSocket proxyingUpgrade سبب وضرورة Connectionتمرير قيمتي `and` بشكل صريح، وأهمية سلوك مهلة الخمول. راجع مرجع وحدة Nginx proxy لمعرفة سلوك التوجيه. بعد اجتياز الفحوصات، افتح مستندًا تجريبيًا، عدّله، احفظه، ثم أعد فتحه قبل دعوة المستخدمين للاعتماد على المسار الجديد.