NetBox в Docker Compose: готовый файл

MAATRIX

Учёт IP-адресов в экселе разваливается быстро: кто-то занял адрес мимо таблицы, дубликаты никто не подсвечивает, а найти свободный блок под новый сервис — уже квест на полчаса. Когда серверов десятки, а стоек или локаций больше одной, ручной учёт превращается в источник инцидентов, а не в документацию. NetBox закрывает эту дыру: единая база IP-планов, VLAN, стоек и оборудования с REST/GraphQL API поверх неё. Ниже — рабочий docker-compose.yml, с которым NetBox поднимается за вечер, разбор каждого параметра и грабли первого запуска.

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

NetBox — это открытая (Apache 2.0) IPAM/DCIM-система, которую изначально написали в DigitalOcean для собственной инфраструктуры, а сейчас её развивает сообщество под крылом NetBox Labs. Два слоя функциональности:

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

Сверху — тенанты (мультиарендность), схемы кабелей и цепей провайдеров (circuits), кастомные поля, теги, шаблоны отчётов на Python и вебхуки. Из NetBox можно тянуть данные через API в Ansible-инвентарь или Terraform-провайдер — это его главное отличие от таблицы: он не просто хранит данные, а отдаёт их машинам.

Разворачивать стоит, когда серверов больше десятка, локаций или стоек несколько, а IP-планом пользуется больше одного человека. Для трёх VPS в одной подсети это избыточно, хватит README с таблицей. NetBox также не заменяет мониторинг — он не проверяет, жив ли хост, а отвечает на вопрос «что вообще есть в инфраструктуре и где».

Готовый docker-compose.yml

Официальный проект netbox-community/netbox-docker собирает стек из нескольких образов: Postgres для данных, два инстанса Redis (очередь задач и кэш) и сам NetBox в трёх ролях — веб, воркер фоновых задач и housekeeping для чистки истёкших сессий. Ниже — компактный вариант для одного узла.

version: "3.8"

services:
  postgres:
    image: postgres:16-alpine
    container_name: netbox-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: netbox
      POSTGRES_USER: netbox
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - netbox-postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U netbox"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: netbox-redis
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD} --appendonly yes
    volumes:
      - netbox-redis-data:/data

  redis-cache:
    image: redis:7-alpine
    container_name: netbox-redis-cache
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_CACHE_PASSWORD}
    volumes:
      - netbox-redis-cache-data:/data

  netbox:
    image: netboxcommunity/netbox:v4.1
    container_name: netbox
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
      redis-cache:
        condition: service_started
    env_file: .env
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - netbox-media:/opt/netbox/netbox/media
      - netbox-reports:/opt/netbox/netbox/reports
      - netbox-scripts:/opt/netbox/netbox/scripts
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/login/"]
      interval: 30s
      timeout: 10s
      retries: 3

  netbox-worker:
    image: netboxcommunity/netbox:v4.1
    container_name: netbox-worker
    restart: unless-stopped
    command: /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py rqworker high default low
    depends_on:
      - netbox
    env_file: .env
    volumes:
      - netbox-media:/opt/netbox/netbox/media
      - netbox-reports:/opt/netbox/netbox/reports
      - netbox-scripts:/opt/netbox/netbox/scripts

  netbox-housekeeping:
    image: netboxcommunity/netbox:v4.1
    container_name: netbox-housekeeping
    restart: unless-stopped
    command: /opt/netbox/housekeeping.sh
    depends_on:
      - netbox
    env_file: .env

volumes:
  netbox-postgres-data:
  netbox-redis-data:
  netbox-redis-cache-data:
  netbox-media:
  netbox-reports:
  netbox-scripts:

Тег v4.1 актуален на момент подготовки статьи (конец августа 2026), но перед запуском сверьтесь со списком тегов netboxcommunity/netbox на Docker Hub и возьмите конкретную минорную версию — привязка к плавающему latest на проде чревата неожиданной миграцией схемы БД при рестарте.

Порт веб-приложения намеренно опубликован только на 127.0.0.1 — снаружи NetBox должен смотреть через обратный прокси с TLS.

Файл .env и генерация SECRET_KEY

Все секреты и параметры подключения вынесены в .env рядом с docker-compose.yml:

SECRET_KEY=замените_на_случайную_строку_50_символов

DB_NAME=netbox
DB_USER=netbox
DB_PASSWORD=надёжный_пароль_postgres
DB_HOST=postgres
DB_PORT=5432

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=пароль_redis
REDIS_CACHE_HOST=redis-cache
REDIS_CACHE_PASSWORD=пароль_redis_cache

ALLOWED_HOSTS=netbox.example.com 127.0.0.1 localhost

SUPERUSER_NAME=admin
SUPERUSER_EMAIL=admin@example.com
SUPERUSER_PASSWORD=временный_пароль_смените_после_входа
SUPERUSER_API_TOKEN=сгенерируйте_отдельно_для_api

SECRET_KEY — не пароль, а ключ подписи сессий и CSRF-токенов Django, не менее 50 символов, без пробелов:

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

