Как установить NetBird VPN на свой VPS

Что дает самостоятельный хостинг сервера NetBird VPN

Самостоятельный хостинг сервера NetBird VPN переносит плоскость управления (control plane) на ваш собственный VPS: это компонент, который хранит список узлов, определяет правила доступа между ними и помогает двум узлам обнаружить друг друга за NAT (network address translation). Сами туннели по-прежнему работают на базе WireGuard и шифруются напрямую между вашими устройствами. Изменяется лишь то, что сторонняя компания больше не хранит инвентарь ваших устройств и не управляет процессом входа. Важно понимать, что именно это дает, поскольку облачная плоскость управления в любом случае не обладает ключами для расшифровки вашего трафика, а список того, что может сделать сервер координации в случае компрометации гораздо короче, чем принято считать до ознакомления с документацией.

NetBird занимает нишу между двумя решениями, которые вам могут быть знакомы. Это mesh-оверлей, где узлы соединяются друг с другом напрямую, а не через единый шлюз. Также это решение с возможностью полной самостоятельной установки, что ставит его в один ряд с Headscale, сервером управления для Tailscale с поддержкой self-hosting. Если вы до этого использовали только туннели с одним шлюзом, сначала ознакомьтесь с разницей между обычным WireGuard и mesh-оверлеем, так как эта концептуальная модель необходима для понимания остальной части страницы.

Если ваша цель — один сервер, через который проходит весь трафик, mesh-сеть будет избыточным решением. Обычный WireGuard VPN на одном VPS или exit node в Tailscale справятся с этой задачей с гораздо меньшими затратами ресурсов. А если цель заключается в доступе к одной частной сети, а не в соединении машин между собой, subnet router Tailscale на VPS анонсирует этот диапазон в вашу существующую сеть без необходимости развертывания всего стека, описанного ниже.

Что на самом деле запускает стек

Структура недавно изменилась, и большинство старых руководств описывают устаревший вариант. Проверено в октябре 2026 года на версиях v0.80.0 и v0.76.2 (релиз, на который ориентируется данное руководство): скрипт быстрого запуска по умолчанию создает файл Compose с тремя сервисами.

• netbird-server содержит API управления, сигнальный сервис, ретранслятор со встроенным STUN-слушателем и встроенный провайдер идентификации. В старых релизах это были отдельные контейнеры, а провайдер идентификации представлял собой отдельную инсталляцию Zitadel, которую нужно было предварительно собрать.
• dashboard — это веб-консоль администратора.
• traefik выполняет TLS termination (завершение TLS) и при первом запуске запрашивает сертификат у Let's Encrypt.

Существуют еще два сервиса, которые остаются выключенными, если вы не подтвердите их запуск в ответ на запрос. Сервис NetBird Proxy публикует внутренние сервисы на публичных именах хостов. CrowdSec фильтрует вредоносный трафик. Ни один из них не требуется для создания работающей mesh-сети, и оба потребляют оперативную память на небольшом сервере.

Если вы переходите с wg-easy в одном Docker-контейнере, это заметное увеличение количества компонентов. Вы получаете взамен политики доступа, учетные записи для каждого пользователя и пиры, которые соединяются напрямую друг с другом, а не через один шлюз.

Что необходимо подготовить перед началом

Публичное доменное имя обязательно. Панель управления, API и ретранслятор работают по протоколу HTTPS на 443 порту. Traefik получает сертификат от Let's Encrypt, используя проверку TLS-ALPN-01, которая выполняется на 443 порту и требует, чтобы доменное имя указывало на ваш VPS из публичной сети. Использование только IP-адреса в этой схеме невозможно.

Создайте одну A-запись, netbird.example.com, указывающую на публичный IPv4-адрес вашего VPS, и дождитесь обновления DNS перед запуском любых операций.

dig +short netbird.example.com

Эта команда должна вывести IP-адрес вашего сервера. Если запустить установщик до распространения DNS, запрос сертификата завершится ошибкой при первом же запуске. Повторные неудачные попытки приведут к срабатыванию лимитов Let's Encrypt, после чего придется ждать их сброса, прежде чем пробовать снова.

Три порта должны быть доступны из Интернета: TCP 80 для перенаправления на 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 (session traversal utilities for NAT) позволяет узлу узнать публичный адрес и порт, назначенные его NAT, чтобы два узла могли попытаться установить прямое соединение. Если заблокировать UDP 3478, узлы все равно смогут соединиться через ретранслятор по протоколу TCP 443, поэтому внешне все будет выглядеть исправно. Узлы, которые не могут найти прямой путь, будут отображать Connection type: Relayed, и их трафик будет проходить через ваш VPS, а не напрямую между узлами. Узлы в одной локальной сети по-прежнему смогут соединяться напрямую, используя локальные адреса.

