device-type: Модуль обнаружения устройств для NGINX

Установка на Debian/Ubuntu

Эти документы относятся к APT пакету nginx-module-device-type, предоставляемому репозиторием GetPageSpeed Extras.

Настройте APT репозиторий, как описано в Настройке APT репозитория.
Установите модуль:

sudo apt-get update
sudo apt-get install nginx-module-device-type

Показать дистрибутивы и архитектуры

| Дистрибутив | Версия            | Компонент  | Архитектуры   |
|-------------|-------------------|------------|----------------|
| debian      | bookworm          | main       | amd64, arm64   |
| debian      | bookworm-mainline | main       | amd64, arm64   |
| debian      | trixie            | main       | amd64, arm64   |
| debian      | trixie-mainline   | main       | amd64, arm64   |
| ubuntu      | focal             | main       | amd64, arm64   |
| ubuntu      | focal-mainline    | main       | amd64, arm64   |
| ubuntu      | jammy             | main       | amd64, arm64   |
| ubuntu      | jammy-mainline    | main       | amd64, arm64   |
| ubuntu      | noble             | main       | amd64, arm64   |
| ubuntu      | noble-mainline    | main       | amd64, arm64   |

Высокопроизводительное обнаружение устройств для NGINX — непосредственно на границе.

Зачем нужен этот модуль?

Обнаружение устройств критически важно для:

Адаптивной подачи — подача активов, оптимизированных для мобильных устройств, без перенаправлений
Сегментации кэша — изменение кэшируемого контента в зависимости от типа устройства
Управления ботами — блокировка собирающих данных, ограничение доступа для краулеров, разрешение для поисковых систем
Контроля AI-краулеров — идентификация и управление GPTBot, ClaudeBot и другими ботами для обучения AI
Обогащения аналитики — передача контекста устройства на бэкенды

Традиционные решения требуют внешних API вызовов, что добавляет задержку и повышение затрат. Этот модуль выполняет обнаружение в процессе с использованием предкомпилированных шаблонов regex — никаких сетевых кругов, никаких сборов за каждый запрос.

Особенности

Особенность	Описание
22 переменные NGINX	Тип устройства, браузер, ОС, классификация бота — всё в виде нативных переменных
4,000+ шаблонов обнаружения	Полное покрытие поддерживается GetPageSpeed
Поддержка Client Hints	Высокая точность обнаружения с современными браузерами
Обнаружение AI-краулеров	Идентификация GPTBot, ClaudeBot, Anthropic-AI, CCBot и более 50 AI ботов
Классификация ботов	Классифицировать как `search_engine`, `ai_crawler`, `crawler`, `monitoring`, `scraper`
JSON вывод	Полный результат обнаружения в виде одной переменной JSON
Нулевая конфигурация	Загрузите модуль, используйте переменные — никаких директив не требуется
Кэширование на уровне запроса	Обнаружение выполняется один раз на запрос, результаты кэшируются в контексте модуля

Статистика шаблонов

800+ шаблонов ботов с категорией, производителем и флагом AI-краулера
500+ шаблонов браузеров с извлечением версии и выявлением движка
300+ шаблонов ОС с классификацией версии и семейства
2,000+ шаблонов устройств для обнаружения бренда и модели

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

1. Загрузите модуль

load_module modules/ngx_http_device_type_module.so;

2. Используйте переменные

server {
    # Подача различного контента в зависимости от устройства
    location / {
        if ($is_mobile) {
            rewrite ^(.*)$ /m$1 last;
        }
    }

    # Блокировка AI-краулеров
    location /content/ {
        if ($is_ai_crawler) {
            return 403;
        }
        proxy_pass http://backend;
    }

    # Отладочный конечный пункт
    location = /device {
        default_type application/json;
        return 200 $device_json;
    }
}

Справочник переменных

Тип устройства

Переменная	Значения	Описание
`$device_type`	`mobile`, `tablet`, `desktop`, `tv`, `console`, `car`, `wearable`, `camera`, `peripheral`, `bot`	Основная классификация
`$is_mobile`	`1` / `0`	Телефон или мобильный браузер
`$is_tablet`	`1` / `0`	Устройство планшета
`$is_desktop`	`1` / `0`	Настольный компьютер или ноутбук
`$is_bot`	`1` / `0`	Бот или краулер
`$is_tv`	`1` / `0`	Смарт ТВ
`$is_console`	`1` / `0`	Игровая консоль
`$is_wearable`	`1` / `0`	Умное устройство

Детали устройства

Переменная	Пример	Описание
`$device_brand`	`Apple`, `Samsung`, `Google`	Производитель устройства
`$device_model`	`iPhone 15`, `Galaxy S24`, `Pixel 8`	Модель устройства

Браузер

Переменная	Пример	Описание
`$browser_name`	`Chrome`, `Firefox`, `Safari`	Название браузера
`$browser_version`	`120.0.0.0`	Полная строка версии
`$browser_family`	`Chrome`, `Firefox`, `Safari`	Семейство браузера
`$browser_engine`	`Blink`, `Gecko`, `WebKit`	Движок рендеринга

Операционная система

Переменная	Пример	Описание
`$os_name`	`Windows`, `Android`, `iOS`	Название ОС
`$os_version`	`14`, `17.2`, `11`	Версия ОС
`$os_family`	`Windows`, `Android`, `Unix`, `iOS`, `macOS`	Семейство ОС

