Как установить и настроить NetBox на VPS

MAATRIX

Когда сеть разрастается до полусотни устройств, таблица в Excel с IP-адресами и стойками превращается в источник ошибок: кто-то занял чужой /29, забыл отметить освобождённый VLAN, а на схеме сервер уже год как переехал в другую стойку. NetBox — открытая IPAM/DCIM-платформа, которая решает эту задачу: единый источник правды для IP-адресации, оборудования, стоек и связей между ними, с API, через который можно автоматизировать остальную инфраструктуру. Разворачивается NetBox быстрее, чем кажется — если сразу делать это правильно, через Docker Compose и с вынесенной базой.

Что такое NetBox и когда он нужен

NetBox изначально написан инженерами DigitalOcean для внутреннего учёта дата-центров и с 2016 года развивается как open-source проект под управлением NetBox Labs. Он закрывает две смежные задачи:

• IPAM (IP Address Management) — учёт префиксов, подсетей, отдельных IP-адресов, VRF, VLAN, ролей адресации (management, вылет в интернет, приватные сети).
• DCIM (Data Center Infrastructure Management) — стойки, юниты в стойке, модели оборудования, физические порты, кабельные соединения, питание.

Поверх этого — модуль виртуализации (кластеры, VM, интерфейсы), учёт контрактов и провайдеров каналов, и REST/GraphQL API, через который Ansible, Terraform или собственные скрипты могут забирать актуальные данные вместо ручного ввода в переменные.

Смысл заводить NetBox появляется, когда вручную поддерживать таблицу становится больнее, чем настроить систему: от пары десятков серверов и подсетей, при работе с несколькими локациями (в том числе если у вас сервера в разных ЦОД — RU, US, UK), или когда данные об инфраструктуре нужно отдавать в автоматизацию по API. Для пяти серверов в одной стойке это избыточно — здесь хватит README.md и здравого смысла.

Требования к серверу

NetBox — это Django-приложение (Python) поверх PostgreSQL и Redis, за фронтом обычно стоит nginx или Caddy как reverse proxy с TLS. Официальный проект netbox-community/netbox-docker — самый предсказуемый способ развернуть весь стек одной командой.

Минимальные требования для рабочей установки:

PostgreSQL и Redis тянут заметную часть памяти сами по себе, поэтому на VPS с 1 ГБ ОЗУ NetBox будет либо падать по OOM, либо постоянно уходить в своп. Если параллельно планируете держать на той же машине ещё и мониторинг или CI-раннеры — берите план с запасом. Здесь пригодится VPS с гибким выбором CPU/RAM — конфигурацию под DCIM-нагрузку удобно подбирать так же, как под любой другой сервис с базой данных.

Установка Docker и подготовка окружения

Если Docker ещё не стоит — ставим по официальному скрипту (актуально для Ubuntu 24.04 и Debian 12):

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
docker compose version

Убедитесь, что docker compose version показывает Compose V2 (встроенный плагин, команда без дефиса) — старый docker-compose с проектом NetBox тоже работает, но плагин удобнее в поддержке.

Создаём рабочую директорию и клонируем официальный репозиторий с готовыми Compose-файлами:

mkdir -p /opt/netbox && cd /opt/netbox
git clone -b release --single-branch https://github.com/netbox-community/netbox-docker.git .

Ветка release даёт стабильные образы, а не ежедневные сборки из main — для продакшена это важно.

Настройка переменных окружения и docker-compose

