آموزش راه اندازی سرور NetBird VPN روی VPS

مزایای میزبانی شخصی (self-hosting) سرور NetBird VPN

میزبانی شخصی سرور NetBird VPN، کنترل‌پلین (control plane) را روی یک VPS متعلق به شما قرار می‌دهد: بخشی که فهرست کلاینت‌ها (peers) را نگه می‌دارد، تصمیم می‌گیرد کدام ماشین به کدام دسترسی داشته باشد و به دو کلاینت کمک می‌کند تا پشت NAT (ترجمه آدرس شبکه) یکدیگر را پیدا کنند. تونل‌ها همچنان WireGuard هستند و مستقیماً بین ماشین‌های شما رمزنگاری می‌شوند. تفاوت در این است که هیچ شرکت خارجی، فهرست دستگاه‌ها یا جریان ورود (login flow) شما را در اختیار ندارد. درک دقیق مزایای این کار ضروری است، زیرا کنترل‌پلینِ میزبانی‌شده نیز هرگز کلیدهای رمزنگاری ترافیک شما را در اختیار ندارد و آنچه یک سرور هماهنگ‌کننده در صورت نفوذ واقعاً می‌تواند انجام دهد، محدودتر از آن چیزی است که اکثر افراد پیش از مطالعه درباره آن تصور می‌کنند.

NetBird بین دو موردی قرار می‌گیرد که احتمالاً از قبل می‌شناسید. این یک mesh overlay است، بنابراین کلاینت‌ها به‌جای ارسال همه ترافیک از طریق یک gateway، مستقیماً به یکدیگر متصل می‌شوند. همچنین این سرویس به‌طور کامل قابل میزبانی شخصی است که آن را در مقابل Headscale، سرور کنترل Tailscale با قابلیت میزبانی شخصی قرار می‌دهد. اگر تاکنون فقط از تونل‌های تک‌دروازه‌ای (single-gateway) استفاده کرده‌اید، ابتدا تفاوت بین WireGuard ساده و mesh overlay را مطالعه کنید، زیرا این مدل ذهنی همان چیزی است که بقیه این صفحه را برای شما مفید می‌کند.

اگر هدف شما صرفاً داشتن یک سرور است که تمام ترافیکتان از آن خارج شود، یک mesh پیچیدگی بیشتری از نیاز شما دارد. یک VPN ساده WireGuard روی یک VPS یا یک exit node در Tailscale این کار را با سربار اجرایی بسیار کمتری انجام می‌دهند. و اگر هدف، دسترسی به یک شبکه خصوصی به‌جای اتصال ماشین‌ها به یکدیگر است، یک subnet router در Tailscale روی یک VPS آن محدوده شبکه را به tailnet موجود شما معرفی می‌کند، بدون اینکه نیازی به پیاده‌سازی کل پشته (stack) زیر باشد.

پشته نرم‌افزاری در حال اجرا

ساختار این پشته اخیراً تغییر کرده است و بیشتر راهنماهای قدیمی، نسخه پیشین را توصیف می‌کنند. از اوت 2026 و در نسخه v0.76.2، اسکریپت quickstart به‌صورت پیش‌فرض یک فایل Compose با سه سرویس ایجاد می‌کند.

• netbird-server شامل API مدیریتی، سرویس سیگنالینگ، رله (relay) با یک STUN listener داخلی و یک ارائه‌دهنده هویت (identity provider) تعبیه‌شده است. در نسخه‌های قدیمی‌تر، این موارد کانتینرهای مجزایی بودند و ارائه‌دهنده هویت یک نصب مستقل Zitadel بود که باید ابتدا آن را می‌ساختید.
• dashboard کنسول وب مدیریتی است.
• traefik وظیفه TLS termination (پایان‌دهی امنیت لایه انتقال) را بر عهده دارد و در اولین اجرا، گواهی را از Let's Encrypt درخواست می‌کند.

دو سرویس دیگر نیز وجود دارند که تا زمانی که در پاسخ به پرسش مربوطه گزینه مثبت را انتخاب نکنید، غیرفعال می‌مانند. سرویس NetBird Proxy، سرویس‌های داخلی را روی نام‌های میزبان عمومی منتشر می‌کند. CrowdSec ترافیک مخرب را فیلتر می‌کند. برای ساخت یک شبکه مش (mesh) فعال به هیچ‌کدام از این دو نیاز نیست و هر دو در سرورهای کوچک، حافظه مصرف می‌کنند.

