Jak zainstalować NetBird VPN na własnym serwerze VPS
Instrukcja samodzielnej konfiguracji serwera NetBird na VPS. Omówienie DNS, certyfikatów TLS, skryptu instalacyjnego oraz zarządzania kluczami dla węzłów w trybie unattended.
Co daje samodzielne hostowanie serwera NetBird VPN
Samodzielne hostowanie serwera NetBird VPN przenosi płaszczyznę sterowania (control plane) na własny VPS. Jest to komponent przechowujący listę węzłów, decydujący o uprawnieniach do połączeń oraz ułatwiający wzajemne odnajdywanie się węzłów za NAT (network address translation). Same tunele nadal wykorzystują protokół WireGuard i są szyfrowane bezpośrednio między maszynami. Zmiana polega na tym, że żadna zewnętrzna firma nie posiada spisu urządzeń ani nie obsługuje procesu logowania. Należy mieć świadomość korzyści, ponieważ hostowana płaszczyzna sterowania również nie posiada kluczy szyfrujących ruch, a co faktycznie może zrobić serwer koordynujący w przypadku przejęcia jest zakresem węższym, niż większość osób zakłada przed lekturą dokumentacji.
NetBird pozycjonuje się pomiędzy rozwiązaniami, które mogą być już znane. Jest to nakładka typu mesh, w której węzły łączą się bezpośrednio ze sobą, zamiast przesyłać cały ruch przez jedną bramę. Jest to również rozwiązanie w pełni hostowalne samodzielnie, co stawia je w jednym rzędzie z Headscale, samodzielnie hostowanym serwerem sterującym Tailscale. Jeśli dotychczas używano wyłącznie tuneli z pojedynczą bramą, należy najpierw przeczytać różnice między zwykłym WireGuard a nakładką mesh, ponieważ ten model pojęciowy jest niezbędny do zrozumienia dalszej części strony.
Jeśli celem jest posiadanie jednego serwera, przez który wychodzi cały ruch, architektura mesh jest rozwiązaniem zbyt złożonym. Zwykły VPN WireGuard na pojedynczym VPS lub węzeł wyjściowy Tailscale realizują to zadanie przy znacznie mniejszym nakładzie pracy. Jeśli natomiast celem jest uzyskanie dostępu do jednej sieci prywatnej, a nie łączenie maszyn ze sobą, router podsieci Tailscale na VPS rozgłasza ten zakres do istniejącej sieci typu tailnet bez konieczności wdrażania całego poniższego stosu.
Co faktycznie uruchamia stos
Układ uległ niedawno zmianie, a większość starszych opracowań opisuje poprzednią wersję. Sprawdzono w październiku 2026 r. w odniesieniu do v0.80.0 oraz v0.76.2, czyli wydania, na którym bazuje ten przewodnik; skrypt quickstart domyślnie tworzy plik Compose z trzema usługami.
netbird-serverobsługuje API zarządzania, usługę sygnałową, przekaźnik z wbudowanym słuchaczem STUN oraz wbudowanego dostawcę tożsamości. W starszych wydaniach były to oddzielne kontenery, a dostawca tożsamości był osobną instalacją Zitadel, którą należało najpierw zbudować.dashboardto konsola administracyjna WWW.traefikdokonuje terminacji TLS (transport layer security) i przy pierwszym uruchomieniu żąda certyfikatu od Let's Encrypt.
Istnieją dwie dodatkowe usługi, które pozostają wyłączone, chyba że użytkownik wyrazi zgodę w odpowiedzi na monit. Usługa NetBird Proxy publikuje usługi wewnętrzne pod publicznymi nazwami hostów. CrowdSec filtruje szkodliwy ruch. Żadna z nich nie jest wymagana do zbudowania działającej sieci mesh, a obie zużywają pamięć na małym serwerze.
Jeśli użytkownik przechodzi z wg-easy w pojedynczym kontenerze Docker, oznacza to wzrost liczby komponentów. W zamian uzyskuje się polityki dostępu, konta dla poszczególnych użytkowników oraz węzły, które łączą się bezpośrednio ze sobą, zamiast przez jedną bramę.
Co należy przygotować przed rozpoczęciem
Publiczna nazwa domenowa jest wymagana. Panel, API i relay działają przez HTTPS na porcie 443, a Traefik pobiera certyfikat z Let's Encrypt, korzystając z wyzwania TLS-ALPN-01 obsługiwanego na porcie 443. Wymaga ono nazwy, która z publicznego Internetu rozwiązuje się na adres tego VPS. W tym scenariuszu sam adres IP nie zadziała.
Utwórz jeden rekord A, netbird.example.com wskazujący publiczny adres IPv4 VPS, i przed wykonaniem kolejnych czynności poczekaj na jego propagację.
dig +short netbird.example.comPolecenie musi wyświetlić adres serwera. Uruchomienie instalatora przed propagacją DNS powoduje niepowodzenie żądania certyfikatu przy pierwszym uruchomieniu. Wielokrotne nieudane walidacje mogą dodatkowo doprowadzić do osiągnięcia limitów Let's Encrypt. W takiej sytuacji trzeba poczekać na ich odnowienie przed ponowną próbą.
W domyślnej konfiguracji z Internetu muszą być dostępne tylko dwa porty: TCP 443 dla panelu, API, ruchu sygnalizacyjnego i relay oraz dla wyzwania certyfikatu, a także UDP 3478 dla STUN. Port TCP 80 musi być wolny lokalnie, ponieważ Traefik nasłuchuje na tym porcie, ale nie musi być publicznie dostępny. Zablokowanie publicznego dostępu do portu 80 uniemożliwia jedynie przekierowanie z HTTP do HTTPS.
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw reload
sudo ufw statusOtwórz te porty również w zaporze sieciowej dostawcy. W większości paneli VPS jest to osobny mechanizm kontroli. Z tego powodu serwer, którego własny ufw status wygląda poprawnie, nadal może odrzucać połączenia.
STUN (session traversal utilities for NAT) umożliwia peerowi ustalenie publicznego adresu i portu przydzielonego przez jego NAT, aby dwa peery mogły spróbować utworzyć bezpośredni tunel. Po zablokowaniu UDP 3478 peery nadal łączą się przez relay na TCP 443, więc awaria może nie być widoczna. Peery, które nie mogą znaleźć bezpośredniej ścieżki, wyświetlają Connection type: Relayed, a ich ruch przechodzi przez VPS zamiast bezpośrednio między peerami. Peery w tej samej sieci LAN nadal mogą łączyć się bezpośrednio, korzystając z lokalnych adresów.
Po stronie oprogramowania potrzebny jest Docker z wtyczką Compose v2 oraz jq i curl. Skrypt sprawdza obecność Docker, Compose i jq, a następnie kończy działanie, jeśli któregoś z nich brakuje. Korzysta z curl bez sprawdzania jego obecności, dlatego należy zainstalować ten komponent wcześniej. Jeśli Docker został niedawno zainstalowany na tym serwerze, najpierw skonfiguruj Docker Compose działający na VPS.
Porty po pominięciu dołączonego reverse proxy
Bez Traefik połączony serwer nadal obsługuje zarządzanie, sygnalizację i relay przez jeden backend HTTP, więc lista portów zwiększa się tylko nieznacznie. Wygenerowany plik Compose publikuje:
- TCP 8080, panel, domyślnie powiązany z 127.0.0.1
- TCP 8081,
netbird-server, domyślnie powiązany z 127.0.0.1 - UDP 3478, STUN, publikowany bezpośrednio
Własny proxy kończy TLS na TCP 443 i przekazuje ruch do tych dwóch portów lokalnych. STUN nie przechodzi przez proxy, dlatego UDP 3478 pozostaje otwarty w zaporze w obu wariantach. Instrukcje wymieniające osobne porty dla management gRPC, signal gRPC i relay opisują starszy układ z wieloma kontenerami.
Wybierz ten wariant tylko wtedy, gdy serwer już kończy TLS dla innej usługi. W przeciwnym razie dołączony Traefik oznacza mniej reguł i mniej błędów.
Instalacja serwera NetBird za pomocą skryptu quickstart
Udokumentowana jednolinijkowa komenda przekazuje najnowsze wydanie bezpośrednio do powłoki:
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bashNależy przypiąć konkretną wersję. latest ulega zmianie, dlatego ta sama komenda uruchomiona w odstępie dwóch tygodni zainstaluje dwa różne wydania, a na dysku nie zostanie informacja, które z nich zapisało konfigurację. Należy pobrać oznaczone wydanie, przeczytać skrypt, a następnie go uruchomić.
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.shNajpierw skrypt pyta o domenę:
Enter the domain you want to use for NetBird (e.g. netbird.my-domain.com):Następnie pyta, jak będzie obsługiwany 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):Należy wybrać [0]. Opcje od 2 do 4 zapisują fragment konfiguracji i pozostawiają podłączenie po stronie administratora, natomiast opcja 5 zapisuje plik Compose, dashboard.env i config.yaml oraz wyświetla dokumentację konfiguracji w terminalu. Jest to prawidłowe na serwerze, na którym proxy już działa, ale nie na świeżym systemie. Opcja 0 pyta następnie o adres e-mail, który Traefik rejestruje na koncie Let's Encrypt. Komunikat nadal opisuje go jako adres do powiadomień o certyfikacie, ale Let's Encrypt zaprzestał wysyłania wiadomości o wygaśnięciu certyfikatów 4 czerwca 2025 roku. Problemy z odnawianiem są więc widoczne w logu Traefik, a nie w skrzynce odbiorczej.
Przy pierwszej instalacji należy odmówić włączenia usługi NetBird Proxy. Wymaga ona dodatkowego rekordu DNS: wieloznacznego rekordu *.netbird.example.com CNAME wskazującego na netbird.example.com, a przy zwykłej sieci mesh nie zapewnia żadnych dodatkowych funkcji. Monit dotyczący CrowdSec pojawia się tylko po włączeniu proxy, dlatego odmowa włączenia proxy pomija również ten etap. Oba komponenty można dodać później.
Skrypt zapisuje pliki w bieżącym katalogu: docker-compose.yml, config.yaml z uprawnieniami 600 oraz dashboard.env. W przypadku dołączonego Traefik dodaje także traefik-dynamic.yaml i proxy.env, ale tylko po włączeniu NetBird Proxy. Ten katalog należy traktować jako zachowywany stan, ponieważ config.yaml zawiera klucz szyfrujący dane w magazynie. Utraty tego pliku nie naprawi ponowna instalacja.
docker compose ps
docker compose logs -f netbird-serverKażda usługa powinna odczytywać running, a log serwera powinien się ustabilizować, zamiast wskazywać na ciągłe restarty. Certyfikat należy monitorować osobno:
docker compose logs traefik | grep -i acmeACME (automatic certificate management environment) to protokół używany przez Traefik do uzyskiwania certyfikatu. Błędy w tym miejscu niemal zawsze wynikają z problemu z DNS albo z zamkniętego portu 443.
Tworzenie pierwszego konta administratora
Otwórz https://netbird.example.com. W przypadku świeżej instalacji zamiast formularza logowania wyświetlona zostanie strona konfiguracji. Wprowadź adres e-mail, nazwę użytkownika oraz hasło, a następnie kliknij Create Account. Konto to stanie się pierwszym kontem administratora, a strona przekieruje użytkownika do formularza logowania.
Konto to jest przechowywane w wewnętrznej bazie użytkowników NetBird, obsługiwanej przez dostawcę tożsamości wbudowanego w kontener netbird-server. Nie wymaga to żadnych zewnętrznych zależności. Jest to największa zmiana w stosunku do samodzielnie hostowanej wersji NetBird sprzed roku, kiedy to poprawne wdrożenie wymagało najpierw uruchomienia Zitadel lub Keycloak, a następnie skopiowania czterech wartości OIDC (OpenID Connect) do setup.env przed rozpoczęciem jakichkolwiek działań.
Jeśli zamiast strony konfiguracji pojawi się ostrzeżenie przeglądarki dotyczące certyfikatu, oznacza to, że certyfikat nie został wystawiony. Należy rozwiązać ten problem przed przejściem dalej, ponieważ panel sterowania komunikuje się z API za pośrednictwem tej samej nazwy hosta i w przypadku nieprawidłowego certyfikatu wystąpią trudne do zdiagnozowania błędy.
Dołączanie pierwszego węzła
Zainstaluj klienta na dowolnej maszynie z systemem Linux, w tym na samym VPS, jeśli ma on należeć do sieci mesh:
curl -fsSL https://pkgs.netbird.io/install.sh | shW systemach Debian i Ubuntu skrypt konfiguruje repozytorium pakietów NetBird, a następnie instaluje klienta za pomocą apt, dzięki czemu menedżer pakietów przejmuje zarządzanie oprogramowaniem. Jeśli przesyłanie skryptu bezpośrednio do powłoki budzi zastrzeżenia, zapisz go najpierw za pomocą curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh i przejrzyj przed uruchomieniem sh install.sh. Niezależnie od metody, sprawdź poprawność instalacji:
apt-cache policy netbirdnetbird to klient wiersza poleceń oraz demon. netbird-ui to aplikacja z ikoną w zasobniku systemowym, która jest zbędna na serwerze typu headless.
Teraz wskaż klientowi swój serwer:
sudo netbird up --management-url https://netbird.example.comPominięcie --management-url spowoduje zarejestrowanie klienta w hostowanej usłudze NetBird, ponieważ jest to domyślne ustawienie wkompilowane w oprogramowanie. Polecenie zostanie wykonane poprawnie, maszyna otrzyma adres, ale Twój własny panel sterowania pozostanie pusty. Jest to częsty błąd.
Polecenie wyświetli adres URL, który należy otworzyć w przeglądarce, aby dokończyć logowanie. Następnie:
netbird status
ip addr show wt0Odczytaj cztery linie z netbird status: Management: Connected, Signal: Connected, linię Relays: raportującą wszystkie dostępne przekaźniki oraz NetBird IP: w zakresie sieci nakładkowej. wt0 to interfejs WireGuard utworzony przez NetBird, który powinien posiadać ten sam adres.
Dołączanie drugiej maszyny bez nadzoru przy użyciu klucza konfiguracji
Logowanie w przeglądarce nie działa w przypadku maszyny bez przeglądarki i bez osoby obsługującej ją lokalnie. Klucz konfiguracji to token uwierzytelniania wstępnego, który rejestruje maszynę bez interaktywnego etapu. Należy utworzyć go w panelu administracyjnym w sekcji Settings → Setup Keys.
Dostępne są dwa rodzaje kluczy. Klucz jednorazowy uwierzytelnia dokładnie jedną maszynę, a następnie zostaje zużyty. Klucz wielokrotnego użytku rejestruje wiele maszyn; opcjonalnie można ustawić limit ich liczby. W obu przypadkach można ustawić termin wygaśnięcia. Oba rodzaje mogą również automatycznie przypisywać nowego peera do grupy, dzięki czemu reguły dostępu tej grupy obowiązują od chwili pojawienia się maszyny.
sudo netbird up --setup-key <SETUP-KEY> \
--management-url https://netbird.example.com \
--hostname build-runner-01--hostname ustawia nazwę wyświetlaną w panelu administracyjnym. Bez tego parametru peer przyjmuje nazwę nadaną mu przez maszynę, a flota wpisów nazwanych ubuntu nie jest użyteczna.
W przypadku kontenerów i krótkotrwałych agentów kompilacji podczas tworzenia klucza należy oznaczyć go jako efemeryczny. Peery zarejestrowane przy użyciu klucza efemerycznego są automatycznie usuwane po pozostawaniu offline przez ponad 10 minut. Dzięki temu na liście peerów nie pozostają nieaktywne wpisy.
Przed zaplanowaniem użycia kluczy konfiguracji należy uwzględnić jedno ograniczenie: wygaśnięcie lub unieważnienie klucza zatrzymuje nowe rejestracje, ale nie rozłącza maszyn, które zostały już przy jego użyciu zarejestrowane. Aby odebrać maszynie dostęp, należy usunąć tego peera.
Czy nadal potrzebny jest osobny dostawca tożsamości?
W przypadku małej instalacji — nie. Wbudowany magazyn użytkowników obsługuje konta utworzone z poziomu panelu administracyjnego i wystarcza dla kilku osób.
Zewnętrzny dostawca tożsamości jest potrzebny, gdy jest już używany i nie ma potrzeby utrzymywania drugiej listy użytkowników. NetBird obsługuje każdego dostawcę zgodnego z OIDC. Należy zarejestrować poufnego klienta OIDC u dostawcy, a następnie dodać go w panelu NetBird, podając nazwę, identyfikator klienta, sekret klienta oraz, jeśli jest wymagany, issuer. NetBird wyświetla adres URL przekierowania, który należy wkleić z powrotem u dostawcy. Dostępne są nazwane integracje z Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik i Pocket ID. Pozostali dostawcy są konfigurowani jako ogólny OIDC. Jeśli używany jest już Authentik jako samodzielnie hostowane rozwiązanie jednokrotnego logowania, ta ścieżka pozwala zachować jedną listę kont zamiast dwóch.
Logowanie lokalne pozostaje dostępne po dodaniu dostawcy, a każdy skonfigurowany dostawca pojawia się na stronie logowania. Należy zachować jedno lokalne konto administratora z silnym hasłem. Błędna konfiguracja OIDC nie pozbawi wtedy dostępu do systemu.
NetBird czy Headscale: który płaszczyznę sterowania wybrać?
Oba rozwiązania eliminują tę samą zależność, czyli zewnętrzny serwer sterujący, z którym łączyłyby się klienty. Projekty te różnią się jednak charakterystyką.
Headscale stanowi reimplementację serwera sterującego Tailscale, co pozwala na korzystanie z oficjalnych klientów Tailscale. Projekt nie posiada oficjalnej konsoli webowej. Zarządzanie użytkownikami oraz kluczami pre-autoryzacji odbywa się za pomocą polecenia headscale w odniesieniu do pliku konfiguracyjnego. Istnieją społecznościowe interfejsy webowe, jednak nie stanowią one części projektu. Rozwiązanie to jest odpowiednie dla użytkowników preferujących przechowywanie stanu w plikach oraz zarządzanie zmianami poprzez system kontroli wersji.
NetBird dostarcza cały produkt: własnego klienta, własny panel, wbudowanego dostawcę tożsamości oraz zasady dostępu edytowane w przeglądarce. Oznacza to więcej komponentów na VPS oraz znacznie mniej pracy przy przekazaniu obsługi współpracownikowi, który nie będzie korzystać z terminala. Jeśli porównanie dotyczy rzeczywiście NetBird i hostowanej usługi Tailscale, a nie Headscale, należy pamiętać, że oba rozwiązania wykorzystują pod spodem WireGuard. Porównanie NetBird i Tailscale opisuje rzeczywiste różnice: kto zarządza płaszczyzną sterowania, jak definiuje się reguły dostępu oraz jak przekaźniki obsługują ruch.
Wybierz Headscale, jeśli korzystasz już z klientów Tailscale lub wymagasz minimalnej płaszczyzny sterowania. Wybierz NetBird, jeśli zarządzanie węzłami wymaga udziału kilku osób i oczekujesz konsoli oraz SSO bez konieczności samodzielnej konfiguracji tych elementów. Przed podjęciem decyzji sprawdź co faktycznie obejmuje darmowy plan Tailscale, ponieważ grupy niekomercyjne liczące do sześciu użytkowników nie ponoszą kosztów za hostowaną płaszczyznę sterowania, otrzymując w zamian nielimitowaną liczbę urządzeń użytkownika oraz 50 zasobów z tagami na start, co może czynić własną instalację zbędną. Po przekroczeniu tego limitu opłaty rosną wraz z liczbą osób, a nie liczbą maszyn, dlatego obliczenie kosztów Tailscale dla danej grupy pozwala uzyskać kwotę, którą można zestawić z kosztami VPS oraz czasem poświęconym na utrzymanie własnego stosu technologicznego.
Jak mały VPS wystarczy do uruchomienia tej usługi?
Udokumentowane minimum to 1 CPU i 2 GB pamięci. Należy wybrać 2 GB.
Na małym serwerze można bezpiecznie pominąć trzy elementy. Należy odrzucić usługę NetBird Proxy, która służy do publikowania usług wewnętrznych pod publicznymi nazwami hostów i nie ma związku z nawiązywaniem połączeń między peerami. Należy pominąć CrowdSec, który skrypt oferuje wyłącznie razem z proxy. Warto dodać go później na serwerze wystawionym do Internetu, a nie podczas pierwszej instalacji. Należy pozostawić domyślny magazyn SQLite w wolumenie netbird_data. Do PostgreSQL należy przejść dopiero po rozdzieleniu wdrożenia między kilka maszyn albo po wystąpieniu rzeczywistej współbieżności. Migrację można wykonać później zgodnie z dokumentacją.
Z przekaźnika nie można zrezygnować. Dwaj peerzy, którym NAT przypisuje inny port dla każdego miejsca docelowego, nigdy nie ustanowią bezpośredniego tunelu. Przekaźnik jest więc jedyną ścieżką, która w ogóle umożliwia ich działanie. Jego wyłączenie oszczędza bardzo mało pamięci, a powoduje problemy z połączeniami, które trudno zdiagnozować.
Gdy jedna maszyna przestaje wystarczać, w pierwszej kolejności należy przenieść z niej przekaźniki. Samodzielny przekaźnik działa z użyciem NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET i NB_ENABLE_STUN. Współdzielony sekret musi być identyczny na przekaźniku i serwerze głównym. W przeciwnym razie uwierzytelnianie klientów na przekaźniku kończy się niepowodzeniem.
Tryby awarii i obserwowane objawy
Panel pokazuje ostrzeżenie dotyczące certyfikatu. Traefik nie uzyskał certyfikatu. Uruchom docker compose logs traefik | grep -i acme. Możliwe są dwie przyczyny. Albo dig +short netbird.example.com nie wskazuje jeszcze na ten VPS, albo port TCP 443 jest zamknięty gdzieś między Let's Encrypt a kontenerem, zwykle w zaporze sieciowej dostawcy, a nie na ufw. Weryfikacja odbywa się na porcie 443, dlatego otwarty port 80 nie rozwiązuje problemu. Przed ponowną próbą usuń przyczynę problemu. Let's Encrypt zezwala na maksymalnie pięć nieudanych autoryzacji dla nazwy hosta i konta w ciągu godziny. Pętla może zablokować kolejne próby do czasu odnowienia tego limitu.
Klient informuje o nawiązaniu połączenia, ale panel jest pusty. Klient zarejestrował się w hostowanej usłudze NetBird, ponieważ brakowało --management-url. Uruchom netbird status --detail i odczytaj wiersz Management:, w którym podano serwer, z którym klient faktycznie się komunikuje. Wartość Management: Connected to https://api.netbird.io:443 oznacza połączenie z chmurą. Uruchom sudo netbird down, a następnie ponownie sudo netbird up --management-url https://netbird.example.com.
Każdy peer ma status Connection type: Relayed. Nie są tworzone tunele bezpośrednie. Cały ruch przechodzi więc przez VPS, co dodaje opóźnienie wynikające z dodatkowego przeskoku. Sprawdź port UDP 3478 w zaporze VPS oraz w zaporze dostawcy. STUN umożliwia peerowi ustalenie własnego publicznego adresu i portu. netbird status --detail wyświetla również Direct: false oraz typy kandydatów ICE (interactive connectivity establishment) dla każdego peera. Pokazuje to, na jakim etapie zakończyła się próba. W niektórych sieciach jedynym dostępnym wynikiem jest połączenie przez przekaźnik i nie oznacza to problemu.
Peer dołącza do sieci, ale nie może dotrzeć do żadnego zasobu. Obecność w mesh nie oznacza, że dwa peery mogą się ze sobą komunikować. Decydują o tym zasady dostępu. Grupa bez przypisanej polityki nie uzyskuje dostępu do żadnych zasobów. Przed rozpoczęciem analizy tras i zapór sprawdź politykę w panelu.
netbird status zgłasza problem z daemonem. Usługa nie działa. Użyj sudo netbird service status i sudo netbird service start. Dzienniki klienta znajdują się w /var/log/netbird/client.log. Jeśli nie można ustalić przyczyny, netbird debug bundle --anonymize --system-info zbiera dzienniki, stan systemu, trasy, ustawienia DNS i stan zapory do jednego archiwum.
Kopie zapasowe i aktualizacje
Cała instalacja opiera się na 2 elementach: katalogu zawierającym docker-compose.yml i config.yaml oraz wolumenie Docker zawierającym bazę danych i klucze szyfrowania. Należy wykonywać ich kopie zapasowe razem. config.yaml zawiera klucz szyfrujący dane w magazynie, dlatego kopia bazy danych bez tego klucza nie pozwala odzyskać zaszyfrowanych kluczy konfiguracji ani tokenów 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 poprzedza nazwy wolumenów nazwą katalogu projektu, dlatego wolumen opisany jako netbird_data zwykle występuje pod nazwą netbird_netbird_data. Najpierw uruchom docker volume ls i użyj wyświetlonej nazwy. W przeciwnym razie polecenie docker run powyżej może po cichu utworzyć pusty wolumen i zarchiwizować nic. Archiwa należy przechowywać poza VPS. Jeśli używane jest już narzędzie do tworzenia kopii zapasowych, restic lub BorgBackup obsłuży część związaną z przechowywaniem kopii poza serwerem.
Aktualizacja serwera polega na pobraniu obrazu i ponownym utworzeniu kontenerów:
docker compose pull
docker compose up -d
docker compose psPrzed zastosowaniem tej procedury uruchom docker compose config | grep image:. Każdy tag o wartości latest należy przypiąć do konkretnej wersji, z tego samego powodu, dla którego przypięto skrypt instalacyjny: trzeba wiedzieć, co jest uruchomione, oraz mieć wersję, do której można wrócić, gdy aktualizacja spowoduje problemy. Klientów należy aktualizować za pomocą menedżera pakietów, który został użyty do ich instalacji.
FAQ
Czy do samodzielnego hostowania NetBird potrzebny jest własny dostawca tożsamości?
Nie. Bieżące wydania zawierają wbudowany magazyn użytkowników, więc pierwsze konto administratora można utworzyć w przeglądarce pod adresem https://netbird.example.com, a następnie dodawać użytkowników z poziomu panelu. Zewnętrzny dostawca OIDC jest opcjonalny i można go dodać później, podając nazwę, identyfikator klienta, sekret klienta oraz, jeśli jest wymagany, issuer. Instrukcje zalecające wdrożenie Zitadel lub Keycloak przed NetBird opisują konfigurację, która nie jest już wymagana. Ich zastosowanie oznacza konieczność utrzymywania dodatkowej usługi.
Dlaczego wszyscy moi peeringi mają stan Connection type: Relayed?
Połączenia bezpośrednie nie są zestawiane, więc ruch przechodzi przez relay na serwerze VPS. Zwykle przyczyną jest zablokowany UDP 3478. Jest to port STUN używany przez peeringi do ustalenia własnego publicznego adresu i portu. Należy otworzyć go w zaporze serwera VPS oraz w osobnej zaporze sieciowej dostawcy. Następnie trzeba ponownie uruchomić netbird status --detail i odczytać wiersz Direct:. Jeżeli oba peeringi znajdują się za NAT przypisującym inny port dla każdego miejsca docelowego, stan relayed jest oczekiwany i nie oznacza błędnej konfiguracji.
Klient połączył się, ale panel nie pokazuje peeringów. Co się stało?
Klient zarejestrował się w hostowanej usłudze NetBird zamiast na własnym serwerze. Dzieje się tak, gdy pominięto --management-url. Polecenie netbird status --detail wyświetla serwer, z którym klient się komunikuje, w wierszu Management:. Wartość taka jak https://api.netbird.io:443 to potwierdza. Należy uruchomić sudo netbird down, a następnie sudo netbird up --management-url https://netbird.example.com. Peering pojawi się wtedy w panelu.
Czym różni się samodzielnie hostowany NetBird od Headscale?
Oba rozwiązania zastępują hostowany serwer sterujący instancją uruchamianą samodzielnie. Headscale jest wyłącznie płaszczyzną sterowania. Zarządza się nim za pomocą polecenia headscale i pliku konfiguracyjnego. Nie ma oficjalnej konsoli internetowej i obsługuje oficjalne klienty Tailscale. NetBird zawiera własnego klienta, panel administratora oraz integrację z dostawcą tożsamości w ramach tego samego stosu. Headscale jest mniejszy w utrzymaniu i przechowuje stan w plikach. NetBird łatwiej przekazać użytkownikom, którzy nie będą korzystać z terminala.
Jakiego rozmiaru VPS potrzebuje samodzielnie hostowany serwer NetBird?
Udokumentowane minimum to 1 CPU i 2 GB pamięci. Przy zakupie należy wybrać wariant z 2 GB pamięci. Podczas instalacji należy odrzucić opcjonalną usługę proxy, co powoduje również pominięcie monitu dotyczącego CrowdSec. Domyślny magazyn SQLite należy pozostawić do czasu, gdy PostgreSQL będzie rzeczywiście potrzebny.