Полное руководство по развертыванию NetBox в Docker для production-хостинга

Что такое NetBox и зачем он нужен

NetBox — это open-source платформа для управления IP-адресами (IPAM) и инфраструктурой центров обработки данных (DCIM). Созданная инженерами из Network to Code, она стала де-факто стандартом для автоматизации сетевой инфраструктуры.

Ключевые возможности:

• IP адресация — полный цикл управления IPv4/IPv6, подсетями, VLAN, VRF
• DCIM — стойки, устройства, соединения, кабели, PDU, питание
• Инвентаризация — модели устройств, производители, серийные номера
• API — полноценный REST API с фильтрацией и поиском
• Автоматизация — интеграция с Ansible, Terraform, Nornir

Для чего используют NetBox в 2026 году:

Сценарий	Примеры
Источник истины (Source of Truth)	Все IP-адреса и устройства хранятся в едином месте
Баз данных для автоматизации	Ansible забирает данные по API для деплоя конфигураций
Аудит и документация	История изменений, кто и когда менял IP
Планирование сети	Проектирование новых сегментов перед внедрением

---

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

Для комфортной работы NetBox в Docker-контейнерах нужен сервер со следующими характеристиками:

Минимальные спецификации:

Компонент	Минимум	Рекомендуется
CPU	2 ядра	4 ядра
RAM	4 ГБ	8 ГБ
Диск	20 ГБ SSD	50 ГБ SSD
Docker	20.10.10+	Последняя стабильная
Docker Compose	1.28.0+	2.0+

Проверка перед установкой:

bash

# Убедитесь, что Docker установлен корректно
docker --version
docker compose version

# Проверьте свободное место
df -h /

# Проверьте доступные порты
ss -tulpn | grep 8000  # По умолчанию NetBox использует 8000

Сетевая доступность:

• Внешний доступ: порт 8000 (можно изменить)
• Внутри контейнеров: PostgreSQL (5432), Redis (6379), Redis-cache (6379)

---

Быстрый старт

Этот раздел позволит запустить NetBox за 5 минут для тестирования.

Шаг 1. Клонируем репозиторий

Используем официальный репозиторий от сообщества NetBox:

bash

git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker

Ветка release — стабильная версия, готовая для production. Для разработчиков есть ветка develop с новыми фичами.

Шаг 2. Настраиваем окружение

Создаём файл переопределения для docker-compose:

bash

cp docker-compose.override.yml.example docker-compose.override.yml

Теперь создаём файл с переменными окружения:

bash

# Переходим в папку с env-файлами
cd env

# Копируем шаблон
cp netbox.env.example netbox.env

# Открываем для редактирования
nano netbox.env

Минимальная конфигурация для первого запуска:

bash

# Генерируем секретный ключ (ВАЖНО: свой для каждого экземпляра!)
SECRET_KEY=your-super-secret-key-here-12345

# Разрешенные хосты
ALLOWED_HOSTS=localhost 127.0.0.1

# Данные суперпользователя
SKIP_SUPERUSER=false
SUPERUSER_NAME=admin
SUPERUSER_EMAIL=admin@example.com
SUPERUSER_PASSWORD=StrongPassword123!
SUPERUSER_API_TOKEN=your-api-token-1234567890

# База данных
DB_NAME=netbox
DB_USER=netbox
DB_PASSWORD=netbox_password_123
DB_HOST=postgres
DB_PORT=5432

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=redis_password_123
REDIS_CACHE_HOST=redis-cache
REDIS_CACHE_PORT=6379
REDIS_CACHE_PASSWORD=redis_cache_password_123

Важно: Пароли должны быть надёжными. Используйте генераторы паролей.

Шаг 3. Запускаем контейнеры

Первый запуск — самый важный момент:

bash

# Скачиваем образы
docker compose pull

# Запускаем (в фоне)
docker compose up -d

Что происходит в этот момент:

1. Поднимаются 5 контейнеров:
   • netbox — веб-приложение (Django + Granian)
   • netbox-worker — Celery для фоновых задач
   • netbox-housekeeping — периодические задачи
   • postgres — база данных
   • redis и redis-cache — кеширование
2. PostgreSQL инициализируется
3. Django выполняет миграции
4. Создаётся суперпользователь
5. Запускается HTTP-сервер на порту 8000

Шаг 4. Проверяем работу

bash

# Статус контейнеров
docker compose ps

# Логи запуска (важно при проблемах)
docker compose logs netbox

# Проверяем, что все сервисы healthy
docker compose ps --format "table {{.Name}}\t{{.Status}}"

Если всё хорошо, открываем браузер:

• http://<IP-вашего-сервера>:8000
• Логин: admin
• Пароль: StrongPassword123!

Жмите на кнопку «Login» и вы внутри!

---

Настройка для production

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

1. Настройка перезапуска контейнеров

Добавьте в docker-compose.override.yml политику перезапуска для всех сервисов:

yaml

services:
  netbox:
    restart: unless-stopped
    
  netbox-worker:
    restart: unless-stopped
    
  netbox-housekeeping:
    restart: unless-stopped
    
  postgres:
    restart: unless-stopped
    volumes:
      - netbox-postgres-data:/var/lib/postgresql/data
      
  redis:
    restart: unless-stopped
    
  redis-cache:
    restart: unless-stopped

2. Увеличение времени health check

На медленных серверах миграции могут занять больше минуты:

yaml

services:
  netbox:
    healthcheck:
      start_period: 120s  # увеличиваем с 60 до 120 секунд
      timeout: 30s
      retries: 5

3. Настройка HTTPS (обязательно для production!)

Официальный образ NetBox не включает встроенный HTTPS. Используйте обратный прокси:

Вариант с Traefik (рекомендуется для Docker-хостинга):

yaml

# docker-compose.override.yml
services:
  netbox:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.netbox.rule=Host(`netbox.your-domain.com`)"
      - "traefik.http.routers.netbox.entrypoints=websecure"
      - "traefik.http.routers.netbox.tls.certresolver=letsencrypt"
      - "traefik.http.services.netbox.loadbalancer.server.port=8080"

Вариант с Nginx (классический):

nginx

# /etc/nginx/sites-available/netbox
server {
    listen 443 ssl http2;
    server_name netbox.your-domain.com;
    
    ssl_certificate /etc/letsencrypt/live/netbox.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/netbox.your-domain.com/privkey.pem;
    
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

4. Переменные для production

Обновите env/netbox.env:

bash

# Обязательно измените
SECRET_KEY=<новый-уникальный-ключ>

# Добавьте все домены
ALLOWED_HOSTS=netbox.your-domain.com 192.168.1.100 localhost

# Отключите отладочный режим
DEBUG=false

5. Создание резервных копий

Резервное копирование базы данных:

bash

# Ежедневный бэкап
docker compose exec -T postgres pg_dump -U netbox netbox > backup_$(date +%Y%m%d).sql

# Или через cron
0 2 * * * cd /opt/netbox-docker && docker compose exec -T postgres pg_dump -U netbox netbox > /backups/netbox_$(date +\%Y\%m\%d).sql

Резервное копирование данных:

bash

# Копируем всё
tar -czf netbox_backup_$(date +%Y%m%d).tar.gz \
  .env \
  env/ \
  configuration/ \
  docker-compose.override.yml

Архитектура и внутреннее устройство

Понимание того, как работает система, критически важно для администрирования.

Схема работы контейнеров

Жизненный цикл контейнера netbox

При старте контейнера выполняется docker-entrypoint.sh:

1. Ожидание PostgreSQLbash# Проверка каждые 3 секунды, максимум 30 попыток while ! pg_isready -h $DB_HOST -p $DB_PORT -U $DB_USER; do sleep 3 done
2. Выполнение миграцийbashpython3 manage.py migrate python3 manage.py trace_paths # пересчёт топологии кабелей python3 manage.py reindex —lazy # обновление поиска
3. Создание суперпользователя (если не создан)bashif ! SKIP_SUPERUSER; then echo «from django.contrib.auth.models import User; \ User.objects.create_superuser(‘$SUPERUSER_NAME’, \ ‘$SUPERUSER_EMAIL’, ‘$SUPERUSER_PASSWORD’)» | python3 manage.py shell fi
4. Запуск HTTP-сервераbashgranian \ —host 0.0.0.0 \ —port 8080 \ —interface wsgi \ —workers 4 \ —threads 8 \ —static-path-mount /static \ netbox.wsgi:application

Использование Granian вместо Gunicorn

Начиная с версии 4.0, NetBox использует Granian — Rust-сервер, который:

Характеристика	Gunicorn (старый)	Granian (новый)
Производительность	✅	🚀 в 2-3 раза выше
Потребление памяти	150-200 МБ	80-100 МБ
Статика	через Nginx	напрямую через —static-path-mount
WebSockets	нет	есть

Почему это круто для вас: меньше памяти, выше скорость, проще настройка.

---

Продвинутые возможности

Работа с плагинами

Плагины расширяют функциональность NetBox. Популярные плагины:

Плагин	Назначение
netbox-topology-views	Визуализация топологии сети
netbox-bgp	Управление BGP-сессиями
netbox-dns	Управление DNS-записями
netbox-device-bay	Управление блэйд-серверами

Установка плагина (на примере netbox-topology-views):

bash

# 1. Заходим в контейнер с правами root
docker compose exec -it --user root netbox /usr/bin/bash

# 2. Устанавливаем плагин
pip install netbox-topology-views

# 3. Выходим и добавляем в конфигурацию
exit

Создаём файл configuration/extra.py:

python

# Добавляем плагин
PLUGINS = [
    'netbox_topology_views',
]

# Конфигурация плагина
PLUGINS_CONFIG = {
    'netbox_topology_views': {
        'enable_napalm': False,  # если не используете NAPALM
        'enable_nautobot': False
    }
}

Перезапускаем контейнер:

bash

docker compose restart netbox

Настройка LDAP-аутентификации

Если у вас корпоративная сеть, подключите Active Directory:

bash

# Устанавливаем пакет LDAP
docker compose exec -it --user root netbox pip install django-auth-ldap

configuration/extra.py:

python

import ldap
from django_auth_ldap.config import LDAPSearch, LDAPGroupQuery

AUTH_LDAP_SERVER_URI = "ldap://dc.your-domain.com"
AUTH_LDAP_BIND_DN = "cn=service,dc=your-domain,dc=com"
AUTH_LDAP_BIND_PASSWORD = "YourServicePassword123"
AUTH_LDAP_USER_SEARCH = LDAPSearch(
    "dc=your-domain,dc=com",
    ldap.SCOPE_SUBTREE,
    "(sAMAccountName=%(user)s)"
)
AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
    "dc=your-domain,dc=com",
    ldap.SCOPE_SUBTREE,
    "(objectClass=group)"
)

