NetBird: модуль скрипта (автоматизация)

NetBird это mesh-сеть на базе WireGuard: машины соединяются напрямую, а адреса и ключи выдаёт управляющий сервер. После подключения панель обращается к нодам по адресам в сети вместо публичных: управление нодами перестаёт зависеть от публичных портов и IP, а публичный путь 2222 остаётся открытым как запасной. Если облако NetBird недоступно, панель всё равно дотянется до нод.

Всё описанное ниже делает модуль скрипта, пункт NetBird: сеть для нод и панели в главном меню. Ручной вариант без скрипта описан в отдельной статье, он подходит всем.

Что понадобится

Установленная панель Remnawave на этой машине и аккаунт в NetBird (облачный на app.netbird.io или свой сервер управления).
Setup-key из аккаунта NetBird для первого подключения.
Для перевода нод и работы со страницей подписки: SSH-доступ с панели до этих машин, настраивается расширением SSH-доступ.
Для режима API (рекомендуется): токен доступа сервисного пользователя NetBird.

Как это устроено

Модуль уводит служебный трафик в частную сеть, но ничего не ломает на публичном пути. Каждому соединению соответствует свой маршрут:

Соединение	Обычный путь	Через NetBird
Панель → ноды (управление)	публичный адрес, порт `2222`	адрес ноды в сети, тот же порт
Страница подписки → панель	публичный адрес панели	отдельный порт панели из диапазона 3100+, закрыт из интернета
Чекер → панель (подписка)	публичная подписка	тот же порт, только `/api/sub/`
Панель → метрики чекера	публичный порт `2112`	адрес чекера в сети, под паролем

Гарантии, которые модуль держит на каждом шаге:

Публичный путь каждой ноды остаётся запасным и не закрывается переводом.
Ничто не привязывается к адресу в сети и порты Docker не публикуются на нём: сервис, привязанный к такому адресу, не пережил бы перезагрузку машины.
Перевод ноды меняет адрес в панели только после живой проверки пути из контейнера панели.
Любой шаг обратим: аварийный возврат нод одной командой, возврат подписки и чекера своим пунктом меню.

Подготовка в аккаунте NetBird

Зарегистрируйтесь на app.netbird.io.
В разделе Settings → Setup Keys создайте ключ:
- тип Reusable, срок годности любой: ключ нужен только в момент подключения, потом модулю он не требуется, делать его бессрочным не обязательно.
- ключ показывается один раз, скопируйте его.
Если планируете режим API (рекомендуется): в разделе Team → Service Users нажмите Create Service User, задайте имя и роль Admin. Затем откройте созданного пользователя и нажмите Create Access Token. Токен показывается один раз, скопируйте его. Срок действия токена (Expires in) выбирайте самый большой из доступных: токен сохраняется на сервере панели и используется модулем постоянно, а после истечения срока режим API перестанет работать, пока вы не введёте новый токен в настройках модуля.

Подключение панели

Выполните на сервере панели:

remnawave_reverse

Выберите пункт NetBird: сеть для нод и панели.
Выберите Подключить эту машину к NetBird.
Вставьте setup-key (ввод скрыт) и подтвердите имя машины.
Модуль установит клиент NetBird, зафиксирует версию пакета, отключит подключения по требованию (lazy) и зарегистрирует сервер в сети. В конце вы увидите адрес в сети панели, например 100.88.10.7/16.
Модуль предложит сразу включить режим API: сам создаст группы и однонаправленные политики, а затем спросит, выключить ли политику Default (предварительно проверив, что пути до нод живы). Отказаться можно: модуль покажет краткую инструкцию по ручной настройке политик, а API включается позже через Настройки.

Клиент подключается с обязательными настройками: DNS NetBird отключён (хостовой /etc/resolv.conf не трогается), маршруты и файрвол клиента не вмешиваются в работу сервера, связь держится постоянно. Если машина была подключена вручную до модуля, пункт Восстановить правильные настройки клиента переприменит их.

Режим API: группы, ключи, политика Default

В меню Настройки модуля (токен доступа, режим API) введите токен доступа сервисного пользователя. Модуль:

создаст группы rrp-…-panel, rrp-…-nodes и однонаправленную политику панель → ноды tcp/2222.
будет выпускать одноразовые ключи для каждой машины и отзывать их сразу после использования, вставлять ключи больше не нужно.
в пункте Политики и Default покажет состояние доступа и по подтверждению выключит Default (с автоматическим возвратом, если пути не выдержат).