Проект поставляется с env/*.example файлами — копируем и правим их под себя, не трогая исходники:

cp env/netbox.env.example env/netbox.env
cp env/postgres.env.example env/postgres.env
cp env/redis.env.example env/redis.env
cp env/redis-cache.env.example env/redis-cache.env

В env/postgres.env задаём собственные значения вместо примерных:

POSTGRES_DB=netbox
POSTGRES_USER=netbox
POSTGRES_PASSWORD=сгенерируйте-длинный-пароль-openssl-rand-base64-32

В env/netbox.env — ключевые параметры приложения:

SUPERUSER_NAME=admin
SUPERUSER_EMAIL=admin@example.com
SUPERUSER_PASSWORD=другой-длинный-пароль
DB_NAME=netbox
DB_USER=netbox
DB_PASSWORD=тот-же-пароль-что-в-postgres.env
SECRET_KEY=сгенерируйте-50-символов-через-openssl-rand-base64-45
ALLOWED_HOSTS=netbox.example.com,10.0.0.10
CORS_ORIGIN_ALLOW_ALL=False

SECRET_KEY генерируется отдельной командой и должен быть уникальным для каждой установки:

python3 -c "import secrets; print(secrets.token_urlsafe(45))"

Redis нужен NetBox для двух разных вещей — очередей задач (webhooks, скрипты) и кэша UI, поэтому в docker-compose.yml вы увидите два отдельных Redis-контейнера (redis и redis-cache) с разными env-файлами. Не объединяйте их в один инстанс без базы 0/1 — при апгрейдах это создаёт путаницу с очисткой кэша.

Запуск и первый вход

Поднимаем стек:

docker compose pull
docker compose up -d
docker compose ps

Первый запуск занимает пару минут — контейнер netbox применяет миграции базы и собирает статику. Следить за процессом:

docker compose logs -f netbox

Когда в логах появится строка о старте Gunicorn-воркеров, сервис готов. По умолчанию NetBox слушает на порту 8080 внутри Compose-сети, наружу проброшен 8000 (проверьте docker-compose.override.yml, при желании поменяйте порт там же). Заходим:

http://IP-вашего-сервера:8000

Логин и пароль — те, что указали в SUPERUSER_NAME/SUPERUSER_PASSWORD. Сразу после входа стоит зайти в Admin → Users и создать персональные учётные записи для остальных инженеров вместо совместного использования суперпользователя — так проще потом разбирать, кто и когда поменял запись в IPAM.

Reverse proxy, TLS и бэкапы

Открывать NetBox наружу без TLS не стоит — в системе хранятся данные об инфраструктуре, которые лучше не отдавать в открытом виде. Ставим nginx перед Docker-стеком:

server {
    listen 443 ssl http2;
    server_name netbox.example.com;

    ssl_certificate     /etc/letsencrypt/live/netbox.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/netbox.example.com/privkey.pem;

    location /static/ {
        alias /opt/netbox/netbox-docker/static-files/;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name netbox.example.com;
    return 301 https://$host$request_uri;
}

Сертификат — через certbot (certbot --nginx -d netbox.example.com) или любой другой ACME-клиент. Директорию static-files монтируйте как volume в docker-compose, чтобы nginx мог отдавать статику напрямую, а не через прокси в Gunicorn — это заметно снижает нагрузку при большом числе устройств в базе.

Данные NetBox — это, по сути, PostgreSQL-база плюс несколько volume-директорий (media, static, отчёты). Дамп базы делается стандартно:

docker compose exec postgres pg_dump -U netbox netbox | gzip > netbox-$(date +%F).sql.gz

Заведите это в cron и храните бэкапы отдельно от сервера — если у вас уже настроен процесс резервного копирования баз данных, NetBox встраивается в него как ещё один PostgreSQL-инстанс без специфики. Отдельная база данных под NetBox без Docker-обвязки тоже возможна — если хотите управлять PostgreSQL сами, посмотрите установку PostgreSQL на VPS и укажите внешний хост в netbox.env вместо встроенного контейнера.

Импорт существующих данных и работа с API

Заполнять IPAM вручную через веб-интерфейс имеет смысл только для небольшого числа записей. Для массового импорта в NetBox есть:

• CSV-импорт через UI — на каждой странице списка (Prefixes, IP Addresses, Devices) есть кнопка Import с шаблоном полей.
• REST API — токен создаётся в Admin → API Tokens, дальше это обычный HTTP с JSON:

curl -s -H "Authorization: Token ВАШ_ТОКЕН" \
     -H "Content-Type: application/json" \
     -X POST http://netbox.example.com/api/ipam/prefixes/ \
     -d '{"prefix": "10.20.0.0/24", "status": "active", "description": "office-lan"}'

• pynetbox — официальная Python-библиотека, удобна для скриптов миграции из старых Excel-таблиц: читаете строки через openpyxl, для каждой вызываете nb.ipam.prefixes.create(...).

Это же API дальше используют Ansible (модуль netbox.netbox) или Terraform-провайдер netbox-community/netbox — динамический inventory тянет список хостов и их роли прямо из NetBox, без ручного редактирования hosts.ini. Если у вас уже есть автоматизация на Ansible, NetBox как источник инвентаря экономит время на синхронизации данных между системами.

Обновление и типичные проблемы

Обновление NetBox через Docker — это смена тега образа и пересборка:

cd /opt/netbox
git pull
docker compose pull
docker compose up -d

Перед мажорным обновлением (например, с 4.0 на 4.1) обязательно читайте release notes — NetBox может требовать промежуточную версию для миграций базы, пропускать релизы не всегда безопасно. Бэкап базы перед апгрейдом — не формальность, а обязательный шаг: миграции необратимы без отдельного отката из дампа.

Частые проблемы на старте:

• 502 от nginx — контейнер netbox ещё не поднялся (миграции идут дольше на слабом CPU) или порт в proxy_pass не совпадает с проброшенным в Compose.
• Статика не грузится, страница без стилей — забыли смонтировать/раздать static-files, проверьте volume и путь alias в nginx.
• Ошибка подключения к Redis — перепутаны env/redis.env и env/redis-cache.env, они должны указывать на разные контейнеры (redis и redis-cache соответственно).
• CSRF-ошибка при входе через HTTPS — не добавили домен в CSRF_TRUSTED_ORIGINS в netbox.env (нужен полный URL со схемой: https://netbox.example.com).

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