تشرح هذه الدليل كيفية ربط إضافة Voice في Discourse بخادم وسائط LiveKit. افتراضيًا، تعمل المكالمات الصوتية بنمط طرف-إلى-طرف (Peer-to-Peer): حيث يرسل كل مشارك صوته مباشرةً إلى جميع المشاركين الآخرين. يعمل هذا بشكل ممتاز للغرف الصغيرة، لكن عرض النطاق الترددي (Bandwidth) يزداد مع حجم الغرفة. توجيه المكالمات عبر LiveKit يحافظ على ثبات معدل رفع البيانات لكل مشارك بغض النظر عن عدد الأشخاص الذين ينضمون.
المتطلبات المسبقة
قبل أن تبدأ، تأكد من توفر ما يلي:
- موقع Discourse يعمل مع تمكين إضافة Voice.
- خادم LiveKit يمكنك الوصول إليه، مع بيانات اعتماد API الخاصة به. يمكنك استضافة LiveKit ذاتيًا أو استخدام خدمة مُدارة مثل LiveKit Cloud.
- وصول المسؤول (Admin) إلى موقع Discourse الخاص بك.
الخطوة 1 — تمكين إضافة Voice
تأتي إضافة Voice مدمجة مع Discourse. انتقل إلى الإدارة → الإعدادات → الإضافات وقم بتفعيل إعداد Voice (voice_enabled).
الخطوة 2 — تجهيز خادم LiveKit وتدوين بيانات الاعتماد
تحتاج إلى ثلاثة أشياء من نشر LiveKit الخاص بك: عنوان WebSocket، مفتاح API، وسر API.
هذه الخطوات بسيطة نسبيًا مع LiveKit Cloud:
- أنشئ مشروعًا في لوحة تحكم LiveKit Cloud.
- من صفحة الإعدادات → المفاتيح الخاصة بالمشروع، اعرض مفتاح API وسر API.
- دوّن عنوان WebSocket (على سبيل المثال
wss://my-project.livekit.cloud).
لنسخ LiveKit المستضافة ذاتيًا، يُرجى الرجوع إلى الوثائق الرسمية الخاصة بها.
الخطوة 3 — تكوين اتصال LiveKit في Discourse
انتقل إلى الإدارة → الإضافات → Voice، افتح الإعدادات واملأ قسم LiveKit:
| الإعداد | ما يجب إدخاله |
|---|---|
voice_livekit_url |
عنوان WebSocket، مثل wss://livekit.example.com (أو ws:// لبيئات الاختبار التي تستخدم HTTP العادي). |
voice_livekit_api_key |
مفتاح API من الخطوة 2. |
voice_livekit_api_secret |
سر API من الخطوة 2. |
voice_livekit_room_policy |
أي الغرف التي تستخدم LiveKit. |
يحدد إعداد voice_livekit_room_policy كيفية اختيار الغرف لنقل البيانات:
| السياسة | السلوك |
|---|---|
disabled |
تعمل جميع المكالمات بنمط طرف-إلى-طرف (وهو الوضع الافتراضي). |
per_room |
يختار منشئو/مديرو الغرف تفعيل الغرف بشكل فردي عبر مربع اختيار استخدام خادم وسائط (SFU) في نموذج الغرفة. |
all_rooms |
يتم توجيه كل الغرف عبر LiveKit. |
الخطوة 5 — إعدادات إضافية اختيارية
تقوم هذه الإعدادات بضبط التكامل بدقة:
| الإعداد | الغرض |
|---|---|
voice_livekit_room_prefix |
بادئة مساحة الأسماء (Namespace) لأسماء الغرف في LiveKit. عند مشاركة خادم LiveKit واحد بين عدة مواقع، اضبط بادئة فريدة لكل موقع. القيمة الافتراضية فارغة وتعني استخدام اسم قاعدة البيانات للموقع. |
voice_livekit_mesh_fallback |
عندما لا يمكن إصدار رمز (Token) لـ LiveKit والغرفة فارغة، ابدأ على شبكة الطرف-إلى-طرف بدلاً من فشل الانضمام. غير مفعلة افتراضيًا — فقد تخفي التدهور الصامت انقطاع LiveKit. |
voice_livekit_recording_enabled |
السماح لمديري الغرف بتسجيل المكالمات التي تعمل على LiveKit. يتم إنتاج التسجيلات بواسطة LiveKit Egress وتخزينها على وحدة تخزين نشر LiveKit الخاص بك (S3، GCS، القرص المحلي) — ولا يتم رفعها إلى Discourse. |
voice_livekit_recording_filepath |
مسار الملف المُمرر إلى LiveKit Egress، مثل voice/{room_name}-{utc}. يدعم مكانيات مثل {room_name}، {room_id}، {time}، {utc}؛ يتم إضافة امتداد الملف تلقائيًا. |
الخطوة 6 — اختياري: تفعيل Webhooks لـ LiveKit
Webhooks هي خط دفاع أخير للمصالحة (Reconcile) فقط. عندما ينقطع اتصال مشارك بشكل مفاجئ أو تنتهي الغرفة، تتيح Webhooks للإضافة تنظيف حالة الحضور وحالة الغرفة خلال ثوانٍ بدلاً من الانتظار حتى انتهاء صلاحية نبض القلب (Heartbeat TTL). هي اختيارية — إذا تعذر تسليمها، ستعمل المكالمات بشكل طبيعي، لكن التنظيف سيستغرق وقتًا أطول قليلاً.
على خادم LiveKit، أضف نقطة نهاية Webhook (تعرض الإضافة المقطع الدقيق على لوحة تحكم المسؤول حتى يصل أول Webhook):
# livekit.yaml
webhook:
api_key: <your-api-key>
urls:
- https://forum.example.com/voice/livekit/webhook
أعد تشغيل LiveKit. يتم مصادقة التسليمات باستخدام سر API — لا حاجة لإعداد سر مشترك إضافي.
الخطوة 7 — التحقق من التكامل
فحص لوحة تحكم Discourse Voice
انتقل إلى الإدارة → الإضافات → Voice → لوحة التحكم. بمجرد وجود أي إعداد لـ LiveKit، تعرض لوحة التحكم بطاقة حالة خادم وسائط LiveKit مع فحوصات حية:
- حالة التكوين (أي الإعدادات موجودة والسياسة النشطة)،
- ما إذا كان يمكن توقيع رموز الوصول (Access Tokens) باستخدام زوج المفاتيح،
- ما إذا كان الخادم قابلاً للوصول وكم عدد الغرف النشطة،
- آخر فحص تلقائي للاتصال،
- ما إذا كانت Webhooks يتم استلامها.
استخدم تحديث (Refresh) لتنفيذ استعلام فوري عند الطلب.
إليك لقطة شاشة للوحة تحكم إضافة Voice مع تفعيل LiveKit:
فحص لوحة تحكم LiveKit
توجد تفاصيل عن المكالمات أيضًا على لوحة تحكم LiveKit. إليك مثالاً:
