استضافة Headscale على VPS: خادم تحكّم Tailscale خاص بك

لماذا تستضيف خادم التحكم ذاتيًا

ما الذي يمنحك إياه Headscale المُستضاف ذاتيًا

• مستخدمون وأجهزة دون حدود: لا سقف يفرضه البرنامج ولا تسعير لكل مقعد — تنمو شبكتك المتشابكة مع فريقك، ولا يحدّها سوى موارد خادم VPS.
• عملاء Tailscale الرسميون في كل مكان: Linux وmacOS وWindows وiOS وAndroid — دون حاجة إلى نسخة مُفرّعة أو عميل بديل.
• أنفاق WireGuard من نظير إلى نظير: يتولى Headscale تبادل المفاتيح وتوزيع ACL فقط؛ أما حركة المرور الفعلية فتمر مباشرة عبر WireGuard بين النظراء.
• Magic DNS: اعثر على كل عقدة في شبكتك عبر اسم مضيفها (laptop.mesh.yourdomain.com) دون تعديل DNS العام.
• سياسات بصيغة HuJSON: صيغة ملف السياسة نفسها المستخدمة في Tailscale، مع ACL وGrants — حدّد أي المستخدمين والأجهزة يصلون إلى أي الخدمات.
• دعم مرحّلات DERP: استخدم خريطة DERP العامة لـ Tailscale لاجتياز NAT، أو فعّل خادم DERP المدمج في Headscale لتبقى المرحّلات لديك أيضًا.
• واجهة API وسطر أوامر headscale: أنشئ المستخدمين، وأصدر مفاتيح المصادقة المسبقة، وأدر العُقد برمجيًا.
• تسجيل دون حساب على tailscale.com: ينضم زملاؤك إلى الشبكة بمفتاح تولّده أنت، أو عبر مزوّد OpenID Connect الذي تستخدمه أصلًا (Keycloak وAuthelia وGoogle Workspace…).
• الشبكات الفرعية وexit nodes وTaildrop وTailscale SSH: يدعم الخادم الوظائف الأساسية لـ Tailscale.
• أقل من 50 MB من الذاكرة في وضع الخمول — يعمل بأريحية على خادم VPS بسعة 1 GB إلى جانب أحمال عمل أخرى.

المتطلبات

المنافذ الواجب فتحها على الخادم

• TCP 443: إلزامي. عبره يسجّل العملاء أنفسهم ويستلمون خريطة الشبكة؛ وهو المنفذ الوحيد الذي لا غنى عنه لخادم التنسيق.
• TCP 80: فقط للتحقق من Let's Encrypt عبر HTTP-01 وللتحويل إلى HTTPS.
• UDP 3478: فقط إذا فعّلت خادم DERP المدمج، الذي يحتاجه لـ STUN. مع خريطة DERP العامة لـ Tailscale لا داعي لفتحه.
• TCP 8080 (Headscale) و9090 (المقاييس) و50443 (gRPC): أبقها على 127.0.0.1. يتحدث الوكيل العكسي إلى 8080 محليًا، ولا تكشف واجهة إدارة gRPC أبدًا ما لم تحتج إليها.

انشر Headscale باستخدام Docker Compose

1. 01

   اكتب ملف Compose

   تتكون الحزمة من خدمة واحدة: الصورة الرسمية docker.io/headscale/headscale:0.29.7، آخر إصدار مستقر في 7 نوفمبر 2026، تُشغَّل بالأمر serve. يحفظ Headscale كل شيء — المفاتيح وقاعدة البيانات وسجلات العُقد — في مجلدين على المضيف: التهيئة، مُحمّلة للقراءة فقط على /etc/headscale، والبيانات على /var/lib/headscale. لا حاجة إلى قاعدة بيانات خارجية أو خدمة تخزين مؤقت؛ فـ SQLite مدمج.

   mkdir -p /opt/headscale/config /opt/headscale/lib
   cat > /opt/headscale/compose.yaml <<'EOF'
   services:
     headscale:
       image: docker.io/headscale/headscale:0.29.7
       container_name: headscale
       restart: unless-stopped
       read_only: true
       tmpfs:
         - /var/run/headscale
       ports:
         - "127.0.0.1:8080:8080"
       volumes:
         - /opt/headscale/config:/etc/headscale:ro
         - /opt/headscale/lib:/var/lib/headscale
       command: serve
       healthcheck:
         test: ["CMD", "headscale", "health"]
   EOF

   لا يُنشر المنفذ إلا على 127.0.0.1: الوكيل العكسي هو الذي يواجه الإنترنت.

2. 02

   ولّد التهيئة

   ابدأ من ملف المثال الخاص بالإصدار الذي تنشره بالضبط، ولا تغيّر سوى المفاتيح أدناه. server_url هو عنوان HTTPS الذي سيتصل به عملاء Tailscale؛ ويجب أن يستمع listen_addr على 0.0.0.0 داخل الحاوية. تُعرَّف قاعدة البيانات تحت database (type: sqlite). لا يبقى إلا مسار مفتاح noise: يولّده Headscale عند أول تشغيل إن لم يكن الملف موجودًا.

   curl -Lo /opt/headscale/config/config.yaml \
     https://raw.githubusercontent.com/juanfont/headscale/v0.29.7/config-example.yaml

   server_url: https://vpn.yourdomain.com
   listen_addr: 0.0.0.0:8080
   noise:
     private_key_path: /var/lib/headscale/noise_private.key
   database:
     type: sqlite
     sqlite:
       path: /var/lib/headscale/db.sqlite
   dns:
     magic_dns: true
     base_domain: mesh.yourdomain.com

   في ServOrbit، تكتب مهمة التوفير ملف config.yaml من نطاقك تلقائيًا.

3. 03

   شغّل الحاوية وتحقق

   شغّل docker compose up -d من /opt/headscale. يولّد Headscale مفتاح noise ثم يبدأ الاستماع على المنفذ 8080. تحقق من نقطة نهاية الصحة: ينبغي أن يُعيد curl -s http://127.0.0.1:8080/health القيمة {"status":"pass"}. الصورة مبنية على أساس distroless بلا صدفة أوامر، لكن سطر أوامر headscale يُستدعى مباشرة: يؤكد docker exec headscale headscale version الإصدار الجاري، ويعرض docker logs --follow headscale السجلات.

4. 04

   أنشئ مستخدمًا وولّد مفتاح مصادقة

   ينظّم Headscale الأجهزة في «مستخدمين» (كانوا يُسمّون سابقًا namespaces). أنشئ واحدًا ثم دوّن معرّفه الرقمي: يتوقع الخيار --user في preauthkeys create هذا المعرّف لا الاسم.

   docker exec headscale headscale users create myteam
   docker exec headscale headscale users list
   docker exec headscale headscale preauthkeys create --user 1 --reusable --expiration 24h

   من دون --reusable لا يصلح المفتاح إلا مرة واحدة، ومن دون --expiration تنتهي صلاحيته بعد ساعة. انسخ المفتاح المعروض — ستستخدمه لتسجيل كل جهاز.

5. 05

   سجّل جهازًا

   على أي جهاز مثبّت عليه عميل Tailscale الرسمي، وجّهه إلى نسخة Headscale الخاصة بك: tailscale up --login-server https://vpn.yourdomain.com --authkey <your-preauth-key>. يظهر الجهاز في قائمة عُقد Headscale خلال ثوانٍ: docker exec headscale headscale nodes list. من دون مفتاح، يفتح العميل صفحة تعرض معرّف مصادقة؛ وافق عليه من الخادم بالأمر docker exec headscale headscale auth register --user myteam --auth-id <AUTH_ID>. بعد التسجيل، تتواصل الأجهزة عبر عنوان IP الشبكة (100.64.x.y) أو عبر اسم مضيف magic DNS.

6. 06

   عرّف سياسات التحكم في الوصول

   ما دامت لا توجد سياسة محمّلة، يسمح Headscale بكل حركة المرور بين العُقد — وهذا مقبول لفريق صغير موثوق، لا حين تتجاور حواسيب المطورين والمتعاقدين وخوادم الإنتاج. أنشئ /opt/headscale/config/policy.hujson وصرّح به في config.yaml عبر policy.path: /etc/headscale/policy.hujson. يستخدم Headscale صيغة HuJSON نفسها المستخدمة في Tailscale: عرّف مجموعات المستخدمين، ووسِم الأجهزة كخوادم أو محطات عمل، واكتب قواعد تحدد أي المجموعات تصل إلى أي المنافذ. يوصي المشروع باستخدام Grants بدل ACL التي يعدّها Tailscale قديمة. تحقق من الملف بالأمر headscale policy check --file <file> ثم أعد التحميل: لا تُقرأ السياسة إلا عند إعادة التحميل (docker kill --signal=HUP headscale، أو systemctl reload headscale في التثبيت الأصلي). احفظ هذا الملف في مستودع Git خاص لتحتفظ بسجل تغييرات الوصول.

7. 07

   أول تسجيل دخول

   لا يملك Headscale واجهة ويب ولا حسابات: إنه خادم التحكم في شبكتك الخاصة، ويُدار عبر سطر الأوامر. عبر SSH: docker exec -it headscale headscale users create monuser، ثم المفتاح بالأمر preauthkeys create --user <ID> --reusable --expiration 24h، واربط أجهزتك بالأمر tailscale up --login-server https://<your-domain> --authkey <key>. يمكن للتطبيقات الرسومية أيضًا استهداف خادم مخصص: على macOS اضغط Option مع النقر على أيقونة Tailscale، ثم قائمة Debug ثم Custom Login Server؛ وعلى iOS الخيار Use custom coordination server في قائمة تسجيل الدخول؛ وعلى Android الخيار Use an alternate server؛ وعلى Windows الأمر tailscale login --login-server في PowerShell.

من دون Docker: حزمة ‎.deb الرسمية

ثبّت Headscale عبر حزمة ‎.deb

1. 08

   نزّل الحزمة وثبّتها

   احصل على حزمة الإصدار المطلوب من صفحة الإصدارات على GitHub، بحسب معمارية جهازك (amd64 أو arm64)، وثبّتها عبر apt الذي يحلّ الاعتماديات:

   HEADSCALE_VERSION="0.29.7"
   HEADSCALE_ARCH="amd64"
   wget --output-document=headscale.deb \
     "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
   sudo apt install ./headscale.deb

   ثم تحقق: يجب أن يعرض headscale version القيمة 0.29.7.

2. 09

   عدّل التهيئة

   تضع الحزمة التهيئة في /etc/headscale/config.yaml ومثالًا محدّثًا في /usr/share/doc/headscale/examples/config-example.yaml. غيّر المفاتيح نفسها كما في Docker (server_url وdatabase وdns.base_domain)، لكن أبقِ listen_addr: 127.0.0.1:8080: تعمل الخدمة على المضيف، ولا ينبغي أن يصل إليها إلا الوكيل العكسي. تقيم البيانات في /var/lib/headscale.

3. 10

   أعد تشغيل الخدمة وتحقق منها

   أعد تشغيل الخدمة لتعيد قراءة التهيئة، ثم افحص حالتها وسجلاتها:

   sudo systemctl restart headscale
   sudo systemctl status headscale
   sudo journalctl -u headscale -f

   يجب أن يظهر Active: active (running). عند أول تشغيل، أكثر الأخطاء شيوعًا هي server_url بلا المخطط https://، ونطاق MagicDNS مطابق لنطاق الخادم.

4. 11

   استخدم سطر الأوامر دون صلاحيات root

   يتحدث سطر الأوامر إلى الخدمة عبر مقبس Unix /var/run/headscale/headscale.sock، الذي لا يصل إليه افتراضيًا إلا المستخدم headscale وroot. استخدم sudo، أو نفّذ الأوامر بصفة المستخدم headscale، أو أضف حسابك إلى المجموعة headscale. تحقق من الوصول بالأمر headscale users list.

