Лимит устройств (HWID)
HWID — идентификатор устройства, который клиентское приложение присылает вместе с запросом подписки. По нему панель понимает, что подписку запрашивает то же самое устройство, а не новое, и может ограничить их количество.
Функция полностью необязательна и выключена по умолчанию. Она работает
только с клиентами, которые умеют отправлять заголовок x-hwid.
Как включить
Лимит настраивается в панели в разделе Subscription → Settings → HWID Device
Limit, а не в .env. Доступны три параметра: сам переключатель, лимит
устройств по умолчанию и текст объявления для клиента. Для отдельного
внешнего сквода настройки можно переопределить, а каждому пользователю —
задать собственный лимит.
| Место | Что задаёт |
|---|---|
| Глобальные настройки подписки | включает лимит, лимит по умолчанию, текст объявления |
| Внешний сквод | переопределяет глобальные настройки для своих пользователей |
| Карточка пользователя | личный лимит устройства для одного пользователя |
Если у пользователя лимит не задан, применяется лимит по умолчанию. Значение
0 в карточке пользователя отключает лимит для него: устройства по-прежнему
записываются, но подписка выдаётся всегда.
Если лимит включён, а клиент не прислал заголовок x-hwid, подписка не
выдаётся. Перед включением убедитесь, что ваши пользователи пользуются
поддерживающими клиентами, иначе они потеряют доступ.
Какие заголовки шлёт клиент
| Заголовок | Обязателен | Описание |
|---|---|---|
x-hwid | да | идентификатор устройства |
x-device-os | нет | платформа, например iOS |
x-ver-os | нет | версия системы |
x-device-model | нет | модель устройства |
user-agent | нет | приложение и его версия |
Значение x-hwid должно состоять из 10–64 символов: латинские буквы, цифры,
знаки = и -. Если формат не подходит, панель отбрасывает заголовок целиком
и считает, что HWID не передан.
curl -H 'x-hwid: UE42LJXu4DbiCaBv' \
-H 'x-device-os: iOS' \
-H 'x-ver-os: 18.3' \
-H 'x-device-model: iPhone 14 Pro Max' \
https://sub.example.com/XXXXXXXXXXXX
В ответ панель добавляет служебные заголовки, по которым клиент показывает понятное сообщение пользователю:
| Заголовок ответа | Когда появляется |
|---|---|
x-hwid-active | лимит включён на стороне панели |
x-hwid-not-supported | лимит включён, но клиент не прислал x-hwid |
x-hwid-max-devices-reached | достигнут максимум устройств |
x-hwid-limit | то же, для совместимости со старыми клиентами |
Что хранится
Каждое устройство попадает в таблицу hwid_user_devices. Ключ — пара
«HWID + пользователь», поэтому одно и то же устройство у двух пользователей
считается двумя записями.
| Колонка | Содержимое |
|---|---|
hwid | идентификатор устройства, до 64 символов |
user_id | владелец подписки |
platform | платформа из x-device-os |
os_version | версия системы из x-ver-os |
device_model | модель из x-device-model |
user_agent | приложение из user-agent |
request_ip | IP-адрес запроса подписки |
created_at, updated_at | когда устройство впервые и последний раз видели |
Что видно в панели
В карточке пользователя отображается список его устройств: платформа, версия системы, модель, IP и даты. Устройство можно удалить по одному или очистить весь список — после этого оно снова сможет подключиться. Есть поиск по HWID.
На отдельной странице HWID собрана сводка: распределение по платформам и
приложениям, общее число уникальных устройств и записей, среднее число
устройств на пользователя, а также список пользователей с наибольшим числом
устройств. Эти же данные доступны по API — команды GET /api/hwid/devices,
GET /api/hwid/stats и GET /api/hwid/devices/top-users.
События добавления и удаления устройства (user_hwid_devices.added и
user_hwid_devices.deleted) приходят в вебхуки. Подробнее —
в разделе Вебхуки.
Срок хранения и приватность
Таблица hwid_user_devices — самая чувствительная в базе: в ней лежат
идентификатор устройства, модель, версия системы, user-agent и IP-адрес. Она
не чистится автоматически, пока вы не включите автоочистку.
| Переменная | По умолчанию | Что делает |
|---|---|---|
SERVICE_CLEAN_OLD_LOGS | false | включает недельную очистку чувствительных таблиц |
HWID_DEVICES_RETENTION_DAYS | 90 | сколько дней хранить устройство |
Отсчёт ведётся от updated_at, то есть от последнего появления устройства:
активно используемые устройства сохраняются, а те, что не возвращались дольше
срока, удаляются. Задача выполняется раз в неделю, в понедельник ночью.
Если история устройств вам не нужна, сократите срок хранения или очистите таблицу вручную — через раздел Logs в панели или аварийный CLI.
Удаление устройства снимает защиту от передачи подписки: пользователь сможет подключить её на новом устройстве, если есть свободный слот. Сравнивайте списки устройств перед массовой очисткой.
Что дальше
- Вебхуки — события устройств и подпись payload.
- Уведомления — оповещения о порогах и истечении.
- Аварийный CLI — массовая очистка устройств.
- Переменные окружения — сроки хранения.