Установка агента
Назначение раздела
Раздел описывает установку Windows-агента СОПКА.Рой на рабочую станцию. Агент подключается к нужной рабочей области по регистрационному ключу: администратору не нужно вручную указывать UUID рабочей области на клиенте.
Создание регистрационного ключа
- Откройте веб-интерфейс СОПКА.Рой и выберите нужную рабочую область.
- Перейдите в «Установка».
- Нажмите «Создать регистрационный ключ». Ключ действует ограниченное время и предназначен для регистрации агента в выбранной рабочей области.
- Скопируйте полный ключ сразу после создания. Позже в интерфейсе отображаются только первые 4 и последние 4 символа.
В базе данных регистрационный ключ используется как проверяемый секрет. Для безопасной эксплуатации не пересылайте его в открытых каналах и отзывайте ключ после завершения установки.
Скачивание пакета
- Скачайте EXE-установщик агента из того же раздела.
- Передайте файл на целевую рабочую станцию по защищённому каналу.
- MSI используется для ручного или корпоративного развёртывания; автоматическое обновление использует EXE. Legacy ZIP не является текущим основным установщиком.
Имя файла не должно содержать название рабочей области. Привязка выполняется сервером по регистрационному ключу.
Установка EXE
Откройте PowerShell или командную строку от имени администратора и запустите установщик одной строкой:
.\CopkaRoySetup.exe /quiet /registration-key "roy_reg_ВАШ_КЛЮЧ" /server-url "https://servername.com/roy"Вместо https://servername.com/roy укажите опубликованный HTTPS-адрес вашей инсталляции или SaaS-рабочей области, доступный с целевой рабочей станции. Базовый путь добавляется только если он предусмотрен адресом подключения.
Установка MSI
Для корпоративного развёртывания используйте MSI-пакет соответствующего выпуска. Запустите команду от имени администратора; имя файла замените на имя полученного пакета:
msiexec.exe /i "CopkaRoyAgent-1.0.0-windows-x64.msi" /qn /norestart ROY_SERVER_URL="https://servername.com/roy" ROY_REGISTRATION_TOKEN="roy_reg_ВАШ_КЛЮЧ" ROY_VALIDATE_SERVER=1/qn включает тихую установку, /norestart запрещает автоматический перезапуск. ROY_SERVER_URL задаёт адрес подключения, ROY_REGISTRATION_TOKEN передаёт регистрационный ключ, ROY_VALIDATE_SERVER=1 включает проверку доступности сервера установщиком. Параметры ниже относятся к EXE-установщику и не передаются в MSI-команду.
Что делает установщик
- создаёт каталог установки и служебные каталоги в
ProgramData; - копирует сервисный агент, пользовательский агент, updater и launcher;
- сохраняет адрес сервера и регистрационный ключ для первичной регистрации;
- устанавливает Windows-службу и автозапуск пользовательского агента;
- запускает первичную регистрацию, heartbeat и получение политики.
Проверка после установки
- клиент появился в списке клиентов выбранной рабочей области;
- в карточке клиента отображаются heartbeat, версия агента и версия протокола;
- агент получил подписанный bundle политик;
- тестовое событие поступает во вкладку «События»;
- пользовательские интерактивные мониторы запущены в пользовательской сессии, а не только в Session 0 службы.
Флаги EXE-установщика
| Флаг | Назначение |
|---|---|
/quiet, --quiet, /silent, --silent | Тихий режим без UI. |
/registration-key, --registration-key, /key, --key | Регистрационный ключ для первичной установки или re-enroll; срок и лимит использований определяются настройками ключа. |
/server-url, --server-url | Внешний URL сервера, например https://servername.com/roy. |
/install-path, --install-path | Каталог программы агента. |
/auto-update, --auto-update, /update, --update | Автообновление уже установленного клиента с сохранением identity. |
/re-enroll, --re-enroll, /reenroll, --reenroll | Явная новая регистрация устройства. |
/reset-data, --reset-data, /clear-settings | Очистить локальные данные; не используется для обычного repair. |
/status, --status, /detect | Проверить установленный клиент; можно добавить /json. |
/uninstall, --uninstall, /remove | Удалить агент; /remove-data дополнительно удаляет ProgramData. |
Повторная установка
Если клиент уже был зарегистрирован, сначала определите цель: восстановить существующую установку или создать новую регистрацию. Для переноса на другой компьютер используйте новый регистрационный ключ. Старые ключи и device-токены следует отозвать, если есть риск их копирования.
Автоматическое обновление агента
Агент версии 1.0.0 поддерживает обновление через EXE-установщик и версионные слоты установки. Сервер сравнивает версию агента, полученную в heartbeat, с текущим релизом. В режиме COPKA_ROY_AGENT_UPDATE_MODE=auto устаревшие клиенты автоматически ставятся в очередь обновления; в режиме manual администратор запускает очередь кнопкой в разделе установки агента.
Глобальный охват задаётся переменной COPKA_ROY_AGENT_UPDATE_ROLLOUT_PERCENT=100. Owner API может установить для конкретной рабочей области значение от 1 до 100. При значении меньше 100 серверная очередь выбирает стабильную долю агентов; heartbeat не может самостоятельно обойти это ограничение.
Обновление выдаётся через одноразовый grant и загружается по защищённому ключу. Для EXE-пакета агент проверяет SHA-256 и запускает CopkaRoySetup.exe /quiet /auto-update; установщик не меняет registration key и сохраняет secure_identity.json. Legacy ZIP-путь проверяет манифест релиза, подпись Ed25519 и SHA-256 файлов. Если новая версия не проходит локальную readiness/health проверку, используется механизм отката.
Диагностика регистрации
Если устройство не появилось, проверьте службу CopkaRoyAgentService, внешний адрес сервера, DNS, TLS и действительность регистрационного ключа. Не используйте localhost как адрес удалённого сервера. Не копируйте secure_identity.json с другого устройства: это переносит чужую identity, а не создаёт отдельную регистрацию.
Если heartbeat есть, но экран или пользовательские функции недоступны, проверьте вход пользователя, запуск CopkaRoyUserAgent в нужном Windows-сеансе и capabilities. Не переустанавливайте устройство только из-за отсутствия интерактивного сеанса.
Вывод устройства из эксплуатации
Сначала согласуйте сохранение истории и материалов, затем отзовите доступ устройства и выполните штатное удаление агента на Windows с административными правами. Отзыв на сервере блокирует связь, но сам по себе не удаляет программу с рабочей станции.
Массовая установка и ресурсный профиль
Число одновременно работающих агентов и число одновременных установок или обновлений - разные параметры. Для массового развёртывания проверяют сроки и лимиты регистрационного ключа, доступность пакета, запас канала и скорость включения компьютеров. Нагрузка от 1000 уже работающих агентов рассчитывается по «Системным требованиям»; регистрация, восстановление связи и распространение пакетов проверяются отдельно.
Проверка агента через AI-чат
После регистрации можно запросить имя, состояние и версию компьютера. Версию сравнивают только с опубликованным релизом для соответствующей платформы и архитектуры. Аналитик не устанавливает агент и не перезапускает службу.
Подробнее: AI-чат: анализ безопасности.