На стороне программного обеспечения вам потребуется Docker с плагином Compose v2, а также jq и curl. Скрипт проверяет наличие Docker, Compose и jq и останавливается, если что-то из этого отсутствует. Он использует curl без предварительной проверки, поэтому установите этот пакет заранее. Если Docker на сервере установлен впервые, сначала выполните настройку Docker Compose на VPS.

Установка сервера NetBird с помощью скрипта быстрого запуска

Документированная команда в одну строку передает последнюю версию напрямую в оболочку:

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

Вместо этого зафиксируйте версию. 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, а также выводит документацию по настройке в терминал. Это подходит для сервера, на котором уже работает прокси, но не для чистого сервера. Вариант 0 запрашивает адрес электронной почты, который Traefik регистрирует в вашей учетной записи Let's Encrypt. В приглашении этот адрес по-прежнему называется адресом для уведомлений о сертификатах, но Let's Encrypt прекратил отправку писем об истечении срока действия 4 июня 2025 года, поэтому проблемы с продлением отображаются в логе Traefik, а не в вашем почтовом ящике.

При первой установке откажитесь от использования прокси-сервиса NetBird. Для него требуется еще одна 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. Относитесь к этой директории как к состоянию, которое нужно хранить, так как config.yaml содержит ключ, шифрующий данные в хранилище. Потеря этого файла не исправляется переустановкой.

docker compose ps
docker compose logs -f netbird-server

Каждый сервис должен отображать статус running, а лог сервера должен стабилизироваться, а не перезапускаться в цикле. Отслеживайте сертификат отдельно:

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment) — это протокол, который Traefik использует для получения сертификата. Ошибки на этом этапе почти всегда связаны с DNS или закрытым портом 443.

Создание первой учетной записи администратора

Откройте https://netbird.example.com. При чистой установке вместо формы входа отображается страница настройки. Введите адрес электронной почты, имя и пароль, затем нажмите Create Account. Эта учетная запись станет первой административной, после чего произойдет перенаправление на форму входа.

Данная учетная запись хранится во внутреннем хранилище пользователей NetBird, которое обслуживается провайдером идентификации, встроенным в контейнер netbird-server. Внешние компоненты не используются. Это главное отличие от self-hosted версии NetBird годовой давности, когда для работы требовалось сначала развернуть Zitadel или Keycloak и скопировать четыре значения OIDC (OpenID Connect) в setup.env до запуска системы.

Если вместо страницы настройки браузер выдает предупреждение о сертификате, значит, сертификат не был выпущен. Устраните эту проблему перед продолжением, так как панель управления взаимодействует с API через то же доменное имя, и при наличии некорректного сертификата возникают ошибки, затрудняющие диагностику.

Подключение первого узла

Установите клиент на любой Linux-машине, включая сам VPS, если вы хотите включить его в mesh-сеть:

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

В Debian и Ubuntu этот скрипт настраивает репозиторий пакетов NetBird, а затем устанавливает клиент через apt, поэтому управление пакетом в любом случае переходит к системному менеджеру. Если вас беспокоит передача скрипта напрямую в оболочку, сначала сохраните его с помощью curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh и изучите содержимое перед запуском sh install.sh. В любом случае проверьте результат установки:

apt-cache policy netbird

netbird — это клиент командной строки и демон. netbird-ui — это приложение для системного трея, оно не требуется на серверах без графического интерфейса.

Теперь укажите клиенту адрес вашего сервера:

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

Если пропустить --management-url, клиент зарегистрируется в облачном сервисе NetBird, так как это значение задано по умолчанию при компиляции. Команда выполнится успешно, машина получит IP-адрес, но ваша панель управления на собственном сервере останется пустой. На эту ошибку попадаются почти все.

Команда выведет URL-адрес, который нужно открыть в браузере для завершения входа. После этого:

netbird status
ip addr show wt0

Прочитайте четыре строки из netbird status: Management: Connected, Signal: Connected, строку Relays: с перечислением всех доступных ретрансляторов и NetBird IP: в диапазоне оверлейной сети. wt0 — это интерфейс WireGuard, создаваемый NetBird, он должен иметь тот же IP-адрес.

Подключение второй машины в автоматическом режиме с помощью setup key

Вход через браузер невозможен на машине без графического интерфейса, если рядом нет пользователя. Setup key — это токен предварительной аутентификации, который регистрирует машину без интерактивного этапа. Создайте его в панели управления в разделе Setup Keys.

