كيفية إعداد خادم Matrix Coturn TURN/STUN للمكالمات الصوتية والمرئية

يؤثر تغيير حالي في استدعاءات Matrix على عملية الاكتشاف، لكنه لا يؤثر على بيانات اعتماد TURN أو المنافذ الخاصة بـ Coturn. في تحديثها الصادر بتاريخ 21 أغسطس 2026، أفادت Matrix.org بأن Element Call 0.24 قد أوقف دعم اكتشاف بروتوكولات MatrixRTC عبر /.well-known/matrix/clientملف الخادم الرئيسي. ينبغي أن تدعم عمليات نشر Element Call المستقلة نقطة نهاية بروتوكولات MatrixRTC؛ بينما احتفظت Element Web/Desktop وElement X بطريقة الاكتشاف القديمة كخيار احتياطي أثناء انتقال العملاء. هذا يختلف عن إعداد TURN التقليدي.

يُهيئ هذا الدليل Coturn لخدمة TURN من Synapse، التي تُوفر بيانات اعتماد ICE مؤقتة للعملاء الذين يستخدمون مكالمات WebRTC التقليدية. تستخدم مكالمات Element Call الحالية ومكالمات MatrixRTC الجماعية وحدة إعادة توجيه انتقائية (SFU) من LiveKit وخدمة ترخيص MatrixRTC. لا يُغني Coturn وحده عن هذه المكونات. إذا كان هدفك هو استضافة Element Call ذاتيًا، فاستخدم مسار LiveKit الموضح في دليل Element Call الرسمي؛ أضف Coturn فقط إذا كانت بنية الوسائط التي اخترتها تتطلب خدمة TURN منفصلة.

اختر مسار الاتصال الصحيح أولاً

بالنسبة لـ MatrixRTC على Synapse، يستخدم دليل الاستضافة الذاتية الحالي لـ Element Call matrix_rtc.transportsسجل نقل الخادم الرئيسي ويُفعّله من خلال علامة الميزة التجريبية الموثقة. ويشير إشعار Matrix.org لعام 2026 إلى أن هذا التغيير في الاكتشاف يُعدّ بالغ الأهمية لعمليات نشر Element Call المستقلة؛ حيث يمكن للمسؤولين الآخرين إعداد نقطة النهاية مع احتفاظ العملاء المدعومين بخيار احتياطي. راجع الدليل الخاص بالعملاء وإصدار Synapse الذي تستخدمه فعليًا.

ما يفعله كوترن

تتيح بروتوكولات STUN لعميل WebRTC اكتشاف عنوان الشبكة العامة الذي يمكنه الإعلان عنه. أما بروتوكولات TURN فتعيد توجيه الوسائط عندما يتعذر على عميلين إنشاء اتصال مباشر عبر أجهزة التوجيه أو جدران الحماية الخاصة بهما. وتُنفذ بروتوكولات Coturn كلا الخدمتين. في حال عدم وجود مُرحِّل متاح، قد يرن الهاتف ولكنه يبقى في حالة "جارٍ الاتصال" عندما يكون المشاركون على شبكات مقيدة أو غير ذات صلة.

يحتاج خادم TURN إلى عنوان IP عام، أو بوابة NAT مزودة بعنوان IP عام وقواعد توجيه صحيحة. لا يمكن لخادم خاص فقط أن يعمل كمرحل إنترنت لمستخدمي Matrix عن بُعد. بالنسبة لنشر Synapse صغير، يمكنك تثبيت Coturn على الخادم الرئيسي أو استخدام مضيف عام منفصل. يوفر المضيف المنفصل حدود جدار حماية أوضح وقابلية توسع مستقلة؛ أما التثبيت على نفس المضيف فهو أبسط، ولكنه يتطلب قواعد جدار حماية دقيقة لضمان عدم كشف المرحل للخدمات الخاصة.

1. قم بتثبيت Coturn وجهز سرًا مشتركًا

على نظامي ديبيان أو أوبونتو، قم بتثبيت حزمة التوزيع:

sudo apt update
sudo apt install coturn

