اجعل خادم Matrix Synapse الخاص بك قابلاً للوصول إليه من أجل الاتحاد
قم بتكوين اكتشاف Synapse و HTTPS وتوجيه الوكيل حتى تتمكن خوادم Matrix المنزلية الأخرى من العثور على خادمك والاتصال به.
لربط خادم Matrix Synapse المنزلي بخادم Synapse، اجعل اسم الخادم قابلاً للاكتشاف والوصول إليه من الإنترنت العام عبر بروتوكول HTTPS، ثم وجّه طلبات خادم Matrix إلى Synapse. في الإعداد الشائع، يتولى خادم وكيل عكسي معالجة TLS على المنفذ 443، ويشير ملف إلى /.well-known/matrix/serverنطاق Matrix الخاص بك إلى هذا الوكيل. إذا كان Synapse يستجيب بالفعل على نطاق اسم الخادم الخاص بك على المنفذ 8448، فقد لا تحتاج إلى تفويض.
يستخدم هذا الدليل example.comاسم خادم Matrix الدائم، واسم matrix.example.comالجهاز أو نقطة نهاية الوكيل. استبدل كلا الاسمين باسمك الخاص. يخزن الخادم المنزلي حسابات وغرف Matrix؛ ويتيح الاتحاد للخوادم المنزلية التواصل فيما بينها. يعتمد نظام أسماء النطاقات (DNS) وقواعد جدار الحماية وبنية الوكيل وشبكات الحاويات والشهادات على مضيفك.
حدد ما إذا كان ينبغي أن تبدو معرّفات المصفوفة للمستخدمين بالشكل التالي: `<Matrix ID>` @name:example.comأو ` <Matrix ID>`. تصبح @name:matrix.example.comقيمة ` <Matrix ID>` جزءًا من معرّفات المصفوفة وعناوين الغرف. تنص وثائق تثبيت Synapse على اختيارها قبل التثبيت لأنه لا يمكن تغييرها لاحقًا دون عواقب. إذا كان Synapse قيد الاستخدام بالفعل، فلا تُغيرها لمجرد مطابقة عنوان ويب؛ استخدم التفويض للاحتفاظ بالمعرّفات الحالية.server_namehomeserver.yaml

قبل التعديل، تأكد من إمكانية الوصول إلى Synapse والخادم الوكيل ونظام أسماء النطاقات العام، وأن لديك شهادة TLS صالحة لنقطة نهاية الاتحاد. احتفظ بنسخة احتياطية homeserver.yamlمن مفتاح التوقيع، الذي يُحدد هوية الخادم الرئيسي. احتفظ بهذا المفتاح في مكان آمن؛ إذ لا يتطلب الإعداد الروتيني للاتحاد إعادة إنشائه.
يستمع برنامج Synapse عادةً إلى بروتوكول HTTP على المنفذ 8008الموجود خلف خادم وكيل عكسي. في المستمع الذي يستقبل حركة مرور الوكيل، اضبط الإعدادات x_forwarded: trueبحيث يتمكن Synapse من استخدام عنوان العميل المُعاد توجيهه من الوكيل ونظامه. يجب على الوكيل تعيين الرؤوس المناسبة X-Forwarded-For، X-Forwarded-Protoبدلاً من تمرير قيم عشوائية مُقدمة من عملاء خارجيين.

يُعدّ الربط 127.0.0.1مناسبًا عندما يعمل الخادم الوكيل على نفس المضيف. أما إذا كان الخادم الوكيل موجودًا في حاوية أو جهاز آخر، فلا يُنصح باستخدامه إلا إذا كان هذا العنوان قابلًا للوصول إليه من الخادم الوكيل. في بيئة حاويات، استخدم عنوان الشبكة أو اسم الخدمة الذي يمكن للخادم الوكيل الوصول إليه، وقيّد الوصول عبر شبكة الحاوية أو جدار الحماية. احتفظ ببنية المستمع الحالية وعدّل القيم ذات الصلة؛ ولا تقم بلصق جزء من التعليمات البرمجية بشكل عشوائي فوق بقية إعداداتك.
قم بتهيئة المضيف الظاهري لبروتوكول HTTPS الخاص بالوكيل لإعادة توجيه كل من طلب /_matrixHTTP /_synapse/clientوعنوان IP إلى مستمع HTTP الخاص بـ Synapse. يحمل المسار الأول واجهات برمجة تطبيقات Matrix، بما في ذلك الاتحاد؛ بينما يُستخدم المسار الثاني لنقاط نهاية عميل Synapse. اتبع المثال الرسمي لبرنامج الوكيل الخاص بك، واحتفظ بمسار الطلب، وأرسل الرؤوس المُعاد توجيهها التي يتوقعها Synapse. لا تقم بتطبيع أو فك تشفير أو إعادة كتابة مسارات URI: فقد تفشل توقيعات طلبات Matrix إذا قام الوكيل بتغيير المسار المُشفّر.

