كيفية تشغيل خادم مستندات ONLYOFFICE خلف موازن تحميل HAProxy

القاعدة الأهم هي: وضع خادم مستندات ONLYOFFICE خلف HAProxy أمرٌ بسيطٌ بالنسبة لخادم خلفي واحد، لكن مجموعة محررات متعددة العُقد تحتاج إلى أكثر من مجرد التوزيع الدوري البسيط. تنص وثائق واجهة برمجة التطبيقات (API) الحالية لـ ONLYOFFICE على أن طلبات المستند نفسه يجب أن تصل إلى عقدة خادم المستندات نفسها أثناء التحرير التعاوني. بالنسبة لعمليات التكامل الحديثة، يُوصى باستخدام shardkeyمُعامل الاستعلام، الذي يُمكن لموازن الأحمال استخدامه لتحديد تقارب المستندات.

إذا كان لديك خادم مستندات واحد فقط وترغب في استخدام HAProxy لإنهاء اتصالات HTTPS، أو اسم مضيف عام ثابت، أو فحوصات مركزية لحالة النظام، فسيكون التكوين أبسط. أما إذا كان لديك خادمان أو أكثر من خوادم المستندات، فاستخدم نفس أساسيات الوكيل، ولكن أضف توجيهًا يعتمد على التوزيع الدوري shardkeyبدلاً من افتراض أن التوزيع الدوري العادي كافٍ.

تمت مراجعة الأمثلة أدناه مقابل وثائق ONLYOFFICE الحالية للوكيل ، ووثائق ONLYOFFICE shard-key ، وإرشادات HAProxy WebSocket الحالية .

عندما يكون هذا الإعداد مناسبًا

يُعدّ HAProxy واجهة أمامية مناسبة عندما ترغب في استخدام عنوان URL عام واحد، مثل https://docs.example.comإنهاء TLS عند موازن الأحمال، وإجراء فحوصات صحية نشطة، أو ربط عدة عُقد لخادم المستندات بنقطة نهاية واحدة. كما أنه مفيد عندما لا ترغب في أن يتصل Nextcloud أو ownCloud أو نظام إدارة المستندات المخصص أو تطبيقك مباشرةً بأي عُقدة من عُقد خادم المستندات.

يفترض هذا الدليل ما يلي:

• يمكن لـ HAProxy الوصول إلى كل خادم مستندات عبر الشبكة الداخلية.
• يعمل كل خادم مستندات بشكل مباشر قبل إدخال موازن الأحمال.
• يتم حل اسم المضيف العام إلى HAProxy.
• تغطي شهادة TLS الخاصة بك اسم المضيف العام.
• إذا كنت تقوم بتشغيل عدة عقد، فسيتم نشرها كبنية ONLYOFFICE متعددة الخوادم مدعومة بدلاً من خوادم مستقلة غير ذات صلة تشترك فقط في موازن تحميل.

الخطوة 1: تحقق من كل خادم مستندات قبل إضافة HAProxy

لا تبدأ بموازن الأحمال. تأكد أولاً من سلامة جميع الخوادم الخلفية من مضيف HAProxy. استخدم ONLYOFFICE كنقطة /healthcheckنهاية للتحقق من توفر المحرر. يُرجع الخادم السليم قيمة صحيحة true؛ ويشمل الفحص التبعيات الأساسية مثل قاعدة البيانات، ووسيط الرسائل، واتصال Redis، والتخزين.

curl -sS http://10.0.10.21/healthcheck
curl -sS http://10.0.10.22/healthcheck

النتيجة المتوقعة:

true
true

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

الخطوة الثانية: اضبط وضع HTTP ومهلات الاتصال التي تسمح باتصالات المحرر

تطبيق ONLYOFFICE هو تطبيق HTTP ويستخدم اتصالات WebSocket طويلة الأمد أثناء التحرير. يمكن لـ HAProxy توجيه اتصالات WebSocket تلقائيًا بعد ترقية HTTP، ولكن سياسة مهلة الاتصال الخاصة به لا تزال مهمة. توصي وثائق HAProxy بقيمة محددة timeout tunnelلاتصالات WebSocket المُرَقَّاة.