# Группы для автоматического назначения прав
AUTH_LDAP_USER_FLAGS_BY_GROUP = {
    "is_active": "cn=netbox_users,dc=your-domain,dc=com",
    "is_staff": "cn=netbox_admins,dc=your-domain,dc=com",
    "is_superuser": "cn=netbox_superadmins,dc=your-domain,dc=com"
}

Интеграция с Prometheus для мониторинга

Добавляем экспорт метрик в configuration/extra.py:

python

# Prometheus метрики
INSTALLED_APPS.append('django_prometheus')

MIDDLEWARE = [
    'django_prometheus.middleware.PrometheusBeforeMiddleware',
] + MIDDLEWARE + [
    'django_prometheus.middleware.PrometheusAfterMiddleware',
]

И в docker-compose.override.yml добавляем:

yaml

services:
  netbox:
    ports:
      - "8000:8080"
      - "8001:8001"  # метрики
    environment:
      PROMETHEUS_METRICS_PORT: 8001

Настройка логирования в Elasticsearch

Для централизованного сбора логов:

configuration/logging.py:

python

LOGGING = {
    'version': 1,
    'handlers': {
        'elasticsearch': {
            'level': 'INFO',
            'class': 'logstash_async.handlers.AsynchronousLogstashHandler',
            'host': 'elasticsearch.your-domain.com',
            'port': 5000,
            'database_path': '/tmp/logstash.db',
        }
    },
    'loggers': {
        'django': {
            'handlers': ['elasticsearch'],
            'level': 'INFO',
        },
        'netbox': {
            'handlers': ['elasticsearch'],
            'level': 'INFO',
        }
    }
}

---

Управление и обслуживание

Повседневные команды

Просмотр логов:

bash

# Все логи
docker compose logs

# Только веб-приложение
docker compose logs netbox

# Только ошибки
docker compose logs netbox | grep ERROR

# Логи в реальном времени
docker compose logs -f netbox

Вход в консоль Django:

bash

docker compose exec netbox python manage.py shell

Выполнение команд управления:

bash

# Создать пользователя
docker compose exec netbox python manage.py createsuperuser

# Переиндексация поиска (если что-то не находится)
docker compose exec netbox python manage.py reindex

# Очистка кэша
docker compose exec netbox python manage.py clear_cache

# Проверка миграций
docker compose exec netbox python manage.py migrate --check

Обновление NetBox

Безопасное обновление:

bash

# 1. Делаем бэкап
docker compose exec -T postgres pg_dump -U netbox netbox > backup_before_update.sql

# 2. Скачиваем новую версию
git pull origin release

# 3. Пересобираем образы
docker compose build --pull

# 4. Запускаем с миграциями
docker compose up -d

# 5. Проверяем логи
docker compose logs netbox --tail 50

Внимание: Если вы используете плагины, проверьте их совместимость с новой версией NetBox.

Мониторинг состояния

bash

# Проверка здоровья всех сервисов
docker compose ps

# Проверка через API
curl http://localhost:8000/api/status/