اگر از wg-easy در یک کانتینر Docker واحد به اینجا آمده‌اید، این تغییر به معنای افزایش تعداد اجزا است. آنچه در ازای این پیچیدگی به دست می‌آورید، سیاست‌های دسترسی، حساب‌های کاربری مجزا و همتایانی (peers) است که به‌جای عبور از یک gateway، مستقیماً به یکدیگر متصل می‌شوند.

پیش‌نیازهای شروع کار

داشتن یک نام دامنه عمومی الزامی است. داشبورد، API و رله همگی از پروتکل HTTPS روی پورت 443 استفاده می‌کنند و Traefik گواهی خود را از طریق چالش HTTP از Let's Encrypt دریافت می‌کند؛ این فرآیند نیازمند دامنه‌ای است که از اینترنت عمومی به VPS شما متصل شود. استفاده از آدرس IP خام در این جریان کارساز نیست.

یک رکورد A ایجاد کنید، netbird.example.com که به آدرس IPv4 عمومی VPS اشاره می‌کند، و پیش از اجرای هر دستوری منتظر بمانید تا این رکورد اعمال شود.

dig +short netbird.example.com

این دستور باید آدرس سرور شما را نمایش دهد. اجرای نصب‌کننده پیش از انتشار کامل DNS باعث می‌شود درخواست گواهی در همان شروع کار با شکست مواجه شود؛ تکرار این شکست‌ها منجر به برخورد با محدودیت‌های نرخ (rate limits) در Let's Encrypt می‌شود و مجبور خواهید شد یک ساعت برای تلاش مجدد صبر کنید.

سه پورت باید از طریق اینترنت در دسترس باشند: پورت TCP 80 برای چالش گواهی و هدایت به HTTPS، پورت TCP 443 برای داشبورد، API، ترافیک signal و relay، و پورت UDP 3478 برای STUN.

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw reload
sudo ufw status

این پورت‌ها را در فایروال شبکه ارائه‌دهنده VPS خود نیز باز کنید. این یک کنترل مجزا در اکثر پنل‌های VPS است و دلیل اصلی این است که چرا با وجود تنظیمات صحیح در ufw status، سرور همچنان اتصالات را رد می‌کند.

STUN (ابزارهای پیمایش نشست برای NAT) روشی است که از طریق آن یک کلاینت، آدرس و پورت عمومی اختصاص‌یافته توسط NAT خود را شناسایی می‌کند تا دو کلاینت بتوانند برای برقراری تونل مستقیم تلاش کنند. اگر پورت UDP 3478 مسدود باشد، کلاینت‌ها همچنان از طریق رله روی پورت TCP 443 متصل می‌شوند و در ظاهر همه چیز درست به نظر می‌رسد. اما در عوض، شما روی تمام کلاینت‌ها وضعیت Connection type: Relayed را مشاهده خواهید کرد و تمام ترافیک به‌جای ارتباط مستقیم بین کلاینت‌ها، از طریق VPS شما عبور می‌کند.

در سمت نرم‌افزار، به Docker به همراه افزونه Compose v2، و همچنین jq و curl نیاز دارید. اسکریپت نصب، وجود تمامی این موارد را بررسی کرده و در صورت نبود هرکدام متوقف می‌شود. اگر Docker روی این سرور جدید است، ابتدا Docker Compose را روی VPS راه‌اندازی کنید.

نصب سرور NetBird با اسکریپت quickstart

دستور تک‌خطی مستند شده، جدیدترین نسخه را مستقیماً به یک shell پایپ می‌کند:

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

به‌جای آن، نسخه را ثابت (Pin) کنید. latest تغییر می‌کند، بنابراین اجرای یک دستور مشابه با فاصله دو هفته، دو نصب متفاوت ایجاد می‌کند و هیچ فایلی روی دیسک ثبت نمی‌کند که کدام نسخه پیکربندی شما را نوشته است. یک نسخه تگ‌شده (tagged release) را دانلود کنید، آن را بخوانید و سپس اجرا کنید.

mkdir -p ~/netbird
cd ~/netbird
curl -fsSL -o getting-started.sh \
  https://github.com/netbirdio/netbird/releases/download/v0.76.2/getting-started.sh
less getting-started.sh
bash getting-started.sh

اسکریپت ابتدا دامنه را می‌پرسد:

Enter the domain you want to use for NetBird (e.g. netbird.my-domain.com):

سپس می‌پرسد که TLS چگونه مدیریت خواهد شد:

Which reverse proxy will you use?
  [0] Traefik (recommended - automatic TLS, included in Docker Compose)
  [1] Existing Traefik (labels for external Traefik instance)
  [2] Nginx (generates config template)
  [3] Nginx Proxy Manager (generates config + instructions)
  [4] External Caddy (generates Caddyfile snippet)
  [5] Other/Manual (displays setup documentation)
Enter choice [0-5] (default: 0):

گزینه [0] را انتخاب کنید. گزینه‌های 2 تا 5 یک قطعه پیکربندی می‌نویسند و سیم‌کشی (اتصال) را به عهده شما می‌گذارند؛ این کار برای سروری که از قبل یک proxy دارد صحیح است، اما برای یک سرور تازه اشتباه است. گزینه 0 سپس یک آدرس ایمیل برای Let's Encrypt می‌خواهد که برای هشدارهای انقضا استفاده می‌شود.

در نصب اول، به سرویس NetBird Proxy پاسخ منفی دهید. این سرویس به دو رکورد DNS دیگر، یعنی proxy.netbird.example.com و wildcard *.proxy.netbird.example.com نیاز دارد و برای یک mesh ساده کاری انجام نمی‌دهد. به CrowdSec نیز پاسخ منفی دهید. هر دو را می‌توان بعداً اضافه کرد.

اسکریپت در دایرکتوری فعلی می‌نویسد: docker-compose.yml، config.yaml با مجوز 600، dashboard.env و در صورت انتخاب Traefik بسته‌بندی‌شده، traefik-dynamic.yaml. آن دایرکتوری را به عنوان وضعیت (state) که باید حفظ کنید در نظر بگیرید، زیرا config.yaml کلیدی را نگه می‌دارد که داده‌ها را در store رمزنگاری می‌کند. از دست دادن آن چیزی نیست که با نصب مجدد حل شود.

docker compose ps
docker compose logs -f netbird-server

هر سرویس باید running را بخواند و لاگ سرور باید به جای ری‌استارت شدن در یک حلقه، پایدار شود. گواهی را جداگانه بررسی کنید:

docker compose logs traefik | grep -i acme

ACME (محیط مدیریت خودکار گواهی) پروتکلی است که Traefik برای دریافت گواهی از آن استفاده می‌کند. خطاها در اینجا تقریباً همیشه مربوط به DNS یا بسته بودن پورت 80 هستند.

ایجاد اولین حساب کاربری مدیر

https://netbird.example.com را باز کنید. در یک نصب تازه، به‌جای فرم ورود، صفحه‌ای برای راه‌اندازی اولیه نمایش داده می‌شود. یک آدرس ایمیل، یک نام و یک رمز عبور وارد کنید و سپس روی Create Account کلیک کنید. این حساب به اولین مدیر تبدیل می‌شود و صفحه به فرم ورود تغییر مسیر می‌دهد.

این حساب در مخزن کاربری اختصاصی NetBird ذخیره می‌شود که توسط یک ارائه‌دهنده هویت (Identity Provider) تعبیه‌شده در کانتینر netbird-server مدیریت می‌گردد. هیچ سرویس خارجی در این فرآیند دخیل نیست. این بزرگ‌ترین تغییر نسبت به نسخه self-hosted یک سال پیش NetBird است؛ زمانی که برای یک نصب فعال، ابتدا باید Zitadel یا Keycloak را راه‌اندازی می‌کردید و پیش از شروع هر کاری، چهار مقدار OIDC (OpenID Connect) را در setup.env کپی می‌کردید.

اگر به‌جای صفحه راه‌اندازی با هشدار گواهی مرورگر مواجه شدید، به این معنی است که گواهی صادر نشده است. پیش از ادامه، این مشکل را برطرف کنید؛ زیرا داشبورد از طریق همان نام دامنه با API ارتباط برقرار می‌کند و در صورت وجود گواهی نامعتبر، با خطاهای گیج‌کننده‌ای مواجه خواهید شد.

اتصال اولین peer

کلاینت را روی هر ماشین لینوکسی نصب کنید؛ اگر می‌خواهید VPS خودتان نیز بخشی از mesh باشد، آن را روی همان VPS نصب کنید:

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