تختلف الإعدادات الدقيقة بين Nginx وCaddy وApache وموازنات الأحمال والاستضافة المُدارة. استخدم الصيغة الحالية للمورد ووثائق Synapse للوكيل العكسي كمرجع. قاعدة الوكيل التي تخدم عميل الويب ولكنها تتجاهل مسار واجهة برمجة تطبيقات الاتحاد غير كافية.
على سبيل المثال، matrix.example.comيجب أن يُشير المسار إلى الخادم الوكيل أو مُوازن الأحمال، ويجب 443أن يكون المنفذ قابلاً للوصول إليه من الخارج. يحتاج الخادم الوكيل إلى شهادة صالحة لـ matrix.example.com. إذا كنت تُقدّم خدمة الاتحاد مباشرةً على example.com:8448، فانشر هذا المسار والشهادة وافتح المنفذ 8448. استخدم إما المنفذ المباشر 8448، وهو المنفذ الافتراضي المتعارف عليه، أو التفويض إلى مضيف آخر ومنفذ مثل 443.
تأكد من قواعد نظام أسماء النطاقات (DNS) وجدار الحماية أو مجموعة أمان السحابة، بالإضافة إلى الشهادة من خارج شبكتك الخاصة. إذا كان هناك شبكة توصيل محتوى (CDN) أو نفق وسيط، فإن دعم حركة مرور Matrix المطلوبة يعتمد على التكوين الحالي لتلك الخدمة؛ لذا راجع وثائقها واختبر المسار الفعلي بدلاً من افتراض التوافق.
إذا كان نطاق معرف المصفوفة هو example.comولكن يمكن الوصول إلى Synapse على matrix.example.com:443، فقم بتقديم ملف JSON هذا عبر HTTPS على https://example.com/.well-known/matrix/server:
{
"m.server": "matrix.example.com:443"
}

