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

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

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

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

اگر در واقع به دنبال سروری هستید که تمام ترافیک شما از آن خارج شود، یک mesh پیچیدگی بیشتری از نیاز شما دارد. یک VPN ساده با WireGuard روی یک VPS یا یک exit node در Tailscale این کار را با سربار اجرایی بسیار کمتری انجام می‌دهد.

اجزای واقعی پشته (stack)

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

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

دو سرویس دیگر نیز وجود دارند که تا زمانی که در اعلان (prompt) تأیید نکنید، غیرفعال می‌مانند. سرویس 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 برای چالش گواهی و هدایت (redirect) به HTTPS، پورت TCP 443 برای داشبورد، API، سیگنال و ترافیک رله، و پورت 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ها است و دلیل اصلی این است که چرا با وجود تنظیمات صحیح در ufw status، سرور همچنان اتصالات را رد می‌کند.

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

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

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

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

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

به‌جای آن، نسخه را ثابت (Pin) کنید. latest تغییر می‌کند، بنابراین اجرای همان دستور با فاصله دو هفته، دو نصب متفاوت ایجاد می‌کند و هیچ فایلی روی دیسک ثبت نمی‌کند که کدام نسخه پیکربندی شما را نوشته است. یک 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. آن دایرکتوری را به عنوان وضعیتی که باید حفظ کنید در نظر بگیرید، زیرا 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 ارتباط برقرار می‌کند و در صورت وجود گواهی نامعتبر، با خطاهای مبهم مواجه خواهید شد.

اتصال اولین همتا

کلاینت را روی هر ماشین لینوکسی نصب کنید؛ اگر می‌خواهید 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 نام دارند، به کسی کمک نمی‌کند.

برای کانتینرها و build agentهای کوتاه‌مدت، هنگام ایجاد کلید، آن را به عنوان 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 را با دستور headscale و از طریق یک فایل پیکربندی مدیریت می‌کنید. رابط‌های کاربری وب توسط جامعه کاربری وجود دارند، اما بخشی از پروژه اصلی نیستند. این مدل برای کسانی مناسب است که می‌خواهند وضعیت (state) آن‌ها در فایل‌ها باشد و تغییراتشان در سیستم کنترل نسخه ثبت شود.

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

اگر از قبل روی کلاینت‌های Tailscale سرمایه‌گذاری کرده‌اید یا می‌خواهید کوچک‌ترین control plane ممکن را داشته باشید، از Headscale استفاده کنید. اگر چندین نفر نیاز به مدیریت peerها دارند و می‌خواهید بدون سرهم‌بندی کردن اجزا، یک کنسول و SSO داشته باشید، NetBird را اجرا کنید.

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

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

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

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

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

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

داشبورد یک هشدار گواهی (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 اختصاصی نیاز دارم؟

خیر. نسخه‌های فعلی شامل یک user store داخلی هستند، بنابراین شما اولین حساب کاربری مدیر را در مرورگر در https://netbird.example.com ایجاد می‌کنید و پس از آن کاربران را از طریق داشبورد می‌افزایید. استفاده از یک OIDC provider خارجی اختیاری است و می‌توان آن را بعداً با چهار مقدار اضافه کرد: نام، 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 کلاینت اختصاصی خود، داشبورد مدیریتی و یکپارچه‌سازی با Identity Provider را در یک پشته (stack) واحد ارائه می‌دهد. اجرای Headscale سبک‌تر است و وضعیت خود را در فایل‌ها نگه می‌دارد. کار با NetBird برای افرادی که از ترمینال استفاده نمی‌کنند، ساده‌تر است.

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

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