در توزیع‌های Debian و Ubuntu، این اسکریپت مخزن بسته‌های NetBird را پیکربندی کرده و سپس کلاینت را از طریق apt نصب می‌کند، بنابراین مدیریت بسته در هر صورت کنترل آن را در دست می‌گیرد. اگر اجرای مستقیم اسکریپت در shell برای شما خوشایند نیست، ابتدا آن را با curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh ذخیره کنید و پیش از اجرای sh install.sh، محتوای آن را بخوانید. در هر صورت، از نصب صحیح اطمینان حاصل کنید:

apt-cache policy netbird

netbird کلاینت خط فرمان و daemon است. netbird-ui برنامه tray دسکتاپ است و سرورهای headless نیازی به آن ندارند.

اکنون کلاینت را به سمت سرور خود هدایت کنید:

sudo netbird up --management-url https://netbird.example.com

اگر --management-url را حذف کنید، کلاینت با سرویس میزبانی‌شده NetBird ثبت می‌شود، زیرا این مقدار پیش‌فرض در زمان کامپایل است. دستور همچنان با موفقیت اجرا می‌شود، ماشین یک آدرس دریافت می‌کند، اما داشبورد self-hosted شما خالی می‌ماند. این اشتباهی است که تقریباً همه یک بار مرتکب می‌شوند.

این دستور یک URL چاپ می‌کند که باید برای تکمیل ورود به سیستم، آن را در مرورگر باز کنید. پس از آن:

netbird status
ip addr show wt0

چهار خط خروجی را از netbird status بخوانید: Management: Connected، Signal: Connected، یک خط Relays: که تمام relayهای موجود را گزارش می‌دهد، و یک NetBird IP: در محدوده overlay. wt0 رابط WireGuard است که NetBird ایجاد می‌کند و باید همان آدرس را داشته باشد.

اتصال یک ماشین دوم به صورت خودکار با استفاده از setup key

ورود از طریق مرورگر برای ماشینی که فاقد رابط گرافیکی است و کاربری پشت آن حضور ندارد، امکان‌پذیر نیست. یک setup key در واقع توکن پیش‌احراز‌هویتی است که ماشین را بدون نیاز به مراحل تعاملی ثبت می‌کند. این کلید را می‌توانید در داشبورد و در بخش Setup Keys ایجاد کنید.

دو نوع کلید وجود دارد. کلید یک‌بارمصرف (one-off) دقیقاً یک ماشین را احراز هویت کرده و سپس باطل می‌شود. کلید قابل‌استفاده مجدد (reusable) تعداد زیادی ماشین را ثبت می‌کند و می‌توان برای آن سقف تعداد تعیین کرد. هر دو نوع کلید دارای تاریخ انقضا هستند و هر دو می‌توانند peer جدید را به‌طور خودکار به یک گروه اختصاص دهند تا قوانین دسترسی آن گروه، بلافاصله پس از ظاهر شدن ماشین اعمال شود.

sudo netbird up --setup-key <SETUP-KEY> \
  --management-url https://netbird.example.com \
  --hostname build-runner-01

--hostname نامی را که در داشبورد نمایش داده می‌شود، تعیین می‌کند. بدون آن، peer از نامی استفاده می‌کند که ماشین برای خود انتخاب کرده است و وجود لیستی از ورودی‌ها که همگی ubuntu نام دارند، کمکی به مدیریت شبکه نمی‌کند.

برای کانتینرها و agentهای build کوتاه‌مدت، هنگام ایجاد کلید، گزینه ephemeral را فعال کنید. peerهایی که با کلید ephemeral ثبت شده‌اند، در صورتی که بیش از 10 دقیقه آفلاین باشند، به‌طور خودکار حذف می‌شوند؛ این کار باعث می‌شود لیست peerها از ورودی‌های بلااستفاده پاک بماند.

یک محدودیت که باید پیش از برنامه‌ریزی با setup keyها در نظر بگیرید: منقضی کردن یا حذف یک کلید، ثبت‌نام‌های جدید را متوقف می‌کند، اما ماشین‌هایی را که قبلاً با آن کلید ثبت شده‌اند، قطع نمی‌کند. برای لغو دسترسی یک ماشین، باید آن peer را حذف کنید.

آیا همچنان به یک ارائه‌دهنده هویت (Identity Provider) مجزا نیاز دارید؟

