‏Netbird: شبكة VPN مشبكة WireGuard باستضافة ذاتية

‏WireGuard الثابت وHeadscale وNetbird: ثلاثة مقاربات مختلفة

‏WireGuard الثابت (انظر دليل WireGuard P2P) يتطلّب توزيع زوج مفاتيح لكل نفق وتحرير /etc/wireguard/wg0.conf عند إضافة كل peer جديد. مناسب لخادمَين أو ثلاثة ثابتة — غير قابل للإدارة على نطاق وكالة.

‏Headscale يُعيد تطبيق خادم التنسيق ‏Tailscale: تحتفظ بعملاء ‏Tailscale الرسميين وتحصل على شبكة مسطّحة بلا حدٍّ للمستخدمين. شبكة واحدة لكل نسخة، دون عزل فطري بين عملاء مختلفين. الاختيار الصحيح لفريق واحد يريد البقاء ضمن بيئة ‏Tailscale.

‏Netbird يسلك المسار المعاكس: يوفّر عميله الخاص وخطة التحكم الخاصة (‏Management + Signal + relay) ومفهوم الشبكات المسمّاة بقواعد وصول دقيقة. نسخة واحدة يمكنها استضافة شبكات معزولة تمامًا — مما يجعله الأداة الطبيعية لوكالة تدير بيئات عملاء منفصلة. واجهة الويب مضمَّنة من البداية.

بنية Netbird: أربعة مكوّنات

يعتمد نشر ‏Netbird ذاتي الاستضافة على أربعة مكوّنات في المستودع ذاته (netbirdio/netbird):

‏Management Server — دماغ خطة التحكم. يوزّع مفاتيح ‏WireGuard ويطبّق قواعد الوصول ويكشف ‏REST API التي تستهلكها واجهة الويب. تخزين ‏SQLite افتراضيًا، ‏MySQL أو ‏PostgreSQL كخيار.

‏Signal Server — خادم الإشارة بين الأقران. يسهّل تبادل واصفات اتصال ‏ICE بين العُقد عند إنشاء نفق ‏WireGuard. لا يمرّ به أي تراسل تطبيقي.

‏COTURN — خادم الترحيل ‏STUN/TURN. يعمل وسيطًا حين تكون الاتصال المباشر بين عُقدتين مستحيلًا (‏NAT مزدوج أو شبكة مؤسسية مقيّدة). لا يمرّ التراسل بـ‏COTURN إلا عند فشل المحاولة المباشرة.

‏Dashboard — واجهة الويب (‏React SPA) التي تستهلك ‏API الإدارة. أنشئ الشبكات وأضف الأقران وحدّد قواعد الوصول وأنشئ مفاتيح الانضمام دون لمس سطر الأوامر.

جميع التراسل بين العملاء يسير عبر ‏WireGuard مشفّر من طرف إلى طرف — لا يرى ‏Management ولا ‏Signal سوى بيانات التعريف، لا التراسل التطبيقي.

المتطلبات المسبقة

‏VPS مخصص لخطة التحكم. خصّص ‏VPS منفصلًا عن عُقد عملائك: ‏2 vCPU وذاكرة وصول عشوائي لا تقل عن 2 جيجابايت. ‏{{vps.start.name}} كافٍ للبداية.

المنافذ المطلوبة على VPS التحكم:

‏443 (TCP) — ‏Management والـ‏Dashboard خلف بروكسي ‏HTTPS عكسي.
‏3478 (UDP) — ‏COTURN STUN/TURN.
‏49152-65535 (UDP) — النطاق الديناميكي لـ‏COTURN لجلسات الترحيل.

عُقد العملاء لا تحتاج إلى فتح أي منفذ واردٍ: عميل ‏Netbird يُنشئ اتصالات صادرة نحو خطة التحكم.