Классификация ботов

Переменная	Пример	Описание
`$bot_name`	`Googlebot`, `GPTBot`, `ClaudeBot`	Идентификатор бота
`$bot_category`	`search_engine`, `ai_crawler`, `crawler`	Категория бота
`$bot_producer`	`Google`, `OpenAI`, `Anthropic`	Оператор бота
`$is_ai_crawler`	`1` / `0`	AI краулер для обучения/поиска

JSON вывод

Переменная	Описание
`$device_json`	Полный результат обнаружения в формате JSON

Пример JSON:

{
  "type": "mobile",
  "browser": {"name": "Chrome", "version": "120.0", "engine": "Blink"},
  "os": {"name": "Android", "version": "14", "family": "Android"},
  "device": {"brand": "Google", "model": "Pixel 8"},
  "bot": null
}

JSON обнаружения бота:

{
  "type": "bot",
  "browser": {"name": "", "version": "", "engine": ""},
  "os": {"name": "", "version": "", "family": ""},
  "device": {"brand": "", "model": ""},
  "bot": {"name": "GPTBot", "category": "ai_crawler", "producer": "OpenAI", "is_ai": true}
}

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

Адаптивная подача контента

## Подача страниц, оптимизированных для мобильных устройств
location / {
    set $variant "desktop";
    if ($is_mobile) { set $variant "mobile"; }
    if ($is_tablet) { set $variant "tablet"; }

    proxy_pass http://backend;
    proxy_set_header X-Device-Variant $variant;
}

Вариация ключа кэша

## Изменение кэша по типу устройства
proxy_cache_key "$scheme$request_uri|$device_type";

## Или просто мобильное против настольного
proxy_cache_key "$scheme$request_uri|$is_mobile";

Управление ботами

## Блокировка краулеров для обучения AI
location / {
    if ($is_ai_crawler) {
        return 403 "AI-краулеры не допускаются";
    }
}

## Ограничение частоты для собирающих данных, разрешение поисковым системам
limit_req_zone $binary_remote_addr zone=scraper:10m rate=1r/s;

location / {
    if ($bot_category = "scraper") {
        limit_req zone=scraper;
    }
    proxy_pass http://backend;
}

Заголовки аналитики

location /api/ {
    proxy_set_header X-Device-Type $device_type;
    proxy_set_header X-Device-Brand $device_brand;
    proxy_set_header X-Browser $browser_name;
    proxy_set_header X-OS $os_name;
    proxy_set_header X-Is-Bot $is_bot;
    proxy_pass http://backend;
}

Отладочный конечный пункт

location = /debug/device {
    default_type text/plain;
    return 200 "Тип: $device_type
Мобильный: $is_mobile
Планшет: $is_tablet
Настольный: $is_desktop
Бот: $is_bot ($bot_name)
AI Краулер: $is_ai_crawler
Браузер: $browser_name $browser_version
Движок: $browser_engine
ОС: $os_name $os_version ($os_family)
Устройство: $device_brand $device_model
";
}

Client Hints

Для повышения точности обнаружения с браузерами на основе Chromium, рекламируйте Client Hints:

add_header Accept-CH "Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version";
add_header Critical-CH "Sec-CH-UA-Mobile";

Модуль обрабатывает эти Client Hints:

Заголовок	Используется для
`Sec-CH-UA`	Бренд и версия браузера
`Sec-CH-UA-Mobile`	Индикатор мобильного устройства (`?1` = мобильный)
`Sec-CH-UA-Model`	Модель устройства (подсказки для планшета/телефона)
`Sec-CH-UA-Platform`	Название ОС
`Sec-CH-UA-Platform-Version`	Версия ОС

Client Hints предоставляют более точную информацию, чем парсинг User-Agent и являются будущим обнаружения устройств.

Приоритет обнаружения

Модуль оценивает сигналы в следующем порядке:

Обнаружение ботов — совпадение regex с более чем 800 шаблонами ботов
Client Hints — если присутствуют, используются для обнаружения мобильных устройств/планшетов/браузеров/ОС
Быстрая проверка UA — быстрые подстрочные совпадения для iPad, iPhone, PlayStation и т. д.
Полные шаблоны устройств — более 2,000 regex шаблонов для бренда/модели
Эвристика для планшетов Android — Android без токена "Mobile" → планшет
Резервный вариант для мобильных устройств — токен "Mobile" → мобильный
Обнаружение браузера — более 500 шаблонов с захватом версии
Обнаружение движка — Blink, Gecko, WebKit и т. д.
Обнаружение ОС — более 300 шаблонов с классификацией семейства

Результаты кэшируются на уровне запроса в контексте модуля.

Сравнение с альтернативами

Особенность	Этот модуль	51Degrees	WURFL	DeviceAtlas
Обнаружение в процессе	✅	✅	✅	❌ (облако)
Без затрат на каждый запрос	✅	❌	❌	❌
Обнаружение AI-краулеров	✅	❌	❌	❌
Классификация ботов	✅	Ограниченная	Ограниченная	Ограниченная
Client Hints	✅	✅	✅	✅
JSON вывод	✅	❌	❌	❌
Динамический модуль	✅	✅	✅	N/A
##