📡 تثبيت خادم UniFi Controller — إدارة أجهزة وشبكات Ubiquiti على Docker

نشر منصة UniFi Network Controller على Ubuntu باستخدام Docker — نظام إدارة شبكات وأجهزة الواي فاي والسويتشات من Ubiquiti مركزياً على المنفذ المشفر 8443.

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

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

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

سكريبت تثبيت مؤتمت — أمر واحد ينشر UniFi Controller على المنفذ المشفر 8443 مع منفذ الربط 8080 وقاعدة بيانات MongoDB جاهزة.
عرض على GitHub

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

wget https://raw.githubusercontent.com/mhmdali94/Docker/refs/heads/main/networking/unifi/unifi-ubuntu.sh
chmod +x unifi-ubuntu.sh
sudo bash unifi-ubuntu.sh

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

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

wget https://raw.githubusercontent.com/mhmdali94/Docker/refs/heads/main/networking/unifi/unifi-ubuntu.sh

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

chmod +x unifi-ubuntu.sh

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

يقوم السكريبت بتثبيت Docker وتجهيز مجلدات التخزين الدائم للإعدادات (`./config`) وقاعدة بيانات MongoDB (`./data`) وتشغيل حزمة UniFi Controller على المنفذ المشفر 8443.

sudo bash unifi-ubuntu.sh

4 إكمال معالج الإعداد وربط الأجهزة

افتح متصفحك وانتقل إلى الرابط المشفر https://ip-سيرفرك:8443 (وتجاوز تحذير الشهادة الذاتية). أنشئ حساب المشرف المحلي، واعتمد أجهزة الـ Access Points والسويتشات عبر رابط الإبلاغ `http://ip-سيرفرك:8080/inform`.

https://:8443
# Accept the self-signed certificate and run the setup wizard

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

المنفذالغرض
8443Web UI (HTTPS)
8080Device inform (adoption + config)
3478/udpSTUN (devices behind NAT)
10001/udpDevice discovery (local L2)
27017MongoDB (internal only)

نظرة عامة

تعد UniFi Network Application (المعروفة سابقاً بـ UniFi Controller) منصة الإدارة المركزية الموحدة لشبكات وأجهزة شركة Ubiquiti العالمية. تعمل المنصة عبر المنفذ المشفر HTTPS 8443 (لوحة التحكم وإدارة الشبكة) والمنفذ 8080 (بروتوكول إبلاغ وربط الأجهزة Device Inform)، لتتيح لمهندسي الشبكات وأصحاب المنازل الذكية إعداد ومراقبة وتهيئة نقاط بث الواي فاي (Access Points)، وسويتشات الـ PoE، وبوابات الأمان عبر موقع واحد أو مواقع جغرافية متعددة دون الحاجة لشراء جهاز Cloud Key العتادي المكلف.

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

يتطلب تشغيل شبكات Ubiquiti شراء جهاز Cloud Key إضافي أو تشغيل البرنامج على حاسوب شخصي يتوقف فور إغلاق شاشة اللابتوب. يمنحك تشغيل UniFi Controller داخل Docker على سيرفر Ubuntu خادماً دائماً ومستقراً 24/7: جمع إحصائيات التغطية اللحظية، وإدارة عدة فروع ومكاتب من لوحة واحدة، وتفعيل التجوال السلس (Seamless Roaming)، مع سيادة كاملة لبيانات شبكتك بدون أي اشتراكات سحابية.

متى تحتاجه

  • تمتلك أجهزة شبكات من Ubiquiti UniFi (أجهزة Access Points أو سويتشات) وتحتاج لخادم تحكم دائم 24/7
  • تريد توفير تكلفة شراء جهاز UniFi Cloud Key أو أجهزة Dream Machine العتادية باهظة الثمن
  • تدير عدة مواقع جغرافية أو فروع تجارية وتريد إدارتها ومراقبتها بالكامل من شاشة تحكم موحدة
  • تريد إنشاء بوابة ضيوف (Guest Wi-Fi Portal) ببطاقات دخول مؤقتة (Vouchers) وتحديد سرعات الإنترنت
  • تحتاج لمراقبة جودة قنوات الواي فاي، وقوة إشارة الهواتف، وأتمتة تحديثات الفيرموير للأجهزة

