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

Этот раздел помогает быстро разбирать проблемы Qarvix: устройство не появляется online, WSS-канал не устанавливается, WireGuard-handshake не обновляется, VPN IP есть, но доступа нет, LAN/API недоступны через туннель или пользователь не видит нужный объект.

Подход простой: проверять по слоям, от общего к частному, и не переустанавливать агент до того, как проверены сеть, маршруты, ACL и журналы.

Коротко

Сначала определите тип участника: управляемое устройство или статический клиент.
Проверьте организацию и сеть.
Проверьте online-статус, Last seen и журналы.
Для управляемого устройства отдельно проверяйте WSS и WireGuard.
Для статического клиента смотрите свежесть WireGuard-handshake.
Если LAN/API недоступны, проверяйте subnet route, ACL, firewall и адресный план.
Для обращения в поддержку собирайте симптомы, время, устройство, сеть и журналы.

Базовый порядок диагностики

Найдите организацию.
Откройте нужную сеть.
Найдите участника.
Проверьте VPN IP.
Проверьте online/offline и Last seen.
Откройте журнал устройства.
Проверьте журнал аудита за период проблемы.
Проверьте маршруты, ACL и peer mesh.
Проверьте доступность локального устройства или API.
Зафиксируйте время, симптомы и результат проверок.

Если проблема плавающая, особенно важны точные даты и время. Без них журнал сложно сопоставить с жалобой.

Устройство не появляется в списке

Симптомы

токен создан, но устройство не появляется;
инженер сообщает, что агент установлен;
в списке устройств нет нового узла;
в журнале аудита видна генерация токена, но нет подключения.

Возможные причины

токен истек;
токен уже использован;
выбрана не та сеть;
устройство не имеет доступа к control plane;
DNS не работает;
TLS-соединение не устанавливается;
время на устройстве сильно отличается;
firewall блокирует WSS.

Что проверить

срок действия токена;
правильную организацию и сеть;
доступ устройства к серверу Qarvix;
DNS на объекте;
время на устройстве;
логи агента;
журнал аудита.

Если токен истек или был использован, создайте новый. Не пытайтесь переиспользовать старый токен.

WSS-канал не устанавливается

WSS нужен управляемому устройству для команд, конфигурации и heartbeat.

Симптомы

устройство не получает конфигурацию;
heartbeat не обновляется;
агент не появляется online;
в логах ошибки подключения к WebSocket;
WireGuard не получает актуальные настройки.

Возможные причины

недоступен endpoint control plane;
блокируется HTTPS/WSS;
ошибка TLS;
неверное время на устройстве;
прокси или firewall обрывает соединение;
неверный токен или учетные данные агента.

Что проверить

доступность адреса сервера с устройства;
DNS;
время и часовой пояс;
сертификат TLS;
правила firewall;
журналы агента;
журнал устройства в Qarvix.

Если WSS не работает, управляемое устройство не сможет стабильно получать команды и обновления конфигурации.

WireGuard-handshake не обновляется

WireGuard-handshake показывает, что участник недавно обменивался защищенным трафиком.

Симптомы

устройство или клиент выглядит offline;
VPN IP есть, но трафик не идет;
статический клиент давно не обновлял статус;
hub не видит свежего handshake.

Возможные причины

UDP заблокирован;
неверные ключи;
неправильный endpoint;
конфликт AllowedIPs;
устройство не отправляет трафик;
firewall блокирует WireGuard;
изменился внешний адрес или NAT-состояние.

Что проверить

UDP-доступ до hub;
конфигурацию WireGuard;
ключи;
AllowedIPs;
наличие исходящего трафика от клиента;
firewall на клиенте и на объекте;
журнал устройства или состояние hub.

Для статического клиента отсутствие свежего handshake не всегда означает аварию. Иногда клиент просто не передавал трафик.

VPN IP есть, но доступа нет

Симптомы

участник online;
VPN IP выдан;
ping или подключение к нужному адресу не проходит;
web/API устройства недоступен.

Возможные причины

ACL запрещает направление;
subnet route не добавлен;
peer mesh выключен;
firewall на роутере блокирует forward;
локальное устройство не отвечает;
нет обратного маршрута;
пересекаются подсети;
выбран не тот адрес или порт.

Что проверить

Пингуется ли VPN IP роутера.
Есть ли маршрут до LAN.
Разрешает ли ACL нужное направление.
Включен ли peer mesh, если нужен прямой доступ.
Пропускает ли firewall роутера трафик в LAN.
Доступно ли локальное устройство из самой LAN.
Нет ли пересечения VPN CIDR и LAN-подсети.

Если VPN IP доступен, а LAN нет, проблема чаще всего в маршруте, ACL или firewall.

LAN-подсеть не работает

Симптомы

роутер online;
VPN IP роутера доступен;
устройства в LAN не открываются;
API за роутером недоступен.

