تكامل LiveKit

يستخدم Bedrud LiveKit للتعامل مع اتصالات الفيديو والصوت في الوقت الفعلي. يوفر LiveKit خادم وسائط SFU (وحدة التوجيه الانتقائي)، ويتعامل Bedrud مع المصادقة وإدارة الغرف وضوابط المشرفين.

مدمج مقابل خارجي

يدعم Bedrud وضعين لنشر LiveKit:

١. الوضع المدمج (الافتراضي): تبدأ الخلفية وتدير عملية خادم LiveKit داخليًا. لا حاجة لبنية تحتية إضافية - تتعامل الخلفية مع دورة حياة عملية LiveKit. ٢. الوضع الخارجي: يتصل Bedrud بخادم LiveKit منفصل أو مجموعة. هذا مفيد للتوسع الأفقي أو عند استخدام مثيل LiveKit Cloud مُدار.

تهيئة الوضع الخارجي

لاستخدام خادم LiveKit خارجي، اضبط المفاتيح التالية في config.yaml:

livekit:
  host: "wss://livekit.example.com:7880"    # Client WebSocket URL (ws:// or wss://)
  internalHost: "https://livekit.example.com:7880"  # Server-to-server API URL
  apiKey: "your-api-key"
  apiSecret: "your-api-secret"
  external: true          # Skip embedded LiveKit startup
  skipTLSVerify: false    # Set true if LiveKit uses self-signed certs

عندما يكون embedded بقيمة false، يتخطى Bedrud بدء تشغيل ملف LiveKit الثنائي المدمج. يجب أن تتطابق مفتاح API والسر مع بيانات اعتماد الخادم الخارجي.

لإعداد وتحويم مجموعة LiveKit، راجع توثيق LiveKit.

تكوين Webhook (خارجي فقط)

عند استخدام خادم LiveKit خارجي، يجب عليك تكوين webhooks حتى يتمكن LiveKit من إعلام Bedrud بانفصال المشاركين وإغلاق الغرف. بدون webhooks، ستصبح حالة قاعدة البيانات قديمة.

نقطة النهاية: https://<your-domain>/api/livekit/webhook

المصادقة: تستخدم توقيع JWT الخاص بـ LiveKit — نفس apiKey/apiSecret الذي قمت بتكوينه أعلاه. لا حاجة لسر منفصل.

LiveKit Cloud: الإعدادات ← Webhooks ← إنشاء webhook جديد. أدخل URL نقطة النهاية واختر مفتاح API الخاص بك.

LiveKit مستضاف ذاتياً: أضف إلى تهيئة YAML الخاصة بـ LiveKit (مثال livekit.yaml):

webhook:
  urls: ["https://bedrud.example.com/api/livekit/webhook"]
  api_key: "your-api-key"

بدون webhook مهيأ بشكل صحيح، لن يتم تسليم أحداث participant_disconnected و room_finished إلى Bedrud. قد تظهر لوحة تحكم المشرف بيانات مشاركين قديمة، ولن يتم تنظيف الغرف تلقائياً.

توافق إصدار LiveKit

يقوم وضع LiveKit المدمج في Bedrud تلقائياً بإنشاء تهيئة متوافقة. ومع ذلك، إذا كنت تستضيف خادم LiveKit خارجي بنفسك، فكن على دراية بالتغييرات الجذرية عبر إصدارات LiveKit:

LiveKit v1.12+ أزال حقل tls من المستوى الأعلى من تهيئته. إذا كنت تستخدم tls: في YAML الخاص بـ LiveKit، فقم بإزالته. قم بتكوين http:// لـ internalHost و ws:// لـ host في تهيئة Bedrud. TURN TLS لا يزال مدعوماً تحت قسم turn:.
LiveKit v1.11 والإصدارات الأقدم تدعم tls: في المستوى الأعلى. استخدم https:// لـ internalHost و wss:// لـ host.

عند الشك، تحقق من إصدار خادم LiveKit الخاص بك باستخدام livekit-server --version واطلع على ملاحظات إصدار LiveKit.

إنشاء التهيئة المدمجة (Embedded Config Generation)

عند تفعيل TLS في الوضع المدمج، يُنشئ Bedrud ملف تهيئة YAML مؤقت لـ LiveKit (/tmp/bedrud-livekit-*.yaml) مع:

تفعيل TURN، وdomain مضبوط تلقائياً من server.host، وudp_port: 3478، وtls_port: 5349، وشهادة TLS للخادم مُعاد استخدامها لـ TURN/TLS
node_ip يُحل عبر livekit.nodeIP ← server.host ← كشف IP الصادر تلقائياً
bind_addresses محذوفة (LiveKit يربط جميع الواجهات افتراضياً)

يُحذف الملف المؤقت عند خروج عملية LiveKit. لتجاوز الإنشاء التلقائي بتهيئة ثابتة، اضبط livekit.configPath أو LIVEKIT_CONFIG_PATH.

كيف يعمل

١. إنشاء الغرفة

عندما ينشئ مستخدم غرفة في Bedrud، لا ينشئ الخادم غرفة LiveKit فورًا. تُنشأ غرف LiveKit عند الطلب عندما ينضم أول مشارك.

٢. رموز الانضمام

عندما ينضم مستخدم إلى اجتماع:

١. يُرسل الواجهة الأمامية طلبًا إلى /api/room/join. ٢. تتحقق الخلفية من أن المستخدم لديه إذن للانضمام إلى تلك الغرفة. ٣. تستخدم الخلفية مفتاح API وسرها لتوليد JWT مُوقَّع (رمز الانضمام). ٤. يحتوي الرمز على:

اسم الغرفة.
هوية المستخدم (اسم العرض).
الصلاحيات - على سبيل المثال، ما إذا كان يمكن للمستخدم نشر الصوت أو مشاركة شاشته. ٥. تتلقى الواجهة الأمامية هذا الرمز وتتصل مباشرة بمنفذ وسائط LiveKit (الافتراضي 7880).

٣. ضوابط الغرفة (المشرف)

تستخدم الخلفية LiveKit Go SDK لتنفيذ إجراءات إدارية:

طرد: يفصل مشاركًا.
كتم: يكتم صوت ميكروفون مشارك قسرًا.
الصلاحيات: يغيّر ما يمكن لمشارك فعله في الوقت الفعلي.

بنية الشبكة

منفذ API (8090/443): يتعامل مع طلبات HTTP وإشارات WebSocket لإعداد المكالمات.
منفذ الوسائط (7880): يتعامل مع بيانات الفيديو والصوت باستخدام بروتوكولات WebRTC. احتياطي ICE/TCP يستخدم المنفذ 7881 عندما يكون UDP محظورًا.
منفذ TURN (3478 UDP / 5349 TLS): يرحل الوسائط للعملاء خلف NATs أو جدران حماية مقيدة. راجع دليل خادم TURN.

لمتطلبات جدار الحماية والمنافذ، راجع اتصال WebRTC.

Troubleshooting

Startup & Config Crashes

Symptom	Cause	Fix
Container crash-loops, logs `could not resolve external IP`	`use_external_ip: true` without explicit `node_ip` in Docker	Set `node_ip: <lan-ip>` under `rtc:` and `use_external_ip: false`
LiveKit exits with `TURN domain required` on v1.12+	`turn.tls_port` is set but no `domain` or TLS cert/key	Add `domain:` under `turn:`, provide `cert_file`/`key_file`, or remove `tls_port` for UDP-only TURN
`field tls not found` on startup	LiveKit v1.12+ removed top-level `tls:` config field	Remove `tls:` block from LiveKit YAML; use `http://` / `ws://` in Bedrud config
`LIVEKIT_CONFIG` env var not picked up	Entrypoint doesn’t parse env var (pre-v1.7 or custom entrypoint)	LiveKit reads `LIVEKIT_CONFIG` natively since v1.7 — verify version; pass via `--config-body` only if needed
Docker: `--config-body` via `sh -c` fails with `flag provided but not defined: -c`	Image entrypoint is `/livekit-server` directly — `command` gets appended, not wrapped by shell	Don’t use a shell wrapper, `LIVEKIT_CONFIG` env var is supported natively by the binary
Docker Compose: `$LIVEKIT_CONFIG` expands to empty string	Compose substitutes `$VAR` from host environment, not container	Use `$$LIVEKIT_CONFIG` to escape docker-compose variable substitution
YAML parsing error from `LIVEKIT_CONFIG`	Incorrect YAML indentation or syntax	Validate: `docker run --rm -e LIVEKIT_CONFIG livekit-server --config-body "$LIVEKIT_CONFIG"`

Connectivity