من يحتاجه

  • أصحاب المنازل الذكية والسيرفرات لتأمين تغطية واي فاي Wi-Fi 6/7 سريعة وتجوال سلس بين الغرف
  • مديرو شبكات الشركات والمكاتب لإدارة منافذ سويتشات الـ PoE وتوزيع شبكات الـ VLANs
  • شركات إدارة الخدمات السحابية (MSPs) لاستضافة خادم تحكم مركزي واحد لعدة عملاء في مساحات مستقلة
  • أصحاب المقاهي والمطاعم والفنادق لتوفير شبكة واي فاي مخصصة للزبائن مع شاشات ترحيب وشروط استخدام
  • مهندسو الشبكات لتوزيع شبكات الـ SSID، وجدولة ساعات عمل الواي فاي، وتطبيق سياسات العزل الأمني

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

  • إدارة 6 أجهزة UniFi AP في مبنى متعدد الطوابق مع تفعيل التجوال السلس فائق السرعة (802.11r/k/v)
  • اعتماد وربط أجهزة Access Points في فرع بعيد عبر الإنترنت باستخدام رابط الـ Inform الخارجي
  • إنشاء شبكة واي فاي مخصصة لأجهزة المنزل الذكي (IoT) معزولة على شبكة افتراضية مستقلة (VLAN 30)
  • تصميم بوابة ترحيبية لضيوف الفندق على منفذ 8880 مع إصدار كروت إنترنت محددة بالوقت والسرعة
  • فحص التداخل اللاسلكي للترددات وجدولة مسح قنوات الواي فاي التلقائي أسبوعياً لضمان أعلى أداء

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

  • إدارة واعتماد الأجهزة مركزياً: التحكم بمئات نقاط البث والسويتشات من خلال واجهة المنفذ 8443
  • إدارة مواقع متعددة (Multi-Site): تنظيم الفروع الجغرافية المستقلة بشبكات VLAN وخرائط منفصلة
  • التجوال السلس فائق السرعة (802.11r/k/v): نقل اتصال الهواتف تلقائياً بين أجهزة البث بدون انقطاع
  • بوابة الضيوف الترحيبية: شاشات تسجيل دخول مخصصة مع دعم بطاقات الدخول (Vouchers) وتحديد السرعة
  • تحليلات وإحصائيات متقدمة: مراقبة فورية لقوة الإشارة (RSSI) واستهلاك القنوات ومعدل نقل البيانات
  • نسخ احتياطي آلي مجدول: جدولة استخراج ملفات النسخ الاحتياطي `.unf` لسهولة الاستعادة السريعة
  • عزل وتجزئة الشبكات (VLANs): ربط كل شبكة واي فاي (SSID) بـ VLAN مستقل مع قواعد جدار حماية صارمة
  • معمارية Docker Compose تجمع خادم UniFi Network مع قاعدة بيانات MongoDB على المنفذ المشفر 8443

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

  • افتح المتصفح وانتقل إلى الرابط https://ip-سيرفرك:8443 (وتجاوز تحذير شهادة الـ SSL)
  • سمّ شبكتك وأنشئ حساب المشرف المحلي وعطّل الوصول السحابي الخارجي إن كنت تفضل الإدارة المحلية
  • وصل جهاز الـ UniFi AP بنفس الشبكة؛ وبمجرد ظهوره باللوحة اضغط 'Adopt'
  • إذا كان الجهاز في شبكة فرعية أخرى، ادخل إليه عبر SSH ونفذ: `set-inform http://ip-سيرفرك:8080/inform`
  • أنشئ شبكة الواي فاي الأساسية واضبط الحماية بـ WPA2/WPA3 Personal
  • ضع واجهة UniFi خلف وكيل عكسي مشفر بـ HTTPS (مثل Nginx) مع شهادة SSL صالحة
  • فعل النسخ الاحتياطي التلقائي من Settings ← System ← Backups

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

  • تنبيه أمني حاسم: عيّن كلمة مرور معقدة لحساب المشرف وفعل التوثيق الثنائي (2FA)
  • استخدم تشفير HTTPS دائماً للوصول للوحة؛ فالنظام يتحكم في كامل البنية التحتية لشبكتك وأمانها
  • افتح منفذ 8080 لأجهزة الشبكة فقط، واقصر الوصول للوحة التحكم 8443 على شبكة الإدارة الداخلية الموثوقة
  • أبقِ منفذ قاعدة البيانات الداخلي MongoDB 27017 مغلقاً عن الإنترنت العام
  • احمِ مجلد الإعدادات `./config` بصلاحيات نظام صارمة بالسيرفر
  • حدّث صورة الحاوية دورياً للحصول على التحديثات الأمنية وإصلاحات الفيرموير

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

