Установка и конфигурация

Содержаниепоказать

Первичная установка
Обновление с пакета mistats на mistats-base
Установка админки MiStats
Логи
- Логи MiStats
- Логи ClickHouse

Первичная установка

Требования

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

процессор: 4 ядра с частотой более 3,5 ГГц, с поддержкой SSE 4.2;
оперативная память: 8 ГБ;
диск: 60 ГБ.

Версии ПО:

Smarty не ниже 2.0 для ТВ-статистики и не ниже 2.12 для видеостатистики;
ClickHouse не ниже 24.3;
Python не ниже 3.8;
ОС: Debian 11, Debian 12, Ubuntu 24.04, Ubuntu 26.04;
отдельная база MiStats на MySQL или PostgreSQL;
Redis.

Часовой пояс сервера MiStats должен совпадать с часовым поясом Smarty. Проверка:

timedatectl | grep 'Time zone'

Если пояса различаются, необходимо задать один и тот же. Пример для Москвы:

timedatectl set-timezone Europe/Moscow

Установка ClickHouse

sudo apt-get install -y apt-transport-https ca-certificates curl gnupg pwgen python3-pip python-is-python3
curl -fsSL 'https://packages.clickhouse.com/rpm/lts/repodata/repomd.xml.key' | sudo gpg --dearmor -o /usr/share/keyrings/clickhouse-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb stable main" | sudo tee \
    /etc/apt/sources.list.d/clickhouse.list
sudo apt-get update

sudo apt-get install -y clickhouse-server clickhouse-client

sudo service clickhouse-server start

Далее нужно запустить клиент ClickHouse. Если он стоит на том же сервере:

clickhouse-client

Если ClickHouse стоит отдельно:

clickhouse-client --host <HOSTNAME> --secure --port 9940 --user <USERNAME> --password <PASSWORD>

В консоли клиента требуется создать базу и пользователя, от имени которого MiStats ходит в ClickHouse. Пароль необходимо сохранить: он понадобится в конфиге MiStats.

CREATE DATABASE smarty_stats;
CREATE USER smarty IDENTIFIED BY '<password>';
GRANT ALL ON smarty_stats.* TO smarty;

Таблицы ClickHouse на этом шаге создавать вручную не нужно. Их создаст миграция после настройки MiStats.

Пакеты MiStats

Пакеты MiStats доступны для скачивания в личном кабинете оператора.

mistats-base — модуль телесмотрения и отчётов;
mistats-video — модуль видеостатистики, требует отдельной опции лицензии.

Версии обоих пакетов в одной установке должны совпадать.

sudo dpkg -i mistats-base_*.deb
sudo dpkg -i mistats-video_*.deb

Вместе с mistats-base ставится утилита mistats_manage (/usr/local/bin) для удобного управления инстансом: миграции, планировщик, сжатие меток.

Первичная настройка

Конфигурация сервиса задаётся в файле /etc/microimpuls/mistats/configuration.yaml. Лицензия — в /etc/microimpuls/mistats/license.yaml.

1. База MiStats

Необходимо создать пустую базу MySQL или PostgreSQL и пользователя. В конфиге MiStats, секция MISTATS_DATABASE, требуется указать данные для подключения:

HOST
PORT
NAME
USER
PASSWORD
DRIVER — драйвер MySQL или PostgreSQL

Пример для MySQL:

MISTATS_DATABASE:
  HOST: 127.0.0.1
  PORT: 3306
  NAME: mistats
  USER: mistats
  PASSWORD: <password>
  DRIVER: mysql

2. Подключение к ClickHouse

В том же конфиге, секция CLICKHOUSE, необходимо указать базу, созданную на шаге установки ClickHouse:

HOST, PORT
DATABASE — в примере выше это smarty_stats
USER, PASSWORD

Пример:

CLICKHOUSE:
  HOST: 127.0.0.1
  PORT: 9000
  DATABASE: smarty_stats
  USER: smarty
  PASSWORD: <password>

3. Лицензия

Ключ лицензии выпускается в личном кабинете оператора и записывается в /etc/microimpuls/mistats/license.yaml. Если ключа нет, mistats не стартует, а в mistats_manage status выводится ошибка с HW key этого сервера. Этот HW key требуется указать в ЛК при выпуске ключа. Сгенерированная лицензия имеет следующий формат:

KEY: "..."
client_id: "..."
client_name: "..."
valid_until: 31.12.2026
features:
  ...

4. Redis, API и CORS

Метки видеостатистики отправляются напрямую с клиентских приложений в MiStats. Их предобработка происходит в Redis, поэтому нужно настроить подключение к нему в configuration.yaml, секция MISTATS_REDIS: HOST, PORT, DB.

