Диагностика типовых проблем

Документ для IT-администратора. Пошаговая диагностика от симптома к решению. Каждый раздел — независимый сценарий, искать через TOC.

Содержание

1. Устройство не enrolled
2. Политика не применяется на устройство
3. Kiosk-режим ломается после перезагрузки
4. Lost mode не работает
5. Remote Assist не подключается
6. MQTT disconnect storm
7. Dashboard 500 / tile 403 / CSP report overflow
8. Где смотреть логи

1. Устройство не enrolled

1.1. Сценарии

QR-сканирование не переходит в установку DPC. - Устройство запускает встроенный браузер вместо DPC-процесса. - На экране appears Ошибка конфигурации DPC.

DPC устанавливается, но в /devices не появляется. - DPC активен, видно в шторке уведомлений, но в admin UI устройство не видно.

Устройство было enrolled, но пропало из списка онлайн.

1.2. Диагностика

Шаг 1 — определить, какой тип provisioning используется

Если клиент не использует Google Play (ТСД на AOSP), только QR работает.

Шаг 2 — проверить содержимое QR

Расшифруйте QR-код любым сканером. Должен содержать JSON:

{
  "android.app.extra.PROVISIONING_DEVICE_ADMIN_COMPONENT_NAME":
    "ru.komendant.dpc/.receivers.AdminReceiver",
  "android.app.extra.PROVISIONING_DEVICE_ADMIN_SIGNATURE_CHECKSUM":
    "<base64-sha256>",
  "android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION":
    "https://mdm.example.ru/downloads/dpc.apk",
  "android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE": {
    "server_url": "https://api.mdm.example.ru",
    "enroll_token": "<jwt>"
  }
}

Частые проблемы QR:

Шаг 3 — DPC установился, но не подключается к MQTT

На устройстве включить USB-debug, получить логи:

adb logcat -s KomendantDPC MQTT

Ищем строки:

Шаг 4 — устройство подключено к MQTT, но нет в /devices

# на сервере
journalctl -u komendant-api --since "10 min ago" | grep -i enroll

Ищем строки enroll.register. Частые ошибки:

• ErrTenantQuotaExceeded — превышен max_devices лицензии → увеличить лицензию
• ErrFingerprintMismatch — устройство заявляет другой hardware-fingerprint чем при первом enroll → re-enroll через factory reset
• ErrTenantMismatch — токен для tenant A, но broker routes в tenant B → проверить /settings/enroll/codes на корректность

1.3. Edge cases

• Xiaomi/Realme/OPPO — у этих OEM агрессивное killing фоновых процессов. В onboarding-инструкции для пользователя: Настройки → Батарея → Без ограничений для DPC.
• Huawei без GMS — DPC работает, но FCM-пуши не доступны; используется pure MQTT. Убедитесь, что MQTT-keepalive ≤ 60 сек.
• Samsung Knox — для полного контроля нужен Knox-E-FOTA. В пилоте Триола — стандартный DPC через Android Enterprise.

2. Политика не применяется на устройство

2.1. Симптом

В admin UI /devices/<id> → Policy Applied показывает desired_version=5, applied_version=3 и висит так > 10 минут.

2.2. Диагностика

Шаг 1 — проверить, получило ли устройство policy push

/devices/<id>/timeline

Событие policy.push.sent должно быть не старше 2 минут. Если нет — MQTT disconnected, перейти в раздел 6.

Шаг 2 — проверить audit events

/audit?device_id=<id>&event=policy.apply.*

Шаг 3 — типовые причины policy.apply.failed

Шаг 4 — RLS / tenant mismatch на бэке

Если /audit пуст вообще — возможно, вы смотрите из-под super-admin без tenant_id:

-- внутри /admin/sql (super-admin only)
SELECT COUNT(*) FROM audit_events WHERE device_id = '<id>' AND tenant_id = '<tenant>';

Если 0 — device не принадлежит вашему tenant, это проблема enrollment; см. раздел 1.

Шаг 5 — DPM API fallback

Некоторые прошивки (MIUI 13, ColorOS 12) периодически сбрасывают policy после OTA. DPC при каждом старте делает DevicePolicyManager.isProfileOwnerApp() → если false, посылает событие dpc.degraded серверу, и сервер показывает устройство в статусе degraded.

Решение: инструктаж пользователя → factory reset и re-enroll.

3. Kiosk-режим ломается после перезагрузки

3.1. Симптом

