🔒 تثبيت Headplane — واجهة إدارة ويب لـ Headscale

انشر Headplane على Ubuntu بـ Docker — واجهة ويب أنيقة لإدارة سيرفر Headscale ذاتي الاستضافة لديك: الأجهزة والمستخدمون والمسارات وقوائم ACL، دون سطر الأوامر، على المنفذ 3054.

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

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

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

سكريبت تثبيت آلي — ينشر Headplane على المنفذ 3054 كواجهة ويب لسيرفر Headscale قائم. سجّل الدخول بمفتاح API الخاص بـ Headscale لإدارة الأجهزة والمستخدمين والمسارات بصرياً.
عرض على GitHub

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

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/vpn/headplane/headplane-ubuntu.sh
chmod +x headplane-ubuntu.sh
sudo bash headplane-ubuntu.sh

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

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

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/vpn/headplane/headplane-ubuntu.sh

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

chmod +x headplane-ubuntu.sh

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

يثبّت السكريبت Docker إن لزم، ويُشغّل Headplane على المنفذ 3054، مع ضبط config.yaml للإشارة إلى سيرفر Headscale الخاص بك (المتوقع على المنفذ 8080). يولّد سر كوكيز (cookie secret)؛ ستُوثّق دخولك عبر مفتاح API الخاص بـ Headscale.

sudo bash headplane-ubuntu.sh

4 إنشاء مفتاح API وفتح واجهة الإدارة

أنشئ مفتاح API لـ Headscale، ثم افتح واجهة إدارة Headplane وسجّل الدخول به لإدارة شبكة tailnet الخاصة بك بصرياً:

http://<your-server-ip>:3054/admin

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

المنفذالغرض
3054Admin UI (host → container 3000) — at /admin
HeadscaleRequires a running Headscale server (expected on 8080)
API keyLog in with a Headscale API key — full tailnet control

نظرة عامة

Headplane واجهة إدارة ويب مفتوحة المصدر لـ Headscale، إعادة التنفيذ ذاتية الاستضافة والمفتوحة المصدر لسيرفر تنسيق Tailscale. يُدار Headscale نفسه بالكامل عبر سطر الأوامر افتراضياً — إنشاء المستخدمين وتسجيل الأجهزة وتحديد قوائم ACL وتفعيل المسارات كلها تتطلب أوامر headscale CLI. يعمل Headplane فوق سيرفر Headscale قائم ويكشف نفس هذه العمليات عبر واجهة ويب حديثة ونظيفة، بحيث تدير شبكتك الخاصة بالكامل (tailnet) بصرياً بدلاً من حفظ خيارات سطر الأوامر.

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

إذا كنت تشغّل Headscale كبديل ذاتي الاستضافة لسيرفر تنسيق Tailscale، يزيل Headplane عناء إدارته فقط عبر SSH وأوامر CLI. تصبح المهام اليومية — الموافقة على أجهزة جديدة، دعوة مستخدمين، مراجعة المسارات وعقد الخروج، تعديل سياسات ACL — بضغطة زر بدلاً من تذكّر أوامر headscale الدقيقة. هذا مفيد بشكل خاص للفرق التي لا يكون فيها كل من يدير الشبكة مرتاحاً على سطر الأوامر، أو للمسؤولين الذين يريدون ببساطة طريقة أسرع للتحقق من حالة الشبكة دون الدخول عبر SSH للسيرفر.

متى تحتاجه

  • تُشغّل سيرفر Headscale ذاتي الاستضافة وسئمت من إدارة المستخدمين والأجهزة والمسارات فقط عبر سطر الأوامر
  • تريد نظرة بصرية شاملة على شبكتك — الأجهزة المتصلة، حالة الاتصال، عناوين IP — دون الدخول عبر SSH للسيرفر
  • عدة أشخاص يساعدون في إدارة الشبكة وليس الجميع مرتاحاً مع أوامر headscale CLI
  • تحتاج الموافقة بشكل متكرر على أجهزة جديدة أو إدارة مسارات الشبكة الفرعية وعقد الخروج وتريد أن يكون ذلك إجراء ويب سريعاً
  • تريد تعديل ومراجعة سياسات ACL برؤية أوضح من تعديل ملف JSON/YAML خام عبر SSH
  • تُشغّل بالفعل Headscale في Docker وتريد حاوية مرافقة تتصل بإعدادك الحالي بأقل تغييرات ممكنة

من يحتاجه

  • عشاق المختبرات المنزلية والاستضافة الذاتية الذين يُشغّلون Headscale كبديل مجاني لخطة التحكم المستضافة من Tailscale
  • الفرق الصغيرة والمؤسسات التي تستضيف VPN شبكي خاصاً بها وتحتاج عدة مسؤولين لإدارته
  • مسؤولو الأنظمة الذين يريدون عرضاً يومياً أسرع لحالة الشبكة بدلاً من تكرار تشغيل أوامر headscale CLI
  • المستخدمون المهتمون بالخصوصية الذين اختاروا Headscale تحديداً لتجنب الاعتماد على خدمة تنسيق Tailscale السحابية
  • مزودو الخدمات المُدارة والاستشاريون الذين يديرون نشر Headscale لعدة عملاء ويريدون واجهة ويب متسقة
  • الفرق التي تحتاج تأهيل موظفين غير تقنيين للموافقة على الأجهزة أو عرض حالة الشبكة دون وصول لسطر الأوامر
  • المطورون الذين يختبرون تغييرات سياسة ACL ويريدون رؤية القواعد الناتجة وتأثيراتها بوضوح أكبر من ملفات الإعداد الخام

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

  • عرض جميع الأجهزة المسجلة في شبكتك مع حالة اتصالها وعناوين IP وأوقات آخر ظهور
  • الموافقة على أو رفض تسجيلات أجهزة جديدة دون الحاجة لوصول SSH لسيرفر Headscale
  • إنشاء وإدارة مستخدمي Headscale وتخصيصات أجهزتهم من نموذج ويب
  • تفعيل أو تعطيل المسارات الفرعية وعقد الخروج التي تعلنها الأجهزة في الشبكة
  • مراجعة وتعديل سياسات ACL التي تتحكم بالأجهزة والمستخدمين المسموح لهم بالتواصل
  • الحصول على نظرة تشغيلية سريعة على صحة الشبكة لاستكشاف مشكلات الاتصال وإصلاحها

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

  • لوحة بصرية تسرد جميع أجهزة الشبكة مع الحالة وعناوين IP والوسوم وأوقات آخر ظهور
  • إدارة مستخدمين — إنشاء وإعادة تسمية وحذف مستخدمي Headscale مباشرة من واجهة الويب
  • الموافقة على الأجهزة وإدارتها، بما في ذلك إعادة التسمية وانتهاء الصلاحية وإزالة الأجهزة من الشبكة
  • إدارة المسارات وعقد الخروج — تفعيل أو تعطيل المسارات الفرعية وعقد الخروج المعلنة من الأقران لكل جهاز
  • عارض/محرر سياسات ACL لمراجعة وتعديل الأجهزة والمستخدمين المسموح لهم بالتواصل
  • مصادقة قائمة على مفتاح API تعيد استخدام نموذج مصادقة Headscale نفسه بدلاً من إدخال قاعدة بيانات مستخدمين منفصلة
  • نشر بحاوية واحدة خفيفة تتصل بأي نسخة Headscale قائمة عبر config.yaml
  • واجهة حديثة ونشطة الصيانة، وتُعد الخليفة الأحدث لواجهات مجتمعية سابقة مثل headscale-ui

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

  • تأكد أن سيرفر Headscale الخاص بك يعمل بالفعل ويمكن الوصول إليه على العنوان المضبوط في config.yaml الخاص بـ Headplane
  • أنشئ مفتاح API لـ Headscale من سيرفر Headscale نفسه بأمر docker exec headscale headscale apikeys create
  • افتح واجهة إدارة Headplane عند http://your-server-ip:3054/admin والصق مفتاح API لتسجيل الدخول
  • راجع قائمة Machines ووافق على الأجهزة أو أعد تسميتها أو أزلها عند تسجيلها في شبكتك
  • أنشئ مستخدمي Headscale ضمن قسم Users لكل شخص أو فريق يحتاج مجموعته الخاصة من الأجهزة
  • فعّل المسارات الفرعية أو عقد الخروج للأجهزة التي تحتاج مشاركة وصول الشبكة أو توجيه حركة المرور عبرها
  • راجع وعدّل سياسات ACL لتحديد بالضبط الأجهزة والمستخدمين المسموح لهم بالوصول لبعضهم البعض
  • احفظ واجهة الإدارة كإشارة مرجعية أو أعدّ وكيلاً عكسياً باسم مضيف سهل للوصول اليومي الأسرع

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

  • عامل مفتاح API الخاص بـ Headscale تماماً مثل كلمة مرور الجذر — فهو يمنح تحكماً إدارياً كاملاً بشبكتك بأكملها
  • لا تكشف المنفذ 3054 الخاص بـ Headplane مباشرة للإنترنت العام بدون وكيل عكسي يوفر HTTPS/TLS
  • قيّد الوصول لواجهة الإدارة على شبكة موثوقة أو VPN أو قائمة IP مسموحة لأن أي شخص يملك مفتاح API يملك تحكماً كاملاً
  • خزّن سر الكوكيز المُولَّد بأمان ولا ترفع config.yaml (الذي قد يشير إلى أسرار) إلى مستودع الكود
  • أعد توليد مفتاح API الخاص بـ Headscale دورياً وفوراً إذا اشتبهت بتسريبه
  • حافظ على تحديث Headplane وسيرفر Headscale الأساسي معاً للحصول على إصلاحات الأمان
  • قيّد من يملك وصول SSH أو Docker لسيرفر Headscale، لأن مفاتيح API تُولَّد من هناك
  • راجع قوائم Machines وUsers دورياً لرصد وإزالة الأجهزة أو الحسابات التي لم تعد بحاجة للوصول

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

تستمع واجهة إدارة Headplane على منفذ المضيف 3054، المرتبط بالمنفذ الداخلي 3000 للحاوية، وتقدّم الواجهة عند المسار /admin. لا يُشغّل شبكة خاصة به — إنه فقط عميل إدارة يتصل عبر شبكة Docker (أو عنوان مضبوط) بسيرفر Headscale القائم لديك، المتوقع على المنفذ 8080 افتراضياً. يجب ألا يُكشف المنفذ 3054 مباشرة للإنترنت بدون HTTPS، لأن تسجيل الدخول يتم عبر مفتاح API يُرسل لهذه النقطة. ضع Headplane خلف وكيل عكسي مثل Nginx Proxy Manager مع شهادة TLS صالحة، وقيّد الوصول على الشبكات الموثوقة أو VPN نظراً للصلاحية الإدارية التي يمنحها مفتاح API.

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

  • انسخ ملف config.yaml الخاص بـ Headplane احتياطياً، فهو يخزّن تفاصيل الاتصال المشيرة لسيرفر Headscale
  • بيانات الشبكة الفعلية (الأجهزة والمستخدمون وACLs) تعيش في Headscale نفسه وليس Headplane — انسخ قاعدة بيانات وإعدادات Headscale احتياطياً كمصدر الحقيقة الأساسي
  • خزّن سر الكوكيز وأي مفاتيح API في مدير أسرار بدلاً من ملفات نصية عادية بجانب الإعدادات
  • احتفظ بنسخة من docker-compose.yml أو أمر التشغيل لإعادة إنشاء Headplane بنفس الإعدادات بعد ترحيل السيرفر
  • وثّق أي سيرفر ومنفذ Headscale يتصل به Headplane، خاصة إذا كنت تُشغّل عدة نسخ من Headscale
  • اختبر أن Headplane يعيد الاتصال بشكل صحيح بعد استعادة نسخة احتياطية من Headscale بالتأكد من ظهور الأجهزة والمستخدمين

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

  • افتراض أن Headplane يحتاج تثبيت Headscale خاصاً به — إنه فقط واجهة ويب ويتطلب سيرفر Headscale منفصل يعمل بالفعل
  • كشف المنفذ 3054 للإنترنت العام بدون TLS، مما يرسل مفتاح API بنص عادي
  • فقدان مفتاح API الخاص بـ Headscale أو عدم تخزينه بأمان، مما يتطلب إصدار مفتاح جديد
  • نسيان أن Headscale نفسه (وليس Headplane) يحمل حالة الشبكة الفعلية، والنسخ الاحتياطي للمكوّن الخاطئ
  • ضبط config.yaml على عنوان أو منفذ Headscale خاطئ، مما يجعل Headplane يفشل بالاتصال أو يعرض بيانات قديمة
  • إعطاء مفتاح API لأشخاص أكثر من اللازم، لأنه يمنح وصولاً إدارياً كاملاً دون تقييد لكل مستخدم
  • عدم تحديث Headplane مع Headscale معاً، مما يعرّض للمخاطرة بمشكلات توافق بعد ترقية إصدار Headscale

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

  • Headplane لا يُحمّل — تحقق من تشغيل الحاوية بـ docker ps وراجع السجلات بـ docker logs headplane
  • فشل تسجيل الدخول بمفتاح API — تأكد أن المفتاح لم تنتهِ صلاحيته وأنه أُنشئ بشكل صحيح بأمر headscale apikeys create على سيرفر Headscale
  • قائمة الأجهزة فارغة أو قديمة — تحقق أن config.yaml يشير لعنوان ومنفذ سيرفر Headscale الصحيحين وأن الحاويتين يمكنهما التواصل عبر الشبكة
  • تعذّر الاتصال بـ Headscale تماماً — تأكد أن Headscale يعمل ويمكن الوصول إليه على المنفذ 8080 (أو منفذك المضبوط) من حاوية Headplane
  • التغييرات المُجراة في Headplane لا يبدو أنها تُطبَّق — تأكد أنك تعدّل نفس نسخة Headscale المتوقعة؛ عدة سيرفرات Headscale قد تسبب لبساً
  • تغييرات ACL لا تُطبَّق — تحقق أن صياغة السياسة صالحة؛ يرفض Headscale ملفات ACL غير صحيحة وسيُظهر Headplane الخطأ الأساسي
  • أخطاء 401/403 بعد أن كان يعمل سابقاً — قد يكون مفتاح API انتهت صلاحيته أو أُلغي؛ أنشئ مفتاحاً جديداً على سيرفر Headscale
  • واجهة الإدارة تُحمّل لكن لا تعرض بيانات — تحقق أن واجهة Headscale API يمكن الوصول إليها وغير محظورة بقاعدة جدار ناري بين الحاويتين

