كيفية استضافة عميل ويب مخصص على Nginx

إذا كان بإمكانك فتح خادم Matrix المنزلي الخاص بك، ولكنك لا ترغب في أن يعتمد المستخدمون على موقع Element الإلكتروني العام، فيمكنك استضافة Element Web كموقع ثابت على خادم Nginx الخاص بك. يتم تقديم الملفات بواسطة Nginx؛ ويبقى خادم Matrix المنزلي خدمة منفصلة تُدير الحسابات والغرف والرسائل والاتحاد. هذا التمييز مهم: فتوجيه عميل الويب إلى Synapse لا يؤدي إلى تثبيت Synapse أو تهيئته.

يستخدم هذا الدليل التمهيدي chat.example.orgموقع Element وخادم matrix.example.orgالمنزل. استبدل كلا الاسمين باسم مضيفك الحقيقي. تفترض الأوامر وجود خادم لينكس بنظام Debian أو Ubuntu؛ وتختلف مسارات الحزم وأسماء الخدمات باختلاف التوزيعة.

ما تحتاجه قبل البدء

جهّز هذه العناصر قبل تغيير ملفات الخادم:

• نطاق أو نطاق فرعي لعميل الويب، مع توجيه نظام أسماء النطاقات (DNS) إلى مضيف Nginx.
• خادم منزلي يعمل بنظام Matrix ويمكن الوصول إليه عبر عنوان URL لبروتوكول HTTPS، مثل https://matrix.example.org.
• تم تثبيت Nginx، مع منح الإذن بتعديل إعدادات الموقع وإعادة تحميل الخدمة.
• شهادة TLS صالحة لاسم مضيف عميل الويب. يجب على المستخدمين تسجيل الدخول عبر HTTPS لأن متصفحهم يرسل بيانات الاعتماد ورموز الجلسة إلى الموقع.
• أرشيف إصدار Element Web المستقر الحالي من المشروع الرسمي. تجنب نشر نسخة تجريبية على خدمة عامة إلا إذا كنت تنوي تحديدًا تشغيل برنامج تطويري.

Element Web هو تطبيق متصفح يتكون من ملفات ثابتة. توصي تعليمات التثبيت الحالية للمشروع بتنزيل إصدار، وفك ضغطه على الخادم، وتوجيه خادم الويب إلى الملفات الناتجة، ثم ضبط الإعدادات config.json. على نظامي Debian وUbuntu، يوفر المشروع أيضًا حزمة Element Web التي تُثبّت مجلد الويب الرئيسي الخاص بها ضمن مجلد محدد، /usr/share/element-webوإعداداتها ضمن مجلد آخر /etc/element-web/config.json. تستخدم الخطوات التالية أرشيف الإصدار، مما يتيح لك اختيار مجلد رئيسي مخصص.

راجع تعليمات تثبيت Element Web والإصدارات الرسمية قبل اختيار الإصدار. إذا كنت تستخدم حزمة Debian، فوجه Nginx إلى جذر الويب الموثق للحزمة، ثم عدّل ملف إعدادات الحزمة؛ ولا تنسخ مسارات الأرشيف أدناه دون تغيير.

1. قم بتنزيل وتثبيت ملفات Element Web

مجلد الجذر هو الدليل الذي يُقدّمه Nginx عند زيارة المستخدم لموقعك. أنشئ مجلد جذر مخصصًا وفك ضغط الإصدار فيه. استبدل أسماء الأرشيفات والمجلدات التي نزّلتها فعليًا؛ إذ تتغير إصدارات البرامج بمرور الوقت.

sudo install -d -o root -g www-data -m 0755 /var/www/element
tar -xzf element-vX.Y.Z.tar.gz
ls

عادةً ما يتم فك ضغط الأرشيف إلى مجلد مُرقّم. انسخ محتويات هذا المجلد، بما في ذلك index.htmlحزم جافا سكريبت والخطوط والصور ونموذج الإعدادات، إلى جذر مستندات Nginx. على سبيل المثال، إذا كان اسم المجلد المُستخرج هو element-vX.Y.Z:

sudo cp -a element-vX.Y.Z/. /var/www/element/
sudo find /var/www/element -type d -exec chmod 755 {} \;
sudo find /var/www/element -type f -exec chmod 644 {} \;
ls -l /var/www/element/index.html /var/www/element/config.sample.json

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

2. قم بتهيئة العميل لاستخدام خادمك المنزلي

يحتاج برنامج Element إلى عنوان خادم منزلي قبل أن يبدأ. انسخ ملف العينة وحدد عنوان URL الافتراضي لواجهة برمجة تطبيقات عميل Matrix. في هذا المثال، يمكن الوصول إلى Synapse عبر https://matrix.example.org:

cd /var/www/element
sudo cp config.sample.json config.json
sudoedit /var/www/element/config.json

قم بتحرير الملف /var/www/element/config.jsonوتأكد من احتوائه على كائن JSON صالح مع default_server_configإدخال، على سبيل المثال:

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.org"
    }
  }
}

يُحدد هذا الخيار الخادم الذي يوفره Element افتراضيًا. ولا يُنشئ حساب Synapse أو يُلزم جميع المستخدمين باختيار هذا الخادم. يُوثّق دليل تكوين Element الحالي default_server_configهذه الطريقة المُفضّلة لتوفير معلومات اتصال الخادم الرئيسي. default_hs_urlالخيار الأقدم مُهمل. إذا كنت ترغب في حصر المستخدمين بخادم واحد، يُوثّق Element إعدادًا منفصلاً disable_custom_urls؛ حدّد ما إذا كان ذلك مناسبًا لمجتمعك قبل تفعيله.

يمكنك أيضًا ضبط بعض التخصيصات المحدودة، مثل اختيار سمة افتراضية أو بعض تفاصيل العلامة التجارية، باستخدام خيارات Element الموثقة. هذا لا يعني استبدالًا كاملًا للعلامة التجارية: فالمشروع يوثق إعدادات التخصيص المختارة بدلًا من إعادة تصميم العلامة التجارية بشكل كامل. راجع دليل التكوين للاطلاع على الخيارات المدعومة في الإصدار الذي قمت بتثبيته؛ ولا تنسخ الإعدادات من إصدار آخر قبل مراجعتها.

راجع مرجع التكوين الحالي لـ Element Web . developقد تتغير الوثائق مع تطور المشروع، لذا تأكد من مطابقة أي مفتاح اختياري مع الإصدار الذي تقوم بنشره.

3. أضف موقع Nginx لعميل الويب

أنشئ إعدادات موقع لاسم مضيف العميل. يفترض هذا المثال أن لديك بالفعل شهادة chat.example.orgفي مسارات الشهادات الموضحة. لم يتم تضمين إصدار الشهادة لأن الطريقة الصحيحة تعتمد على مضيفك ومزود خدمة DNS وإعدادات TLS الحالية.

server {
    listen 80;
    server_name chat.example.org;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name chat.example.org;

    ssl_certificate     /etc/letsencrypt/live/chat.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/chat.example.org/privkey.pem;

    root /var/www/element;
    index index.html;

    # Revalidate the client files after deployments.
    add_header Cache-Control "no-cache" always;

    # Element Web hosting security headers.
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Content-Security-Policy "frame-ancestors 'self'" always;

    location / {
        try_files $uri $uri/ =404;
    }
}

ضع الكتلة في ملف الموقع المناسب لتوزيعتك، وفعّل ذلك الموقع إذا لزم الأمر، وتأكد من أن إعدادات Nginx العامة تُحمّل mime.typesالملف القياسي. يستخدم Nginx أنواع MIME لإخبار المتصفحات ما إذا كانت الاستجابة عبارة عن JavaScript أو CSS أو JSON أو نوع ملف آخر. rootيجب أن يشير المسار إلى الدليل الذي يحتوي مباشرةً على الملف index.html.