برای یک نصب کوچک، خیر. مخزن کاربری داخلی، حساب‌هایی را که از طریق داشبورد ایجاد می‌شوند مدیریت می‌کند و این برای تعداد کمی از کاربران کافی است.

زمانی به یک ارائه‌دهنده هویت خارجی نیاز دارید که از قبل یکی داشته باشید و نخواهید لیست دومی از کاربران ایجاد کنید. NetBird هر ارائه‌دهنده‌ای را که از پروتکل OIDC پشتیبانی کند، می‌پذیرد. یک کلاینت OIDC محرمانه (confidential) در ارائه‌دهنده خود ثبت کنید و سپس آن را در داشبورد NetBird با چهار مقدار اضافه کنید: نام، client ID، client secret و issuer. NetBird یک URL برای تغییر مسیر (redirect URL) به شما می‌دهد تا آن را در ارائه‌دهنده خود وارد کنید. ادغام‌های از پیش تعریف‌شده برای Google، Microsoft Entra ID، Okta، Zitadel، Keycloak، Authentik و Pocket ID وجود دارد و سایر موارد به عنوان OIDC عمومی (generic) اضافه می‌شوند. اگر در حال حاضر از Authentik به عنوان سرویس Single Sign-On خودمیزبان استفاده می‌کنید، این همان مسیری است که باعث می‌شود به جای دو لیست، تنها یک لیست از حساب‌های کاربری داشته باشید.

ورود محلی (Local login) پس از افزودن یک ارائه‌دهنده همچنان در دسترس باقی می‌ماند و هر ارائه‌دهنده‌ای که پیکربندی شده باشد در صفحه ورود ظاهر می‌شود. یک حساب مدیریتی محلی با رمز عبور قوی نگه دارید. در صورت خرابی پیکربندی OIDC، این کار راهی برای دسترسی به سیستم برای شما باقی می‌گذارد.

NetBird یا Headscale: کدام کنترل پلین (control plane) را باید اجرا کنید؟

هر دو ابزار یک وابستگی مشابه را حذف می‌کنند: سرور کنترل میزبانی‌شده‌ای که کلاینت‌های شما در حالت عادی به آن متصل می‌شوند. این دو پروژه از نظر ساختار با یکدیگر متفاوت هستند.

Headscale پیاده‌سازی مجدد سرور کنترل Tailscale است و شما همچنان از کلاینت‌های رسمی Tailscale استفاده می‌کنید. هیچ کنسول وب رسمی برای آن وجود ندارد. شما کاربران و کلیدهای پیش‌احراز هویت (pre-authentication keys) را با دستور headscale و از طریق یک فایل پیکربندی مدیریت می‌کنید. رابط‌های کاربری وب توسط جامعه کاربری توسعه یافته‌اند و بخشی از پروژه اصلی نیستند. این مدل برای کسانی مناسب است که می‌خواهند وضعیت (state) سیستم در فایل‌ها ذخیره شود و تغییرات در سیستم کنترل نسخه (version control) ثبت گردد.

NetBird کل محصول را ارائه می‌دهد: کلاینت اختصاصی، داشبورد اختصاصی، یک ارائه‌دهنده هویت (identity provider) داخلی و سیاست‌های دسترسی که در مرورگر ویرایش می‌شوند. این مدل قطعات متحرک بیشتری روی VPS شما ایجاد می‌کند، اما برای تحویل به همکارانی که هرگز ترمینال را باز نمی‌کنند، بسیار کم‌دردسرتر است.

اگر از قبل از کلاینت‌های Tailscale استفاده می‌کنید یا می‌خواهید کوچک‌ترین کنترل پلین ممکن را داشته باشید، Headscale را اجرا کنید. اگر چندین نفر نیاز به مدیریت همتایان (peers) دارند و می‌خواهید بدون سرهم‌بندی اجزای مختلف، یک کنسول و قابلیت SSO داشته باشید، NetBird را انتخاب کنید. پیش از انتخاب نهایی، بررسی کنید که طرح رایگان Tailscale دقیقاً چه مواردی را پوشش می‌دهد، زیرا گروهی که شامل حداکثر شش کاربر با تعداد نامحدود دستگاه باشد، هزینه‌ای برای کنترل پلین میزبانی‌شده نمی‌پردازد و ممکن است اصلاً دلیلی برای اجرای آن نداشته باشد. فراتر از این سقف، هزینه بر اساس تعداد افراد افزایش می‌یابد، نه تعداد ماشین‌ها؛ بنابراین محاسبه هزینه Tailscale برای گروه شما عددی را به دست می‌دهد که می‌توانید آن را با هزینه VPS و زمانی که صرف نگهداری این پشته (stack) می‌کنید، مقایسه کنید.

