كيفية إصلاح مشكلة خطأ 502 في بوابة خادم مستندات ONLYOFFICE خلف Nginx

يعرض المتصفح رسالة الخطأ "502 Bad Gateway" عند فتح رابط ONLYOFFICE Docs، أو يتعذر على موصل Nextcloud/ownCloud الوصول إلى خادم المستندات. في كلتا الحالتين، يتلقى Nginx عادةً طلبًا ولكنه لا يحصل على استجابة صحيحة من خادمه المصدر. قد يكون هذا الخادم المصدر هو خدمة المستندات الداخلية لـ ONLYOFFICE، أو حاوية Docker، أو خادم وكيل عكسي آخر. حدد أولًا خادم Nginx الذي أعاد الخطأ 502، ثم اختبر الوجهة التالية مباشرةً قبل تغيير الإعدادات.

يوصي دليل استكشاف أخطاء نظام لينكس الحالي من ONLYOFFICE بفحص خدمات ds-docserviceNginx ds-converterوسجلات خادم المستندات. كما يشير دليل الخادم الوكيل العكسي إلى عناوين المضيف والبروتوكول المُعاد توجيهها. يتحقق التسلسل أدناه من سلامة الخدمة أولاً، ثم توجيه Nginx وشبكة Docker.

1. اكتشف أي خادم Nginx يُرجع رمز الخطأ 502

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

في نظام لينكس المثبت باستخدام الحزم، اختبر نقطة نهاية خادم المستندات المحلي:

curl -i http://127.0.0.1/healthcheck

إذا كان الخادم مُعدًا لخدمة ONLYOFFICE على منفذ محلي غير المنفذ الافتراضي، فاستخدم ذلك المنفذ. عادةً ما يُعيد التثبيت السليم استجابة HTTP ناجحة true. إذا فشل هذا الطلب المحلي، فأصلح خدمة خادم المستندات قبل تعديل أي خادم وكيل خارجي. إذا نجح محليًا ولكن اسم المضيف العام يُعيد رمز 502، فركز على خادم Nginx الخارجي، والبروتوكول، والرؤوس، ومسار جدار الحماية.

تحقق من العمليات التي تمتلك المنافذ المتوقعة:

sudo ss -ltnp | grep -E ':(80|443|8080|8000)\b'

تختلف المنافذ باختلاف بنية الشبكة. في عملية ربط Docker الشائعة، يتم ربط منفذ المضيف، مثل 8080، بمنفذ الحاوية 80؛ ويمكن لتثبيت الحزمة استخدام خادم Nginx الخاص بها على المضيف. لا تفترض أن هذا 127.0.0.1:80هو المصدر الصحيح لمجرد وجود كلا الخدمتين على جهاز واحد.

2. تحقق من خدمات وسجلات ONLYOFFICE

عند تثبيت حزمة لينكس، افحص خدمة المستندات والمحول:

sudo systemctl status ds-docservice ds-converter
sudo journalctl -u ds-docservice -u ds-converter --since "15 minutes ago" --no-pager

يُدرج دليل استكشاف الأخطاء وإصلاحها الخاص بـ ONLYOFFICE هذه الخدمات، ويُحدد نقص الذاكرة، وتعارض المنفذ 80، وسجلات الخدمة كعناصر يجب التحقق منها عند فشل بدء تشغيل خدمات Docs. إذا كانت إحدى الخدمات متوقفة، فافحص الخطأ الذي ظهرت فيه أولاً، ثم أعد تشغيل الخدمة المتأثرة فقط.

sudo systemctl restart ds-docservice

يوجد دليل سجلات لينكس الرئيسي في [المسار] /var/log/onlyoffice/documentserver/. تحقق من سجل أخطاء Nginx وسجلات خدمة التوثيق بحثًا عن رسائل مثل "تم رفض الاتصال" أو "انتهت مهلة الخادم" أو ملف مفقود. تشير هذه الرسائل إلى أسباب مختلفة: فرفض الاتصال يعني عادةً أن عملية الخادم أو المنفذ غير متاح، بينما قد تعني انتهاء المهلة أن الخدمة مثقلة أو متوقفة.

تحقق أيضًا من مساحة القرص والذاكرة المتاحة إذا كانت الخدمات تتوقف بشكل متكرر:

df -h
free -h

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

3. تحقق من أن Nginx يشير إلى المصدر الذي يمكن الوصول إليه

اقرأ المضيف الظاهري النشط وتأكد من العنوان والمنفذ بدقة proxy_pass. من الجهاز أو الحاوية التي يعمل عليها Nginx، اطلب المصدر مباشرةً. على سبيل المثال، إذا كانت الحاوية تنشر المنفذ 80 كمنفذ المضيف 8080:

curl -i http://127.0.0.1:8080/healthcheck

استبدل عنوان المثال بنقطة النهاية التي يمكن الوصول إليها فعليًا من الخادم الوكيل. إذا كان Nginx يعمل في حاوية Docker منفصلة، 127.0.0.1​​فإن المقصود هو حاوية Nginx نفسها، وليس مضيف Docker أو حاوية ONLYOFFICE. استخدم اسم خدمة يمكن الوصول إليه على شبكة Docker مشتركة، أو عنوان المضيف الصحيح والمنفذ المنشور.

تأكد من تطابق بروتوكول المصدر مع بروتوكول الخادم. استخدم هذا الخيار فقط http://إذا كان مستمع الخادم يستخدم بروتوكول HTTP العادي، وفقط https://إذا كان مُهيأً لاستخدام بروتوكول TLS. قد يؤدي إرسال HTTP إلى منفذ TLS، أو TLS إلى منفذ HTTP عادي، إلى ظهور خدمة سليمة على أنها غير متاحة لـ Nginx.