Там же требуется задать адрес API для отправки меток и запросов отчётов для админки, секция MISTATS. HOST — адрес, на котором API принимает запросы, PORT — порт. Порт по умолчанию — 8095.

CORS.ENABLED по умолчанию включено. CORS.ALLOWED_HOSTS нужен для меток видеостатистики: в него вносят адреса портала клиентских приложений, с которых запросы уходят в API MiStats, например https://tv.example.com.

Пример:

MISTATS_REDIS:
  HOST: 127.0.0.1
  PORT: 6379
  DB: 0
MISTATS:
  HOST: 0.0.0.0
  PORT: 8095
CORS:
  ENABLED: true
  ALLOWED_HOSTS:
    - https://tv.example.com

5. Окружение, миграции и запуск

Зависимости и миграции ставятся через mistats_manage:

sudo systemctl daemon-reload
sudo mistats_manage venv_install
sudo mistats_manage requirements
sudo mistats_manage migrate clickhouse
sudo mistats_manage migrate mistats_db
sudo mistats_manage start
sudo mistats_manage status

Команды mistats_manage, которыми ставится сервис:

Команда	Что делает
`venv_install`	создаёт окружение в `/usr/share/microimpuls/venvs/mistats`
`requirements`	ставит зависимости
`migrate clickhouse`	накатывает миграции ClickHouse
`migrate mistats_db`	накатывает миграции базы MiStats
`start`, `stop`, `restart`, `status`	управляет сервисами `mistats`, `mistats_queue` и `mistats_scheduler`

В статусе должны быть запущены mistats, mistats_queue и mistats_scheduler. Если установлен mistats-video, планировщик сам поставит в очередь сжатие меток видеосмотрения, отдельный cron для этого не нужен.

Число процессов очереди настраивается в конфиге, секция DRAMATIQ. Для первой установки значения по умолчанию менять не нужно.

Подключение Smarty: телесмотрение

В INSTALLED_APPS конфига Smarty должен быть модуль viewstats. Лицензия Smarty должна содержать этот модуль.

В конфиг Smarty также нужно прописать адрес API MiStats и порог, после которого Smarty выгружает метки из своего Redis:

VIEWSTATS_MISTATS_BASE_URL = 'http://127.0.0.1:8095' # хост и порт, на которых слушает API MiStats
VIEWSTATS_BUFFER_MAX_COUNT = 2500000

Метки телесмотрения с клиентских устройств сначала попадают в Smarty, а потом оттуда выгружаются в MiStats через API /stats/push/, который требует авторизации с помощью токена. Предусмотрено 2 режима авторизации Smarty в MiStats:

VIEWSTATS_MISTATS_API_TOKEN — должен быть заполнен при VIEWSTATS_MISTATS_USE_NEW_AUTH = True
VIEWSTATS_MISTATS_ACCESS_TOKEN — должен быть заполнен при VIEWSTATS_MISTATS_USE_NEW_AUTH = False

Токен VIEWSTATS_MISTATS_API_TOKEN должен совпадать с записью в AUTH.API.TOKENS на стороне MiStats. Значения по умолчанию совпадают. Если токен нужно изменить, то нужно это сделать в обоих конфигах.

После правки конфига необходимо перезапустить uWSGI:

sudo service uwsgi restart

Далее в cron требуется добавить выгрузку меток телесмотрения из Smarty в MiStats. Интервал запуска должен совпадать со значением портальной опции push_stat_interval. По умолчанию она равна 300000 миллисекундам (5 минут), ниже установка команды в cron с тем же периодом:

*/5 * * * * smarty_manage push_stats --settings=settings.<settings name>

Метку телесмотрения Smarty считает завершённой по опции VIEWSTATS_MAXIMUM_MINUTES_BETWEEN_INTERVALS. Рекомендуемое значение — 5 минут, столько же, сколько push_stat_interval по умолчанию. Если интервал портала был увеличен, это значение в минутах также нужно увеличить и не оставлять меньше нового интервала:

VIEWSTATS_MAXIMUM_MINUTES_BETWEEN_INTERVALS = 5

Чтобы приставки и приложения начали отправку меток телесмотрения, в админке Smarty на странице «Настройки STB и приложений» необходимо включить чекбокс «Включить сбор статистических данных на сервер Smarty».

Видеосмотрение

Метки видеосмотрения отправляются напрямую в MiStats, минуя Smarty. На данный момент видеосмотрение отправляют следующие клиентские интерфейсы и приложения:

Futuristic;
Sibseti;
Titanium;
мобильное приложение.

Интерфейсы начинают слать метки, если:

включен чекбокс «Включить сбор статистических данных на сервер Smarty» в админке для устройства;
для устройства добавлена опция mistats_api_url с указанием адреса API MiStats;
адрес портала добавлен в CORS.ALLOWED_HOSTS в конфиге MiStats.