حداقل مشخصات VPS برای اجرای این سرویس چقدر است؟

حداقل مشخصات مستندشده، 1 هسته CPU و 2 گیگابایت حافظه رم است. با توجه به اینکه مدیریت کاربران اکنون به‌صورت محلی انجام می‌شود، یادداشت‌های خود NetBird حداقل رم مورد نیاز را نزدیک به 1 گیگابایت اعلام کرده‌اند؛ این در حالی است که در ساختار قدیمی که شامل استقرار کامل Zitadel بود، به 2 تا 4 گیگابایت رم نیاز داشتیم. پیشنهاد می‌شود 2 گیگابایت رم تهیه کنید. این فضای اضافی به شما اجازه می‌دهد تا هنگام ارتقا، ایمیج‌های جدید دانلود شوند در حالی که ایمیج‌های قدیمی هنوز روی دیسک قرار دارند.

در یک سرور کوچک، حذف سه مورد ایمن است. از سرویس NetBird Proxy صرف‌نظر کنید؛ این سرویس برای انتشار سرویس‌های داخلی روی نام‌های دامنه عمومی است و ارتباطی به اتصال کلاینت‌ها (peers) به یکدیگر ندارد. از نصب CrowdSec صرف‌نظر کنید؛ بهتر است آن را بعداً به سروری که در معرض اینترنت است اضافه کنید تا اینکه از همان روز اول درگیر آن شوید. از همان دیتابیس پیش‌فرض SQLite در حجم netbird_data استفاده کنید و تنها زمانی به PostgreSQL مهاجرت کنید که استقرار خود را بین چندین ماشین تقسیم کرده‌اید یا با همزمانی (concurrency) واقعی مواجه شده‌اید؛ این کار طبق مستندات، مهاجرتی است که می‌توانید بعداً انجام دهید.

رله (relay) تنها مؤلفه‌ای است که نمی‌توانید آن را حذف کنید. دو کلاینتی که NAT آن‌ها برای هر مقصد یک پورت متفاوت اختصاص می‌دهد، هرگز نمی‌توانند تونل مستقیم برقرار کنند؛ بنابراین رله تنها مسیری است که باعث می‌شود آن‌ها اصلاً کار کنند. غیرفعال کردن آن حافظه بسیار کمی آزاد می‌کند و باعث ایجاد اختلالاتی در اتصالات می‌شود که عیب‌یابی آن‌ها دشوار است.

زمانی که یک سرور دیگر پاسخگو نبود، رله‌ها اولین چیزی هستند که باید به سرور دیگری منتقل شوند. یک رله مستقل با NB_LISTEN_ADDRESS، NB_EXPOSED_ADDRESS، NB_AUTH_SECRET و NB_ENABLE_STUN اجرا می‌شود. رمز مشترک (shared secret) باید در رله و سرور اصلی دقیقاً یکسان باشد، در غیر این صورت کلاینت‌ها در احراز هویت با آن شکست می‌خورند.

حالت‌های شکست و آنچه مشاهده خواهید کرد

داشبورد هشدار گواهی (certificate warning) نمایش می‌دهد. Traefik موفق به دریافت گواهی نشده است. دستور docker compose logs traefik | grep -i acme را اجرا کنید. این مشکل دو علت دارد. یا dig +short netbird.example.com هنوز این VPS را بازنمی‌گرداند، یا پورت TCP 80 در جایی بین Let's Encrypt و کانتینر بسته است؛ این مورد معمولاً در فایروال شبکهٔ ارائه‌دهنده رخ می‌دهد، نه در ufw. پیش از تلاش مجدد در یک حلقه، علت را برطرف کنید، زیرا اعتبارسنجی‌های ناموفق محدودیت نرخ (rate limit) دارند و دسترسی شما به تلاش‌های بعدی برای یک ساعت مسدود خواهد شد.