ALLOWED_HOSTS перечисляет через пробел домены и IP, с которых NetBox готов принимать запросы — забудете добавить реальный домен, получите Bad Request (400) вместо интерфейса логина. Файл .env добавьте в .gitignore, если храните конфиг в репозитории: в нём пароль от БД, ключ Redis и токен суперпользователя.

Первый запуск, миграции и суперпользователь

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

docker compose up -d
docker compose logs -f netbox

При первом старте контейнер netbox сам прогоняет миграции Django и — если заданы переменные SUPERUSER_* — создаёт первого администратора (в логах видны строки Running migrations и Superuser created successfully). Если переменные не заданы, создайте суперпользователя вручную:

docker compose exec netbox /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py createsuperuser

До настройки прокси интерфейс доступен по SSH-туннелю: ssh -L 8080:127.0.0.1:8080 user@server, дальше http://127.0.0.1:8080/. После логина смените временный пароль и, если нужно, сгенерируйте постоянный API-токен в профиле.

Проверьте статус контейнеров: docker compose ps. Если netbox-worker постоянно перезапускается — почти всегда неверный пароль к redis в .env.

HTTPS через обратный прокси

Открывать NetBox напрямую в интернет без TLS не стоит — в базе хранятся не только IP-адреса, но и секреты в кастомных полях, история изменений инфраструктуры. Проще всего вынести терминацию TLS на Traefik или nginx перед контейнером netbox, оставив сам NetBox на 127.0.0.1:8080. Развёртывание и сертификат Let's Encrypt через Traefik разобраны в статье Traefik как reverse proxy для Docker — для NetBox набор лейблов минимальный:

  netbox:
    # ...
    ports: []
    networks:
      - traefik-public
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.netbox.rule=Host(`netbox.example.com`)"
      - "traefik.http.routers.netbox.entrypoints=websecure"
      - "traefik.http.routers.netbox.tls.certresolver=letsencrypt"
      - "traefik.http.services.netbox.loadbalancer.server.port=8080"

Если предпочитаете nginx с certbot, достаточно proxy_pass http://127.0.0.1:8080; с проброской заголовков Host, X-Forwarded-For и X-Forwarded-Proto — NetBox их учитывает при формировании ссылок в интерфейсе и API.

Наполнение базы: сайты, стойки, IP-планы

Пустой NetBox бесполезен, пока в него не занесена структура. Порядок обычно такой:

1. Organization → Sites — создайте сайт под каждую физическую или логическую локацию (дата-центр, офис, отдельная стойка у провайдера).
2. DCIM → Racks — заведите стойки внутри сайта, укажите высоту в юнитах — дальше устройства размещаются визуально по позициям.
3. DCIM → Device Types → Devices — типы оборудования (модель, вендор, число юнитов) и сами устройства, привязанные к стойке и позиции.
4. IPAM → Aggregates → Prefixes → IP Addresses — сначала крупные агрегаты (например, весь блок, выданный провайдером), затем префиксы для подсетей, затем конкретные адреса на интерфейсах устройств.

Ручной ввод годится для старта, но сила NetBox — в API. Пример синхронизации существующего сервера через pynetbox:

import pynetbox

nb = pynetbox.api("https://netbox.example.com", token="ваш_api_token")

nb.dcim.devices.create(
    name="app-server-01",
    device_type=1,
    site=1,
    status="active",
)

nb.ipam.ip_addresses.create(
    address="10.20.0.15/24",
    status="active",
)

Такими скриптами удобно наполнять базу из существующего инвентаря (Ansible facts, вывод terraform show, старая таблица) без ручного клика по интерфейсу, а дальше держать NetBox источником правды для инвентаря и Terraform-модулей.

Бэкапы, обновления и типичные проблемы

Данные NetBox живут в трёх местах: база Postgres, том netbox-media (загруженные файлы и изображения устройств) и .env с секретами. Бэкап Postgres — простой pg_dump по расписанию:

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

Для регулярных бэкапов с ротацией и переносом во внешнее хранилище подойдёт BorgBackup — туда же логично добавить том netbox-media.

Обновление:

docker compose pull
docker compose up -d
docker compose logs -f netbox   # проверить, что миграции прошли без ошибок

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

Частые проблемы первого месяца:

• Bad Request (400) сразу после логина — не добавлен домен в ALLOWED_HOSTS.
• Загруженные файлы пропадают после пересоздания контейнера — забыли примонтировать том netbox-media, вместо него использовался анонимный volume, удалённый вместе с контейнером.
• Медленный поиск на тысячах объектов — не хватает ресурсов Postgres; для баз с десятками тысяч записей стоит смотреть в сторону выделенного инстанса Postgres, а не контейнера на том же VPS, что и веб-нагрузка. Общие подходы к диагностике — в статье PostgreSQL на сервере: частые ошибки и решения.
• Плагины NetBox требуют совпадения версии с ядром — при обновлении проверяйте совместимость заранее, а не по трейсбеку в логах постфактум.

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