Быстрое подключение устройств

Эта инструкция описывает два основных сценария:

• управляемое устройство: роутер или edge-устройство подключается по одноразовому токену;
• статический клиент: ноутбук, телефон или рабочая станция получает WireGuard-профиль.

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

Перед началом

Проверьте:

• вы вошли в панель Qarvix;
• выбрана нужная организация;
• создана WireGuard-сеть, например home-net;
• для управляемого устройства модель относится к поддерживаемому оборудованию и есть доступ к роутеру, на который будет установлен агент;
• для статического клиента известны имя пользователя или устройства и целевая платформа.

Стартовая точка: раздел Устройства.

Сценарий 1: управляемое устройство через токен

Используйте этот путь для роутеров и устройств, которыми должен управлять агент Qarvix.

1. Откройте раздел устройств

В левом меню нажмите Устройства. На странице видны статус устройства, VPN IP, принадлежность к сети, прошивка, модель, производитель и версия агента.

2. Нажмите "Добавить устройство"

Откройте форму добавления устройства.

3. Выберите сеть

В поле Сеть выберите сеть, в которую должно войти устройство.

Пример: home-net (10.100.0.0/24).

4. Выберите срок действия токена

В поле Срок действия токена выберите срок жизни токена подключения:

• 1 час - подключение выполняется прямо сейчас;
• 8 часов - подключение в течение рабочего дня;
• 24 часа - универсальное значение по умолчанию;
• 7 дней - для удаленной работы, если инженер подключит устройство позже.

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

5. Сгенерируйте токен

Нажмите Сгенерировать токен.

Важно:

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

6. Запустите подключение на устройстве

После генерации Qarvix сразу показывает не токен сам по себе, а готовую команду:

curl -fsSLk https://wss.qarvix.kz/install.sh | sh -s -- <compound-token>

Команда скачивает установочный скрипт, который сам определяет модель роутера и архитектуру, спрашивает сервер, какая сборка агента подходит, скачивает и проверяет ее, устанавливает как procd-сервис и передает токен агенту для регистрации - вручную ничего настраивать не нужно. Скрипт одинаковый для всех поддерживаемых моделей Teltonika, отдельная страница с командами под конкретную модель не нужна.

Последний аргумент - не просто секрет, а составной токен: адрес контроллера, к которому агент должен подключиться, зашит в его начале в base64, через точку - одноразовый секрет. Устанавливающий скрипт этот адрес не трогает и передает токен как есть - его декодирует и применяет уже сам агент при регистрации. Из-за этого адрес, с которого скачивается скрипт, и адрес, к которому в итоге подключится агент, могут не совпадать.

Передать инженеру нужно только эту команду целиком - организация и сеть уже зашиты в токене, дополнительно сообщать их не нужно. Есть два способа:

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

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

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

7. Проверьте результат

Вернитесь в Устройства и обновите список.

Проверьте:

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

Сценарий 2: статический WireGuard-клиент

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

1. Откройте раздел устройств

В левом меню нажмите Устройства.

2. Нажмите "Добавить клиента"

Откройте форму добавления статического клиента.

3. Выберите сеть

В поле Сеть выберите сеть для подключения клиента.

Пример: home-net (10.100.0.0/24).

4. Укажите имя клиента

Используйте понятные имена:

• Ноутбук Антона;
• ПК администратора офиса;
• Телефон инженера поддержки;
• macOS полевого инженера.

5. Выберите платформу

Доступные варианты:

• Windows;
• macOS;
• Linux;
• Android;
• iOS.

6. Создайте клиента

Нажмите Создать.

Деталь безопасности: пара ключей WireGuard генерируется в браузере, приватный ключ не отправляется на сервер.

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

Проверка после подключения

Устройства

Проверьте:

• имя;
• сеть;
• VPN IP;
• статус;
• последнее появление online;
• версию прошивки и агента, если применимо.

Детальная страница сети

Откройте Сети, затем нужную сеть.

Проверьте, что устройство есть в Участниках, VPN IP соответствует ожидаемому диапазону, а для нужного трафика настроены Exit Node, Контроль доступа или Peer Mesh.

Журнал устройства

Откройте Журнал устройства.

Проверьте события:

• Came online;
• Configuration applied;
• agent_update_result;
• события Teltonika API, если подключается устройство Teltonika.

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

Токен истек

Сгенерируйте новый токен с подходящим сроком действия.

Токен уже использован

Токен подключения одноразовый. Если устройство не появилось в разделе Устройства, проверьте Журнал аудита и Журнал устройства, затем создайте новый токен.

Устройство появилось, но осталось Offline

Проверьте доступ устройства к контрольному контуру, запуск агента, WSS/TLS-соединение, UDP-порт WireGuard и возможный конфликт VPN-подсети с локальной сетью.

Устройство Online, но трафик не проходит

Проверьте VPN IP, участие в нужной сети, включенные ACL, разрешающие политики, exit node, subnet route и настройки peer mesh.