# Проверка базы данных
docker compose exec postgres psql -U netbox -c "SELECT version();"

---

Решение проблем

Проблема 1: Контейнер не стартует, висит в unhealthy

Причина: Миграции занимают больше времени, чем health check ожидает.

Решение: Увеличьте start_period:

yaml

services:
  netbox:
    healthcheck:
      start_period: 180s

Проблема 2: Ошибка подключения к PostgreSQL

Причина: Неправильные учётные данные или PostgreSQL не готов.

Решение: Проверьте логи:

bash

docker compose logs postgres

Включите дебаг подключения в env/netbox.env:

bash

DB_WAIT_DEBUG=1

Проблема 3: Глобальный поиск не работает

Причина: Индекс поиска повреждён или устарел.

Решение:

bash

# Полная переиндексация
docker compose exec netbox python manage.py reindex

# Сброс и пересоздание индекса
docker compose exec netbox python manage.py reindex --clear

Проблема 4: Не сохраняются изменения в IP-адресах

Причина: Проблемы с кэшированием Redis.

Решение:

bash

# Очистка кэша
docker compose exec netbox python manage.py clear_cache

# Перезапуск Redis
docker compose restart redis redis-cache

Проблема 5: Плагин не виден в интерфейсе

Причина: Плагин не добавлен в PLUGINS в конфигурации.

Решение: Проверьте configuration/extra.py и перезапустите:

bash

docker compose exec netbox python manage.py validate_plugins
docker compose restart netbox

---

Безопасность и оптимизация

Чек-лист безопасности для production

• □ SECRET_KEY сгенерирован уникальный (не из примера!)
• □ DEBUG=False в production
• □ ALLOWED_HOSTS содержит только ваши домены
• □ Используется HTTPS (через обратный прокси)
• □ Пароли в env-файлах сложные (минимум 16 символов)
• □ Регулярные бэкапы базы данных
• □ Обновления устанавливаются не реже раза в месяц
• □ Логирование настроено (не в stdout в продакшене)

Оптимизация производительности

1. Настройка количества воркеров:

В docker-compose.override.yml:

yaml

services:
  netbox-worker:
    environment:
      CELERY_WORKER_CONCURRENCY: 4  # по числу ядер CPU

2. Увеличение лимитов PostgreSQL:

В docker-compose.override.yml:

yaml

services:
  postgres:
    command: 
      - "postgres"
      - "-c"
      - "max_connections=200"
      - "-c"
      - "shared_buffers=256MB"
      - "-c"
      - "effective_cache_size=768MB"

3. Использование Redis-кэша:

В configuration/extra.py:

python

CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': f'redis://:{REDIS_CACHE_PASSWORD}@{REDIS_CACHE_HOST}:{REDIS_CACHE_PORT}/1',
        'OPTIONS': {
            'CLIENT_CLASS': 'django_redis.client.DefaultClient',
            'PARSER_CLASS': 'redis.connection.HiredisParser',
            'CONNECTION_POOL_CLASS': 'redis.BlockingConnectionPool',
            'CONNECTION_POOL_CLASS_KWARGS': {
                'max_connections': 50,
                'timeout': 20,
            },
            'MAX_CONNECTIONS': 50,
            'PICKLE_VERSION': -1,
        },
    }
}

Автоматизация с Ansible

Пример playbook для ежедневного обслуживания:

yaml

---
- name: NetBox maintenance
  hosts: netbox-server
  tasks:
    - name: Backup database
      docker_container_exec:
        container: netbox-postgres
        command: pg_dump -U netbox netbox
      register: backup
    
    - name: Save backup
      copy:
        content: "{{ backup.stdout }}"
        dest: "/backups/netbox_{{ ansible_date_time.date }}.sql"
    
    - name: Reindex search
      docker_container:
        name: netbox
        command: python manage.py reindex

---

Заключение

NetBox в Docker — это мощное, масштабируемое решение для управления сетевой инфраструктурой. Следуя этому руководству, вы развернёте production-ready систему, которую можно использовать как:

• Единый источник правды для всей сетевой команды
• Базу для автоматизации (Ansible, Terraform, Python-скрипты)
• Платформу для планирования новых сегментов и устройств

Полезные ссылки:

• Официальный репозиторий netbox-docker
• Документация NetBox
• Сообщество NetBox в Slack
• Плагины для NetBox

Дальнейшие шаги:

1. Настройте внешний доступ через HTTPS
2. Импортируйте свои данные через API или CSV
3. Настройте резервное копирование
4. Подключите мониторинг (Prometheus + Grafana)
5. Интегрируйте с вашими системами автоматизации

Удачи в управлении вашей сетью! 🚀