Первые шаги в Qarvix

Эта страница помогает пройти первый рабочий маршрут в Qarvix: выбрать организацию, создать сеть, добавить устройство или статического клиента, проверить связь и выдать доступ команде.

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

Что должно получиться

После выполнения шагов у вас будет:

выбранная организация, к которой относятся устройства;
первая WireGuard-сеть Qarvix;
хотя бы один участник сети: управляемый роутер, hub или статический клиент;
понятный VPN-адрес у каждого участника;
базовая проверка online-статуса и журналов;
выданный доступ пользователю или сервисной команде;
понимание, куда смотреть при проблемах со связью.

Базовая модель

В Qarvix удобно мыслить не отдельными VPN-файлами, а управляемым контуром.

Сущность	Что означает	Пример
Организация	Верхний уровень владения и прав	Компания, клиент, холдинг
Сеть	Изолированный WireGuard-контур	`home-net`, `retail-east`, `cameras-prod`
Устройство	Роутер или узел с агентом Qarvix	Teltonika, OpenWrt, промышленный gateway
Статический клиент	WireGuard-клиент без агента	ноутбук инженера, телефон, сервер учета
Маршрут до подсети	Доступ к LAN за роутером	`192.168.10.0/24` за объектом
Правило доступа	Кто и куда может ходить	инженер -> камеры, мониторинг -> API

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

Шаг 1. Выберите организацию

После входа в панель проверьте, в какой организации вы работаете. Это важно: сети, устройства, пользователи, журналы и отчеты привязаны к выбранной области.

Используйте отдельные организации, если нужно разделять:

разных юридических клиентов;
независимые команды эксплуатации;
площадки с разными правилами безопасности;
пилотный контур и production-контур;
направления или площадки, по которым должны формироваться отдельные отчеты.

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

Шаг 2. Создайте первую сеть

Сеть Qarvix - это управляемый WireGuard-контур. Внутри сети находятся участники: роутеры, hub, статические клиенты и другие узлы.

При создании сети задайте понятное имя и VPN-диапазон.

Хорошие имена:

home-net;
office-demo;
retail-kokshetau;
cameras-warehouse;
meters-prod.

Для первого теста можно использовать диапазон вида:

10.100.0.0/24

Перед production-развертыванием проверьте, что VPN-диапазон не пересекается с локальными подсетями на объектах. Пересечения подсетей - одна из частых причин, почему устройство online, но нужный сервис недоступен.

Шаг 3. Добавьте первого участника сети

Есть два основных варианта.

Управляемое устройство

Выберите этот вариант для роутера или gateway, на котором будет установлен агент Qarvix.

Такой участник держит две связи:

WSS-канал управления для команд, конфигурации, heartbeat и обновления состояния;
WireGuard-туннель для пользовательского трафика.

Это основной сценарий для объектов за NAT, мобильным оператором, обычной SIM-картой или закрытой сетью без белого IP.

Статический клиент

Выберите этот вариант для ноутбука, телефона, сервера учета или рабочей станции, где нужен обычный WireGuard-профиль без агента.

Статический клиент не держит WSS-канал, поэтому его online-статус определяется по свежести WireGuard-handshake на hub. Это нормально: отсутствие heartbeat агента для такого клиента не считается ошибкой.

Шаг 4. Проверьте VPN-адрес и статус

После подключения откройте список устройств или детальную страницу сети.

Проверьте:

участник появился в правильной сети;
VPN IP выдан из ожидаемого диапазона;
статус соответствует типу участника;
для управляемого устройства видна версия агента, модель и прошивка, если устройство передает эти данные;
Last seen обновляется;
в журнале устройства нет повторяющихся ошибок подключения.

Если устройство online, но доступ до локального сервиса не работает, не начинайте с переустановки агента. Сначала проверьте маршруты, ACL, subnet routes, peer mesh и пересечение подсетей.

Шаг 5. Решите, нужен ли доступ к LAN за роутером

Сам факт подключения роутера к Qarvix не всегда означает, что нужно открывать всю локальную сеть за ним.

Типовые варианты:

Сценарий	Что включить
Нужно зайти только на сам роутер	Достаточно VPN IP роутера
Нужно открыть камеры, PLC, кассы или API за роутером	Добавьте маршрут до LAN-подсети
Нужно выпускать трафик через объект	Настройте exit node
Нужно прямое взаимодействие между участниками	Включите peer mesh, если это разрешено политикой
Нужно ограничить доступ по ролям и направлениям	Включите ACL и задайте правила

Для руководителей и сервисных команд это выглядит просто: объект подключен один раз, а доступ к нужной LAN-подсети включается централизованно в панели.

Шаг 6. Выдайте доступ пользователю или команде

Не передавайте один VPN-профиль всем подряд. В Qarvix доступ лучше выдавать персонально или через роль.

Минимальная схема:

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

Если в компании используется единый вход, запланируйте подключение OIDC SSO. Если доступ выдается вручную, включайте 2FA для учетных записей с административными правами.

Шаг 7. Проверьте журналы и отчеты

После первого подключения проверьте не только факт связи, но и следы событий.

Посмотрите:

журнал аудита: кто создал сеть, устройство, токен или правило доступа;
журнал устройства: когда агент подключился, получил конфигурацию и применил настройки;
список устройств: текущие статусы и последние появления online;
отчеты: что можно выгрузить для эксплуатации, контроля работ или разбора инцидента.

Отчеты важны не только для технической команды. Для руководителя это подтверждение, что объекты подключены, доступ управляется централизованно, а действия пользователей можно проверить.

Шаг 8. Проверьте доступ к API устройств

Если за роутером находятся камеры, PLC, приборы учета, датчики или локальные сервисы, Qarvix может дать доступ не только к связи, но и к API этих устройств через туннель.

Примеры:

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

Такой доступ лучше оформлять как отдельный сценарий: кто обращается, к какому адресу, по какому протоколу и с какими ограничениями.

Контрольный список первого запуска

Организация выбрана правильно.
Сеть создана с непересекающимся VPN-диапазоном.
Устройство или клиент добавлены в нужную сеть.
VPN IP выдан корректно.
Управляемый роутер держит WSS и WireGuard.
Статический клиент имеет свежий WireGuard-handshake.
LAN-маршрут добавлен только при необходимости.
ACL и доступ по умолчанию соответствуют политике безопасности.
Пользователи получают персональный доступ.
В журналах видны события подключения и применения конфигурации.
Для объекта понятно, какие сервисы доступны через туннель.

Куда идти дальше

Быстрое подключение устройств - пошаговое подключение роутера или статического клиента.
Организации и сети - как разделять клиентов, филиалы и команды.
Пользователи, роли и SSO - приглашения, роли, 2FA, API-токены и OIDC SSO.
Устройства и VPN-адреса - статусы, токены, клиенты и адреса.
Сети, маршруты и ACL - exit node, peer mesh, subnet routes и правила доступа.
API устройств через туннель - доступ к локальным сервисам за роутером.
Журналы и отчеты - эксплуатационная проверка и материалы для контроля.