توفر هذه الحزمة خدمة systemd، وملف التكوين الرئيسي عادةً ما يكون موجودًا في [اسم الملف] /etc/turnserver.conf. تستخدم التوزيعات الأخرى اسم حزمة خاص بها، ونظام إدارة خدمة، ومسار تكوين خاص بها.

ابتكر سرًا قويًا وسريًا. على سبيل المثال:

openssl rand -hex 32

استخدم نفس السر في كلٍ من Coturn وSynapse. تعامل معه ككلمة مرور: لا تُعِد استخدام قيمة مثال من التوثيق، ولا تُضِفها إلى مستودع عام، ولا تُضمِّنها في تقرير خطأ عام. إذا كان إصدار Synapse لديك يدعم هذه الميزة turn_shared_secret_path، فيمكنك تخزين السر في ملف محمي بدلاً من تضمينه مباشرةً في YAML. أضاف Synapse هذا الإعداد في الإصدار 1.116.0؛ تحقق من الإصدار المُثبَّت لديك قبل استخدامه.

2. قم بتهيئة Coturn للترحيل الموثق

قم بتعديل /etc/turnserver.confاسم الخدمة وكلمة المرور المشتركة للمصادقة وتعيينهما. استبدل عناصر نائبة النطاق والكلمة السرية بما يلي:

listening-port=3478
tls-listening-port=5349

fingerprint
use-auth-secret
static-auth-secret=REPLACE_WITH_THE_SAME_RANDOM_SECRET
realm=turn.example.org

min-port=49152
max-port=65535

no-tcp-relay
no-multicast-peers
user-quota=12
total-quota=1200

syslog

use-auth-secretيُفعّل هذا الخيار آلية بيانات اعتماد TURN محدودة المدة التي يستخدمها Synapse. لا تقم بتكوين وصول مجهول أو كشف خادم وسيط مفتوح. تُعدّ قيم الحصص المذكورة أعلاه نقطة انطلاق مستمدة من إرشادات Coturn الخاصة بـ Synapse؛ عدّلها وفقًا لعدد المستخدمين المتوقع وسعة النظام. no-tcp-relayيمنع هذا الخيار العملاء من طلب الاتصال من الخادم الوسيط بوجهات TCP عشوائية؛ ولا يعني ذلك بالضرورة تعطيل TCP كوسيلة نقل من العميل إلى TURN.

يمكن إساءة استخدام بروتوكول TURN كحلقة وصل للوصول إلى عناوين الشبكة الداخلية أو الحساسة. طبّق نطاقات عناوين النظراء المحظورة بالكامل في مثال أمان Synapse Coturn الحالي، بما في ذلك النطاقات ذات الصلة بشبكات IPv4 وIPv6 الخاصة بك. راجع القواعد قبل نسخها إذا كان المستخدمون بحاجة فعلية للوصول إلى نظراء الشبكة الخاصة. حافظ أيضًا على تحديث Coturn وراقب سجلاته وحصصه.

قم بتعيين العنوان العام عندما يكون Coturn خلف NAT

إذا كان مضيف TURN موجودًا خلف جهاز توجيه، فأضف عنوانه العام إلى التكوين حتى يعلن Coturn عن عنوان ترحيل يمكن الوصول إليه:

external-ip=YOUR_PUBLIC_IPV4
listening-ip=YOUR_PRIVATE_IPV4

استبدل القيم النموذجية بالعناوين الفعلية؛ عنوان الاستماع اختياري إذا كان Coturn مرتبطًا بالفعل بالواجهة الصحيحة. قم بتوجيه نطاق مستمع TURN ونطاق الترحيل من الموجه إلى هذا الخادم. يُعد عدم تطابق العنوان الخارجي سببًا شائعًا للمكالمات التي تعمل على نفس الشبكة المحلية ولكنها تفشل بين الشبكات المختلفة.

3. افتح منافذ الاستماع والترحيل

اسمح بالمنافذ التي تتطابق مع إعدادات Coturn الخاصة بك في كل من جدار الحماية المضيف وأي جدار حماية سحابي أو جهاز توجيه:

• TCP و UDP 3478 لمستمع TURN المعتاد.
• نطاق الترحيل الافتراضي الموضح أعلاه هو UDP 49152–65535. إذا اخترت نطاقًا أصغر، فقم بتكوين نفس النطاق في Coturn وجدار الحماية.
• TCP 5349 لـ TURN عبر TLS، و UDP 5349 فقط إذا قمت بتمكين DTLS وكنت تنوي تقديمه.

بالنسبة لـ UFW، يمكن أن تبدو مجموعة قواعد الاستماع الأساسية لبروتوكول UDP/TCP ومجموعة قواعد إعادة توجيه UDP على النحو التالي:

sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
sudo ufw allow 49152:65535/udp

أضف قواعد 5349 فقط عند تهيئة مُستمع TLS أو DTLS المُناسب وإعلانه. تحقق أيضًا من مجموعة أمان مُزود الخدمة؛ إذ لا يُمكن لقاعدة UFW على مستوى المُضيف تجاوز قاعدة حظر دخول السحابة. لا تنشر واجهة التحكم الإداري لـ Coturn على الإنترنت.

4. قم بتهيئة Synapse لإصدار بيانات اعتماد Coturn

أضف إعدادات TURN التالية إلى تكوين Synapse النشط، عادةً homeserver.yaml. يجب أن يُحل اسم المضيف علنًا إلى مضيف TURN:

turn_uris:
  - "turn:turn.example.org:3478?transport=udp"
  - "turn:turn.example.org:3478?transport=tcp"
turn_shared_secret: "REPLACE_WITH_THE_SAME_RANDOM_SECRET"
turn_user_lifetime: 1h
turn_allow_guests: true

يُعلن أول عنواني URI عن بروتوكولات نقل TURN العادية على المنفذ 3478. إذا تم تكوين بروتوكول TLS واختباره، يمكنك أيضًا الإعلان عن عنوان URI مثل turns:turn.example.org:5349?transport=tcp. لا تُعلن عن أي turns:عنوان URI إلا إذا كانت الشهادة والمستمع وجدار الحماية وتوافق العميل مُفعّلة. يتم تعيين شهادة TLS والمفتاح الخاص لـ Coturn باستخدام certو pkeyفي إعداداته.

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

أعد تشغيل برنامجي Coturn و Synapse بعد تغيير ملفاتهما:

sudo systemctl restart coturn
sudo systemctl restart matrix-synapse

استخدم اسم وحدة نظام Synapse systemd الفعلي لديك إذا كان مختلفًا. أعد تحميل أو تشغيل العملاء المتأثرين؛ يتم تحديث إعدادات TURN الخاصة بـ Synapse بشكل دوري، لذلك قد لا يرى العميل التغيير على الفور.

هل يجب عليك تفعيل خيار TURN عبر بروتوكول TLS؟

ابدأ بتفعيل بروتوكول UDP/TCP TURN على المنفذ 3478 وتأكد من عمل خادم الترحيل المُرشّح. أضف TURN عبر TLS فقط إذا كانت شبكات المستخدمين بحاجة إليه، مثل جدران الحماية المؤسسية التي تسمح بحركة مرور شبيهة بـ TLS ولكنها تحظر UDP العادي. يُوسّع TLS نطاق الاتصال، ولكنه يُضيف تجديد الشهادات، ومستمعًا إضافيًا، وفحوصات توافق العميل.

هناك تحذير خاص بـ Matrix: يحذر دليل Synapse Coturn الحالي من أن بروتوكول TLS/DTLS مع شهادات Let's Encrypt لا يعمل مع عملاء Matrix الذين يستخدمون مكتبة WebRTC الخاصة بـ Chromium، بما في ذلك Element Android وiOS كما هو مذكور في ذلك الدليل. تحقق من توافق إصدارات عميلك قبل نشر عنوان URI لبروتوكول TLS. يوصي الدليل نفسه بإعداد الخدمة الأساسية أولاً ثم إضافة TLS/DTLS لاحقاً.

5. تحقق من بيانات الاعتماد واختبرها من شبكة خارجية