Возможные причины

не добавлен subnet route;
маршрут добавлен к неправильному gateway;
локальная подсеть указана неверно;
firewall роутера запрещает forward;
локальное устройство использует другой gateway;
адресная подсеть пересекается с сетью пользователя;
ACL запрещает доступ.

Что проверить

правильность LAN CIDR;
gateway-устройство;
таблицу маршрутов;
firewall;
доступность устройства из LAN;
ACL;
журнал применения конфигурации агентом.

API устройства недоступен через туннель

Симптомы

LAN-маршрут есть;
устройство пингуется или частично доступно;
web/API не открывается;
интеграция получает timeout или connection refused.

Возможные причины

неверный порт;
сервис слушает только локальный интерфейс;
локальный firewall блокирует порт;
API требует HTTPS или отдельную авторизацию;
ACL разрешает ICMP, но не нужный TCP/UDP;
устройство доступно только с определенных адресов;
сертификат устройства не доверенный.

Что проверить

IP и порт API;
доступность API из LAN объекта;
протокол HTTP/HTTPS/RTSP/Modbus или другой;
локальный firewall;
ACL по портам;
учетные данные API;
логи интеграции.

Пользователь не видит объект

Симптомы

устройство существует, но пользователь его не видит;
пользователь видит организацию, но не сеть;
доступ был выдан, но объект недоступен.

Возможные причины

пользователь в другой организации;
роль пользователя не привязана к нужной сети;
роль не позволяет видеть устройства;
доступ подрядчика был отозван;
пользователь вошел не через тот аккаунт или SSO-группу.

Если устройство не отображается в панели, дело не в ACL: ACL решает, куда доходит трафик участника, а не что пользователь видит в интерфейсе. Видимость определяется организацией, ролью и тем, к каким сетям она привязана.

Что проверить

организацию пользователя;
роль и сети, к которым она привязана;
группы SSO, если используется OIDC;
журнал аудита;
правила доступа;
активность учетной записи.

Токен подключения не работает

Симптомы

агент сообщает ошибку регистрации;
устройство не появляется;
токен вводится повторно;
токен был отправлен давно.

Возможные причины

токен истек;
токен уже использован;
токен создан для другой сети;
токен скопирован с ошибкой;
устройство не может достучаться до сервера.

Что делать

проверьте срок действия;
создайте новый токен;
убедитесь, что выбрана правильная сеть;
передайте токен только ответственному инженеру;
проверьте WSS-доступ с устройства.

Проблемы после изменения ACL

Симптомы

доступ работал и пропал после изменения правил;
часть устройств группы теряет доступ, часть продолжает работать;
мониторинг перестал получать данные.

Возможные причины

правило стало слишком строгим;
забыто разрешение до LAN-подсети;
устройство не входит в нужную группу правила;
правило применилось не к той сети;
доступ по умолчанию запрещает направление.

Что проверить

журнал аудита;
последнее изменение ACL;
в какую группу входит устройство;
какие адреса и порты разрешены;
какие правила применяются раньше;
есть ли отдельное правило для API или LAN.

Что приложить в поддержку

Чтобы поддержку можно было начать без длинной переписки, приложите:

организацию;
название сети;
имя устройства или клиента;
VPN IP;
LAN-подсеть, если проблема с маршрутом;
адрес и порт API, если проблема с устройством за роутером;
точное время проблемы;
скриншот статуса;
фрагмент журнала устройства;
фрагмент журнала аудита;
что уже проверили;
ожидаемый и фактический результат.

Если проблема связана с роутером, добавьте модель, прошивку и версию агента.

Быстрая таблица симптомов

Симптом	Сначала проверить
Устройство не появилось	токен, WSS, DNS, время
Устройство offline	heartbeat, WSS, журнал агента
Статический клиент offline	свежесть WireGuard-handshake
VPN IP есть, но связи нет	ACL, peer mesh, AllowedIPs
LAN недоступна	subnet route, gateway, firewall
API не открывается	порт, протокол, ACL, локальный firewall
Пользователь не видит сеть	организация, роль и привязанные к ней сети, SSO-группа
После изменений все сломалось	журнал аудита и последнее изменение

Контрольный список диагностики

Определен тип участника.
Проверена организация и сеть.
VPN IP выдан корректно.
Online/offline прочитан с учетом типа участника.
WSS проверен для управляемого устройства.
WireGuard-handshake проверен для клиента.
Subnet route проверен для LAN.
ACL проверен для нужного направления.
Firewall и локальная сеть объекта проверены.
Журналы приложены к обращению.

Связанные разделы

Устройства и VPN-адреса - типы участников и статусы.
Сети, маршруты и ACL - маршруты, peer mesh и правила доступа.
API устройств через туннель - диагностика локальных API.
Журналы и отчеты - где искать события и изменения.
Offline-развертывание - особенности закрытых контуров.