Дерево безопасной диагностики для случая, когда контейнер NetBird остаётся подключённым, но после обновления образа журнал сообщает о недействительном setup key: состояние peer, ключ регистрации и постоянный volume проверяются раздельно.
Не делайте вывод по одной строке журнала
Сначала запишите версию образа до и после обновления, имя контейнера, время сообщения и фактический статус peer в панели управления. Если peer остаётся online и обычные разрешённые соединения работают, это отдельный наблюдаемый факт. Строка setup key is invalid относится к попытке использовать ключ, но сама по себе не доказывает, что действующее состояние peer потеряно. Не публикуйте сам ключ, идентификаторы peer или полный журнал. Если одновременно исчез доступ к панели, изменились сетевые правила либо контейнер постоянно перезапускается, остановите эксперимент и разберите эти симптомы отдельно.
Проверьте постоянное состояние контейнера
Официальная Docker-инструкция NetBird сохраняет состояние в каталоге /var/lib/netbird и предлагает подключать к нему постоянный volume. Сопоставьте текущий mount с тем, который использовался до обновления: имя или путь должны указывать на прежнее хранилище, а не на новый пустой каталог. Эта проверка не требует удаления файлов. Если mount изменился, зафиксируйте конфигурацию запуска и вернитесь к владельцу развёртывания. Не создавайте новый peer и не очищайте volume, пока не понятно, существует ли прежнее состояние и нужен ли его резервный снимок.
Отделите ключ регистрации от уже созданного peer
Setup key используется для добавления peer и может быть одноразовым или многократным. Официальная API-схема также различает срок действия, отзыв и число использований. Поэтому проверяйте в панели именно запись ключа: тип, expiration, revoked и usage, не вставляя секрет в чат или тикет. Истёкший либо израсходованный ключ объясняет отказ новой регистрации, но не доказывает, что уже сохранённый peer обязан перестать работать. Если контейнер неожиданно пытается зарегистрироваться заново, сначала выясните, почему он не видит прежнее состояние.
Проведите обратимый контрольный запуск
Сохраните текущие параметры запуска и снимок метаданных volume, затем один раз перезапустите тот же образ с тем же постоянным хранилищем и без изменения сетевых политик. Сравните только три результата: peer сохранил идентичность, peer создал запрос новой регистрации или процесс завершился раньше. Не меняйте одновременно ключ, volume и версию образа — такой опыт не покажет причину. Если требуется новая регистрация, используйте процедуру владельца сети и новый разрешённый ключ только после подтверждения, что восстановление прежнего состояния невозможно или не предусмотрено.
Когда остановиться и что передать в поддержку
Остановитесь до удаления volume, peer и ключей, если состояние хранилища неоднозначно, есть несколько контейнеров с одной конфигурацией либо непонятно, кто управляет ключами. В пакет данных включите версию образа, безопасно отредактированный способ запуска, факт наличия mount, временную шкалу обновления, статус peer до и после и точную строку ошибки без секретов. Не прикладывайте NB_SETUP_KEY, токены, адреса частной сети и полный environment. Такой набор позволяет проверить расхождение между регистрацией и сохранённым состоянием без разрушительных действий.
Материал подготовлен редакцией с помощью ИИ, затем проверен по официальной документации NetBird; форумная ветка использована только как обезличенный сигнал симптома.
Источники и проверка
- NetBird — Install with Docker проверено 2026-08-06
- NetBird API — Setup Keys проверено 2026-08-06
- NetBird — Bootstrap via config file проверено 2026-08-06
Информация актуальна на дату публикации. Правила сервисов, приложений и сетей могут меняться.