Устройство в kiosk-policy с lock_task_enabled=true. После reboot — возвращается launcher OS, kiosk теряется до ручного открытия приложения.

3.2. Диагностика

Шаг 1 — проверить BootReceiver

DPC регистрирует BOOT_COMPLETED receiver. Проверить в logcat после перезагрузки:

adb logcat -s KomendantDPC | grep BootReceiver

Должно быть: BootReceiver.onReceive: restoring kiosk mode.

Если нет — receiver не вызван. Причины:

• OEM battery optimization бъёт BOOT_COMPLETED до того, как app'у дают CPU. Решение: в policy добавить request_battery_optimization_exempt=true.
• App hibernation (Android 12+) — ОС «усыпила» app за неделю без запуска. Решение: policy app_hibernation_exempt через DevicePolicyManager.setApplicationExemptions (требует Android 13+).

Шаг 2 — Foreground Service permission

DPC держит FGS (notification "Управление устройством активно"). Если FGS убита — kiosk тоже. Проверка:

adb shell dumpsys activity services | grep komendant

Должен быть active service. Если AnrScreen: fgs_timeout — приложение превысило лимит FGS без interaction.

Решение: в AndroidManifest.xml DPC используется foregroundServiceType="systemExempted" + REQUEST_COMPANION_RUN_IN_BACKGROUND permission, подписывается через policy fgs_always_on.

Шаг 3 — Persistent notification

/devices/<id>/policy → kiosk → show_persistent_notification=true. Без этого некоторые Android (13+) могут убить foreground service через 6 часов.

4. Lost mode не работает

4.1. Симптом

Нажимаем /devices/<id> → Lost Mode. Экран устройства не блокируется, координаты не приходят.

4.2. Диагностика

Шаг 1 — проверить delivery

/audit?device_id=<id>&event=lostmode.*

Ищем: - lostmode.command.sent — сервер послал команду - lostmode.overlay.shown — устройство приняло и наложило overlay - lostmode.location.report — первая локация

Если command.sent есть, а overlay.shown нет — устройство offline либо DPC degraded.

Шаг 2 — Lock Screen Overlay permission

Overlay использует TYPE_APPLICATION_OVERLAY. На Android 11+ требует runtime-permission SYSTEM_ALERT_WINDOW. У device-owner даётся автоматически, но на некоторых OEM (Xiaomi) нужно отдельно включить в Настройки → Приложения → DPC → Отображение поверх других.

Проверить:

adb shell appops get ru.komendant.dpc SYSTEM_ALERT_WINDOW

Должно быть allow. Если default — DPC policy auto_grant_overlay=true.

Шаг 3 — Location permission

Lost mode шлёт координаты раз в 60 сек. Для этого нужен ACCESS_BACKGROUND_LOCATION + FGS_TYPE_LOCATION (Android 14+).

adb shell dumpsys package ru.komendant.dpc | grep permission | grep granted=true

Должны быть: - android.permission.ACCESS_FINE_LOCATION: granted=true - android.permission.ACCESS_BACKGROUND_LOCATION: granted=true - android.permission.FOREGROUND_SERVICE_LOCATION: granted=true

Если нет — обновить DPC до версии с foregroundServiceType="location" в manifest.

Шаг 4 — Google Play Services

На AOSP без GMS location работает через FusedLocationProvider fallback на LocationManager (GPS+NETWORK). На Huawei без HMS — только GPS, точность ниже. Это ожидаемое поведение.

5. Remote Assist не подключается

5.1. Симптом

В /remote-assist → New Session → Device admin и устройство показывают Connecting..., сессия не устанавливается.

5.2. Диагностика

Шаг 1 — TURN-сервер

Remote Assist использует WebRTC с принудительным iceTransportPolicy: "relay" (всё через TURN). Проверить:

curl -X POST https://api.mdm.example.ru/api/v1/remote-assist/turn-credentials \
  -H "Authorization: Bearer <admin-token>"

Должен вернуть JSON с urls, username, credential. Далее проверка самого TURN:

# С клиентской машины
turnutils_uclient -v -u <username> -w <credential> turn.mdm.example.ru -p 3478

Должны быть allocation и refresh успешными.

Частые причины отказа:

Шаг 2 — RELAY-only ICE

Если на сети клиента жёсткий NAT и нет UDP — даже TURN не поможет без 443/TCP. Fallback:

/settings/remote-assist
  ice_servers:
    - turns:turn.mdm.example.ru:5349?transport=tcp