4. تحقق من الرؤوس المُعاد توجيهها وخادم وكيل WebSocket

ينصح دليل ONLYOFFICE للخوادم الوكيلة العكسية بالاحتفاظ X-Forwarded-Protoبالبروتوكول X-Forwarded-Hostواسم المضيف الأصليين لكي يتعرف التطبيق عليهما. كما تُمرر أمثلة Nginx الرسمية رؤوس الترقية. إذا كان هناك خادم وكيل خارجي أمام ONLYOFFICE، فقارن إعداداته بالسيناريو الرسمي الذي يتوافق مع بنية شبكتك.

يُعرض أدناه مثال مبسط لحاوية Docker مرتبطة بالمنفذ 8080 على المضيف. ضع التوجيه mapداخل سياق Nginx http، وقم بتعديل اسم المضيف وإعدادات TLS ومنفذ المصدر بما يتناسب مع إعداداتك.

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

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

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

هذا نموذج مرجعي، وليس بديلاً جاهزاً للاستخدام في كل عملية تثبيت. على وجه الخصوص، لا تقم بلصقه فوق إعدادات Nginx الخاصة بـ ONLYOFFICE المُثبّتة مسبقاً دون معرفة أي جزء من الخادم يمتلك المنفذين 80 و443. إذا كان Nginx يشترك في نفس المضيف مع ONLYOFFICE المُثبّت مسبقاً، فتأكد أولاً من عدم وجود تعارض في المنافذ، ثم وجّه الوكيل الخارجي إلى المُستمع الداخلي المُهيأ لعملية النشر الخاصة بك.

بعد التعديل، اختبر الإعدادات قبل إعادة تحميل Nginx:

sudo nginx -t
sudo systemctl reload nginx

في حال فشل اختبار التكوين، يُرجى تصحيح الملف والسطر المُبلغ عنهما قبل إعادة التحميل. يُعدّ خطأ بناء الجملة وخطأ 502 من المصدر مشكلتين منفصلتين؛ فالنجاح nginx -tيؤكد صحة بناء الجملة، وليس استجابة المصدر.

5. إذا كان برنامج ONLYOFFICE يعمل في Docker، فافحص حالته وتعيين المنافذ الخاصة به.

تحقق مما إذا كانت الحاوية قيد التشغيل وما هو منفذ المضيف المنشور:

docker ps --filter name=onlyoffice
docker port <container_name_or_id>
docker logs --tail 100 <container_name_or_id>

يُحدد دليل تثبيت Docker الرسمي منافذ المضيف بمنفذ الحاوية 80، ويتحقق المثال من سجلات الحاوية في حال عدم تحميل صفحة الترحيب. استخدم المنفذ المُشار إليه كمنفذ المصدر من docker portجانب المضيف. عند تشغيل كل من Nginx وONLYOFFICE كحاويات، ضعهما على شبكة مشتركة ووجّه حركة البيانات إلى اسم خدمة ONLYOFFICE ومنفذ الحاوية، بدلاً من توجيهها إلى عنوان الاسترجاع الخاص بالمضيف.

تحقق من حالة سلامة الحاوية إذا كان ملف Compose الخاص بك يُعرّف فحصًا للسلامة. يتحقق مثال Compose الحالي http://localhost:8000/info/info.jsonمن داخل الحاوية. قد تحتوي الحاوية "قيد التشغيل" على خدمة مستندات غير سليمة. إذا كانت الخدمة قيد إعادة التشغيل أو غير سليمة، فاستخدم السجلات للتحقق من بدء تشغيل قاعدة البيانات والذاكرة والتكوين قبل تغيير الوكيل الخارجي.

يوثّق برنامج ONLYOFFICE مسارات Docker الدائمة للسجلات والشهادات وذاكرة التخزين المؤقت للملفات. تجنّب حذف وحدات التخزين أثناء استكشاف الأخطاء وإصلاحها؛ فقد تحتوي على شهادات أو بيانات أخرى ضرورية لاستعادة الخدمة.

6. أعد التحميل، واختبر نقطة نهاية الصحة، وأعد اختبار التكامل

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

curl -i https://docs.example.com/healthcheck

استخدم عنوان URL الحقيقي لخادم المستندات. يُشير نجاح الاستجابة من كلٍّ من الخادم المحلي واسم المضيف العام إلى قدرة Nginx على الوصول إلى الخادم الخلفي وإرجاع استجابة الحالة. ثم افتح صفحة الترحيب الخاصة بخادم المستندات، وأعد محاولة الإجراء الذي فشل في الأصل في Nextcloud أو ownCloud أو أي موصل آخر لديك.

إذا نجح فحص السلامة ولكن لا يزال الموصل يُبلغ عن خطأ، فقد تكمن المشكلة المتبقية خارج مسار Nginx 502، على سبيل المثال، عنوان URL الخاص بالموصل، أو موثوقية TLS، أو إعدادات JWT. قارن هذه القيم مع إعدادات الموصل وONLYOFFICE بدلاً من الاستمرار في تغيير مهلات الوكيل بشكل عشوائي.

تشخيص سريع

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

• استكشاف أخطاء مستندات ONLYOFFICE وإصلاحها لنظام التشغيل Linux
• مستندات ONLYOFFICE خلف خادم وكيل
• مثال رسمي من ONLYOFFICE لخادم وكيل Nginx HTTPS-to-HTTP
• وثائق ONLYOFFICE: تثبيت Docker وتعيين المنافذ
• مثال على إنشاء ملف في خادم مستندات ONLYOFFICE