Symptom	Cause	Fix
Admin dashboard shows “LiveKit disconnected”	Bedrud can’t reach LiveKit HTTP API	Verify `internalHost` in config; run `curl http://<internalHost>/` from Bedrud host; check firewall
Token generated but client connection times out	LiveKit WebSocket unreachable from browser	Check `host` in `livekit:` config (must be reachable by clients); verify DNS/firewall; test with `wscat`
Embedded LiveKit not starting	Missing binary or permission	Ensure `internal/livekit/bin/livekit-server` exists (even empty file for build); check Bedrud server logs
Port 7880 already in use	Another process on same port	Change `livekit.port` or use different Docker port mapping
Redis connection fails in LiveKit logs	Redis unreachable or wrong address	Verify `redis.address:` in LiveKit YAML; check container network connectivity
`curl http://127.0.0.1:7880` returns connection refused	LiveKit crashed during startup	Check `docker logs` / `journalctl`; look for RTC/TURN validation errors near the bottom of the log
Token expired before client connected	Short JWT validity window	Request a fresh token via `POST /api/room/join` before each connection attempt

Media & TURN

Symptom	Cause	Fix
Participants join but no audio/video	UDP port range blocked or wrong `node_ip`	Open UDP 50000-60000; verify `node_ip` is the externally reachable address
Clients behind NAT can’t connect	TURN not configured or ports blocked	Enable TURN; open UDP 3478 (and TCP 5349 for TLS); verify TURN domain resolves
`Could not resolve external IP` on startup (non-Docker)	No STUN internet access or DNS failure	Set explicit `node_ip` and `use_external_ip: false`
Self-signed cert errors with external LiveKit	Bedrud’s `skipTLSVerify` is `false`	Set `skipTLSVerify: true` in Bedrud’s `livekit:` config
Clients connect via relay unnecessarily	`node_ip` is a private IP behind NAT	Set `node_ip` to the public IP or use `use_external_ip: true` with STUN access
TURN relay not used by clients	Direct WebRTC path is working (expected)	Check `chrome://webrtc-internals` — `srflx` candidates = direct path, no TURN needed

Webhook & State

Symptom	Cause	Fix
Database shows stale active participants after disconnect	Webhook not configured for external LiveKit	Add `webhook:` block to LiveKit YAML with URL `https://<domain>/api/livekit/webhook`
Participants never marked inactive	Firewall blocking webhook delivery from LiveKit to Bedrud	Check LiveKit logs for webhook delivery errors; ensure port 443/8090 is reachable from LiveKit
Room not cleaned up after all leave	`empty_timeout` / `departure_timeout` too high	Reduce values in LiveKit YAML `room:` section

Recording (Egress)

Bedrud uses LiveKit’s RoomCompositeEgress API to record rooms as MP4 files.

Prerequisites

Redis — LiveKit egress requires Redis for coordinating egress workers. Without Redis, StartRoomCompositeEgress returns permission errors.

Egress S3 storage (external mode only) — For external LiveKit, you must configure an egress: section in your LiveKit YAML so recordings are stored to durable S3-compatible storage. Otherwise the FileURL is a local path unreachable from Bedrud.

egress:
  s3:
    access_key: "your-s3-access-key"
    secret_key: "your-s3-secret-key"
    endpoint: "http://minio:9000"
    bucket: "bedrud-recordings"
    region: "us-east-1"
    force_path_style: true

Troubleshooting: Recording

Symptom	Cause	Fix
`twirp error unauthenticated: permissions denied` when starting recording	Egress JWT missing `Room` field in grant	Update `egressAuthContext` to include `Room: roomName` in the `VideoGrant`
`twirp error unauthenticated: permissions denied` even with valid API key	Redis not configured for LiveKit, or egress workers unavailable	Add `redis:` section to LiveKit YAML; ensure Redis is healthy
Recording starts but `FileURL` is a local path (e.g., `/tmp/...`)	No `egress:` S3 config — LiveKit writes to worker temp dir	Add `egress.s3:` block to LiveKit YAML pointing to S3-compatible storage
`process_recording` job fails to download	External LK’s file URL points to inaccessible local path	Configure egress S3 so LiveKit produces S3 URLs

See also the TURN Server Guide for TURN-specific troubleshooting, WebRTC Connectivity for STUN/ICE/firewall debugging, and Installation Troubleshooting for port/perm/setup issues.

انظر أيضًا

دليل خادم TURN - بنية TURN والتهيئة و TLS واستكشاف الأخطاء
اتصال WebRTC - مكدس اتصال STUN/ICE/TURN/SFU الكامل
نظرة عامة على البنية - بنية النظام الكاملة