قدّم Headscale عبر HTTPS خلف Nginx

map $http_upgrade $connection_upgrade {
  default keep-alive;
  ''      close;
}

server {
  listen 80;
  server_name vpn.yourdomain.com;
  location = /generate_204 { return 204; }
  location / { return 301 https://$server_name$request_uri; }
}

server {
  listen 443 ssl;
  http2 on;
  server_name vpn.yourdomain.com;
  ssl_certificate     /etc/letsencrypt/live/vpn.yourdomain.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/vpn.yourdomain.com/privkey.pem;

  location / {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_pass http://127.0.0.1:8080;
  }
}

trusted_proxies:
  - 127.0.0.1/32
  - ::1/128

تحقق من أن العُقد ترى بعضها

افحص الشبكة المتشابكة من عميل

1. 12

   اقرأ حالة الشبكة

   على عقدة مسجّلة، شغّل tailscale status. يسرد الأمر النظراء مع عنوان IP الشبكة واسمهم ونوع الارتباط: تعني direct أن نفق WireGuard قائم دون وسيط، وتعني relay أنه يمر عبر مرحّل DERP — يعمل، لكن بزمن استجابة أعلى.

2. 13

   اختبر الاتصال

   خذ عنوان IP أحد النظراء من tailscale status ثم نفّذ ping 100.64.0.2، أو الأفضل tailscale ping <node-name> الذي يبيّن هل وصل الرد مباشرة أم عبر مرحّل. إذا ظهر النظير لكنه لا يستجيب، يقيس tailscale netcheck زمن الاستجابة نحو كل منطقة DERP ويكشف UDP صادرًا محجوبًا.

3. 14

   اختبر حل أسماء MagicDNS

   مع dns.magic_dns: true، تستجيب كل عقدة لاسمها القصير واسمها الكامل: ping node-name أو ping node-name.mesh.yourdomain.com. لا حاجة إلى أي سجل DNS عام لهذه الأسماء الداخلية. إذا فشل الحل، يعرض tailscale dns status تهيئة DNS التي استلمها العميل من الخادم.

حالة استخدام: SSH بين خوادم VPS دون كشف المنفذ 22

اقصر SSH على الشبكة المتشابكة

1. 15

   حدّد الواجهة وعنوان الشبكة

   على كل خادم VPS، ينشئ عميل Tailscale الواجهة tailscale0. يعرض tailscale ip -4 عنوان الشبكة للجهاز؛ دوّن عنوان خادم الإنتاج، مثلًا 100.64.0.3.

2. 16

   اسمح بـ SSH عبر tailscale0 فقط

   على خادم الإنتاج، اسمح بـ SSH على واجهة الشبكة المتشابكة قبل رفضه في غيرها — يطبّق UFW أول قاعدة مطابقة:

   ufw allow in on tailscale0 to any port 22 proto tcp
   ufw deny 22/tcp
   ufw enable
   ufw status verbose

   لم يعد المنفذ 22 متاحًا من الإنترنت، لكنه يبقى مفتوحًا لكل عُقد الشبكة التي تسمح بها سياستك.

3. 17

   اتصل عبر الشبكة المتشابكة

   من خادم التطوير أو من محطة عملك المسجّلة، اتصل عبر عنوان IP أو اسم MagicDNS: ssh [email protected] أو ssh [email protected]. يمر كل شيء داخل النفق المشفّر؛ ثم حدّد في سياسة Headscale أي المجموعات يمكنها الوصول إلى المنفذ 22 على هذا الخادم.

انقل فريقًا يعمل حاليًا على Tailscale

انقل العملاء إلى Headscale

1. 18

   استرجع سياسة الوصول

   انسخ ملف سياسة الـ tailnet من محرر Access controls في لوحة Tailscale وابدأ منه: صيغة HuJSON هي نفسها. افحصه بالأمر headscale policy check قبل الانتقال — فبعض الوظائف، مثل IP sets، غير مدعومة، ولا يتوفر إلا جزء من autogroups.

2. 19

   افصل كل عميل ثم أعد وصله

   على Linux أو من سطر الأوامر، نفّذ تسجيل الخروج ثم إعادة الاتصال بمفتاح مصادقة مسبقة:

   tailscale logout
   tailscale up --login-server https://vpn.yourdomain.com --authkey <PREAUTHKEY>

   على macOS وiOS وAndroid وWindows، سجّل خروج الحساب من التطبيق، ثم أضف الخادم المخصص كما ورد أعلاه.

3. 20

   ابدأ بأجهزة الاختبار

   انقل أولًا محطة عمل وخادمًا للاختبار، وتحقق من tailscale status ومن حل الأسماء، ثم أجهزة التطوير، والإنتاج في الأخير. ما دامت بعض الأجهزة في الجهة الأخرى، فلن ترى الشبكتان بعضهما: خطّط لنقل الخدمة وعملائها في النافذة الزمنية نفسها.

4. 21

   أغلق حساب Tailscale أو خفّض خطته

   بعد نقل كل العُقد والتحقق منها، أغلق الـ tailnet أو عد إلى خطة Personal إن كان لديك استخدام شخصي. ولّد مفتاح مصادقة مسبقة جديدًا للتسجيلات القادمة بدل الاحتفاظ بمفتاح الانتقال إلى ما لا نهاية.

Headscale مقابل Tailscale Cloud

Tailscale Personal وTailscale Standard وHeadscale

مرّر الجدول أفقيًا

ما لا يحل Headscale محله

النسخ الاحتياطي والترقيات

• خذ نسخة احتياطية قبل كل ترقية: يطبّق Headscale ترحيلات قاعدة البيانات عند تشغيل الإصدار الجديد. أوقف الخدمة، وانسخ التهيئة والبيانات، ثم أعد التشغيل: cd /opt/headscale && docker compose stop, cp -aR /opt/headscale /opt/headscale.backup-$(date +%Y%m%d%H%M%S), docker compose up -d.
• يحتوي مجلد البيانات على db.sqlite وnoise_private.key: فقدان هذا المفتاح يغيّر هوية الخادم ويُجبر كل العُقد على إعادة التسجيل. انسخه أيضًا خارج الخادم، إلى تخزين كائنات مثلًا.
• ترقَّ إصدارًا بعد إصدار: يشترط المشروع المرور بكل إصدار ثانوي مستقر (مثلًا 0.27 ثم 0.28 ثم 0.29)، دائمًا في آخر تصحيح له، دون تخطي أي منها.
• اقرأ ملاحظات الإصدار على GitHub قبل كل ترقية: فهي تنبّه إلى تغييرات التهيئة الكاسرة. ثم قارن ملف config.yaml لديك بملف المثال الخاص بالإصدار الجديد.

استكشاف الأعطال: الأخطاء الأكثر شيوعًا

• لا ينجح العميل في التسجيل: تحقق من أن https://vpn.yourdomain.com/health يستجيب من الخارج، وأن server_url يطابق نطاق الشهادة تمامًا، وأن الوكيل يمرّر ترويستي Upgrade وConnection.
• اتصالات relay بدل direct: يحجب NAT صارم أو جدار ناري حركة UDP بين العقدتين. شغّل tailscale netcheck على الطرفين لمعرفة ما يُحجب؛ تبقى الحركة ممكنة عبر مرحّلات DERP.
• عقدة تظهر بحالة offline: وصل العميل إلى الخادم لكنه لا يحافظ على الجلسة. افحص systemctl status tailscaled وjournalctl -u tailscaled على العقدة؛ والسبب الأكثر شيوعًا جدار ناري محلي يقطع الاتصالات الصادرة.
• يرفض Headscale التشغيل بعد ترقية: أُعيدت تسمية مفتاح تهيئة أو حُذف. يذكره السجل باسمه؛ ارجع إلى ملف المثال الخاص بالإصدار المثبّت.
• لا يحل MagicDNS الأسماء: تحقق من أن dns.magic_dns على true وأن dns.base_domain يختلف عن نطاق server_url، ثم أعد وصل العميل ليستلم تهيئة DNS الجديدة.