كيفية إعداد الاتحاد على ماتريكس سينابس: دليل خطوة بخطوة

تتيح خاصية "اتحاد المصفوفة" لخادم Synapse المنزلي تبادل أحداث الغرفة مع خوادم منزلية أخرى، مما يسمح للمستخدمين الذين يستخدمون خوادم مختلفة بالمشاركة في نفس الغرفة. لإعداد هذه الخاصية، اجعل واجهة برمجة تطبيقات الاتحاد الخاصة بـ Synapse متاحة عبر HTTPS، وانشر معلومات اكتشاف الخادم الصحيحة، واسمح بحركة مرور الشبكة المطلوبة، واختبر نقطة النهاية العامة. لا يكفي مجرد تشغيل Synapse أو فتح المنفذ 8448 إذا كان نظام أسماء النطاقات (DNS) أو بروتوكول أمان طبقة النقل (TLS) أو توجيه الوكيل غير صحيح.

يستخدم هذا الدليل نموذجًا نموذجيًا لنشر خادم وكيل عكسي: نطاق هوية Matrix هو example.org، ويعمل Synapse على matrix.example.org، ويتولى الخادم الوكيل معالجة TLS على المنفذ 443. استبدل كلا النطاقين المذكورين في المثال بنطاقك الخاص. إذا كان Synapse متاحًا بالفعل عبر HTTPS على example.org:8448، فلن تحتاج عادةً إلى تفويض. تعتمد الأوامر ومسارات الملفات على ما إذا كنت قد ثبّت Synapse من حزمة، أو بيئة افتراضية، أو حاوية.

ما الذي يجب أن يكون صحيحاً قبل أن ينجح الاتحاد؟

• يتمتع خادم Synapse الخاص بك باسم نطاق عام ثابت server_name. يظهر هذا الاسم في معرّفات المصفوفة مثل `<اسم النطاق @alex:example.org>`؛ تغييره لاحقًا ليس تعديلًا روتينيًا لاسم المضيف.
• يمكن للخوادم المنزلية الأخرى الوصول إلى واجهة برمجة تطبيقات الاتحاد عبر HTTPS والتحقق من صحة شهادة TLS.
• يؤدي اكتشاف الخادم إلى توجيه الخوادم المنزلية البعيدة إلى المضيف والمنفذ الصحيحين. منفذ الاتحاد القياسي هو 8448؛ ويمكن أن يشير التفويض إلى HTTPS على المنفذ 443.
• تسمح قواعد جدار الحماية بحركة المرور الواردة على نقطة نهاية الاتحاد التي اخترتها، بالإضافة إلى اتصالات الاتحاد الصادرة.

تُعنى خدمة الاتحاد بالتواصل بين الخوادم. وهي لا تُفعّل الغرف الخاصة تلقائيًا ولا تدعو مستخدمين آخرين. لا يزال يتعين على المستخدمين الانضمام إلى الغرف أو تلقي دعوات إليها، وتُحدد عضوية الغرفة وإعداداتها من يمكنه المشاركة. ابدأ بتحديد شكل معرّفات المصفوفة الخاصة بك، ثم استخدم نفس النطاق الخاص بـ Synapse server_name.

الخطوة 1: تحقق من اسم خادم Synapse وطريقة نشره

افتح النطاق النشط homeserver.yamlوتأكد من أنه server_nameالنطاق الذي تنوي الاحتفاظ به. الترتيب الشائع هو:

server_name: "example.org"
public_baseurl: "https://matrix.example.org/"

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

تحقق من كيفية تثبيت Synapse وإدارته. تستخدم خدمة systemd، ومجموعة Docker Compose، ونشر Kubernetes، ومنتج الاستضافة المُدارة إجراءات إعادة تشغيل وشبكات مختلفة. طبّق الأمثلة أدناه على ملف التكوين الصحيح، واحتفظ بأي مستمعين وإعدادات مخصصة موجودة.

الخطوة الثانية: اختر الاتحاد المباشر على المنفذ 8448 أو التفويض إلى المنفذ 443

هناك مساران شائعان للاتحادات الجديدة:

• استخدم المنفذ الافتراضي 8448: وجّه نظام أسماء النطاقات (DNS) الخاص server_nameبالنطاق إلى الخادم، واعرض بروتوكول HTTPS على المنفذ 8448، وقدّم شهادة صالحة لهذا النطاق. إذا كانت واجهات برمجة التطبيقات (APIs) متاحة على النطاق المُسمى server_nameعلى المنفذ 8448، فإن وثائق Synapse تُشير إلى عدم الحاجة إلى التفويض.
• استخدم المنفذ 443 مع التفويض: قم بالخدمة https://example.org/.well-known/matrix/serverباستخدام JSON لتوجيه الخوادم الأخرى إلى نقطة النهاية الفعلية، على سبيل المثال {"m.server":"matrix.example.org:443"}. يجب أن يتم حل اسم المضيف المفوض بشكل عام وأن يقدم شهادة صالحة لـ matrix.example.org.