يُعدّ رأس no-cache المذكور أعلاه أساسًا بسيطًا وسهل الاستخدام في النشر: إذ تُعيد المتصفحات التحقق من صحة الملفات بعد التحديث بدلًا من الاستمرار في استخدام رمز العميل القديم. تنصّ ملاحظات استضافة Element تحديدًا على عدم تخزين الملفات /config.*.jsonو /i18nو /versionو /index.htmlمؤقتًا، وتوصي بإعادة التحقق من صحة جذر الموقع. إذا أضفت لاحقًا تخزينًا مؤقتًا طويل الأمد للأصول الثابتة الكبيرة، فاحرص على تحديث هذه المسارات والتحقق من تسمية الأصول في الإصدار قبل إنشاء قواعد التخزين المؤقت.

توصي صفحة "اقرأني" الخاصة بـ Element على الويب باستخدام خاصية منع الإطارات ورؤوس أنواع المحتوى للمواقع المستضافة ذاتيًا. إذا كنت قد قمتَ بالفعل بتعيين سياسة أمان المحتوى (CSP) في مكان آخر، فأضفها frame-ancestors 'self'إلى تلك السياسة الموجودة بدلًا من إرسال رأس CSP ثانٍ. قد تحظر سياسة CSP التقييدية البرامج النصية الضرورية للتطبيق، لذا لا تنسخ سياسة عامة دون اختبارها على العميل المُثبَّت.

اقرأ متطلبات الاستضافة والتخزين المؤقت لـ Element Web ووثائق الوحدة الأساسية الرسمية لـ Nginx لمعرفة سلوك معالجة الملفات الثابتة.roottry_files

4. تحقق من صحة الإعدادات وأعد تحميل Nginx

اختبر الإعدادات قبل تطبيقها. إذا أبلغ Nginx عن خطأ، فاستمر في تشغيل العملية الحالية أثناء إصلاح الملف والسطر المُبلغ عنهما؛ ولا تقم بإعادة تحميل إعدادات معطوبة.

sudo nginx -t
sudo systemctl reload nginx
curl -I https://chat.example.org/
curl -I https://chat.example.org/config.json

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

curl -fsS https://chat.example.org/config.json | python3 -m json.tool

ثم افتح https://chat.example.orgالمتصفح. ستظهر لك شاشة تسجيل الدخول أو الترحيب الخاصة بـ Element مع خادم Matrix الرئيسي كخادم افتراضي. جرّب حسابًا تجريبيًا، وتحقق من أدوات مطوري المتصفح بحثًا عن طلبات الشبكة الفاشلة، وتأكد من أن تسجيل الدخول وتحميل قائمة الغرف وإرسال الرسائل تعمل بشكل صحيح. إن تحميل الصفحة بنجاح يثبت فقط أن Nginx قد قام بتشغيل عميل الويب؛ ولا يثبت أن الخادم الرئيسي متاح أو مُهيأ بشكل صحيح.

5. اجعل خاصية اكتشاف الخادم المنزلي تعمل عند الحاجة

إذا كانت معرّفات Matrix الخاصة بك تستخدم اسم خادم مثل `<اسم الخادم>` example.orgبينما واجهة برمجة تطبيقات Synapse موجودة على `<اسم واجهة matrix.example.orgبرمجة التطبيقات>`، فيمكن لعملاء Matrix استخدام استجابة معروفة للعميل على `< https://example.org/.well-known/matrix/clientاسم الاستجابة>` لاكتشاف عنوان URL الخاص بواجهة برمجة التطبيقات. تقع نقطة النهاية الاختيارية هذه على النطاق الموجود في معرّف Matrix، وليس تلقائيًا على اسم مضيف عميل الويب Element. تبدو الاستجابة البسيطة كما يلي:

{
  "m.homeserver": {
    "base_url": "https://matrix.example.org"
  }
}

قم بتقديمه بصيغة JSON مع رؤوس CORS المطلوبة لعملاء المتصفح. توفر وثائق تثبيت Synapse مثالًا لـ Nginx، وتشير إلى أنه public_baseurlيجب أن يتطابق مع عنوان URL الذي يستخدمه العملاء للوصول إلى Synapse. إذا كان تكوين Element الخاص بك يُحدد عنوان URL الصحيح للخادم الرئيسي مباشرةً، وقام المستخدمون بإدخال هذا الإعداد الخاص بالعميل، فقد لا تكون هناك حاجة إلى اكتشاف الخادم في هذا الإعداد الأساسي.