Без режима API модуль работает, но ключи для новых машин придётся создавать и вставлять вручную, а политики настраивать самому.

Перевод нод в сеть NetBird

Для каждой ноды нужен SSH-доступ с панели (расширение «SSH-доступ»). Модуль подключает машины только по публичному адресу: адрес в сети после перевода становится основным путём панели к ноде.

В меню NetBird выберите Ноды: перевод в сеть NetBird…, затем Перевод ноды в сеть NetBird и укажите ноду.
Подтвердите план. Модуль подключит машину к NetBird, проверит путь до 2222 прямо из контейнера панели и только потом сменит адрес ноды в панели на адрес в сети.
Дождитесь подтверждённого переподключения. Публичное правило 2222 при этом остаётся как запасной путь.

Если путь не прошёл проверку, адрес ноды не меняется, а модуль подсказывает вероятные причины (политики, подключения по требованию, плагины нод). Любой незавершённый перевод можно продолжить или вернуть обратно из того же пункта меню.

Ноды, уже подключённые к NetBird вручную, модуль возьмёт под управление через Импорт нод… в том же подменю.

Страница подписки

Пункт Страница подписки на отдельном сервере рассчитан на страницу подписки, которая уже работает на отдельной машине. Модуль:

открывает на панели отдельный порт из диапазона 3100+, закрытый из интернета, и разрешает на нём только адрес сервера подписки в сети.
подключает машину подписки к NetBird, если клиента там ещё нет.
переписывает её compose на адрес панели в сети: EGAMES_COOKIE и auth-гейты из compose уходят, конфигурация панели больше не проходит через публичный интернет.
перед изменением сохраняет снимок публичной конфигурации и проверяет результат живьём: контейнер держится, панель отвечает.

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

Xray Checker

Пункт Xray Checker через сеть NetBird переносит чекер на работу внутри сети:

чекер берёт подписку у панели только через /api/sub/, публичная подписка ему не нужна.
метрики и страница мониторинга отвечают под паролем и только машинам сети, из интернета их не видно.
перед переносом модуль сохраняет снимок публичной конфигурации чекера, если она была.

Возврат на публичный путь идёт тем же пунктом: найденный снимок публичного чекера восстанавливается и проверяется, а без снимка поставленный модулем контейнер чекера останавливается и удаляется, публичный чекер тогда поднимается модулем Xray Checker.

Аварийный возврат и диагностика

Пункт Аварийный возврат нод на публичные адреса одной командой возвращает все ноды на публичные адреса, NetBird при этом не отключается.
Диагностика и сверка адресов сверяет записанные в модуле адреса с фактическими (адрес мог измениться после переподключения), показывает состояние клиента и путей.

Отключение

Отключить NetBird (с полным возвратом) останавливает клиент на этой машине, установка и состояние модуля сохраняются. Порядок при сворачивании схемы: сначала верните ноды на публичные адреса (аварийным возвратом или по одной), затем перенесите обратно подписку и чекер, панель отключается последней. Пока в панели есть ноды с адресами сети, а подписка или чекер работают через неё, модуль не даст панели отключиться.

Полное удаление

Пункт Удалить NetBird полностью сносит всю схему целиком, а не одну машину панели. Пока что-то ещё работает через сеть (ноды в панели, сервер подписки, чекер), модуль откажется и подскажет, что сначала вернуть на публичный путь. Дальше по желанию клиент удаляется и с нод, куда его ставил модуль: по SSH выполняется отключение, выход из сети и удаление пакета, а старые записи этих машин вычищаются из аккаунта. Затем то же самое на самой панели: клиент, регистрация и состояние модуля (режим, токен доступа, записи нод). Группы и политики в аккаунте остаются. Единственный ручной хвост: клиент на сервере подписки или чекера, если они работали через сеть и уже возвращены на публичный путь (модуль их адресов после возврата не помнит), там выполните apt purge netbird. Это способ начать прогоны с нуля: после удаления пункт Подключить эту машину к NetBird снова предлагает подключение, как в первый раз.

Меню модуля: что делает каждый пункт

Состав меню зависит от состояния машины: до установки клиента виден только пункт подключения, часть пунктов появляется только на панели или в режиме API. Шапка меню показывает клиента (версию и закрепление), адрес в сети, связь с сетью и режим работы.