المنفذ 8448 ليس إلزاميًا في جميع عمليات النشر. إذا كنت تستخدم التفويض إلى المنفذ 443، فيمكن للاتحاد الوارد استخدام المنفذ 443 بدلاً منه. إذا كانت الاتصالات الصادرة مقيدة بجدار حماية صادر، فاسمح باستخدام كل من المنفذين 443 و8448 لأن الخوادم البعيدة قد تستخدم أيًا منهما. اختر مسارًا واردًا واحدًا واجعل سجل نظام أسماء النطاقات (DNS) وشهادة TLS والخادم الوكيل العكسي وجدار الحماية متوافقة معه.

الخطوة 3: توجيه واجهة برمجة تطبيقات الاتحاد الخاصة بـ Synapse عبر الوكيل العكسي

يستمع برنامج Synapse عادةً على منفذ HTTP 8008 خلف خادم وكيل عكسي. يقوم هذا الخادم بإنهاء بروتوكول HTTPS وإعادة توجيه نقاط نهاية Matrix إلى Synapse. في homeserver.yamlالمستمع ذي الصلة، تأكد من أن مستمع HTTP يتضمن موارد كل من العميل والاتحاد، وأنه يثق في رؤوس الوكيل.

listeners:
  - port: 8008
    type: http
    tls: false
    x_forwarded: true
    bind_addresses: ['127.0.0.1']
    resources:
      - names: [client, federation]

هذا مثالٌ على مستمع، وليس بديلاً جاهزاً لجميع إعدادات التثبيت. إذا كان Synapse يعمل داخل حاوية، 127.0.0.1فقد يمنع الربط داخل الحاوية حاوية الوكيل من الوصول إليه؛ استخدم شبكة الخدمة وعنوان ربط مناسب بدلاً من ذلك. حافظ على خصوصية مستمع الواجهة الخلفية، واعرض الوكيل فقط كما هو مُخطط له.

قم بتهيئة الخادم الوكيل لإعادة توجيه الطلبات /_matrixإلى /_synapse/clientالمنفذ 8008، وذلك بتعيين قيمتي X-Forwarded-Forو X-Forwarded-Proto. بالنسبة لـ NGINX، يمكن أن يكون الموقع الأساسي كالتالي:

location ~ ^(/_matrix|/_synapse/client) {
    proxy_pass http://127.0.0.1:8008;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
}

استخدم عنوان المصدر الصحيح لشبكة المضيف أو الحاوية. لا تُضِف مسارًا مُعاد كتابته إلى ملف `/.htm` proxy_pass؛ إذ تُحذِّر إرشادات Synapse الخاصة بالوكيل من أنَّ توحيد مسارات الطلبات المُشفَّرة قد يُسبِّب أخطاءً في التحقق من توقيع الاتحاد. إذا احتاج المستخدمون إلى تحميل ملفات كبيرة، فاجعل حد حجم التحميل للوكيل مُتوافقًا مع إعداد تحميل الوسائط في Synapse.

الخطوة الرابعة: تهيئة TLS و DNS

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

أنشئ سجل A عامًا، وإذا كنت تستخدم IPv6، فأنشئ سجل AAAA matrix.example.orgللإشارة إلى الخادم الوكيل. تأكد من وصول كلا السجلين إلى الخدمة المطلوبة؛ فقد يتسبب سجل AAAA غير صحيح في فشل الخوادم البعيدة التي تدعم IPv6 حتى في حال عمل IPv4. إذا كنت تستخدم المنفذ 8448 مباشرةً، example.orgفيجب أن يؤدي DNS إلى المُستمع، ويجب أن تتطابق شهادته مع example.org.

الخطوة 5: نشر معلومات اكتشاف الخادم

بالنسبة للمثال المفوض، اجعل عنوان URL الخاص بـ HTTPS أدناه يُرجع الحالة 200 و JSON مع نقطة النهاية المحددة:

https://example.org/.well-known/matrix/server

{
  "m.server": "matrix.example.org:443"
}

قم بنشره كـ application/json. تأكد من إمكانية قراءته علنًا دون تسجيل دخول، وأنه لا يُعيد التوجيه في حلقة لا نهائية، وأن اسم المضيف والمنفذ يتطابقان مع خادم وكيل TLS. لا تنشره matrix.example.orgفي الملف إذا كان الوكيل يُوجّه عملية الاتحاد إلى مكان آخر.

لا يستطيع Synapse تقديم هذا الملف serve_server_wellknown: trueإلا عند توجيه الطلبات https://<server_name>/إليه بشكل صحيح. إذا كان اسم خادمك هو example.orgولكن Synapse مُستضاف على matrix.example.org، فإن خادم ويب ثابت أو وكيل عكسي على example.orgغالبًا ما يكون المكان الأنسب لتقديم استجابة التفويض.