تحقق أولاً من أن برنامج Coturn يعمل، ثم راجع سجلاته:

sudo systemctl status coturn
sudo journalctl -u coturn -f

بعد ذلك، من خلال جلسة عميل Matrix موثقة، افحص الطلب المُرسل إلى نقطة نهاية واجهة برمجة تطبيقات العميل والخادم الحالية في Synapse /_matrix/client/v3/voip/turnServer. يجب أن تتضمن الاستجابة الناجحة اسم المستخدم وكلمة المرور ومدة الصلاحية وعنوان TURN URI الذي قمتَ بتكوينه. لا تُشارك هذه الاستجابة علنًا؛ فهذه البيانات عبارة عن رموز وصول مؤقتة لخادم الترحيل الخاص بك.

استخدم نموذج WebRTC Trickle ICE الرسمي للاختبار باستخدام اسم المستخدم وكلمة المرور المُسترجعة من Synapse. أضف عنوان TURN URI وبيانات الاعتماد، وشغّل اختبار جمع بيانات ICE، وابحث عن مرشح من نوعه STUN relay. قد يُظهر خادم يستجيب فقط لـ STUN مرشحًا من نوع الخادم الانعكاسي، ولكنه قد يفشل في نقل الوسائط. اختبر من اتصال جوال أو شبكة خارج شبكتك المحلية، ثم أجرِ مكالمة فعلية بين مشاركين على شبكات مختلفة.

تشخيص الأعطال الشائعة

• لم تظهر بيانات اعتماد TURN: تأكد من أن Synapse قد حمّل الإعدادات الصحيحة، وأُعيد تشغيله بنجاح، وأن السر المشترك مُعيّن. افحص استجابة الطلب بحثًا عن /voip/turnServer...
• تظهر بيانات الاعتماد ولكن لا توجد نماذج مرشحة للترحيل: تحقق من TCP/UDP 3478، واسم المضيف المعلن عنه، ومطابقة السر، وسجلات Coturn، ونطاق ترحيل UDP من خلال كل جدار حماية.
• تعمل المكالمات على شبكة محلية واحدة، لكنها تفشل عبر الشبكات الأخرى: فحص external-ip، وإعادة توجيه المنافذ، ومسار العودة. يجب على Coturn الإعلان عن العنوان العام الذي يمكن للعملاء الوصول إليه.
• يتم الاتصال فقط عند تعطيل TLS: تأكد من سلسلة الشهادات، ومستمع TLS، turns:وURI المعلن عنه، والتوافق الخاص بالعميل.
• تعمل المكالمات التقليدية، لكن مكالمة Element لا تعمل: تحقق من إعدادات نقل MatrixRTC/LiveKit بشكل منفصل. لا يُعد اختبار Coturn الناجح دليلاً على التحقق من خدمة ترخيص LiveKit SFU أو MatrixRTC.

بالنسبة لعملاء المتصفح، يمكن لتشخيصات WebRTC في المتصفح إظهار ما إذا كانت الوسائط قد اختارت مرشحًا للترحيل. بالنسبة لـ MatrixRTC، تحقق من أن Synapse ينشر نقطة نهاية النقل وأن مسارات LiveKit WebSocket والتفويض قابلة للوصول. اختبر كلاً من نقطة النهاية الحالية وأي آلية اكتشاف احتياطية موثقة مطلوبة من قبل العملاء الذين تدعمهم.

مراجع التكوين

• سينابس: تهيئة خادم TURN
• Synapse: تثبيت Coturn، والأمان، وNAT، وتكوين TLS
• مرجع تكوين Synapse لـ TURN و MatrixRTC
• مثال ملف turnserver.conf الرسمي من Coturn
• دليل استضافة MatrixRTC ذاتيًا: مكالمة العناصر
• نشر LiveKit وتكوين TURN
• تحديث من Matrix.org حول اكتشاف النقل في Element Call 0.24
• مواصفات واجهة برمجة تطبيقات Matrix Client-Server، بما في ذلك نقطة نهاية بيانات اعتماد TURN