Как установить 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.76.2, скрипт быстрого запуска по умолчанию создает файл Compose с тремя сервисами.

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

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

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

Что необходимо перед началом работы

Публичное доменное имя обязательно. Панель управления, API и ретранслятор работают по протоколу HTTPS на порту 443, а Traefik получает сертификат от Let's Encrypt через HTTP-запрос (HTTP challenge). Для этого требуется имя, которое разрешается в IP-адрес вашего 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 на сервере установлен впервые, сначала настройте 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 по 5 записывают фрагмент конфигурации и оставляют настройку связей вам, что правильно для сервера, где уже работает прокси, но не подходит для «чистой» системы. Вариант 0 запрашивает адрес электронной почты для Let's Encrypt, который используется для уведомлений об истечении срока действия сертификатов.

При первой установке откажитесь от использования сервиса NetBird Proxy. Ему требуются две дополнительные DNS-записи, proxy.netbird.example.com и wildcard-запись *.proxy.netbird.example.com, при этом для обычной mesh-сети он не дает преимуществ. Также откажитесь от CrowdSec. Оба компонента можно добавить позже.

Скрипт записывает файлы в текущую директорию: docker-compose.yml, config.yaml с правами доступа 600, dashboard.env и traefik-dynamic.yaml, если вы выбрали встроенный Traefik. Относитесь к этой директории как к состоянию, которое нужно хранить, так как 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 или закрытым 80 портом.

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

Откройте 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 Keys.

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

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

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

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

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

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

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

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

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

Какого минимального размера VPS достаточно для работы?

Документированный минимум составляет 1 CPU и 2 GB оперативной памяти. Согласно собственным заметкам NetBird, текущий нижний порог составляет около 1 GB RAM, так как управление пользователями теперь локальное, в отличие от 2–4 GB, требовавшихся ранее при развертывании полного стека Zitadel. Приобретайте 2 GB. Дополнительный запас памяти позволит обновлять образы, пока старые еще находятся на диске.

На небольшом сервере можно безопасно отказаться от трех компонентов. Отключите сервис NetBird Proxy: он предназначен для публикации внутренних сервисов по публичным доменным именам и не влияет на соединение узлов (peers) между собой. Откажитесь от CrowdSec: его стоит добавить на сервер, доступный извне, позже, а не в первый день. Используйте хранилище SQLite по умолчанию в томе netbird_data, а на PostgreSQL переходите только при распределении развертывания по нескольким машинам или при достижении реальной высокой нагрузки; миграция на него подробно описана и может быть выполнена позже.

Релей (relay) — это единственный компонент, от которого нельзя отказываться. Если NAT двух узлов назначает разные порты для каждого направления, они не смогут установить прямой туннель, поэтому релей остается единственным способом обеспечить их связь. Его отключение почти не экономит память, но приводит к разрывам соединений, которые сложно диагностировать.

Когда ресурсов одного сервера становится недостаточно, релеи — это первое, что нужно вынести на отдельную машину. Автономный релей запускается с помощью NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET и NB_ENABLE_STUN. Общий секрет (shared secret) должен быть идентичным на релее и на основном сервере, иначе клиенты не смогут пройти аутентификацию.

Режимы сбоев и их признаки

В панели управления отображается предупреждение о сертификате. Traefik не получил сертификат. Выполните docker compose logs traefik | grep -i acme. Существует две причины. Либо dig +short netbird.example.com еще не указывает на этот VPS, либо порт TCP 80 закрыт где-то между Let's Encrypt и контейнером — обычно это сетевой файрвол провайдера, а не ufw. Устраните причину перед повторными попытками, так как на неудачные проверки накладываются ограничения по частоте запросов, и вы заблокируете себе возможность повтора на час.

Клиент сообщает об успешном подключении, но панель управления пуста. Клиент зарегистрировался в облачном сервисе 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) для каждого узла, что позволяет понять, на каком этапе остановилась попытка соединения. В некоторых сетях relay-соединение — единственный доступный вариант, и это не является ошибкой.

Узел подключается, но не имеет доступа к ресурсам. Нахождение в 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

Нужен ли мне собственный провайдер идентификации для самостоятельного размещения NetBird?

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

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

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

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

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

Какой размер VPS нужен для сервера NetBird?

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