💡 تثبيت Z-Wave JS UI — لوحة التحكم وبوابة شبكات Z-Wave الذكية على Docker
نشر منصة Z-Wave JS UI على Ubuntu باستخدام Docker — لوحة التحكم البصرية وإدارة الشبكة المشبكية وبوابة MQTT والربط مع Home Assistant لأجهزة Z-Wave على المنافذ 8230 و3005.
📦 الملفات والأكواد المطلوبة
قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.
التثبيت السريع:
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/iot/zwave-js-ui/zwave-js-ui-ubuntu.sh
chmod +x zwave-js-ui-ubuntu.sh
sudo bash zwave-js-ui-ubuntu.sh
خطوات التنفيذ
1 تحميل السكريبت
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/iot/zwave-js-ui/zwave-js-ui-ubuntu.sh
2 منح صلاحية التنفيذ
chmod +x zwave-js-ui-ubuntu.sh
3 تشغيل المثبت
يقوم السكريبت بتثبيت Docker وتحديد مسار دونجل الـ USB التسلسلي لـ Z-Wave (`/dev/serial/by-id/*`) وتجهيز مجلد التخزين الدائم (`./store`) وتشغيل Z-Wave JS UI على المنفذ 8230 (لوحة الويب) والمنفذ 3005 (خادم WebSockets لهوم أسيستانت).
sudo bash zwave-js-ui-ubuntu.sh
4 تهيئة مفاتيح الأمان وإقران الأجهزة
افتح متصفحك على الرابط http://ip-سيرفرك:8230. أدخل مفاتيح الأمان التشفيرية S0 وS2، واختر مسار دونجل الـ USB، وابدأ في إقران الأقفال الذكية والمخفتات والحساسات بسهولة.
http://<your-server-ip>:8230
المنافذ المستخدمة
| المنفذ | الغرض |
|---|---|
| 8230 | Web control panel (host → container 8091) |
| 3005 | WebSocket server (host → container 3000) — connect Home Assistant here |
| USB stick | Manual: edit compose to map your /dev/serial/by-id device |
نظرة عامة
تعد Z-Wave JS UI (المعروفة سابقاً باسم Zwave2Mqtt) لوحة تحكم وبوابة ويب بصرية شاملة ومفتوحة المصدر تم بناؤها بالاعتماد على محرك Z-Wave JS الرسمي الحديث. تعمل المنصة عبر واجهة الويب على المنفذ 8230 وخادم WebSockets على المنفذ 3005 مع تمرير دونجل الـ USB التسلسلي، لتوفر منظومة تحكم متكاملة لشبكات Z-Wave الذكية. وتتضمن خريطة طبولوجيا بصرية للشبكة المشبكية، ومحرراً لإعدادات ومعاملات الأجهزة، وبوابة MQTT مباشرة، وتحديثات البرامج الثابتة اللاسلكية (OTA)، وإدارة مفاتيح الأمان S2، والتكامل الأصلي مع Home Assistant.
لماذا تستخدمه
تقيد البوابات التجارية (مثل SmartThings وFibaro وVera) أجهزتك بالسحابات المغلقة، وتقدم أدوات تشخيص ضعيفة، مع استجابة بطيئة للأوامر المحلية. تمنحك Z-Wave JS UI قوة تحكم محلية 100%: إدارة أجهزة Z-Wave من الجيلين 700 و800 باستجابة فائقة السرعة في أجزاء من الثانية، وفحص مسارات الإشارة المشبكية بصرياً، وتحديث برامج الأجهزة لاسلكياً، مع ربط مباشر ومستقر بنظام Home Assistant عبر الـ WebSockets السريعة.
متى تحتاجه
- لديك أجهزة منزل ذكي تعمل ببروتوكول Z-Wave (أقفال أبواب ذكية، ومخفتات، وترموستات، وحساسات) وتريد لوحة تحكم بصرية
- تريد تشغيل محرك Z-Wave JS الرسمي فائق الأداء كحاوية مستقلة لربطها بنظام Home Assistant
- تريد بوابة MQTT مفتوحة المصدر تنشر حالات وحساسات أجهزة Z-Wave مباشرة لوسيط MQTT
- تحتاج لخريطة شبكة مشبكية بصرية تفاعلية لفحص مسارات التوجيه وقوة الإشارة وجودة الاتصال
- تريد إقران أجهزة أمنية عالية الحماية (مثل أقفال Schlage وYale) باستخدام تشفير S2 ومسح الـ QR عبر SmartStart
من يحتاجه
- مستخدمو Home Assistant الراغبون في تشغيل شبكة Z-Wave احترافية وسريعة على سيرفراتهم الخاصة
- أصحاب السيرفرات المنزلية لربط أقفال الأبواب الذكية، وبوابات الكراج، وصفارات الإنذار بأمان تام
- مهندسو وفنيو المنازل الذكية لفحص صحة الإشارة وضبط معاملات الهاردوير المتقدمة
- مطورو إنترنت الأشياء (IoT) للتفاعل مع أجهزة Z-Wave عبر واجهات JSON-RPC WebSockets أو MQTT
- المهتمون بالخصوصية والأمان الذين يرفضون ربط أقفال أبواب منازلهم ببوابات وسحابات تجارية
حالات الاستخدام الشائعة
- ربط 40 مخفتاً ومفتاحاً وحساساً بتقنية Z-Wave بسرعة استجابة لحظية في أقل من أجزاء من الثانية
- إقران قفل باب Schlage الذكي بتشفير S2 Access Control عالي الأمان وإدارة الأرقام السرية (PINs) بصرياً
- استعراض خريطة الشبكة المشبكية الحية لتحديد الأجهزة الضعيفة وإصلاح مسارات التوجيه (Network Heal)
- تحديث البرامج الثابتة (OTA) لمفاتيح Zooz وFibaro لاسلكياً بضغطة زر واحدة من لوحة التحكم
- إرسال قراءات حساسات Z-Wave إلى Node-RED وهوم أسيستانت في نفس الوقت عبر WebSockets وMQTT
الميزات الرئيسية
- لوحة تحكم بصرية على المنفذ 8230: إدارة كاملة للعقد، وإعادة تسمية الكيانات، وتعديل المعاملات، والمجموعات
- خادم WebSockets لهوم أسيستانت على المنفذ 3005: تكامل أصلي واكتشاف تلقائي فوري مع Home Assistant
- خريطة طبولوجيا مشبكية بصرية: رسم تفاعلي مباشر يوضح الجيران ومسارات التوجيه وجودة الرابط اللاسلكي
- حماية S2 المتقدمة وSmartStart: دعم كامل لطبقات التشفير S0 وS2 Unauthenticated وS2 Authenticated وS2 Access
- تحديثات البرامج الثابتة اللاسلكية (OTA): رفع وتثبيت ملفات التحديثات الرسمية للأجهزة عبر الهواء بدون فكها
- بوابة MQTT مدمجة ومباشرة: نشر واستقبال حالات وأوامر Z-Wave عبر مواضيع MQTT القياسية
- نسخ واستعادة ذاكرة الدونجل (NVM Backup): أخذ نسخة احتياطية من ذاكرة قطعة USB بضغطة زر واحدة واستعادتها
- معمارية Docker Compose تجمع Z-Wave JS UI مع ربط مجلد `./store` ودونجل الـ USB
كيفية الاستخدام بعد التثبيت
- افتح المتصفح وانتقل إلى الرابط http://ip-سيرفرك:8230
- انتقل إلى Settings ← Z-Wave، واختر المنفذ التسلسلي لدونجل الـ USB (`/dev/serial/by-id/*`) وولّد مفاتيح S0/S2 عشوائية
- اضغط 'Save' وتأكد من تحول حالة المحرك للون الأخضر (Driver READY)
- اضغط 'Manage Nodes' ← 'Inclusion' واضبط أجهزتك الذكية في وضع الإقران لضمها للشبكة
- في Home Assistant، أضف تكامل Z-Wave وضع رابط خادم الـ WebSockets: `ws://ip-سيرفرك:3005`
- ضع واجهة Z-Wave JS UI خلف وكيل عكسي مشفر بـ HTTPS مع شهادة SSL صالحة
- أعد سكريبت نسخ احتياطي دوري لمجلد الإعدادات `./store`
أفضل ممارسات الأمان
- تنبيه أمني حاسم: احتفظ بنسخة من مفاتيح الأمان التشفيرية S0 وS2 في مدير كلمات مرور آمن
- لا تكشف لوحة التحكم على المنفذ 8230 للإنترنت العام نهائياً؛ واقصرها على شبكتك المحلية الموثوقة أو VPN
- احمِ مجلد البيانات `./store` المحتوي على قاعدة بيانات العقد ومفاتيح الأمان بصلاحيات نظام صارمة (`chmod 700`)
- في حال تفعيل وسيط MQTT، استخدم كلمة مرور قوية لمستخدم Mosquitto
- استخرج نسخة احتياطية من ذاكرة الدونجل (NVM Backup) دورياً من قائمة الإجراءات
- حدّث صورة الحاوية دورياً للحصول على أحدث ملفات تعريف الأجهزة الذكية المطروحة بالأسواق
المنافذ وإعدادات جدار الحماية
يقدم Z-Wave JS UI لوحة التحكم عبر منفذ TCP 8230 (المحول من منفذ 8091 الداخلي) وخادم الـ WebSockets الخاص بـ Home Assistant عبر منفذ TCP 3005 (المحول من 3000 الداخلي). اسمح بالمنفذين 8230 و3005 للشبكة المحلية (`ufw allow 8230/tcp && ufw allow 3005/tcp`). وفي الإنتاج، وجه حركة الويب عبر وكيل عكسي مشفر بـ SSL على المنفذ 443.
النسخ الاحتياطي والصيانة
- انسخ مجلد `./store` احتياطياً، والذي يحتوي على `settings.json` و`nodes.json` وكافة ملفات التكوين والكاش للأجهزة
- حمل ملف النسخ الاحتياطي لذاكرة الدونجل (ملف بصيغة `.bin`) من الواجهة (Actions ← NVM Management ← Backup)
- احتفظ بنسخة من ملف `docker-compose.yml` ومفاتيح تشفير S2
- أتمت النسخ الاحتياطي اليومي للمجلدات وارفعه إلى مساحة تخزين سحابية عبر restic أو rsync
الأخطاء الشائعة
- استخدام مسارات المنافذ العامة مثل `/dev/ttyUSB0` التي قد يتغير ترتيبها عند إعادة تشغيل السيرفر بدلاً من مسار `/dev/serial/by-id/*` الثابت
- فقدان مفاتيح الأمان S2 مما يجعل من المستحيل استعادة أو تشغيل أقفال الأبواب الذكية المشفرة عند إعادة التثبيت
- عدم ربط مجلد التخزين الدائم `./store`، مما يسبب مسح كاش الأجهزة وإعادة مقابلتها بالكامل عند تحديث الحاوية
- توصيل دونجل USB بمنافذ USB 3.0 مباشرة بدون كابل تمديد (مما يسبب تشويشاً كهرومغناطيسياً يضعف الإشارة)
- محاولة إقران الحساسات التي تعمل بالبطارية دون إيقاظها عدة مرات بالضغط على زر الإقران أثناء التهيئة الأولى
استكشاف الأخطاء وإصلاحها
- فشل إقلاع المحرك / خطأ المنفذ التسلسلي — تأكد من مسار دونجل الـ USB في `/dev/serial/by-id/*` وصلاحيات الوصول بالسيرفر
- فشل اتصال Home Assistant — تأكد من وضع رابط المنفذ 3005 في تكامل هوم أسيستانت (`ws://ip-سيرفرك:3005`) وليس منفذ 8230
- الأجهزة معلقة في حالة 'Interviewing' — أيقظ الحساسات التي تعمل بالبطارية يدوياً (بالضغط على زر الإقران مرة أو مرتين)
- عقد ميتة أو فقدان حزم الإشارة — قم بإجراء إصلاح للشبكة (Heal Network) من قائمة الإجراءات وأضف مفاتيح كهربائية لتقوية الإشارة
- رفض الاتصال بواجهة الويب — تأكد من عمل الحاوية بالأمر `docker compose ps` وافحص السجلات: `docker logs zwave-js-ui -f`
البدائل
إضافة Z-Wave JS الرسمية في Home Assistant OS. محرك OpenZWave القديم والملغى. البوابات التجارية مثل SmartThings وFibaro Home Center وHubitat Elevation.
متى لا تستخدمه
تجنب استخدام Z-Wave JS UI إذا كانت أجهزتك الذكية تعمل حصراً ببروتوكول زيجبي أو الواي فاي ولا تملك أي أجهزة Z-Wave (حيث صُممت Zigbee2MQTT لزيجبي؛ وESPHome للواي فاي). وإذا كنت تستخدم نظام Home Assistant OS بالكامل وتفضل تثبيت الإضافات الرسمية من المتجر بضغطة واحدة، فإن إضافة Z-Wave JS الرسمية مدمجة بالمتجر.
هل تحتاج مساعدة احترافية؟
توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.
- التثبيت وتجهيز السيرفر
- الإعداد المتقدم وإعداد التوجيه
- تصليب الأمان وتحسين جدار الحماية
- إعداد شهادات SSL/TLS مع Let's Encrypt
- ربط النطاق المخصص والوكيل العكسي
- جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
- المراقبة الفورية وتنبيهات الجاهزية
- الترحيل من المنصات القائمة
- استكشاف مشكلات الاتصال والأداء وإصلاحها
- سكريبتات أتمتة مخصصة وعقود دعم مستمر
الأسئلة الشائعة
ما الفرق بين المنفذ 8230 والمنفذ 3005 في Z-Wave JS UI؟
المنفذ 8230 يقدم لوحة التحكم البصرية عبر المتصفح حيث تقوم بضبط الإعدادات واستعراض خريطة الشبكة وإقران الأجهزة. بينما المنفذ 3005 يشغل خادم الـ WebSockets المخصص الذي يتصل به Home Assistant لمزامنة حالات الأجهزة والتحكم بها لحظياً.
ما هي أفضل قطع ودونجلات USB الموصى بها لـ Z-Wave JS UI؟
من أفضل القطع الموصى بها: دونجل Zooz 800 Series Stick (ZST39)، ودونجل Aeotec Z-Stick 7 (ZWA010)، وقطعة HomeSeer SmartStick+، وSilicon Labs UZB7.
لماذا تعد مفاتيح تشفير الأمان S2 بالغة الأهمية؟
تشفير S2 (Security 2) يحمي الأجهزة الحساسة (مثل أقفال الأبواب وبوابات الكراج وصفارات الإنذار) بتشفير AES-128 وتبادل مفاتيح Diffie-Hellman، مما يمنع هجمات التنصت وإعادة تشغيل الأوامر الخبيثة.
هل يمكن استخدام Z-Wave JS UI بدون Home Assistant عبر بروتوكول MQTT؟
نعم! تتضمن Z-Wave JS UI بوابة MQTT متكاملة. يمكنك تفعيل الـ MQTT في الإعدادات لنشر قراءات الحساسات وإرسال أوامر التحكم عبر مواضيع MQTT القياسية لمنصة Node-RED أو سكريبتاتك الخاصة.
كم يستهلك تطبيق Z-Wave JS UI من الذاكرة العشوائية (RAM)؟
تم بناء Z-Wave JS UI بـ Node.js ويستهلك عادة ما بين 80 إلى 180 ميجابايت فقط من الذاكرة العشوائية داخل Docker.