يستخدم UniFi منفذ TCP 8443 (للوحة الويب المشفرة HTTPS)، ومنفذ TCP 8080 (لبروتوكول ربط الأجهزة Device Inform)، ومنفذ UDP 3478 (لخدمة STUN)، ومنفذ UDP 10001 (لاكتشاف الأجهزة). اسمح بالمنفذ 8443 لشبكة الإدارة (`ufw allow 8443/tcp`). وافتح منفذ 8080 ومنفذ STUN 3478 لأجهزة UniFi بالشبكة (`ufw allow 8080/tcp && ufw allow 3478/udp`).

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

  • حمل ملفات النسخ الاحتياطي `.unf` مباشرة من واجهة UniFi من Settings ← System ← Backups
  • انسخ مجلد `./config` احتياطياً، والذي يحتوي على شهادات السيرفر والإعدادات والسجلات
  • انسخ مجلد `./data` الذي يحتوي على كامل قاعدة بيانات MongoDB
  • أتمت النسخ الاحتياطي اليومي للمجلدات وارفعه إلى مساحة تخزين سحابية عبر restic أو rsync
  • اختبر الاستعادة برفع ملف `.unf` داخل حاوية جديدة للتأكد من استرجاع إعدادات الأجهزة بسلاسة

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

  • استخدام بروتوكول HTTPS أو منفذ 8443 في رابط الـ Inform (حيث تتصل الأجهزة حصراً عبر HTTP ومنفذ 8080)
  • كتابة `localhost` أو `127.0.0.1` كرابط للـ Inform مما يمنع أجهزة البث الفيزيائية من الوصول للسيرفر
  • عدم ربط مجلدي الإعدادات وقاعدة البيانات، مما يجعل كافة أجهزة الواي فاي تفصل بعد إعادة تشغيل الحاوية
  • استخدام إصدارات غير متوافقة من قاعدة MongoDB (حيث يتطلب UniFi إصدار 4.4 أو 7.0 حسب نسخة الحاوية)
  • كشف منفذ الإدارة 8443 للإنترنت العام مباشرة دون تقييد عناوين الـ IP المسموح بها

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

  • فشل اعتماد جهاز البث (Adoption Failed) — ادخل للـ AP عبر SSH (البيانات الافتراضية `ubnt`/`ubnt`) ونفذ `set-inform http://ip-سيرفرك:8080/inform` مرتين
  • ظهور خطأ 502 Bad Gateway في الواجهة — انتظر دقيقة إلى دقيقتين لاكتمال إقلاع جافا وقاعدة البيانات ثم راجع السجلات: `docker logs unifi-controller -f`
  • ظهور خطأ STUN في حالة الأجهزة — تأكد من فتح منفذ UDP 3478 في جدار الحماية (`ufw allow 3478/udp`)
  • تحذير المتصفح من شهادة غير موثوقة — هذا طبيعي للشهادة الذاتية المدمجة؛ اضغط 'خيارات متقدمة' ثم 'متابعة'
  • استهلاك مرتفع للذاكرة — اضبط حدود الذاكرة لجافا بمتغيرات البيئة: `MEM_LIMIT=1024` و`MEM_MAX_LIMIT=2048`

البدائل

نظام Omada Controller لأجهزة شبكات TP-Link Omada. منصة Aruba Central السحابية. نظام OpenWrt المفتوح للراوترات. برنامج MikroTik WinBox لأجهزة ميكروتك. أجهزة UniFi Cloud Key العتادية.

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

تجنب استخدام UniFi Controller إذا كنت لا تمتلك أجهزة شبكات من تصنيع شركة Ubiquiti UniFi (حيث أن البرنامج مخصص حصراً لأجهزة يوبيكويتي ولا يمكنه إدارة راوترات وسويتشات الشركات الأخرى مثل Asus أو Netgear). وإذا كنت تمتلك أجهزة TP-Link Omada، فإن نظام Omada Controller هو المخصص لها.

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

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

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

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

هل أحتاج لشراء جهاز UniFi Cloud Key إذا قمت بتشغيل هذه الحاوية؟

لا! توفر هذه الحاوية المستضافة ذاتياً نفس ميزات نظام UniFi Network المتاح في أجهزة Cloud Key العتادية تماماً، مما يوفر عليك تكلفة شراء أجهزة إضافية مع استقرار دائم 24/7 على سيرفرك.

هل يتوقف الواي فاي عن العمل إذا تم إيقاف خادم UniFi Controller؟

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

ما الفرق بين المنفذ 8443 والمنفذ 8080 في UniFi؟

المنفذ 8443 (HTTPS) مخصص حصراً للوحة التحكم الرسومية التي تفتحها في المتصفح لإدارة الشبكة. بينما المنفذ 8080 (HTTP) هو قناة الاتصال (Inform) التي تستخدمها أجهزة البث والسويتشات للإبلاغ عن حالتها واستقبال الإعدادات.

كيف أعتمد جهاز Access Point موجود في فرع آخر أو شبكة فرعية مختلفة؟

ادخل للجهاز عبر بروتوكول SSH (بيانات الدخول الافتراضية `ubnt`/`ubnt`) ونفذ الأمر: `set-inform http://ip-سيرفرك:8080/inform`. ثم افتح لوحة التحكم واضغط 'Adopt'، وأعد تنفيذ الأمر مرة ثانية لاكتمال الربط.

كم يستهلك UniFi Controller من الذاكرة العشوائية (RAM)؟

تم بناء النظام بلغة Java مع قاعدة بيانات MongoDB، ويستهلك عادة ما بين 750 ميجابايت إلى 1.5 جيجابايت من الذاكرة العشوائية داخل Docker حسب عدد الأجهزة والأجهزة المتصلة بالواي فاي.