کلاینت می‌گوید متصل شده اما داشبورد خالی است. کلاینت با سرویس میزبانی‌شدهٔ NetBird ثبت شده است، زیرا --management-url وجود نداشت. دستور netbird status --detail را اجرا کنید و خط Management: را بخوانید که نام سروری که کلاینت واقعاً با آن در ارتباط است را نشان می‌دهد. مشاهده Management: Connected to https://api.netbird.io:443 به این معنی است که کلاینت به فضای ابری (cloud) متصل شده است. دستور sudo netbird down را اجرا کرده و سپس دوباره sudo netbird up --management-url https://netbird.example.com را بزنید.

همهٔ همتاها (peers) وضعیت Connection type: Relayed را نشان می‌دهند. هیچ تونل مستقیمی شکل نمی‌گیرد، بنابراین تمام ترافیک از VPS شما عبور می‌کند و یک گام (hop) به تأخیر اضافه می‌شود. پورت UDP 3478 را در فایروال VPS و فایروال ارائه‌دهنده بررسی کنید، زیرا STUN همان چیزی است که به یک همتا اجازه می‌دهد آدرس عمومی و پورت خود را تشخیص دهد. دستور netbird status --detail همچنین Direct: false و انواع کاندیداهای ICE (برقراری اتصال تعاملی) را برای هر همتا چاپ می‌کند که نشان می‌دهد تلاش تا چه مرحله‌ای پیش رفته است. در برخی شبکه‌ها، relayed تنها نتیجهٔ ممکن است و مشکلی وجود ندارد.

یک همتا ملحق می‌شود اما به هیچ‌چیز دسترسی ندارد. بودن در شبکهٔ مش (mesh) به این معنی نیست که دو همتا می‌توانند با هم صحبت کنند. سیاست‌های دسترسی (access policies) این موضوع را تعیین می‌کنند و گروهی که هیچ سیاستی به آن متصل نباشد، به هیچ‌چیز دسترسی نخواهد داشت. پیش از شروع عیب‌یابی مسیرها و فایروال‌ها، سیاست را در داشبورد بررسی کنید.

دستور netbird status مشکل دیمون (daemon) را گزارش می‌کند. سرویس در حال اجرا نیست. از sudo netbird service status و sudo netbird service start استفاده کنید. لاگ‌های کلاینت در /var/log/netbird/client.log قرار دارند. برای هر موردی که نمی‌توانید تشخیص دهید، netbird debug bundle --anonymize --system-info لاگ‌ها، وضعیت، مسیرها، تنظیمات DNS و وضعیت فایروال را در یک آرشیو جمع‌آوری می‌کند.

پشتیبان‌گیری و ارتقا

دو مورد کل نصب را تشکیل می‌دهند: دایرکتوری حاوی docker-compose.yml و config.yaml، و Docker volume که پایگاه داده و کلیدهای رمزنگاری را در خود نگه می‌دارد. از آن‌ها با هم پشتیبان بگیرید. config.yaml کلیدی را نگه می‌دارد که داده‌ها را در مخزن رمزنگاری می‌کند، بنابراین کپی پایگاه داده بدون آن، به داده‌هایی غیرقابل خواندن بازگردانی می‌شود.

docker volume ls
docker compose down
sudo tar czf netbird-config.tgz -C ~ netbird
docker run --rm -v netbird_netbird_data:/data -v "$PWD":/backup \
  alpine tar czf /backup/netbird-data.tgz -C /data .
docker compose up -d

دستور Compose پیشوندهایی را با نام دایرکتوری پروژه به نام volumeها اضافه می‌کند، بنابراین volumeای که در netbird_data مستند شده است، معمولاً به صورت netbird_netbird_data ظاهر می‌شود. ابتدا docker volume ls را اجرا کنید و از نامی که چاپ می‌کند استفاده کنید، در غیر این صورت docker run در بالا با ایجاد بی‌سروصدای یک volume خالی و آرشیو نکردن هیچ داده‌ای، شکست می‌خورد. آرشیوها را خارج از VPS نگه دارید. اگر از قبل ابزار پشتیبان‌گیری دارید، restic یا BorgBackup بخش انتقال به خارج از سایت را مدیریت می‌کنند.

ارتقای سرور شامل یک pull و یک recreate است:

docker compose pull
docker compose up -d
docker compose ps

پیش از آنکه به این روش تکیه کنید، docker compose config | grep image: را اجرا کنید. هر تگی که latest را نشان می‌دهد باید به یک نسخه خاص پین شود، به همان دلیلی که اسکریپت نصب را پین کردید: شما می‌خواهید بدانید چه چیزی در حال اجراست و می‌خواهید نسخه‌ای داشته باشید که در صورت بروز مشکل در ارتقا، به آن بازگردید. کلاینت‌ها از طریق همان مدیر بسته‌ای که آن‌ها را نصب کرده است، ارتقا می‌یابند.

