NetBox на сервере: частые ошибки и решения

MAATRIX

NetBox — де-факто стандарт для учёта IP-адресов, VLAN'ов, стоек и сетевого оборудования (IPAM/DCIM), но на практике эта Django-система доставляет немало проблем: 502 от nginx после обновления, зависшие миграции базы, расхождение между тем, что реально живёт в сети, и тем, что записано в базе NetBox. Если вы administrируете сеть из десятков VLAN'ов и сотен адресов вручную в Excel — рано или поздно придёте к NetBox, и эта статья — сборник решений тех проблем, которые вы почти наверняка встретите по дороге.

Ошибка 1: 502 Bad Gateway после установки или обновления

Самая частая жалоба новых пользователей NetBox: nginx поднялся, но отдаёт 502. Причина почти всегда в том, что gunicorn (WSGI-сервер, на котором крутится Django-приложение NetBox) либо не запустился, либо слушает не тот сокет, который ждёт nginx.

Проверка идёт по цепочке:

systemctl status netbox netbox-rq
journalctl -u netbox -n 100 --no-pager

Если сервис netbox.service в состоянии failed, смотрите причину в логе — чаще всего это одна из трёх вещей: не выполнены миграции базы, не собраны статические файлы, либо неверный путь до сокета в /opt/netbox/netbox/netbox/configuration.py.

Конфиг gunicorn лежит в /opt/netbox/gunicorn.py, и там указан bind-адрес:

bind = '127.0.0.1:8001'

В nginx он должен совпадать с proxy_pass:

location / {
    proxy_pass http://127.0.0.1:8001;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Если используете unix-сокет вместо TCP-порта, убедитесь, что права на файл сокета позволяют nginx (обычно пользователь www-data) до него достучаться — типичная ошибка: gunicorn пишет сокет с правами только для своего пользователя netbox, и nginx получает Permission denied в логе, что превращается в тот же 502. Настройки firewall на самом сервере тоже стоит перепроверить — если порт 8001 случайно оказался открыт наружу или, наоборот, локальный трафик режется правилами, см. настройку UFW на сервере.

Ошибка 2: миграции базы зависают или падают с конфликтом

NetBox активно развивается, и при обновлении между минорными версиями (например, с 4.0 на 4.1) обязателен прогон миграций Django:

cd /opt/netbox
source venv/bin/activate
python3 netbox/manage.py migrate

Частые проблемы здесь:

• Миграция висит бесконечно — почти всегда означает, что на таблицу наложена блокировка другим процессом (незакрытая транзакция, зависший gunicorn-воркер, который не остановили перед обновлением). Остановите netbox и netbox-rq перед миграцией, а не пытайтесь мигрировать на живой базе.
• django.db.utils.ProgrammingError: relation already exists — обычно значит, что миграции применялись частично (прервали Ctrl+C на середине) или база была создана вручную с похожей схемой. Смотрите состояние через python3 netbox/manage.py showmigrations — приложение покажет, какие миграции отмечены как применённые ([X]), а какие нет.
• Несовпадение версии PostgreSQL — NetBox требует довольно свежий PostgreSQL (проверяйте актуальный минимум в release notes конкретной версии NetBox, он периодически поднимается). На Ubuntu 24.04 из репозитория обычно приходит подходящая версия, но если сервер апгрейдили с более старого дистрибутива, могла остаться версия 12-13.

Перед любым апгрейдом NetBox — обязательный бэкап базы:

pg_dump -U netbox -h localhost netbox > /var/backups/netbox_$(date +%F).sql

Общие грабли самого PostgreSQL под NetBox (настройка shared_buffers, ограничение соединений, права пользователя) разобраны в статье про частые ошибки PostgreSQL на сервере — почти всё оттуда применимо.

Ошибка 3: Redis не подключается — падают кэш и очереди задач

NetBox использует Redis для двух вещей: кэширования и очереди фоновых задач (webhooks, отчёты, скрипты). Если Redis недоступен, интерфейс NetBox либо тормозит на каждой странице, либо часть функций (например, webhooks) молча не работает.

Типичная ошибка в логе gunicorn:

redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused.

Проверьте, что Redis вообще поднят и слушает нужный интерфейс:

systemctl status redis-server
redis-cli ping

Конфигурация Redis в NetBox задаётся в configuration.py двумя отдельными блоками — для кэша и для очередей (REDIS['tasks'] и REDIS['caching']), и это частый источник путаницы: люди меняют пароль или порт только в одном блоке, забывая про второй, и получают половину функциональности, работающей "странно". Если у вас нестандартная настройка Redis с паролем, убедитесь, что PASSWORD указан в обоих блоках конфига одинаково.

Ошибка 4: расхождение данных — IPAM живёт своей жизнью

Это не техническая ошибка в смысле "что-то упало", а самая опасная проблема эксплуатации NetBox: база данных постепенно перестаёт соответствовать реальности. Кто-то выдал IP вручную, забыв отметить в NetBox; кто-то удалил VLAN на свитче, а запись осталась. Через полгода NetBox превращается в красивую, но лживую картинку.

Практические меры, которые реально помогают:

• Заведите правило: любое изменение в сети сначала фиксируется в NetBox, потом применяется на оборудовании — а не наоборот. Это организационная мера, но именно она чаще всего решает проблему разъезда данных.
• Используйте NetBox как источник правды для автоматизации — если конфиги генерируются из NetBox через API (Ansible, Nornir, скрипты), расхождение просто невозможно физически: то, что не в NetBox, не попадёт в конфиг.
• Периодическая сверка: скрипт, который через API NetBox и через опрос реального оборудования (SNMP, API коммутаторов) сравнивает списки VLAN и IP, репортит расхождения. Даже раз в неделю по cron — уже сильно лучше, чем ничего.

Пример простого запроса к API NetBox для выгрузки всех активных префиксов:

curl -s -H "Authorization: Token $NETBOX_TOKEN" \
  "https://netbox.example.com/api/ipam/prefixes/?status=active" | jq '.results[].prefix'

Ошибка 5: медленный интерфейс на больших инвентарях

На инсталляциях с десятками тысяч устройств и IP-адресов NetBox может ощутимо тормозить, особенно на страницах с большим числом связанных объектов (например, список интерфейсов устройства с кучей IP на каждом).

Что обычно помогает:

1. Проверить настройки PostgreSQL — на дефолтных параметрах (shared_buffers = 128MB) большая база просто не влезает в кэш, каждый запрос идёт на диск. Ориентировочно shared_buffers стоит поднимать до 25% от RAM сервера, но точную цифру подбирайте под свою нагрузку и объём данных — универсального значения нет.
2. Индексы и VACUUM — если база давно не проходила VACUUM ANALYZE, планировщик запросов начинает работать по устаревшей статистике. Настройте автовакуум или запускайте вручную после массовых импортов.
3. Кэш Redis — убедитесь, что REDIS['caching'] действительно активен, а не отключён по недосмотру — без кэша NetBox пересчитывает много агрегатов на каждый запрос.
4. Ограничивайте page_size — при работе через API с большими выборками задавайте ?limit= явно, иначе клиент может запросить весь датасет разом.

Если NetBox крутится в Docker Compose (официальный netbox-docker — самый частый способ деплоя), стоит также свериться с общими граблями контейнерных стеков — они одинаковы что для NetBox, что для любого другого сервиса на Compose: частые ошибки Docker Compose в продакшене.

Ошибка 6: LDAP/SSO авторизация не работает

Во многих компаниях NetBox подключают к корпоративному LDAP или SSO, и здесь тоже есть свой набор типовых проблем.

LDAP: чаще всего ошибка в ldap_config.py — неверный AUTH_LDAP_BIND_DN или сертификат для LDAPS не подхватывается системой. Проверить связь можно напрямую, в обход NetBox:

ldapsearch -x -H ldaps://ldap.example.com -D "CN=svc-netbox,OU=Service,DC=example,DC=com" -W -b "DC=example,DC=com" "(sAMAccountName=testuser)"

Если эта команда не находит пользователя или падает с ошибкой сертификата — проблема не в NetBox, а в самом LDAP-подключении, и чинить нужно именно его.

SSO (SAML/OIDC): типичная ошибка — несовпадение redirect_uri, зарегистрированного у провайдера, с тем, что реально отдаёт NetBox (особенно если сервис стоит за reverse-прокси и путает http/https в заголовках — возвращаемся к правильной настройке X-Forwarded-Proto в nginx, см. Ошибку 1). Если у вас на сервере уже настроен Let's Encrypt для терминации TLS, полезно свериться с частыми ошибками Let's Encrypt на сервере — там разобраны похожие проблемы с заголовками за прокси.

Ошибка 7: NAPALM/backup-скрипты не могут достучаться до оборудования

Если вы используете плагины NetBox для сбора конфигураций с реального оборудования (NAPALM, netmiko-интеграции) — частая проблема в том, что сам сервер NetBox не имеет прямого сетевого доступа до management-сегмента, где живут свитчи и роутеры. NetBox для IPAM/DCIM не обязан физически видеть сеть, которую описывает — но если вы вешаете на него активные проверки, стоит явно выделить сетевой маршрут (или VPN-туннель) от сервера NetBox до management VLAN, и прописать разрешающие правила firewall в обе стороны, а не полагаться на "само заработает".

Частые вопросы