📡 تثبيت Homebridge — أدخل أي جهاز إلى Apple HomeKit

انشر Homebridge على Ubuntu باستخدام Docker — جسر يجعل الأجهزة الذكية غير المتوافقة مع HomeKit تعمل مع Apple Home وSiri، يعمل في وضع شبكة المضيف (host network) مع واجهة الإعداد على المنفذ 8581.

⚠️ راجع أي سكريبت دائمًا قبل تشغيله على سيرفرك، واختبره في بيئة تجريبية أولاً.

📦 الملفات والأكواد المطلوبة

قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.

سكريبت تثبيت آلي — أمر واحد ينشر Homebridge في وضع شبكة المضيف مع واجهة الإعداد على المنفذ 8581. وضع شبكة المضيف مطلوب حتى يتمكن HomeKit من اكتشافه عبر mDNS.
عرض على GitHub

التثبيت السريع:

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/iot/homebridge/homebridge-ubuntu.sh
chmod +x homebridge-ubuntu.sh
./homebridge-ubuntu.sh

خطوات التنفيذ

1 تحميل السكريبت

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/iot/homebridge/homebridge-ubuntu.sh

2 منحه صلاحية التنفيذ

chmod +x homebridge-ubuntu.sh

3 تشغيل المثبت

./homebridge-ubuntu.sh

4 فتح واجهة الإعداد وإنشاء حساب

http://your-server-ip:8581

المنافذ المستخدمة

المنفذالغرض
8581Homebridge config UI (host network mode; mDNS discovery requires it)

نظرة عامة

Homebridge سيرفر Node.js مجاني ومفتوح المصدر يُحاكي بروتوكول أجهزة HomeKit الخاص بآبل (HAP)، ويتيح للأجهزة الذكية التي لا تدعم HomeKit أصلاً أن تظهر داخل تطبيق Apple Home وتستجيب لـ Siri. بدلاً من انتظار الشركة المصنّعة لإضافة دعم HomeKit رسمي، يعتمد Homebridge على مجتمع إضافات (plugins) ضخم — آلاف الإضافات التي تغطي علامات تجارية مثل Xiaomi وTP-Link Kasa وTuya وSonoff وEcobee وRing — كل واحدة تترجم واجهة برمجة التطبيقات الخاصة بذلك الجهاز إلى أجهزة HomeKit. واجهة الويب Homebridge Config UI X تجعل تثبيت الإضافات وإدارة الإعدادات والاقتران مع Apple Home ممكناً بالكامل عبر المتصفح دون الحاجة لتحرير JSON يدوياً.

لماذا تستخدمه

يتعرف تطبيق Apple Home فقط على الأجهزة التي تأتي بدعم HomeKit رسمي، وهو ما يستبعد جزءاً كبيراً من أجهزة المنزل الذكي الاقتصادية والإقليمية، وخصوصاً الكثير من الأجهزة المباعة في الشرق الأوسط التي تدعم فقط تطبيقات الشركة المصنّعة الخاصة بها. يسدّ Homebridge هذه الفجوة: ثبّت الإضافة المجتمعية المطابقة لعلامة جهازك، فيظهر في Apple Home جنباً إلى جنب مع أجهزتك المعتمدة من HomeKit، قابلاً للتحكم الكامل عبر Siri وأتمتة HomeKit ومركز التحكم. إنه مجاني بالكامل، مفتوح المصدر برخصة Apache-2.0، ويعمل بالكامل على سيرفرك الخاص دون أي اعتماد على السحابة أو حساب لدى طرف ثالث سوى ما تحتاجه إضافة الجهاز نفسها.