الأساس العملي هو:

global
    log /dev/log local0
    log /dev/log local1 notice
    daemon
    maxconn 4096

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5s
    timeout client 60s
    timeout server 60s
    timeout tunnel 1h

يُعدّ تحديد مهلة ساعة واحدة للنفق مثالاً، وليس شرطاً عاماً. اختر قيمةً تتناسب مع سلوك التحرير في مؤسستك، وسياسة الأمان، وحدود الموارد. إذا كان المحررون ينقطعون عن الاتصال على فترات منتظمة جداً، فقارن هذه الفترة مع مهلة الخمول في HAProxy وأي جدار حماية أو خادم وكيل عكسي.

الخطوة 3: إنهاء بروتوكول HTTPS والاحتفاظ بسياق الطلب الأصلي

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

يمكن أن تبدو واجهة HAProxy الأمامية النظيفة على النحو التالي:

frontend onlyoffice_http
    bind *:80
    mode http
    http-request redirect scheme https code 301

frontend onlyoffice_https
    bind *:443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    mode http
    option httplog

    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]

    default_backend onlyoffice_docs

لا تحتاج عادةً إلى إعادة إنشاء قواعد NGINX Upgradeوقواعد Connectionالترويسة يدويًا في وضع HTTP الحديث لـ HAProxy. يتعرف HAProxy على ترقية HTTP إلى WebSocket ويُحوّل الاتصال إلى وضع النفق. المهم هو عدم إضافة قواعد تُزيل أو تُعطّل طلب الترقية.

لضمان رؤية عنوان IP الخاص بالعميل، أضف ذلك option forwardforفي الواجهة الخلفية. سيؤدي ذلك إلى إنشاء X-Forwarded-Forرأس من عنوان مصدر العميل.

الخطوة الرابعة: أضف فحوصات الصحة واختر قاعدة التوازن المناسبة

خادم مستندات واحد

إذا كان HAProxy يعمل كواجهة أمامية لخادم مستندات واحد، فيمكن أن تكون الواجهة الخلفية بسيطة:

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    server ds1 10.0.10.21:80 check

في هذا التصميم، يعتبر HAProxy بشكل أساسي وكيلًا عكسيًا ونقطة نهاية TLS وبوابة صحية.

عُقد خادم مستندات متعددة

في بيئة نشر متعددة العُقد، لا تعتمد على التوزيع الدوري البسيط للتحرير التعاوني. تنص وثائق ONLYOFFICE الحالية على ضرورة وصول جميع الطلبات المتعلقة بالمستند نفسه إلى الخادم نفسه. تتضمن طلبات التحرير من المتصفح إلى الخادم مفتاح تجزئة تلقائيًا، وينبغي على التطبيقات إضافته ?shardkey=<document-key>إلى طلبات الأوامر والتحويلات وطلبات منشئ المستندات حيثما وُثِّق ذلك.

يدعم HAProxy التجزئة على معلمات استعلام عنوان URL، لذا فإن الواجهة الخلفية المناسبة لواجهة برمجة تطبيقات ONLYOFFICE Docs القياسية هي:

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    balance url_param shardkey

    server ds1 10.0.10.21:80 check
    server ds2 10.0.10.22:80 check

تقوم خوارزمية HAProxy url_paramبتشفير مُعامل سلسلة الاستعلام المُختار. في حال عدم وجود هذا المُعامل، يعود HAProxy إلى سلوك موازنة الأحمال العادي. لذا، من الأهمية بمكان أن يُرسل نظام التكامل الخاص بك مفتاح التجزئة في الطلبات التي يُوصي بها ONLYOFFICE.