اتبع إرشادات عميل Synapse المعروفة واختبر عنوان URL النهائي curlقبل توقع عمل خاصية اكتشاف مُعرّف المستخدم. ولضمان عزل أمني، توصي إرشادات أمان Synapse باستضافة الخادم الرئيسي على نطاق مُسجّل مُختلف عن نطاق تطبيقات الويب الحساسة كلما أمكن ذلك؛ توفر النطاقات الفرعية المنفصلة بعض الحماية، ولكن يُفضّل استخدام نطاق مُسجّل مُنفصل.

مشاكل شائعة يجب تجنبها

• يعرض Nginx الخطأ 403: تحقق من أذونات قراءة الملفات والمجلدات وتأكد من أن عامل Nginx يمكنه اجتياز كل دليل رئيسي.
• الصفحة فارغة أو تُظهر خطأ 404 عند استخدام جافا سكريبت: تأكد من rootأن المسار يشير إلى محتويات مجلد الإصدار المُستخرج، وليس إلى مجلد أعلى أو أسفل منه. راجع سجلات أخطاء Nginx وسجلات الوصول.
• يتم تحميل العنصر ولكن لا يمكن الاتصال أو تسجيل الدخول: تحقق من ملف base_urlin config.json، وشهادة HTTPS الخاصة بالخادم الرئيسي، وصلاحيات جدار الحماية، وأي إعدادات CORS أو خادم وكيل عكسي من جانب Synapse. يتم تطبيق CORS بواسطة المتصفحات؛ ولا يمكن لموقع Nginx الثابت إصلاح سياسة المصدر الخاصة بالخادم الرئيسي تلقائيًا.
• لا تظهر التغييرات الأخيرة: تحقق من رؤوس ذاكرة التخزين المؤقت لـ /، /index.html، /config.json، /version، و /i18n، ثم قم بتحديث المتصفح بالكامل بعد التأكد من استبدال الملفات المنشورة.
• صفحة تسجيل الدخول تعمل على بروتوكول HTTP فقط: أكمل إعداد TLS وأعد توجيه HTTP إلى HTTPS قبل دعوة المستخدمين لتسجيل الدخول.

قائمة التحقق النهائية للنشر

• اسم مضيف Element Web يُشير إلى خادم Nginx ولديه شهادة HTTPS صالحة.
• يحتوي جذر المستند على ملفات الإصدار index.html، والأصول، وملف صالح config.json.
• تشير بيانات JSON m.homeserver.base_urlإلى واجهة برمجة تطبيقات عميل HTTPS المتاحة لخادم Matrix المنزلي الخاص بك.
• sudo nginx -tيتم تمريرها، ويقوم Nginx بعرض كل من الصفحة الرئيسية وعبر config.jsonHTTPS.
• يمكن للمتصفح تسجيل الدخول وإرسال طلب حقيقي إلى الخادم الرئيسي دون أخطاء تتعلق بالشهادة أو CORS أو الملفات المفقودة.
• تسمح قواعد التخزين المؤقت الخاصة بك بتفعيل ملفات العميل الجديدة والتكوين بعد الترقية.

بمجرد اجتياز هذه الفحوصات، يتم تشغيل عميل Element Web المخصص بواسطة Nginx، ويصبح بإمكانه التواصل مع خادم Matrix الرئيسي. حافظ على تحديث Element Web، واحتفظ بنسخة احتياطية من الإصدار السابق وإعداداته، وأعد فحص عنوان URL الخاص بالخادم الرئيسي وطلبات الشبكة من المتصفح بعد كل ترقية.

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

• وثائق تثبيت Element Web
• دليل تكوين Element Web
• إرشادات حول استضافة المواقع الإلكترونية، وعنوان الأمان، والتخزين المؤقت من Element
• وثائق URI المعروفة لعميل Synapse
• إرشادات أمان Synapse
• توثيق وحدة Nginx الأساسية