FAQ

آیا برای میزبانی شخصی NetBird به ارائه‌دهنده هویت (Identity Provider) اختصاصی نیاز دارم؟

خیر. نسخه‌های فعلی شامل یک مخزن کاربری داخلی هستند؛ بنابراین شما اولین حساب مدیر را در مرورگر و در آدرس https://netbird.example.com ایجاد می‌کنید و پس از آن کاربران را از طریق داشبورد می‌افزایید. استفاده از یک ارائه‌دهنده OIDC خارجی اختیاری است و می‌توان آن را بعداً با چهار مقدار نام، client ID، client secret و issuer اضافه کرد. راهنماهایی که پیشنهاد می‌کنند پیش از NetBird، سرویس Zitadel یا Keycloak را مستقر کنید، مربوط به تنظیماتی هستند که دیگر الزامی نیستند و دنبال کردن آن‌ها باعث می‌شود یک سرویس اضافی را به‌طور غیرضروری اجرا کنید.

چرا همه همتایان (peers) من وضعیت Connection type: Relayed را نشان می‌دهند؟

اتصالات مستقیم برقرار نمی‌شوند، بنابراین ترافیک از طریق relay روی VPS شما عبور می‌کند. دلیل معمول این است که پورت UDP 3478 مسدود شده است؛ این همان پورت STUN است که همتایان برای کشف آدرس عمومی و پورت خود از آن استفاده می‌کنند. آن را در فایروال VPS و فایروال شبکه ارائه‌دهنده خود باز کنید، سپس دوباره netbird status --detail را اجرا کرده و خط Direct: را بخوانید. در شبکه‌ای که NAT آن برای هر مقصد یک پورت متفاوت اختصاص می‌دهد، وضعیت relayed تنها نتیجه ممکن است و هیچ‌چیز اشتباه پیکربندی نشده است.

کلاینت من متصل شده اما داشبورد هیچ همتایی را نشان نمی‌دهد. چه اتفاقی افتاده است؟

کلاینت به‌جای سرور شما، با سرویس میزبانی‌شده NetBird ثبت شده است؛ این اتفاق زمانی رخ می‌دهد که --management-url حذف شود. دستور netbird status --detail سروری را که کلاینت با آن در ارتباط است در خط Management: چاپ می‌کند، بنابراین مقداری مانند https://api.netbird.io:443 این موضوع را تأیید می‌کند. دستور sudo netbird down و سپس sudo netbird up --management-url https://netbird.example.com را اجرا کنید تا همتا در داشبورد شما ظاهر شود.

تفاوت NetBird میزبانی‌شده شخصی با Headscale چیست؟

هر دو جایگزینی برای سرور کنترل میزبانی‌شده هستند که شما خودتان اجرا می‌کنید. Headscale فقط یک صفحه کنترل (control plane) است: شما آن را با دستور headscale و یک فایل پیکربندی مدیریت می‌کنید، کنسول وب رسمی ندارد و کلاینت‌های رسمی Tailscale را هدایت می‌کند. NetBird کلاینت اختصاصی، داشبورد مدیریتی و یکپارچه‌سازی با ارائه‌دهنده هویت را در همان پشته (stack) ارائه می‌دهد. اجرای Headscale سبک‌تر است و وضعیت خود را در فایل‌ها نگه می‌دارد. کار با NetBird برای افرادی که از ترمینال استفاده نمی‌کنند، ساده‌تر است.

سرور NetBird با میزبانی شخصی به چه اندازه VPS نیاز دارد؟

حداقل مقدار مستندشده، 1 هسته CPU و 2 گیگابایت حافظه است و 2 گیگابایت مقداری است که باید تهیه کنید. در نسخه‌های اخیر، حداقل نیاز عملی به حدود 1 گیگابایت کاهش یافته است، زیرا ارائه‌دهنده هویت اکنون به‌جای یک استقرار جداگانه، در دل برنامه تعبیه شده است. در حین نصب، از سرویس‌های اختیاری proxy و CrowdSec صرف‌نظر کنید و تا زمانی که واقعاً به PostgreSQL نیاز پیدا نکرده‌اید، از مخزن پیش‌فرض SQLite استفاده کنید.