يختلف الأمر مع WOPI. تشير ONLYOFFICE إلى أن تكاملات WOPI تستخدم WOPISrcمُعامل الاستعلام لنفس غرض التوجيه. لا تقم بنسخ balance url_param shardkeyالسطر دون تغيير إلى تصميم WOPI وتفترض أنه يوفر التقارب المطلوب.

تحقق من صحة HAProxy وأعد تحميله بأمان

قبل إعادة تحميل الخدمة، تحقق من صحة الإعدادات:

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

لا تقم بإعادة التحميل إلا بعد نجاح التحقق من صحة بناء الجملة:

sudo systemctl reload haproxy
sudo systemctl status haproxy

إذا كانت توزيعتك تستخدم مدير خدمة أو مسار تكوين مختلفًا، فقم بتعديل هذه الأوامر وفقًا لذلك. يُفضّل إعادة التحميل على إعادة التشغيل القسري غير الضرورية عندما تدعم حزمة HAProxy إعادة تحميل التكوين بسلاسة.

اختبر من خلال عنوان URL العام، وليس فقط من داخل شبكة الواجهة الخلفية.

والآن اختبر ما الذي سيصل إليه المستخدمون ومنصة إدارة المستندات الخاصة بك فعلياً:

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

الجسم المتوقع هو:

true

ثم تحقق من شهادة TLS:

openssl s_client -connect docs.example.com:443   -servername docs.example.com </dev/null 2>/dev/null   | openssl x509 -noout -subject -issuer -dates

وأخيرًا، افتح مستندًا حقيقيًا من خلال التطبيق المُدمج. يُثبت فحص السلامة فقط أن نقطة نهاية خادم المستندات جاهزة؛ ولا يُثبت صحة عناوين URL الخاصة بالاستدعاء، أو تكوين JWT، أو تنزيلات المستندات، أو استدعاءات الحفظ، أو تقارب العقد المتعددة.

ما الذي يجب التحقق منه عند تحميل المحرر ثم انقطاع الاتصال أو فشل الحفظ؟

هل تحتاج إلى جلسات تفاعلية؟

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

يُفسر هذا التمييز نفسه سبب عدم اعتبار جلسة ثابتة بسيطة تعتمد على ملفات تعريف الارتباط بديلاً عن سلوك التوجيه الموثق من قِبل ONLYOFFICE. استخدم مفتاح التجزئة الموثق للتطبيق عند إنشاء نشر واجهة برمجة تطبيقات المستندات متعددة العُقد.

قائمة التحقق النهائية للتكوين

• كل خادم مستندات يعود trueمن /healthcheckقبل إضافته إلى HAProxy.
• يعمل HAProxy في وضع HTTP للواجهة الأمامية والخلفية لـ ONLYOFFICE.
• يتم إنهاء بروتوكول HTTPS بشهادة صالحة لاسم مضيف خادم المستندات العام.
• X-Forwarded-Protoويتم X-Forwarded-Hostتوجيهها بشكل صحيح.
• مدة مهلة نفق WebSocket طويلة بما يكفي لجلسات التحرير الحقيقية.
• تقوم عمليات فحص سلامة النظام الخلفي بإزالة العقد المعطلة من الخدمة.
• تستخدم حركة مرور واجهة برمجة تطبيقات المستندات متعددة العقد shardkeyتقاربًا قائمًا على -، وليس التوزيع الدوري البسيط وحده.
• تستخدم عمليات نشر WOPI التوجيه المناسب لـ WOPISrc.
• يعمل فحص الصحة العامة، ويمكن فتح مستند حقيقي وتعديله وحفظه من خلال التكامل.

بالنسبة لخادم مستندات واحد، يُعد HAProxy في الأساس خادم وكيل عكسي نظيف وطبقة TLS. أما بالنسبة لعدة خوادم مستندات، فيكمن الاختلاف الحاسم في التوجيه المُراعي للمستندات. لذا، قم ببناء الوكيل بناءً على هذا المطلب أولاً، ثم أضف فحوصات السلامة، وبروتوكول HTTPS، وضبط مهلة الاتصال.