Подключение

Подключить эту машину к NetBird: первое подключение машины: установка клиента, регистрация по ключу, проверка, что NetBird не тронул DNS и маршруты сервера. После подключения модуль предлагает включить режим API.
Настройки модуля (токен доступа, режим API): ввод и хранение токена доступа, включение и выключение режима API, ротация токена сервера подписки.
Политики и Default (режим API): только в режиме API: модуль создаёт группы и политику «панель → ноды», показывает чужие пиры и предлагает выключить политику Default (предварительно проверив, что пути до нод выживут, а при неудаче возвращает её обратно).

Ноды

Ноды: перевод в сеть NetBird, импорт ручной схемы, статус: подменю работы с нодами:
- Перевод ноды в сеть NetBird: перенос одной ноды: клиент устанавливается на неё по SSH, путь проверяется прямо из контейнера панели, адрес в панели меняется на адрес в сети, перезапуск подтверждается. Публичный путь 2222 остаётся запасным, незаконченный перевод можно продолжить или вернуть.
- Импорт нод, уже подключённых к NetBird вручную: для нод, подключённых до модуля своими силами: модуль находит в панели ноды с адресами из вашей сети NetBird и вносит их в своё состояние.
Аварийный возврат нод на публичные адреса: одной командой возвращает все ноды на публичные адреса, NetBird при этом не отключается.
Страница подписки на отдельном сервере: открывает на панели отдельный порт (закрытый из интернета) и переводит сервер подписки на панель через сеть NetBird. Когда страница уже в сети, пункт сначала предлагает вернуть её на публичный путь (восстановление из снимка с проверкой публичного пути) или перевести заново после ручных правок.
Xray Checker через сеть NetBird: чекер берёт подписку у панели только через сеть, метрики и страница мониторинга отвечают только машинам внутри сети. Возврат на публичный путь идёт тем же пунктом: снимок публичного чекера восстанавливается, без снимка контейнер модуля останавливается и удаляется.

Служебные пункты

Диагностика и сверка адресов: состояние клиента и обязательных настроек, сверка записанных адресов с фактическими, предупреждения о чужих настройках и незакреплённом пакете.
Восстановить правильные настройки клиента: перезапуск клиента с обязательными настройками: нужен, если машина была подключена вручную до модуля или диагностика показала расхождение.
Обновить клиент NetBird (по одной машине): узнаёт последнюю версию из репозитория, Enter ставит её. Если установлена последняя, модуль так и скажет. Версия закреплена, чтобы фоновые обновления не перезапускали клиент сами.
Отключить NetBird (с полным возвратом): обратимое отключение: останавливает клиент, установка и состояние модуля сохраняются.
Удалить NetBird полностью (клиент и состояние модуля): полный снос для прогонов с нуля (см. выше).

Ручная установка (без модуля)

Если модуль недоступен, минимальный набор шагов такой (со всеми оговорками, которые модуль закрывает автоматически):

# на панели и на ноде
curl -fsSL https://pkgs.netbird.io/install.sh | sh
apt-mark hold netbird

# ключ передавайте только через файл, не в командной строке (ключ в argv виден в ps и истории)
install -m600 /dev/null /run/nbkey
printf '%s' 'ВАШ-SETUP-KEY' > /run/nbkey
netbird up --setup-key-file /run/nbkey --disable-dns=true --disable-client-routes=true \
    --disable-server-routes=true --block-inbound=false --disable-firewall=false
rm -f /run/nbkey
netbird service reconfigure --service-env NB_LAZY_CONN=off

Затем в панели укажите адрес ноды в сети в поле «Адрес» её карточки. Помните: без однонаправленных политик трафик между пирами ничем не ограничен (Default = все ко всем), а UFW-правила на интерфейс wt0 не действуют: доступ фильтруется только политиками NetBird.

Итог

Панель и ноды связаны защищённым туннелем, публичный 2222 остаётся запасным путём.
Подписка и мониторинг ходят через сеть NetBird, их порты закрыты из интернета.
В любой момент всё возвращается на публичные адреса: ноды одной командой, подписка и чекер своими пунктами меню.

NetBird вручнуюТот же результат без скрипта: установка клиента, ключи и политики своими руками, для любого сервера.

SSH-доступ к машинамКлючи и цели для второй машины: нужны модулю NetBird для перевода нод и страницы подписки.