متى تحتاجه

  • تملك أجهزة ذكية — مقابس، لمبات، مستشعرات، ثيرموستات — لا تدعم Apple HomeKit أصلاً
  • تريد التحكم بكل شيء عبر تطبيق Apple Home وSiri بدلاً من التنقل بين خمسة تطبيقات مختلفة لكل علامة تجارية
  • علامتك التجارية للمنزل الذكي تنشر تطبيقات فقط في مناطق أو أنظمة لا تشمل اعتماد HomeKit الرسمي
  • تريد دمج عدة علامات تجارية من الأجهزة ضمن أتمتة ومشاهد HomeKit موحدة
  • تُشغّل بالفعل Home Assistant أو مركزاً آخر وتريد عرض كياناته في Apple Home تحديداً
  • تحتاج جسراً ذاتي الاستضافة ومستقراً يستمر بالعمل حتى لو تعطلت خدمة سحابة الشركة المصنّعة

من يحتاجه

  • أسر بيئة Apple التي تريد أن يعمل كل جهاز ذكي مع Siri وتطبيق Home بغض النظر عن العلامة التجارية
  • عشاق المختبرات المنزلية والاستضافة الذاتية الذين يُشغّلون سيرفراً صغيراً بالفعل ويريدون إضافة التحكم بالمنزل الذكي إليه
  • المستخدمون في الشرق الأوسط ومناطق أخرى حيث تتجاوز الكثير من العلامات الاقتصادية للمنزل الذكي اعتماد HomeKit الرسمي
  • من يهاجرون من تطبيقات مقفلة بالعلامة التجارية مثل Tuya Smart أو Mi Home نحو واجهة تحكم موحدة واحدة
  • مستخدمو Home Assistant الذين يريدون ظهور أجهزة مركز الأتمتة الحالي لديهم في Apple Home أصلاً أيضاً
  • المستأجرون وأصحاب المنازل الذين يوحّدون المقابس واللمبات والكاميرات والمستشعرات من علامات مختلفة في واجهة واحدة

حالات الاستخدام الشائعة

  • جسر أجهزة Xiaomi Mi Home أو TP-Link Kasa أو Tuya/Smart Life أو Sonoff إلى Apple Home وSiri
  • التحكم بالثيرموستات الذكية والمقابس والمستشعرات من عدة علامات غير مدعومة عبر أتمتة HomeKit واحدة
  • تشغيل اختصارات Siri ومشاهد HomeKit لأجهزة كانت لتبقى حبيسة تطبيق الشركة المصنّعة الخاص بها
  • جسر كيانات نسخة Home Assistant إلى HomeKit بحيث يظهر كل شيء في تطبيق Apple Home أيضاً
  • إضافة بث كاميرات IP غير معتمدة من HomeKit إلى تطبيق Home عبر إضافة كاميرا مخصصة
  • أتمتة الإضاءة والمفاتيح باستخدام تحديد الموقع الجغرافي والأتمتة الزمنية في تطبيق Apple Home بغض النظر عن العلامة التجارية

الميزات الرئيسية

  • آلاف الإضافات المجتمعية التي تغطي تقريباً كل علامة تجارية وبروتوكول رئيسي للمنزل الذكي
  • Homebridge Config UI X — واجهة ويب كاملة لتثبيت الإضافات وتحرير الإعدادات ومراقبة السجلات
  • جسور فرعية (Child Bridges) لعزل الإضافات كل على حدة بحيث لا تُسقط إضافة غير مستقرة الجسر بأكمله
  • نسخ احتياطي واستعادة مدمجان لكامل إعداداتك والإضافات المثبتة من واجهة الويب
  • اقتران عبر رمز QR ورمز PIN متوافق مباشرة مع تدفق 'إضافة جهاز' القياسي في Apple Home
  • بحث عن الإضافات وتثبيت بنقرة واحدة وإدارة التحديثات دون لمس سطر الأوامر
  • وصول للطرفية (Terminal) وبث مباشر للسجلات من داخل واجهة الويب لتصحيح مشكلات الإضافات
  • دعم للملحقات (Accessories) والمنصات (Platforms) وإضافات المنصات الديناميكية التي تغطي الإضاءة والأقفال والمستشعرات والكاميرات والمزيد

