Обзор системы

Назначение

TVIP Provisioning Service — это система автоматической конфигурации TVIP-приставок через механизм provisioning. Сервис обрабатывает запросы от приставок, управляет конфигурациями и предоставляет API для администрирования.

Принцип работы

Общая схема работы

  1. TVIP-приставка делает запрос /prov/tvip_provision.xml с заголовком Mac-Address

  2. Backend проверяет наличие устройства в базе данных

  3. Если устройство отсутствует — создаётся новая запись и возвращается дефолтная конфигурация

  4. Если устройство существует — возвращается его кастомная конфигурация или дефолтная

  5. Администратор может управлять конфигурациями через API или веб-интерфейс

Диаграмма взаимодействия

sequenceDiagram participant T as TVIP Приставка participant P as Provision Service participant D as PostgreSQL participant F as Frontend Note over T: Первое обращение T->>P: GET /prov/tvip_provision.xml P->>D: Проверка устройства D-->>P: Не найдено P->>D: Создание записи P->>D: Получение дефолтного конфига D-->>P: XML конфигурация P-->>T: Возврат дефолтного конфига Note over T: Последующие запросы T->>P: GET /prov/tvip_provision.xml P->>D: Поиск конфигурации D-->>P: Кастомный/дефолтный конфиг P-->>T: Возврат конфига Note over F: Администрирование F->>P: GET /api/devices P-->>F: Список устройств F->>P: PUT /api/default/config/replace P->>D: Обновление дефолтного конфига F->>P: PUT /api/devices/{mac}/config/replace P->>D: Обновление конфига устройства F->>P: POST /api/devices/{mac}/config/reset P->>D: Сброс конфига к дефолту

Архитектурные принципы

Clean Architecture

Проект построен на основе Clean Architecture с чётким разделением на слои:

  • Domain Layer — доменные сущности, value objects, интерфейсы репозиториев

  • Application Layer — use cases с бизнес-логикой

  • Infrastructure Layer — реализация репозиториев, БД, DI

  • Presentation Layer — REST API endpoints

Dependency Injection

Используется встроенный механизм FastAPI Depends() для инжекции зависимостей. Провайдеры зарегистрированы в infrastructure/di/injection.py.

Repository Pattern

Абстракция доступа к данным через интерфейсы репозиториев позволяет легко заменять реализацию хранилища.

Технологический стек

Backend

  • Python 3.9+ — язык программирования

  • FastAPI — веб-фреймворк для REST API

  • SQLAlchemy 2.0 — ORM для работы с PostgreSQL

  • Pydantic — валидация данных

  • asyncpg — асинхронный драйвер для PostgreSQL

  • xmltodict — сериализация конфигураций в XML

  • pydash — работа с вложенными структурами (dot notation)

  • Uvicorn — ASGI сервер

Frontend

  • React 18 — UI библиотека

  • Vite — сборщик и dev сервер

  • Axios — HTTP клиент

  • React Router — маршрутизация

Инфраструктура

  • PostgreSQL — СУБД

  • Docker — контейнеризация

  • Docker Compose — оркестрация контейнеров

  • Nginx — reverse proxy

  • Supervisord — управление процессами в контейнере

Форматы данных

XML конфигурация

TVIP-приставки получают конфигурацию в формате XML. Корневой элемент — <provision>.

Пример структуры:

<?xml version="1.0" encoding="UTF-8"?>
<provision reload="86400">
    <operator name="MyOperator"/>
    <time tz="Europe/Moscow" ntp="pool.ntp.org"/>
    <tv_protocols default="stalker">
        <protocol type="stalker" server="http://portal.example.com"/>
    </tv_protocols>
</provision>

Dot notation

Для API используется формат dot notation — плоское представление XML структуры с точками для навигации по иерархии. Атрибуты обозначаются префиксом @.

Пример:

{
    "provision.@reload": "86400",
    "provision.operator.@name": "MyOperator",
    "provision.time.@tz": "Europe/Moscow",
    "provision.time.@ntp": "pool.ntp.org",
    "provision.tv_protocols.@default": "stalker",
    "provision.tv_protocols.protocol.@type": "stalker",
    "provision.tv_protocols.protocol.@server": "http://portal.example.com"
}

Метаданные устройства

Система хранит следующую информацию об устройствах:

  • MAC-адрес — уникальный идентификатор (формат XX:XX:XX:XX:XX:XX)

  • IP-адрес — последний известный IP

  • Модель приставки — строка из заголовка tvip-model

  • Время последней активности — последний запрос конфигурации

  • ID кастомной конфигурации — ссылка на индивидуальную конфигурацию (если установлена)

Сценарии использования

Базовое развертывание

Для типичного развертывания требуется:

  1. Настроить DNS или hosts файл для перенаправления tvipupdate.net на IP сервера

  2. Запустить систему через Docker Compose

  3. Настроить дефолтную конфигурацию через API или веб-интерфейс

  4. TVIP-приставки автоматически получат конфигурацию при подключении

Управление устройствами

  • Просмотр списка зарегистрированных устройств

  • Фильтрация по IP, модели, времени активности

  • Настройка индивидуальной конфигурации для конкретной приставки

  • Сброс к дефолтной конфигурации

Управление конфигурациями

  • Получение и изменение дефолтной конфигурации

  • Частичное обновление параметров (PATCH-like через PUT с dot notation)

  • Полная замена конфигурации

  • Экспорт/импорт конфигураций

Мониторинг

  • Отслеживание активности устройств (Требует реализации)

  • Проверка времени последнего обращения

  • Аудит изменений конфигураций (Требует реализации)

Ограничения и требования

Сетевые требования

  • TVIP-приставки должны иметь доступ к серверу на порту 7373 (или 80/443 при использовании nginx)

  • Необходима подмена DNS записи tvipupdate.net или настройка hosts файла на приставках

Производительность

Точное оценивание нагрузки зависит от количества устройств и частоты запросов. Пока что не было возможность провести полноценное тестирование под нагрузкой. (Все тесты упирались в железо. Поэтому количестро rps невозможно указать.)

Но из рекомендаций можно выделить следующее:

  • PostgreSQL должна быть настроена для работы с большим количеством одновременных подключений

  • Рекомендуется использовать connection pooling

  • Для высоконагруженных систем рассмотреть масштабирование backend через Kubernetes

Безопасность

  • API не имеет встроенной аутентификации (рекомендуется настроить на уровне nginx)

  • База данных должна быть доступна только внутри Docker сети

  • Рекомендуется использовать HTTPS для production окружения

Следующие шаги