Первая метка отправляется через минуту после старта фильма или серии сериала, следующие — с интервалом опции push_stat_interval.

Проверка authkey меток видеосмотрения происходит по адресу SMARTY.URL. Значение по умолчанию рассчитано на Smarty на том же сервере и порту 8000. В конфиг нужно указать фактический URL Smarty.

Необходимые опции конфига MiStats:

VIDEO_STATS_COMPRESSOR.MAXIMUM_MINUTES_BETWEEN_VIDEO_CHECKPOINTS — через сколько минут без новых меток просмотр считается завершённым. Рекомендуемое значение — 5. Оно не должно быть меньше push_stat_interval, если окно короче паузы между метками, один просмотр режется на несколько.
VIDEO_STATS_COMPRESSOR.CALL_INTERVAL_SECONDS — как часто планировщик запускает сжатие меток, в секундах. Рекомендуемое значение — 600, это 10 минут, примерно вдвое больше окна закрытия.

VIDEO_STATS_COMPRESSOR:
  MAXIMUM_MINUTES_BETWEEN_VIDEO_CHECKPOINTS: 5
  CALL_INTERVAL_SECONDS: 600

На основании этой статистики Smarty умеет создавать подборку популярных фильмов с помощью команды create_video_selection_by_popularity.

Обновление с пакета mistats на mistats-base

Эта инструкция нужна, если уже установлен пакет mistats (до разделения на модули mistats-base и mistats-video):

sudo dpkg -r mistats
sudo dpkg -i mistats-base_*.deb

Если systemd пишет, что unit-файл изменился на диске, необходимо выполнить sudo systemctl daemon-reload.

При переезде у сервиса изменятся пути и формат файлов конфигурации, поэтому нужно будет произвести миграцию текущего конфига на новый формат с помощью специальной команды. При обновлении сборки старая конфигурация не удаляется, а перемещается в /var/lib/mistats/legacy.

После обновления необходимо выполнить:

python3 /usr/share/microimpuls/mistats/backend/commands/migrate_mistats_configuration.py \
  /var/lib/mistats/legacy/configuration.py \
  -d /var/lib/mistats/legacy/mistats_defaults.py \
  -o /etc/microimpuls/mistats/configuration.yaml

Старый конфиг передаётся первым аргументом. -d — путь к defaults.py со значениями по умолчанию. -o — путь, куда записать configuration.yaml. В тот же каталог скрипт записывает license.yaml. Без -o YAML печатается в stdout, а license.yaml не создаётся.

Параметр, которого нет в новой схеме, скрипт не переносит и пишет предупреждение. Если обязательного параметра нет ни в defaults.py, ни в configuration.py, скрипт завершается с ошибкой. Недостающее значение нужно добавить в configuration.yaml по первичной настройке.

Дальше — mistats_manage venv_install, mistats_manage requirements, mistats_manage migrate clickhouse, mistats_manage migrate mistats_db и mistats_manage start. Миграции дополняют уже существующие таблицы ClickHouse.

Установка админки MiStats

Раздел будет дополнен.

Логи

Логи MiStats

Свои логи MiStats пишет в файлы. Пути задаются в /etc/microimpuls/mistats/configuration.yaml, секция LOGS.MISTATS.

ERROR_FILE_PATH — ошибки;
ACCESS_FILE_PATH — обращения к API;
MISTATS_FILE_PATH — основной лог сервиса;
COMMANDS_FILE_PATH — команды.

Ошибка старта, в том числе по лицензии, видна и в mistats_manage status.

Логи ClickHouse

По умолчанию ClickHouse пишет внутренние логи без ограничения хранения. Даже без статистики просмотров это быстро занимает диск.

В /etc/clickhouse-server/config.xml у каждого системного лога (блоки с суффиксом _log) необходимо задать ttl:

<clickhouse>
  <query_log>
    <database>system</database>
    <table>query_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <ttl>event_date + INTERVAL 7 DAY</ttl>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
  </query_log>

  <trace_log>
    <database>system</database>
    <table>trace_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <ttl>event_date + INTERVAL 1 DAY</ttl>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
  </trace_log>

  <metric_log>
    <database>system</database>
    <table>metric_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <ttl>event_date + INTERVAL 3 DAY</ttl>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
  </metric_log>
</clickhouse>

Сильнее всего растёт trace_log. Срок хранения потом можно увеличить. Размер таблиц:

SELECT table, formatReadableSize(sum(bytes)) AS size
FROM system.parts
WHERE database = 'system'
GROUP BY table
ORDER BY sum(bytes) DESC;

Очистить уже накопленное:

TRUNCATE TABLE system.query_log;
TRUNCATE TABLE system.trace_log;
TRUNCATE TABLE system.metric_log;