كيفية الاستخدام بعد التثبيت

  • افتح واجهة الإعداد على http://your-server-ip:8581 وأنشئ حساب المسؤول عند أول زيارة
  • استخدم تبويب Plugins للبحث عن وتثبيت الإضافة المطابقة لعلامة جهازك (مثل homebridge-tuya أو homebridge-kasa)
  • اضبط كل إضافة ببيانات اعتماد جهازك أو رموز API المحلية عبر نموذج الإعدادات في الواجهة
  • أعد تشغيل Homebridge من الواجهة بعد تثبيت أو ضبط إضافة حتى يلتقط الأجهزة الجديدة
  • افتح تطبيق Apple Home، اضغط على إضافة جهاز، وامسح رمز اقتران HomeKit الظاهر في واجهة Homebridge أو السجلات
  • انقل الإضافات المعرضة للتعطل إلى جسر فرعي خاص بها تحت Settings لحماية بقية إعدادك
  • نظّم الأجهزة المجسورة حديثاً ضمن غرف وأضفها إلى مشاهد وأتمتة HomeKit الحالية
  • تحقق من صفحة حالة Homebridge دورياً للتأكد أن كل الإضافات المضبوطة تُظهر حالة سليمة

أفضل ممارسات الأمان

  • لا تكشف المنفذ 8581 مباشرة للإنترنت أبداً — فهو يمنح تحكماً كاملاً بأجهزتك الذكية وسيرفرك
  • عيّن كلمة مرور قوية لحساب مسؤول واجهة الإعداد فور تسجيل الدخول الأول
  • قيّد الوصول عن بُعد على VPN مثل WireGuard بدلاً من وكيل عكسي عام، لأن واجهة الإعداد لا تملك مصادقة ثنائية مدمجة افتراضياً في كل الإعدادات
  • حدّث Homebridge وكل الإضافات المثبتة بانتظام — الإضافات يصونها المجتمع وتصدر إصلاحات الأمان كإصدارات جديدة
  • ثبّت الإضافات فقط من سجل Homebridge الرسمي أو مصدر GitHub موثّق — الإضافات من طرف ثالث تعمل بصلاحية كاملة على السيرفر
  • راجع أي الإضافات تطلب بيانات اعتماد سحابية (رموز حساب لدى الشركة المصنّعة) وافهم أي بيانات تغادر شبكتك
  • اعزل الإضافات غير المستقرة أو الأقل ثقة في جسر فرعي خاص بها بحيث يكون نطاق تأثير أي اختراق أصغر

المنافذ وإعدادات جدار الحماية

تستمع واجهة Homebridge Config UI X على المنفذ 8581 لواجهة الويب. ولأن Apple HomeKit يكتشف الجسور باستخدام بث mDNS/Bonjour المتعدد، ولا تُمرر شبكة Docker الجسرية الافتراضية حركة البث المتعدد إلى شبكة المضيف، يجب أن تعمل حاوية Homebridge في وضع شبكة المضيف (host network mode) — أي أنها تشارك مكدس شبكة المضيف مباشرة بدلاً من العزل خلف الجسر الافتراضي لـ Docker. هذا يعني أن Homebridge لا ينشر منافذ الحاوية بالطريقة المعتادة؛ بل أي منفذ يربطه العملية (8581 للواجهة، بالإضافة لأي منافذ تستخدمها إضافات ملحقات معينة للكاميرات أو خدمات أخرى) يُكشف مباشرة على المضيف. لا تكشف المنفذ 8581 أبداً للإنترنت العام — قيّد الوصول على شبكتك المحلية أو VPN، لأنه يمنح تحكماً إدارياً كاملاً في إعداد منزلك الذكي.