من الأخطاء الشائعة الخلط بين ملفي "الخادم" /.well-known/matrix/clientو" /.well-known/matrix/serverالعميل". يساعد ملف الخادم خوادم المنازل الأخرى على اكتشاف عمليات الاتحاد الواردة. أما ملف العميل، فيُعلن عن عنوان URL لخادم المنزل المُتاح للعملاء، وهو اختياري لعمليات الاتحاد. قم بإعداده بشكل منفصل فقط إذا كنت ترغب في أن يكتشف العملاء المتوافقون عنوان URL الخاص بالعميل من خلال معرّفات مصفوفة المستخدمين.

الخطوة 6: افتح مسارات جدار الحماية المطلوبة

للاتصالات الواردة المباشرة، اسمح بوصول بروتوكول TCP عبر المنفذ 8448 إلى مستمع TLS أو الخادم الوكيل. أما في حالة الاتصال المفوض، فاسمح بوصول بروتوكول TCP عبر المنفذ 443 إلى الخادم الوكيل. عادةً ما تستخدم اتصالات العميل بروتوكول HTTPS عبر المنفذ 443. إذا كان الوصول إلى الشبكة الصادرة مقيدًا، فاسمح لبرنامج Synapse بالاتصال بخوادم منزلية بعيدة عبر المنفذين 443 و8448. لا تفتح منفذ Synapse الخلفي 8008 للإنترنت العام عندما يكون الخادم الوكيل العكسي هو نقطة الدخول العامة.

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

الخطوة 7: أعد التشغيل بأمان وتحقق من نقاط النهاية العامة

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

curl -i https://example.org/.well-known/matrix/server
curl -i https://matrix.example.org/_matrix/federation/v1/version

بالنسبة للأمر الأول، توقع استجابة HTTPS مع نص JSON يحتوي على البيانات الصحيحة m.server. أما بالنسبة للأمر الثاني، فتوقع استجابة HTTPS ناجحة من Synapse بدلاً من خطأ في الخادم الوكيل، أو تحذير بشأن الشهادة، أو انتهاء مهلة الاتصال. قد يختلف نص الاستجابة باختلاف إصدار Synapse.

بعد ذلك، أدخل اسم نطاقك server_name(على سبيل المثال، example.orgليس بالضرورة اسم مضيف الخادم الوكيل) في أداة اختبار اتحاد النطاقات . أصلح أي أخطاء مُبلغ عنها في نظام أسماء النطاقات (DNS) أو التفويض أو الشهادة أو نقطة النهاية، ثم أعد تشغيل الاختبار. أخيرًا، ادعُ مستخدمًا على خادم منزلي آخر إلى غرفة اختبار أو انضم إلى غرفة مُستضافة في مكان آخر. تُعد نتيجة الاختبار الناجحة فحصًا مفيدًا للاتصال العام، لكنها لا تضمن أن يتصرف كل خادم بعيد أو سياسة غرفة أو جدار حماية أو تكوين عميل بنفس الطريقة.

المفاهيم الخاطئة التي تؤدي إلى إعدادات معيبة أو غير متوقعة

• "يجب عليّ دائمًا فتح المنفذ 8448." لا. المنفذ الافتراضي هو 8448، ولكن يمكن لتفويض الخادم توجيه عمليات الاتحاد الواردة إلى المنفذ 443. افتح المنفذ الذي يستخدمه مسار الاكتشاف المنشور فعليًا.
• "يُمكّن ملف العميل المعروف من إنشاء الاتحاد." هذا غير صحيح. فعملية اكتشاف الاتحاد تستخدم نقطة نهاية الخادم المعروفة أو نظام أسماء النطاقات الاحتياطي المدعوم؛ أما نقطة نهاية العميل فلها غرض مختلف.
• "يجعل الاتحاد كل غرفة محلية عامة." كلا. يُمكّن الاتحاد من التواصل بين الخوادم. لا تزال رؤية الغرفة والعضوية تحكم المشاركة؛ قم بدعوة حساب بعيد إلى غرفة اختبار للتأكد من حالة الاستخدام التي تحتاجها.
• "يثبت فحص الصحة المحلي الأخضر وجود الاتحاد." كلا. لا تختبر الفحوصات المحلية نظام أسماء النطاقات العام، أو التحقق من صحة بروتوكول TLS الخارجي، أو ترجمة عناوين الشبكة (NAT)، أو قواعد جدار الحماية السحابي، أو توجيه الوكيل. اختبر من الخارج واستخدم أداة اختبار الاتحاد.

توصي وثائق Synapse المُحدّثة باستخدام خادم وكيل عكسي لإنهاء بروتوكول TLS، وتشرح منافذ العميل والاتحاد المنفصلة. راجع الأدلة الرسمية لتكوين الخادم الوكيل العكسي ، وتفويض الاتحاد الوارد ، وخيارات تكوين Synapse ، وإرشادات جدار الحماية والأمان . للاطلاع على قواعد اكتشاف الخادم، راجع مواصفات واجهة برمجة تطبيقات Matrix Server-Server . تفترض الأمثلة الواردة هنا استخدام Synapse القياسي خلف خادم وكيل عكسي HTTPS؛ قد تتطلب شبكات الحاويات، وعمليات النشر المُدارة، وتخطيطات المستمع المُخصصة قيمًا مختلفة.