Существует два типа ключей. Одноразовый ключ аутентифицирует ровно одну машину, после чего становится недействительным. Многоразовый ключ регистрирует множество машин, при этом можно ограничить их количество. Для обоих типов задается срок действия, и оба позволяют автоматически назначать новый узел в группу, чтобы правила доступа для этой группы применялись сразу после появления машины.

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

--hostname задает имя, отображаемое в панели управления. Без этого параметра узел будет использовать имя, которое машина присвоила себе сама, а список из множества записей с именем ubuntu не несет никакой пользы.

Для контейнеров и кратковременных агентов сборки при создании ключа установите флаг ephemeral. Узлы, зарегистрированные с помощью ephemeral ключа, автоматически удаляются, если они находятся в офлайне более 10 минут. Это позволяет избежать появления «мертвых» записей в списке узлов.

Перед планированием использования setup key важно учесть одно ограничение: истечение срока действия или отзыв ключа останавливает регистрацию новых машин, но не отключает те, что уже были зарегистрированы с его помощью. Чтобы ограничить доступ машине, необходимо удалить этот узел.

Нужен ли вам отдельный провайдер идентификации?

Для небольшой инсталляции — нет. Встроенное хранилище пользователей позволяет управлять учетными записями, созданными через панель управления, и этого достаточно для нескольких человек.

Внешний провайдер идентификации необходим, если он у вас уже есть и вы не хотите поддерживать второй список пользователей. NetBird поддерживает любого провайдера, работающего по протоколу OIDC. Зарегистрируйте конфиденциальный OIDC-клиент в вашем провайдере, а затем добавьте его в панели управления NetBird, указав четыре значения: имя, client ID, client secret и issuer. NetBird предоставит вам URL для перенаправления (redirect URL), который нужно вставить в настройки провайдера. Существуют готовые интеграции для Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik и Pocket ID, а любые другие решения подключаются как универсальный OIDC. Если вы уже используете Authentik в качестве собственного решения для единого входа, это позволит сохранить единый список учетных записей вместо двух.

Локальный вход остается доступным после добавления провайдера, и каждый настроенный провайдер отображается на странице входа. Оставьте одну локальную учетную запись администратора с надежным паролем. Это позволит вам войти в систему, если конфигурация OIDC будет нарушена.

NetBird или Headscale: какой control plane выбрать?

Оба решения устраняют одну и ту же зависимость — необходимость обращаться к центральному серверу управления, к которому в противном случае подключались бы ваши клиенты. Однако это проекты разного типа.

Headscale — это реализация сервера управления Tailscale, при которой вы продолжаете использовать официальные клиенты Tailscale. Официальная веб-консоль отсутствует. Управление пользователями и ключами предварительной аутентификации осуществляется через команду headscale при работе с конфигурационным файлом. Существуют сторонние веб-интерфейсы, созданные сообществом, но они не являются частью проекта. Это подходит тем, кто предпочитает хранить состояние в файлах, а изменения — в системе контроля версий.

NetBird поставляет полный набор компонентов: собственный клиент, собственную панель управления, встроенный провайдер идентификации и политики доступа, которые редактируются в браузере. Это увеличивает количество компонентов на VPS, но такой вариант намного проще передать коллеге, который не будет работать в терминале. Если вы действительно сравниваете NetBird с размещённым Tailscale, а не с Headscale, учитывайте, что оба решения используют WireGuard. В сравнении NetBird и Tailscale разобраны их фактические различия: кто управляет control plane, как задаются правила доступа и как relay-серверы передают трафик.

Используйте Headscale, если вы уже используете клиенты Tailscale или вам нужен максимально компактный control plane. Используйте NetBird, если управлять узлами должны несколько человек, а вам необходимы консоль и SSO без самостоятельной сборки системы. Прежде чем сделать выбор, ознакомьтесь с тем, что на самом деле входит в бесплатный тариф Tailscale, так как некоммерческая группа до шести пользователей ничего не платит за использование облачного сервера управления, получая неограниченное количество устройств на пользователя и 50 тегированных ресурсов, и, возможно, у вас нет причин разворачивать собственный сервер. При превышении этого лимита стоимость зависит от количества людей, а не машин, поэтому расчет стоимости Tailscale для вашей группы даст вам цифру, которую можно сопоставить с затратами на VPS и временем, необходимым для обслуживания этого стека.

Насколько маленьким может быть VPS для запуска?

Документированный минимум составляет 1 CPU и 2 GB оперативной памяти. Приобретайте 2 GB.

На небольшом сервере можно безопасно отказаться от трех компонентов. Отключите сервис NetBird Proxy, который предназначен для публикации внутренних сервисов под публичными именами хостов и не влияет на соединение узлов между собой. Пропустите 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 и на основном сервере, иначе клиенты не смогут пройти аутентификацию.