النسخ الاحتياطي والصيانة

  • استخدم ميزة النسخ الاحتياطي المدمجة في واجهة الإعداد (Settings → Backup) لتنزيل لقطة كاملة من إعداداتك والإضافات المثبتة
  • خزّن أرشيفات النسخ الاحتياطي خارج السيرفر، لأنها قد تحتوي بيانات اعتماد الأجهزة ورموز API لحساباتك الذكية
  • انسخ دليل تخزين Homebridge احتياطياً (config.json ومجلد persist وبيانات الإضافات) مباشرة إذا كنت تفضّل نسخاً احتياطياً على مستوى الملفات
  • وثّق الإضافات المثبتة وإصداراتها في حال احتجت لإعادة تثبيتها يدوياً بعد عطل
  • اختبر استعادة نسخة احتياطية على جهاز أو VM احتياطي دورياً للتأكد أن العملية تعمل فعلاً قبل أن تحتاجها
  • أعد الاقتران مع Apple Home بعد استعادة كاملة إذا تغيّرت هوية الجسر (اسم المستخدم/PIN) أثناء الاستعادة

الأخطاء الشائعة

  • تشغيل Homebridge في وضع شبكة Docker الجسرية الافتراضية، ما يُعطّل اكتشاف mDNS الخاص بـ HomeKit بصمت
  • كشف المنفذ 8581 للإنترنت دون VPN، ما يمنح أي شخص يجده تحكماً كاملاً بمنزلك الذكي
  • تثبيت إضافات من مصادر غير رسمية أو غير موثّقة تطلب صلاحيات مفرطة أو بيانات اعتماد الأجهزة
  • ترك كلمة مرور المسؤول الافتراضية دون تغيير بعد تسجيل الدخول الأول
  • حشر عشرات الإضافات غير المستقرة في الجسر الرئيسي بدلاً من عزل الخطيرة منها في جسور فرعية
  • نسيان أن المضيف وحاوية Docker يجب أن يكونا على نفس الشبكة الفرعية LAN مثل الهاتف الذي يُشغّل تطبيق Home
  • عدم إعادة تشغيل Homebridge بعد تغيير إعدادات إضافة، فلا تُطبَّق الإعدادات الجديدة أبداً
  • تخطي نسخ الإعدادات وبيانات persist احتياطياً، ما يفرض إعادة اقتران كل جهاز من جديد بعد أي عطل

استكشاف الأخطاء وإصلاحها

  • تطبيق Home لا يجد الجسر — تأكد أن Homebridge يعمل في وضع شبكة المضيف وليس شبكة Docker الجسرية الافتراضية
  • فشل الاقتران أو انتهاء المهلة — تأكد أن الهاتف الذي يُشغّل تطبيق Home على نفس الشبكة المحلية/الشبكة الفرعية لمضيف Homebridge
  • إضافة تُسقط الجسر بأكمله بشكل متكرر — انقلها إلى جسر فرعي خاص بها تحت Settings حتى تفشل بمعزل عن الباقي
  • الأجهزة تظهر بحالة 'لا استجابة' في Apple Home — تحقق من سجل الإضافة في واجهة الإعداد بحثاً عن أخطاء مصادقة أو اتصال بالجهاز أو واجهة API السحابية الخاصة به
  • لا يمكن تسجيل الدخول لواجهة الإعداد — تحقق أن المنفذ 8581 قابل للوصول وغير محظور بجدار حماية المضيف، ثم أعد ضبط كلمة مرور المسؤول عبر سطر الأوامر إذا لزم
  • التغييرات في config.json لا تُطبَّق — أعد تشغيل خدمة أو حاوية Homebridge بعد أي تعديل يدوي في الإعدادات
  • تعارض عدة جسور على الشبكة — تأكد أن كل نسخة Homebridge وجسر فرعي يستخدم اسم مستخدم فريداً (بنمط MAC) ومنفذاً فريداً
  • فشل بث إضافات الكاميرات — تحقق أن منافذ البث المطلوبة قابلة للوصول أيضاً ضمن إعداد وضع شبكة المضيف

البدائل

Home Assistant منصة أتمتة منزلية كاملة بلوحات تحكم خاصة بها ومئات التكاملات الأصلية وتكامل HomeKit Bridge مدمج — أقوى بكثير من Homebridge لكنه أثقل بكثير للتشغيل وأصعب في التعلم. Hoobs واجهة أمامية أكثر سهولة ونضجاً مبنية فوق Homebridge مع فئة Pro مدفوعة لمزيد من الراحة، موجهة للمستخدمين الأقل تقنية. openHAB منصة أتمتة كاملة أخرى بدعم HomeKit عبر إضافة، وهي أيضاً أثقل من Homebridge وحده. إذا كان هدفك الوحيد هو جعل الأجهزة غير المدعومة من HomeKit تظهر في Apple Home بأقل قدر من التعقيد، يبقى Homebridge الخيار الأخف والأكثر تركيزاً ودعماً على نطاق واسع.

