آموزش راه اندازی سرور 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.80.0 و همچنین نسخه 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 گواهی خود را از Let's Encrypt با استفاده از چالش TLS-ALPN-01 دریافت می‌کند. این چالش روی پورت 443 پاسخ داده می‌شود و نیازمند دامنه‌ای است که از اینترنت عمومی به 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) روشی است که یک کلاینت از طریق آن آدرس عمومی و پورتی که NAT برایش تعیین کرده را می‌آموزد تا دو کلاینت بتوانند یک تونل مستقیم ایجاد کنند. اگر پورت UDP 3478 مسدود باشد، کلاینت‌ها همچنان از طریق رله روی پورت TCP 443 متصل می‌شوند و در ظاهر مشکلی دیده نمی‌شود. اما در عوض، شما روی تمام کلاینت‌ها Connection type: Relayed دریافت می‌کنید و تمام ترافیک به‌جای ارتباط مستقیم بین کلاینت‌ها، از طریق VPS شما عبور می‌کند.

در سمت نرم‌افزار، به Docker به همراه افزونه Compose v2، به‌علاوه jq و curl نیاز دارید. اسکریپت نصب، وجود Docker، Compose و 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 تغییر می‌کند، بنابراین اجرای همان دستور با فاصله دو هفته، دو نصب متفاوت ایجاد می‌کند و هیچ فایلی روی دیسک ثبت نمی‌کند که کدام نسخه پیکربندی شما را نوشته است. یک نسخه تگ‌شده را دانلود کنید، آن را بخوانید و سپس اجرا کنید.

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 تا 4 یک قطعه پیکربندی می‌نویسند و سیم‌کشی را به عهده شما می‌گذارند، و گزینه 5 فقط فایل Compose را می‌نویسد و مستندات راه‌اندازی را در ترمینال چاپ می‌کند. این کار روی سیستمی که از قبل یک پروکسی دارد درست است، اما روی یک سیستم تازه اشتباه است. گزینه 0 سپس یک آدرس ایمیل می‌خواهد که Traefik آن را با حساب Let's Encrypt شما ثبت می‌کند. پرامپت هنوز آن را آدرسی برای اعلان‌های گواهی می‌نامد، اما Let's Encrypt از تاریخ 4 ژوئن 2025 ارسال ایمیل‌های انقضا را متوقف کرده است، بنابراین مشکلات تمدید به‌جای صندوق ورودی شما، در لاگ Traefik ظاهر می‌شوند.

در نصب اول، به سرویس NetBird Proxy پاسخ منفی دهید. این سرویس به یک رکورد DNS دیگر نیاز دارد، یک CNAME با نام *.netbird.example.com که به netbird.example.com اشاره کند، و برای یک mesh ساده هیچ کاری انجام نمی‌دهد. پرامپت CrowdSec فقط زمانی ظاهر می‌شود که پروکسی فعال باشد، بنابراین رد کردن پروکسی، آن را نیز نادیده می‌گیرد. هر دو را می‌توان بعداً اضافه کرد.

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

docker compose ps
docker compose logs -f netbird-server

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

docker compose logs traefik | grep -i acme

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

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

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: کدام کنترل پلین را باید اجرا کنید؟

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

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

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

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

حداقل منابع مورد نیاز برای یک VPS چقدر است؟

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

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

رله (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 443 در جایی بین Let's Encrypt و کانتینر بسته است؛ این مشکل معمولاً در فایروال شبکه ارائه‌دهنده رخ می‌دهد، نه در ufw. چالش (challenge) روی پورت 443 پاسخ داده می‌شود، بنابراین باز بودن پورت 80 در اینجا کمکی نمی‌کند. پیش از تلاش مجدد در یک حلقه، علت را برطرف کنید، زیرا Let's Encrypt تنها اجازه 5 اعتبارسنجی ناموفق در هر ساعت برای هر نام دامنه را می‌دهد و اجرای حلقه باعث می‌شود تا زمان پر شدن مجدد این سهمیه، دسترسی شما برای تلاش‌های بعدی مسدود شود.

کلاینت می‌گوید متصل شده اما داشبورد خالی است. کلاینت با سرویس میزبانی‌شده 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) به تأخیر (latency) اضافه می‌شود. پورت UDP 3478 را در فایروال VPS و فایروال ارائه‌دهنده بررسی کنید، زیرا STUN همان پروتکلی است که به همتا اجازه می‌دهد آدرس عمومی و پورت خود را تشخیص دهد. دستور netbird status --detail همچنین Direct: false و انواع کاندیداهای ICE (مخفف interactive connectivity establishment) را برای هر همتا چاپ می‌کند که نشان می‌دهد تلاش تا چه مرحله‌ای پیش رفته است. در برخی شبکه‌ها، 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 کلاینت اختصاصی، داشبورد مدیریتی و یکپارچه‌سازی با ارائه‌دهنده هویت را در یک پشته واحد ارائه می‌دهد. اجرای Headscale سبک‌تر است و وضعیت خود را در فایل‌ها نگه می‌دارد. کار با NetBird برای افرادی که از ترمینال استفاده نمی‌کنند، ساده‌تر است.

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

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