البرامج المطلوبة على VPS التحكم: ‏Docker Engine 24+ وDocker Compose v2 واسم نطاق يشير إلى ‏IP الخادم وشهادة ‏TLS (‏Let's Encrypt عبر السكريبت المرفق أو البروكسي العكسي المعتاد).

على كل عُقدة عميل: ثنائي ‏netbird (حزمة ‏Debian/RPM أو ثنائي ثابت) وصلاحية ‏root أو ‏sudo.

نشر خطة التحكم وربط ثلاث عُقد

تشغيل سكريبت الإعداد

على ‏VPS التحكم، حمّل سكريبت ‏Netbird الرسمي ودعه يُنشئ مجموعة ‏Docker Compose الكاملة:

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh -o getting-started.sh
bash getting-started.sh

يطلب السكريبت نطاقك (مثلًا netbird.your-domain.com)، ويُنشئ docker-compose.yml وconfig.yaml وdashboard.env وتهيئة ‏COTURN، ثم يُشغّل الحاوية. في النهاية يطبع عنوان واجهة الويب وأول Setup Key — احتفظ به.

التحقق من تشغيل الخدمات الأربع

بعد انتهاء السكريبت، تأكّد من اشتغال الحاويات:

docker compose ps

يجب أن ترى أربع خدمات بحالة ‏running: netbird-management وnetbird-signal وnetbird-coturn وnetbird-dashboard. اختبر ‏Management API من داخل ‏VPS:

curl -s https://netbird.your-domain.com/api/v1/peers \
  -H 'Authorization: Token <your-PAT>'

استجابة ‏JSON فارغة [] تؤكد أن الخدمة تعمل ولا يوجد أي peer منضمّ بعد.

إنشاء شبكة ومفتاح Setup Key في واجهة الويب

افتح https://netbird.your-domain.com في متصفحك. سجّل الدخول بالحساب الذي أُنشئ خلال الإعداد (أو عبر موفّر ‏OIDC المهيَّأ).

في قائمة ‏Setup Keys، انقر ‏Create Setup Key. سمّه (vps-client-a)، اختر النوع Reusable (لانضمام عدة أجهزة بالمفتاح ذاته) وحدّد مدة الصلاحية. انسخ المفتاح — ستحتاجه على كل عُقدة.

انضمام العُقدة 1

على ‏VPS العميل الأول، ثبّت عميل ‏Netbird:

curl -fsSL https://pkgs.netbird.io/install.sh | bash

ثم اربطه بخطة التحكم:

netbird up \
  --management-url https://netbird.your-domain.com \
  --setup-key <YOUR_SETUP_KEY>

تأكّد من الاتصال:

netbird status

يجب أن ترى ‏Status: Connected وعنوان ‏IP شبكي في النطاق 100.64.x.x يُخصّصه خادمك.

انضمام العُقدتين 2 و3

كرّر بالضبط الإجراء ذاته على ‏VPS العميل الثاني والثالث. أمر ‏curl ذاته لتثبيت العميل، وأمر ‏netbird up ذاته مع --management-url و--setup-key نفسيهما (إذا كان المفتاح من نوع Reusable).

بعد انضمام العُقد الثلاث، تحقّق من العُقدة 1 أن الأقران مرئيون:

netbird status --detail

يسرد الناتج كل peer مع عنوان ‏IP الشبكي وحالته (Connected أو Connecting) وزمن الوصول.

اختبار الاتصال الشبكي دون أي منفذ عام مفتوح

قبل الاختبار، راجع حالة جدار الحماية على العُقدة 1 — لا ينبغي أن يكون أي منفذ وارد مفتوحًا نحو العُقد الأخرى:

sudo ufw status numbered

يجب أن يظهر فقط المنفذ 22 (‏SSH). الآن انقر العُقدة 2 عبر عنوانها الشبكي (مرئي في netbird status --detail، مثلًا 100.64.0.2):

ping -c 3 100.64.0.2

يعبر الـ‏ping نفق ‏WireGuard المُنشأ بين الأقران. إن كانت العُقدتان خلف ‏NAT صارم، يوفّر ‏COTURN الترحيل — يعمل الـ‏ping في كلتا الحالتين دون أي قاعدة ‏UFW إضافية.

التمييز بين الاتصال المباشر والاتصال عبر relay

للتمييز بين الاتصال المباشر ومرور ‏COTURN:

netbird status --detail

العمود Connection type يُظهر P2P للاتصال المباشر أو Relayed حين يتدخّل ‏COTURN. ‏P2P هو الحالة الطبيعية بين ‏VPS ذات عناوين ‏IPv4 عامة مباشرة. ‏Relayed يعني أن ‏Netbird اضطرّ للمرور بخادم ‏COTURN — تحقّق حينئذٍ من إمكانية الوصول إلى منافذ ‏UDP 3478 والنطاق 49152-65535 من العُقد.

عزل متعدد العملاء: مجموعات الأقران وقواعد الوصول

قوة ‏Netbird على ‏Headscale تكمن في مفهوم الشبكة المعزولة لكل مجموعة. افتراضيًا، جميع الأقران المنضمّين بالمفتاح ذاته ينتمون لمجموعة مشتركة. لعزل خوادم العميل أ عن خوادم العميل ب:

1. أنشئ مجموعة لكل عميل في واجهة الويب (Networks → Groups → Add Group). سمّها client-a وclient-b.

2. عيّن كل peer لمجموعته. في تفاصيل الـ‏peer، قسم ‏Assigned Groups، أضف المجموعة المقابلة وأزل مجموعة All إن أردت عدم التواصل بين المجموعات.

3. حدّد قواعد الوصول (Access Control → Policies). سياسة client-a-internal تسمح بالتراسل بين أقران مجموعة client-a. لا تُنشأ أي قاعدة بين client-a وclient-b: الشبكتان محكمتان تمامًا.

يمكنك أيضًا تعريف Network Routes: يعمل peer كموجّه لشبكة فرعية خاصة (مثلًا 192.168.10.0/24) ويكشفها لأقران المجموعة، دون الحاجة لتثبيت عميل ‏Netbird على كل جهاز في الشبكة الفرعية.

العمليات اليومية

تجديد مفتاح Setup Key أو إلغاؤه. في واجهة الويب، Setup Keys → مفتاحك → Revoke. الأقران المنضمّون يحتفظون باتصالهم؛ المحاولات الجديدة بهذا المفتاح سترفض. أنشئ مفتاحًا جديدًا للانضمامات القادمة.

إلغاء peer. Peers → اختر الـ‏peer → Delete. تُزال العُقدة فورًا من الشبكة. من جانب العميل، netbird status ينتقل إلى Disconnected وتُدمَّر أنفاق ‏WireGuard نحو هذا الـ‏peer.

واجهة API للأتمتة. يكشف ‏Netbird ‏REST API موثّقة. أنشئ ‏Personal Access Token (Settings → Access Tokens) وأدِر كل شيء من أدوات ‏Ansible أو خطوط ‏CI:

curl -s https://netbird.your-domain.com/api/v1/peers \
  -H 'Authorization: Token <PAT>'

المراقبة. يكشف ‏Management Server مقاييس ‏Prometheus على /metrics. اربط ‏Grafana بهذا المسار لمتابعة عدد الأقران المتصلين وجلسات ‏COTURN النشطة وزمن الإشارة.

التصليب: المصادقة الثنائية على Dashboard وأخذ نسخ احتياطية

لوحة ‏Netbird تدعم ‏OIDC (‏Keycloak وAuthentik وAzure AD) — فعّلها لفرض ‏MFA على جميع مدراء خطة التحكم. بدون ‏SSO، يبقى الحساب المحلي محميًا بكلمة مرور فحسب.

قاعدة بيانات ‏SQLite لخادم ‏Management هي الحالة الدائمة الوحيدة لشبكتك: فقدان هذا الملف يعني إعادة انضمام جميع أقرانك. ثبّت مجلدًا ‏Docker مسمّى (netbird_management) وخذ نسخة احتياطية منه يوميًا:

docker run --rm \
  -v netbird_management:/data \
  -v /opt/backups:/backup \
  alpine tar czf /backup/netbird-$(date +%Y%m%d).tar.gz /data

احتفظ بسبعة أيام من التناوب على الأقل.

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

‏COTURN غير متاح — الأقران يبقون في Relayed أو لا يتصلون أبدًا.
تحقّق من فتح منافذ ‏UDP 3478 والنطاق 49152-65535 في جدار حماية ‏VPS التحكم (ufw status). اختبر من عُقدة عميل: nc -u -z netbird.your-domain.com 3478. غياب الاستجابة = تراسل مفلتَر. بعض المزوّدين يحجبون نطاقات ‏UDP الواسعة افتراضيًا — افتحها صراحةً.

Peer عالق في Connecting.
هذا يعني نجاح التواصل مع ‏Management/Signal (انضمّ الـ‏peer) لكن نفق ‏WireGuard لا يتشكّل. الأسباب الشائعة: عنوان ‏IP العام لـ‏VPS التحكم خاطئ في config.yaml (حقل --turn-external-ip في ‏COTURN)، أو النطاق الديناميكي ‏UDP مغلق. أعد تشغيل getting-started.sh مع --external-ip صريحًا إن كان ‏VPS خلف ‏NAT.

فشل دقّة ‏DNS بين الأقران.
‏Netbird يتضمّن محلّل ‏DNS يوزّع أسماء <hostname>.netbird.cloud على كل peer. إن فشل ping node2.netbird.cloud بينما ping 100.64.0.2 نجح، تحقّق من تشغيل خدمة netbird على الـ‏peer (systemctl status netbird) وأن ‏DNS نشط: resolvectl status | grep netbird.

NAT مزدوج — لا اتصال مباشر وCOTURN مثقَل.
إن كان كلا الـ‏peer خلف ‏NAT صارم، الاتصال المباشر مستحيل وكل التراسل يمرّ بـ‏COTURN. تأكّد أن ‏VPS التحكم له ‏IPv4 عام مباشر وأن --turn-external-ip يشير إليه. لعُقد العملاء خلف ‏NAT صارم، لا شيء يُفعل — ‏COTURN مُصمَّم تحديدًا لهذه الحالة.

تحديث الحزمة — عُقد منقطعة مؤقتًا.
تحديث ‏Management Server يقطع الأقران لثوانٍ خلال إعادة تشغيل الحاوية. جدوِل التحديثات خارج نوافذ حركة البيانات، أو فعّل restart: always على جميع الحاويات لتقليص وقت التوقف.

ما تغيّره الشبكة المشبكة في إدارة الأسطول

شبكة ‏Netbird المشبكة ذاتية الاستضافة تحلّ محلّ ثلاث طبقات كنت تديرها يدويًا: توزيع مفاتيح ‏WireGuard وقواعد ‏UFW بين الخوادم وتوثيق الوصولات المتقاطعة. كل ‏VPS عميل جديد ينضمّ بأمر واحد؛ كل إلغاء فوري ومركزي.

العزل بالمجموعات يُتيح لك النموّ دون خطر التداخل: خوادم عميلَين مختلفَين لا يمكنها التراسل ولو اشتغلت على البنية التحتية ذاتها. وتبقى خطة التحكم تحت سيطرتك — لا اعتماد على ‏SaaS خارجي، ولا حدٍّ لعدد المقاعد، ولا اشتراك لكل عُقدة.

للمضيّ أبعد، دوّن تهيئة العُقد في ‏Ansible (انظر دليل Ansible): تثبيت العميل وتشغيل netbird up يصبحان مهمتَين معادلتَين في دور قابل لإعادة الاستخدام.