البدائل

headscale-ui هي واجهة الويب المجتمعية الأصلية لـ Headscale — أبسط وأخف لكنها أقل نشاطاً في التطوير وبواجهة أقدم مقارنة بـ Headplane. إدارة Headscale فقط عبر أوامره الخاصة (headscale command) خيار متاح دائماً ولا يتطلب حاوية إضافية، لكنه يفقد النظرة البصرية الشاملة ويكون أبطأ للمهام الروتينية مثل الموافقة على الأجهزة. إذا كنت منفتحاً على ترك الاستضافة الذاتية، تقدّم وحدة تحكم Tailscale المستضافة واجهة ويب مصقولة مماثلة لكنها تتطلب الثقة في خدمة تنسيق Tailscale السحابية بدلاً من تشغيل خدمتك الخاصة. للفرق الملتزمة بالاستضافة الذاتية لـ Headscale التي تريد أحدث واجهة ويب نشطة الصيانة، يُعد Headplane حالياً الخيار الأقوى.

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

Headplane غير مفيد بحد ذاته — يجب أن تُشغّل بالفعل (أو ترغب بتشغيل) سيرفر Headscale، فإذا لم تقرر بعد الاستضافة الذاتية لخطة تحكم VPN الشبكي الخاصة بك، ابدأ بـ Headscale نفسه أو فكّر في خدمة Tailscale المستضافة أولاً. إذا كان فريقك مرتاحاً تماماً بإدارة Headscale عبر SSH وسطر الأوامر ويقدّر إبقاء النشر بأقل حد ممكن، فإضافة Headplane تعني حاوية إضافية وسطح هجوم إضافي قد لا تحتاجه. للنشرات الصغيرة جداً بمسؤول أو اثنين وعدد قليل من الأجهزة، قد يكون سطر الأوامر وحده أبسط من إعداد وتأمين واجهة ويب منفصلة. إذا كنت تحتاج ميزات مؤسسية مثل تكامل SSO أو سجلات تدقيق تفصيلية تتجاوز ما يكشفه Headscale نفسه، لا يضاهي Headplane ولا Headscale حالياً حلاً تجارياً مُدارًا بالكامل.

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

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

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

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

ما هو Headplane؟

إنها واجهة إدارة ويب لـ Headscale، إعادة التنفيذ ذاتية الاستضافة والمفتوحة المصدر لسيرفر تحكم Tailscale. يُدار Headscale عادة عبر سطر الأوامر؛ يضع Headplane واجهة ويب نظيفة فوقه بحيث يمكنك عرض وإدارة شبكتك — الأجهزة والمستخدمين والمسارات الفرعية وعقد الخروج وقوائم ACL — دون لمس سطر الأوامر.

ما المنفذ الذي يستخدمه وكيف أسجّل الدخول؟

يعمل Headplane على منفذ المضيف 3054 (مرتبط بمنفذ الحاوية 3000)، مع واجهة الإدارة عند /admin. لا يملك اسم مستخدم/كلمة مرور خاصة به — تُوثّق دخولك بمفتاح API الخاص بـ Headscale تولّده على سيرفر Headscale.

هل أحتاج Headscale يعمل بالفعل؟

نعم. Headplane مجرد واجهة إدارة — لا يُشغّل شبكة بحد ذاته. يجب أن يكون لديك بالفعل سيرفر تحكم Headscale (متوقع على المنفذ 8080)، يتصل به Headplane عبر config.yaml.

كيف أُنشئ مفتاح API؟

على سيرفر Headscale، شغّل أمر Headscale لإنشاء مفتاح API (docker exec headscale headscale apikeys create). ينتج عن ذلك مفتاح تلصقه في تسجيل دخول Headplane.

كيف يُقارَن بـ headscale-ui؟

كلاهما واجهات ويب مجتمعية لـ Headscale. headscale-ui هو الخيار الأقدم والأبسط؛ Headplane عموماً هو الأحدث والأكثر نشاطاً في التطوير بواجهة أجمل.