متى لا تستخدمه

إذا احتجت منصة أتمتة منزلية كاملة بمحرك قواعد ولوحات تحكم ومئات التكاملات بخلاف HomeKit، فإن Home Assistant أساس أفضل — ويمكنك جسره إلى HomeKit لاحقاً إذا لزم. إذا كنت لا تستخدم أجهزة Apple إطلاقاً، فلا فائدة من Homebridge، لأن مهمته الكاملة هي عرض الأجهزة على Apple HomeKit وSiri. إذا كانت أجهزتك الذكية تأتي بدعم HomeKit رسمي بالفعل، فأنت لا تحتاج Homebridge لها إطلاقاً — فقط أضفها مباشرة في تطبيق Home. وإذا لم تكن مرتاحاً لتشغيل وضع شبكة المضيف على سيرفرك (الذي يكشف الحاوية بالكامل لشبكة المضيف)، ففكّر بتشغيل Homebridge على جهاز مخصص يعمل باستمرار مثل Raspberry Pi بدلاً من سيرفر مشترك متعدد الخدمات.

هل تحتاج مساعدة احترافية؟

توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.

  • التثبيت وتجهيز السيرفر
  • الإعداد المتقدم وإعداد التوجيه
  • تصليب الأمان وتحسين جدار الحماية
  • إعداد شهادات SSL/TLS مع Let's Encrypt
  • ربط النطاق المخصص والوكيل العكسي
  • جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
  • المراقبة الفورية وتنبيهات الجاهزية
  • الترحيل من المنصات القائمة
  • استكشاف مشكلات الاتصال والأداء وإصلاحها
  • سكريبتات أتمتة مخصصة وعقود دعم مستمر
تواصل مع PrismaTechWork

الأسئلة الشائعة

ما هو Homebridge؟

Homebridge جسر يجعل أجهزة المنزل الذكي التي لا تدعم Apple HomeKit تظهر في تطبيق Apple Home وتستجيب لـ Siri.

لماذا يحتاج وضع شبكة المضيف؟

لأن HomeKit يكتشف الجسور باستخدام mDNS (بروتوكول Bonjour من آبل)، وبث mDNS المتعدد لا يعمل عبر شبكة Docker الجسرية الافتراضية — فتبقى الحاوية الجسرية غير مرئية لتطبيق Home. تشغيل Homebridge في وضع شبكة المضيف يتيح له مشاركة شبكة المضيف حتى يعمل الاكتشاف.

على أي منفذ تعمل الواجهة؟

واجهة إعداد Homebridge على الويب تعمل على المنفذ 8581. ولأن الحاوية تستخدم شبكة المضيف، يُقدَّم هذا المنفذ مباشرة على المضيف. افتح http://your-server:8581 لإنشاء حساب المسؤول وإدارة الإضافات.

كيف أُضيف جهازاً إلى Apple Home؟

ثبّت واضبط أولاً الإضافة المناسبة في واجهة Homebridge لنوع جهازك. ثم افتح تطبيق Apple Home، اختر إضافة جهاز، وامسح رمز اقتران HomeKit الظاهر في واجهة Homebridge. بعد الاقتران، يظهر الجسر وأجهزته في Home ويستجيبون لـ Siri.

كيف يُقارَن بـ Home Assistant؟

Home Assistant منصة أتمتة كاملة بمئات التكاملات ولوحات تحكم خاصة بها، أقوى بكثير لكنه أثقل بكثير. Homebridge مُركّز: مهمته الوحيدة هي جعل الأجهزة غير المدعومة من HomeKit تظهر في Apple Home.