يُستخدم المنفذ 443 بشكلٍ صريح في هذا المثال؛ إذا لم تُحدد منفذًا، فسيستخدم نظام اكتشاف المصفوفة المنفذ 8448 افتراضيًا. لا تخلط بين هذا الملف وملف /.well-known/matrix/client، الذي يُساعد العملاء في العثور على واجهة برمجة تطبيقات العميل والخادم، وهو منفصل عن اتحاد الخوادم. يستطيع Synapse تقديم ملف معروف للخادم بنفسه عندما يتم توجيه نطاق اسم الخادم مباشرةً إلى Synapse، ولكن مع نقطة نهاية منفصلة، عادةً ما تنشر الملف على خادم الويب الخاص بنطاق اسم الخادم.
يتم تحديد اكتشاف الاتحاد بواسطة Matrix وتوثيقه بواسطة Synapse. تسمح مواصفات Matrix بالاكتشاف من خلال /.well-known/matrix/server؛ لذا يُرجى مراجعة تعليمات تفويض Synapse قبل اختيار طريقة أخرى مثل سجل SRV، حيث يؤثر ذلك أيضًا على توقعات TLS.
اطلب عنوان URL للاكتشاف من جهاز خارج الشبكة الخاصة بالخادم. يجب أن يُعيد كائن JSON المذكور أعلاه عبر HTTPS دون صفحة تسجيل دخول، أو إعادة توجيه HTML، أو تحذير بشأن الشهادة، أو موقع ويب غير ذي صلة. ثم تحقق من أن اسم المضيف المُفوَّض قابل للحل، وأن شهادته صالحة، وأن المنفذ المُعلن عنه يصل إلى Synapse. استخدم أداة فحص إعدادات الخادم الوكيل وأعد تحميله قبل الاختبار.
أخيرًا، أدخل اسم خادمك (على سبيل المثال، `@` example.com، وليس اسم المضيف المُفوَّض إلا إذا كان هو اسم خادمك server_name) في أداة اختبار اتحاد المصفوفة الرسمية . كما يقترح دليل اتحاد Synapse إجراء الاختبار بالانضمام إلى غرفة عامة مثل `@` #synapse:matrix.org. يؤكد نجاح الفحص اجتياز فحوصات الاكتشاف والوصول الشائعة؛ ولكنه لا يضمن عمل كل خادم بعيد أو كل عملية في الغرفة، لأن سياسات الشبكة البعيدة وظروفها تختلف.
إذا أفاد برنامج الاختبار بعدم إمكانية الوصول إلى خادمك، فتحقق من النطاق والمنفذ اللذين تم اختبارهما، ونظام أسماء النطاقات (DNS)، وقواعد جدار الحماية، واسم الشهادة، ومسارات الوكيل، والعناوين المُعاد توجيهها، وما إذا كان إعادة التوجيه قد غيّر الطلب. يُحذّر دليل اتحاد Synapse الحالي تحديدًا من أن خوادم الاتحاد في Synapse قد لا تتبع عمليات إعادة التوجيه HTTP 308 في بعض الحالات. تجنّب الاعتماد على إعادة التوجيه 308 لنقطة نهاية الاتحاد، وأعد الاختبار بعد تصحيحها. راجع الوثائق الخاصة بإصدار Synapse المُثبّت لديك لمعرفة السلوك الخاص بكل إصدار.
يتطلب الاتحاد أن تتمكن الخوادم المنزلية البعيدة من اكتشاف واجهة برمجة تطبيقات الاتحاد والوصول إليها. لا يمكن التأكد من عمل ذلك مع جميع الخوادم البعيدة من خلال الإعدادات وحدها. تأكد من المسار باستخدام أداة الاختبار والانضمام إلى غرفة حقيقية، ثم ابحث عن نقطة النهاية أو الخطأ المحدد الذي تسبب في المشكلة.
تُعدّ لوحات واجهة المستخدم هذه أمثلة تخطيطية لبيانات التكوين والاكتشاف، وليست لقطات شاشة من خادم مباشر. تمت مراجعة مراجع التوثيق في 10 أكتوبر 2026.
قم بتكوين اكتشاف Synapse و HTTPS وتوجيه الوكيل حتى تتمكن خوادم Matrix المنزلية الأخرى من العثور على خادمك والاتصال به.
قم بتكوين عميل Keycloak OIDC وموفر Synapse حتى يتمكن مستخدمو Element Web من تسجيل الدخول من خلال خادم الهوية الخاص بك دون الكشف عن أسرار العميل.
احفظ مفتاح الاسترداد، وتحقق من جلسات Element الخاصة بك، وتأكد من إمكانية استعادة مفاتيح الرسائل المشفرة دون الخلط بين النسخة الاحتياطية وكلمة مرور حسابك.
تشخيص حالات فشل نفاد الذاكرة في Synapse أثناء المزامنة، وضبط التخزين المؤقت بأمان، وتحديد تراكم الطلبات، والتحقق من استخدام الذاكرة بشكل مستقر.
تتبع حالات فشل شهادات اتحاد المصفوفة إلى الخادم الصحيح، وإصلاح سلسلة TLS أو ثقة CA، والتحقق من الإصلاح دون تعطيل عمليات التحقق الأمني.
توجيه عملاء Matrix والاتحاد عبر Cloudflare على HTTPS 443، والحفاظ على اكتشاف Synapse، وتجنب تخزين حركة مرور API مؤقتًا أو تعطيل عمليات تحميل الوسائط.
قم بعمل نسخة احتياطية من Synapse باستخدام pg_dump، وقم بحماية مفتاح التوقيع والوسائط الخاصة به، واستعدها في قاعدة بيانات PostgreSQL نظيفة دون إعادة استخدام المفاتيح القديمة التي تستخدم لمرة واحدة.
قم بإعداد Mjölnir باستخدام حساب Matrix مخصص، وغرفة إدارة مشفرة، وDocker Compose، وقائمة السياسات، وفحوصات الأذونات.
تجاوز استخدام الخادم الوكيل القديم وقم بتكوين ميزة المزامنة المنزلقة المدمجة في Synapse. تحقق من اكتشاف العميل، ثم قم بقياس تحميل قائمة الغرف وسلوك إعادة الاتصال على هاتف متوافق.
قم بنشر Element Web كموقع ثابت، وقم بتوجيهه إلى خادم Matrix الرئيسي الخاص بك، وأضف HTTPS، وقم بتكوين Nginx لتقديم التحديثات بدون ملفات قديمة.