Режимы сбоев и диагностика

Панель управления показывает предупреждение о сертификате. 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 разрешает только пять неудачных попыток авторизации на одно доменное имя для одной учетной записи в час, и при превышении этого лимита вы будете заблокированы для повторных попыток до обновления лимита.

Клиент сообщает о подключении, но панель управления пуста. Клиент зарегистрировался в облачном сервисе NetBird, так как отсутствовал --management-url. Выполните netbird status --detail и прочитайте строку Management:, в которой указан сервер, с которым фактически идет обмен данными. Если вы видите Management: Connected to https://api.netbird.io:443, значит, клиент обращается к облаку. Выполните sudo netbird down, а затем снова sudo netbird up --management-url https://netbird.example.com.

Каждый узел показывает Connection type: Relayed. Прямые туннели не создаются, поэтому весь трафик проходит через ваш VPS, добавляя лишний этап задержки. Проверьте порт UDP 3478 на файрволе VPS и на файрволе провайдера, так как именно STUN позволяет узлу узнать свой публичный адрес и порт. Команда netbird status --detail также выводит Direct: false и типы кандидатов ICE (interactive connectivity establishment) для каждого узла, что показывает, насколько далеко продвинулась попытка соединения. В некоторых сетях ретрансляция (relayed) — единственный доступный результат, и это не является ошибкой.

Узел подключился, но ничего не доступно. Нахождение в сети mesh не означает, что два узла могут обмениваться данными. Это определяют политики доступа, и группа без привязанной политики не имеет доступа ни к чему. Проверьте политику в панели управления, прежде чем приступать к отладке маршрутов и файрволов.

netbird status сообщает о проблеме с демоном. Служба не запущена. Используйте 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 добавляет префикс с именем директории проекта к названиям томов, поэтому том, описанный как netbird_data, обычно отображается как netbird_netbird_data. Сначала выполните docker volume ls и используйте имя, которое он выведет, иначе команда docker run завершится ошибкой: она молча создаст пустой том и не заархивирует ничего. Храните архивы вне VPS. Если у вас уже есть инструмент для резервного копирования, restic или BorgBackup помогут с отправкой данных на удалённое хранилище.

Обновление сервера выполняется через pull и пересоздание:

docker compose pull
docker compose up -d
docker compose ps

Прежде чем полагаться на этот метод, выполните docker compose config | grep image:. Любой тег со значением latest следует зафиксировать на конкретной версии по той же причине, по которой вы фиксировали скрипт установки: вы должны знать, что именно запущено, и иметь версию для отката, если обновление пройдёт некорректно. Клиенты обновляются через тот менеджер пакетов, с помощью которого они были установлены.

FAQ

Нужно ли мне собственное решение для управления идентификацией (IdP), чтобы развернуть NetBird самостоятельно?

Нет. Текущие релизы включают встроенное хранилище пользователей, поэтому вы создаете первую учетную запись администратора в браузере по адресу https://netbird.example.com, а затем добавляете пользователей через панель управления. Внешний OIDC-провайдер является опциональным и может быть добавлен позже при наличии четырех параметров: имя, client ID, client secret и issuer. Руководства, рекомендующие развертывать Zitadel или Keycloak перед NetBird, описывают настройку, которая больше не требуется; их использование лишь создает необходимость поддерживать еще один дополнительный сервис.

Почему все мои узлы отображаются как Connection type: Relayed?

Прямые соединения не устанавливаются, поэтому трафик проходит через ретранслятор на вашем VPS. Обычно это происходит из-за блокировки UDP-порта 3478 — это STUN-порт, который узлы используют для определения своего публичного IP-адреса и порта. Откройте его в брандмауэре на 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, и узел появится в вашей панели управления.

Чем self-hosted версия NetBird отличается от Headscale?

Оба решения позволяют заменить облачный сервер управления на собственный. Headscale — это только плоскость управления: вы управляете им через команду headscale и файл конфигурации, официальная веб-консоль отсутствует, а в качестве клиентов используются официальные приложения Tailscale. NetBird поставляется с собственным клиентом, панелью администратора и интеграцией с IdP в одном стеке. Headscale требует меньше ресурсов и хранит состояние в файлах. NetBird проще передать пользователям, которые не работают с терминалом.

Какой VPS нужен для самостоятельного размещения NetBird?

Минимальные системные требования: 1 ядро CPU и 2 GB оперативной памяти, при этом 2 GB — это рекомендуемый объем. Откажитесь от опционального прокси-сервиса во время установки (это также пропустит запрос на установку CrowdSec) и используйте хранилище SQLite по умолчанию, пока не возникнет реальная необходимость в PostgreSQL.