Шаг 3 — сигналинг не достиг

WebRTC offer/answer идут через WebSocket к API. Проверка:

/devices/<id>/timeline → ищем ra.session.invite.received

Если событие есть на сервере, но DPC не показал UI — значит WebSocket разорван. Проверить в DPC logs adb logcat -s KomendantDPC-WS:

WS connection lost, code=1006, reason=

1006 — сеть прервалась. DPC переподключается автоматически через exp-backoff (1с, 2, 4, 8, 16, 32, 60).

Шаг 4 — Permission SYSTEM_CAPTURE_VIDEO_OUTPUT

Для share-screen через MediaProjection устройство покажет диалог Разрешить Комендант DPC записывать экран?. Это одноразовое согласие пользователя, skipped быть не может (требование Android security). Пользователь должен нажать «Разрешить».

6. MQTT disconnect storm

6.1. Симптом

В /ops/grafana → Komendant Overview → MQTT видно пик emqx_mqtt_disconnects_total > 50/минута. Устройства флапают online ⇄ offline.

6.2. Диагностика

Шаг 1 — проверить EMQX logs

docker logs emqx --tail 500 | grep -E 'disconn|acl|auth'

Ищем паттерны:

Шаг 2 — ACL rules

Каждый device подписан только на devices/<device_id>/cmd/# и publish только в devices/<device_id>/ack/#. Проверить:

docker exec emqx emqx ctl acl list | grep <device_id>

Если нет записи → команда komendant-cli mqtt sync-acl --device <id>.

Шаг 3 — Token refresh loop

DPC раз в 6 часов делает refresh. Если API возвращает 401 — DPC повторяет → storm. Проверка:

journalctl -u komendant-api --since "1 hour ago" | grep -c 'token refresh failed'

Если > 50 → на сервере истёк JWT signing key rotation, нужно komendant-cli jwt rotate-key. После — все DPC переконнектятся автоматически.

Шаг 4 — Clean session

Если в policy случайно выставлен mqtt_clean_session=true — DPC при каждом reconnect теряет in-flight messages, что вызывает дубликаты команд и новые disconnects. Фикс: /settings/mqtt → clean_session=false (default).

7. Dashboard 500 / tile 403 / CSP report overflow

7.1. Dashboard 500

В admin UI /dashboard показывает 500 Internal Server Error.

Проверка:

journalctl -u komendant-api --since "5 min ago" | grep ERROR | tail -20

Частые причины:

7.2. Tile 403

Отдельный дашборд-плиток возвращает 403. Причина — RLS: пользователь смотрит данные не из своего tenant.

Типовой случай: super-admin переключился в tenant A, но в URL остался tenant_id=B. Очистить cookie komendant_active_tenant и выбрать нужный в /admin/tenants.

7.3. CSP report overflow

В /ops/prometheus видно рост komendant_csp_reports_total > 1000/min.

Причина: браузер пользователей рапортует нарушения CSP (inline scripts, сторонние trackers). Это не критично, но забивает storage.

Решение:

1. Проверить /admin/security/csp-reports — какие директивы флапают.
2. Если это какой-то легитимный ресурс (например, Яндекс.Метрика в landing) — добавить в whitelist connect-src в nginx.
3. Включить CSP rate-limit в nginx: limit_req zone=csp burst=5 nodelay на /csp-report.

8. Где смотреть логи

8.1. Серверные логи

8.2. Grafana + Loki

Если observability развернут: https://mdm.example.ru/ops/grafana (basic-auth из .env).

Dashboards: - Komendant Overview — устройства, policy-apply, MQTT, SLA - API SLO — p50/p95/p99 latency, error rate - Licensing — active devices vs limit - Backup — last success timestamp, S3 offsite

8.3. Audit log (для IT-админа tenant-а)

/admin/audit — фильтры по user, device, event type, время. Экспорт в CSV и JSON. Хранится 7 лет (152-ФЗ + наш SLA).

8.4. Export в SIEM

Если у клиента MaxPatrol/Kaspersky KUMA — настройте syslog-forwarder:

/settings/integrations/siem
  type: syslog
  host: siem.example.ru
  port: 514
  protocol: tcp+tls
  format: CEF | LEEF

Теги и поля — см. docs/security-log-tags.md.

Версия документа: 1.0 (2026-04-18). Для ошибок, не описанных здесь: support@komendant-mdm.ru, приложить journalctl --since "1 hour ago" -u komendant-api > api.log.