آموزش راه اندازی سرور NetBird VPN روی VPS
با راهنمای گام به گام نصب NetBird روی VPS آشنا شوید. این آموزش شامل تنظیمات DNS و TLS، استفاده از setup keys برای اتصال خودکار و مقایسه فنی آن با Headscale است.
مزایای میزبانی شخصی (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 443 برای داشبورد، API، ترافیک سیگنال و رله، و چالش گواهی؛ و پورت UDP 3478 برای STUN. پورت TCP 80 باید بهصورت محلی آزاد باشد زیرا Traefik به آن متصل میشود، اما نیازی نیست که از بیرون در دسترس باشد. مسدود کردن دسترسی عمومی به پورت 80 تنها مانع از تغییر مسیر (redirect) HTTP به HTTPS میشود.
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 را نشان میدهند و ترافیک آنها بهجای ارتباط مستقیم (peer to peer)، از طریق VPS شما عبور میکند. کلاینتهای موجود در یک شبکه محلی (LAN) همچنان میتوانند با استفاده از آدرسهای محلی خود مستقیماً متصل شوند.
در بخش نرمافزاری، شما به Docker به همراه افزونه Compose v2، بهعلاوه jq و curl نیاز دارید. اسکریپت نصب، وجود Docker، Compose و jq را بررسی میکند و در صورت نبود هرکدام متوقف میشود. این اسکریپت از curl استفاده میکند اما آن را بررسی نمیکند، بنابراین ابتدا آن را نصب کنید. اگر Docker روی این سرور جدید است، ابتدا Docker Compose را روی VPS راهاندازی کنید.
پورتها در صورت عدم استفاده از reverse proxy پیشفرض
بدون Traefik، سرور ترکیبی همچنان مدیریت، سیگنال و رله را روی یک backend HTTP واحد ارائه میدهد، بنابراین لیست پورتها تغییر چندانی نمیکند. فایل Compose تولیدشده پورتهای زیر را منتشر میکند:
- TCP 8080، داشبورد، که بهصورت پیشفرض به 127.0.0.1 متصل است
- TCP 8081،
netbird-server، که بهصورت پیشفرض به 127.0.0.1 متصل است - UDP 3478، STUN، که مستقیماً منتشر میشود
پراکسی شخصی شما TLS را روی TCP 443 خاتمه میدهد و درخواستها را به آن دو پورت محلی هدایت میکند. STUN هرگز از پراکسی عبور نمیکند، بنابراین پورت UDP 3478 در هر صورت باید روی فایروال باز باشد. راهنماهایی که پورتهای جداگانهای برای gRPC مدیریت، gRPC سیگنال و رله ذکر میکنند، مربوط به ساختار قدیمی چند-کانتینری هستند.
تنها زمانی این روش را انتخاب کنید که سرور شما در حال حاضر برای سرویس دیگری TLS را خاتمه میدهد. در غیر این صورت، استفاده از Traefik همراه با بسته نرمافزاری، قوانین کمتر و خطاهای کمتری به همراه دارد.
نصب سرور 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، یعنی dashboard.env و config.yaml را مینویسد و مستندات راهاندازی را در ترمینال چاپ میکند. این کار برای سروری که از قبل یک proxy دارد درست است، اما برای یک سرور تازه، اشتباه است. گزینه 0 سپس یک آدرس ایمیل میخواهد که Traefik آن را با حساب Let's Encrypt شما ثبت میکند. پرامپت هنوز آن را آدرسی برای اعلانهای گواهی مینامد، اما Let's Encrypt از تاریخ 4 ژوئن 2025 ارسال ایمیلهای انقضا را متوقف کرده است، بنابراین مشکلات تمدید بهجای صندوق ورودی شما، در لاگ Traefik ظاهر میشوند.
در نصب اول، به سرویس NetBird Proxy پاسخ منفی دهید. این سرویس یک رکورد DNS دیگر میخواهد، یک CNAME با نام wildcard برای *.netbird.example.com که به netbird.example.com اشاره کند، و برای یک mesh ساده هیچ کاری انجام نمیدهد. پرامپت CrowdSec فقط زمانی ظاهر میشود که proxy فعال باشد، بنابراین رد کردن proxy باعث نادیده گرفتن آن نیز میشود. هر دو را میتوان بعداً اضافه کرد.
اسکریپت در دایرکتوری فعلی مینویسد: docker-compose.yml، config.yaml با مجوز 600، و dashboard.env. با Traefik همراه، فایلهای traefik-dynamic.yaml و proxy.env فقط زمانی اضافه میشوند که NetBird Proxy را فعال کنید. آن دایرکتوری را به عنوان وضعیت (state) که باید حفظ کنید در نظر بگیرید، زیرا config.yaml کلیدی را نگه میدارد که دادهها را در store رمزنگاری میکند. از دست دادن آن چیزی نیست که با نصب مجدد حل شود.
docker compose ps
docker compose logs -f netbird-serverهر سرویس باید running را بخواند و لاگ سرور باید پایدار شود و نه اینکه در یک حلقه مدام restart شود. گواهی را جداگانه مانیتور کنید:
docker compose logs traefik | grep -i acmeACME (محیط مدیریت خودکار گواهی) پروتکلی است که 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 netbirdnetbird کلاینت خط فرمان و 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 در واقع توکن پیشاحرازهویتی است که ماشین را بدون نیاز به مراحل تعاملی ثبت میکند. این کلید را میتوانید در داشبورد و در مسیر Settings → 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 کل محصول را بهصورت یک مجموعه کامل ارائه میکند: client اختصاصی، dashboard اختصاصی، identity provider داخلی و access policyهایی که از طریق browser ویرایش میشوند. این یعنی اجزای بیشتری روی VPS شما اجرا میشود و سپردن مدیریت آن به همکاری که قرار نیست هیچوقت terminal را باز کند، بسیار سادهتر است. اگر واقعاً در حال مقایسه NetBird با Tailscale میزبانیشده هستید، نه با Headscale، هر دو در لایه زیرین از WireGuard استفاده میکنند. بنابراین مقایسه NetBird و Tailscale تفاوتهای واقعی آنها را پوشش میدهد: چه کسی control plane را اجرا میکند، access ruleها چگونه نوشته میشوند و relayها چگونه traffic را منتقل میکنند.
اگر از قبل از کلاینتهای Tailscale استفاده میکنید یا به دنبال کوچکترین کنترل پلین ممکن هستید، از Headscale استفاده کنید. اگر چندین نفر نیاز به مدیریت کلاینتها (peers) دارند و میخواهید بدون سرهمبندی قطعات مختلف، یک کنسول و قابلیت SSO داشته باشید، NetBird را انتخاب کنید. پیش از انتخاب نهایی، بررسی کنید که طرح رایگان Tailscale دقیقاً چه مواردی را پوشش میدهد؛ زیرا یک گروه غیرتجاری که شامل حداکثر 6 کاربر باشد، برای استفاده از کنترل پلین میزبانیشده هزینهای نمیپردازد و از همان ابتدا به دستگاههای نامحدود برای کاربران و 50 منبع برچسبدار (tagged resources) دسترسی دارد و ممکن است اصلاً نیازی به اجرای سرور شخصی نداشته باشد. پس از عبور از این سقف، هزینه بر اساس تعداد افراد افزایش مییابد، نه تعداد ماشینها؛ بنابراین محاسبه هزینهای که Tailscale برای گروه شما در نظر میگیرد، عددی را به دست میدهد که میتوانید آن را با هزینه VPS و زمانی که صرف نگهداری این پشته (stack) میکنید، مقایسه کنید.
حداقل مشخصات VPS برای اجرای این سرویس چقدر است؟
حداقل مشخصات مستندشده، 1 هسته CPU و 2 گیگابایت حافظه رم است. پیشنهاد میشود 2 گیگابایت رم تهیه کنید.
در سرورهای کوچک، حذف سه مورد زیر بلامانع است. از نصب سرویس NetBird Proxy صرفنظر کنید؛ این سرویس برای انتشار سرویسهای داخلی روی نامهای دامنه عمومی کاربرد دارد و ارتباطی به اتصال مستقیم همتایان (peers) به یکدیگر ندارد. از CrowdSec نیز صرفنظر کنید؛ این ابزار تنها در کنار پروکسی توسط اسکریپت پیشنهاد میشود و بهتر است در آینده و پس از عمومیسازی سرور به آن اضافه شود، نه در روز اول. از همان ذخیرهساز پیشفرض SQLite در volume مربوط به 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 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 کلیدی را نگه میدارد که دادههای حساس در مخزن را رمزنگاری میکند، بنابراین کپی دیتابیس بدون آن، امکان بازیابی کلیدهای تنظیمات رمزنگاریشده و توکنهای API را فراهم نمیکند.
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 -dCompose پیشوند نام دایرکتوری پروژه را به نام volumeها اضافه میکند، بنابراین volumeای که در netbird_data مستند شده است، معمولاً به صورت netbird_netbird_data ظاهر میشود. ابتدا docker volume ls را اجرا کنید و از نامی که چاپ میکند استفاده کنید، در غیر این صورت docker run در بالا با ایجاد یک volume خالی و بدون آرشیو کردن چیزی، با شکست مواجه میشود. آرشیوها را خارج از VPS نگهداری کنید. اگر از قبل ابزار پشتیبانگیری دارید، restic یا BorgBackup بخش انتقال به خارج از سایت را مدیریت میکنند.
ارتقای سرور شامل pull کردن و بازسازی مجدد است:
docker compose pull
docker compose up -d
docker compose psپیش از آنکه به این روش تکیه کنید، docker compose config | grep image: را اجرا کنید. هر تگی که latest را میخواند باید به یک نسخه خاص پین (pin) شود، به همان دلیلی که اسکریپت نصب را پین کردید: شما میخواهید بدانید چه چیزی در حال اجراست و میخواهید نسخهای داشته باشید که در صورت بروز مشکل در ارتقا، به آن بازگردید. کلاینتها از طریق همان مدیر بستهای که آنها را نصب کرده است، ارتقا مییابند.
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 گیگابایت عددی است که باید تهیه کنید. در طول نصب، از سرویس پروکسی اختیاری صرفنظر کنید (که باعث رد شدن از مرحله CrowdSec نیز میشود) و تا زمانی که واقعاً به PostgreSQL نیاز پیدا نکردهاید، از همان مخزن پیشفرض SQLite استفاده کنید.