¶ Агент на Windows
Эта страница поможет, если компьютер с Windows не появляется в Ринго после установки агента, не работают веб-терминал, политики, скрипты или установка пакетов, или компьютер в Ринго показан без связи. На Windows агент — единственный канал управления, поэтому любые проблемы с такими компьютерами начинаются здесь.
Все команды на этой странице выполняйте в PowerShell, запущенном от имени администратора.
¶ Как устроен агент на Windows
Агент работает как служба Windows и связывается с сервером двумя способами. По постоянному соединению websocket (/socket.io/) сервер сообщает агенту, что для него есть задача, и через это же соединение работает веб-терминал. Сами задачи агент забирает и возвращает результаты запросами HTTPS к /agent/connect. Кроме того, примерно раз в 10 минут агент сам опрашивает сервер, даже если задач нет.
| Что | Где |
|---|---|
| Служба | RingoAgent («Ringo Agent»), запуск автоматический, от имени LocalSystem. При сбое Windows перезапускает её через 5, 15 и 30 с. |
| Агент | C:\ProgramData\Ringo\Agent\ringo.exe |
| Модуль установки и обновления | C:\ProgramData\Ringo\Updater\updater.exe |
| Лог агента | C:\ProgramData\Ringo\Logs\agent.ГГГГ-ММ-ДД.0.log, отдельный файл на каждые сутки, время в UTC. |
| Лог установки и обновления | C:\ProgramData\Ringo\Logs\updater.ГГГГ-ММ-ДД.0.log, время в UTC. Модуль обновления из прежней установки пишет в updater.log с местным временем. |
| Загруженные пакеты | C:\ProgramData\Ringo\Applications |
| Сертификаты | Хранилище «Личное» компьютера (Cert:\LocalMachine\My): «Ringo Device Identity» и «Ringo Agent Device Identity». Корневой сертификат «Ringo Built-in Certificate Authority» — в хранилище «Доверенные корневые центры сертификации». |
| Идентификатор устройства | Раздел реестра HKLM\SOFTWARE\Ringo\DeviceIdentity, значение DeviceUuid. |
| Терминал и служебные скрипты | PowerShell |
Агент подключается к серверу напрямую. Системные настройки прокси Windows (WinHTTP) и переменные HTTPS_PROXY и HTTP_PROXY он не использует. Если в сети компьютера нет прямого выхода на сервер Ринго по порту 443, откройте его.
¶ Установка агента
-
На компьютере с Windows откройте в браузере
https://<домен>/enrollи войдите с учётной записью Ринго. -
Нажмите У меня другая платформа, выберите Windows и нажмите Скачать установщик Windows.
-
Распакуйте архив
ringo-agent-windows.zip. В нём файлservice.batи модуль установки для двух архитектур:updater-amd64.exeиupdater-arm64.exe. -
Нажмите правой кнопкой мыши на
service.bat, выберите Запуск от имени администратора и введите1(Install Agent). Архитектуруservice.batопределяет сам.
В service.bat уже записаны адрес сервера и код регистрации, поэтому один архив подходит для любого числа компьютеров. Код регистрации действует от 7 до 90 дней с момента скачивания архива. Если архив скачан давно, скачайте новый.
Чтобы установить агент без вопросов, например через групповую политику или систему распространения ПО, выполните в папке с распакованным архивом:
.\service.bat --non-interactive --action install
Результат установки записывается в C:\ProgramData\Ringo\Logs\updater.<ГГГГ-ММ-ДД>.0.log и выводится в окне service.bat. При успешной установке последняя запись — Ringo agent was installed successfully!.
При установке модуль скачивает агент (/agent/manifest, /agent/bundle), регистрирует компьютер (/agent/checkin, /scep, /agent/certificate) и создаёт службу. Компьютер появляется в разделе Компьютеры сразу после регистрации, а сведения о нём — через 1–2 минуты, когда агент выполнит первую задачу.
¶ Частые причины
- Агент не установлен или служба остановлена — см. шаг 1.
- Нет прямого выхода на сервер, прокси или сертификат — см. шаг 2.
- Компьютер удалён в Ринго, и агент удалил себя — см. шаг 3.
- Терминал недоступен в первые минуты после установки или включения компьютера — см. Терминал недоступен сразу после запуска.
¶ Шаг 1. Служба агента установлена и запущена
Проверьте состояние агента:
C:\ProgramData\Ringo\Agent\ringo.exe status
Ожидаемый результат:
Agent version: '5ed51db'
Device UUID: eafb7b72-ee79-4de3-afcd-8b9c759ea822
Credential key provider: Microsoft Platform Crypto Provider
Credential key title: ringo-key-di-…
Device identity certificate: found, expires at '2028-10-13 14:24:32 +0000 UTC'
Agent device identity certificate: found, expires at '2028-10-13 14:24:32 +0000 UTC'
Service status: Running
Device UUID — это UDID компьютера в Ринго. По нему ищите записи в логе backend.
| Результат | Что это значит | Что делать |
|---|---|---|
Файл ringo.exe не найден или Service status: NotFound |
Агент не установлен или удалён. | Установите агент (см. Установка агента). Если агент удалился сам, см. шаг 3. |
Service status: Stopped |
Служба остановлена или ещё запускается. После установки и включения компьютера служба остаётся в состоянии StartPending, пока агент не выполнит накопившиеся задачи (после установки — несколько минут); ringo.exe status в это время показывает Stopped. |
Выполните Get-Service RingoAgent. Если Status — StartPending, подождите. Если Stopped, запустите службу командой Start-Service RingoAgent и проверьте снова. |
Device identity certificate: not found или Agent device identity certificate: not found |
Нет сертификата, с которым агент проходит авторизацию. | Переустановите агент (см. шаг 3). |
Service status: Running, сертификаты найдены |
Агент запущен. Running не означает, что агент подключён к серверу. |
Переходите к шагу 2. |
Чтобы перезапустить агент, выполните Restart-Service RingoAgent.
¶ Шаг 2. Агент подключается к серверу
Посмотрите, какие логи есть у агента:
Get-ChildItem C:\ProgramData\Ringo\Logs
Покажите последние записи лога за сегодня, подставив дату по UTC:
Get-Content C:\ProgramData\Ringo\Logs\agent.<ГГГГ-ММ-ДД>.0.log -Tail 30
Пока агент работает, размер текущего файла лога может показываться равным 0. Файл при этом не пустой: Windows обновляет размер открытого файла с задержкой.
Успешный запуск и подключение выглядят так (записи identity пропущены):
2026-10-15 10:00:35 | agent-win | service | info | starting ringo agent service
2026-10-15 10:00:46 | agent-win | client | info | sync: sending connect idle
2026-10-15 10:00:48 | agent-win | client | info | sync: got empty result, waiting for command
2026-10-15 10:00:48 | agent-win | service | info | ringo agent started
2026-10-15 10:00:49 | agent-win | client | info | socket: connect
2026-10-15 10:00:49 | agent-win | client | info | socket: auth:verified
От запуска службы до первого обращения к серверу проходит от 10 секунд до двух минут: в это время агент определяет идентификатор устройства (записи identity | resolve … identity).
| Запись в логе агента | Что это значит | Что делать |
|---|---|---|
sync: initial sync failed: … connectex: An attempt was made to access a socket in a way forbidden by its access permissions. |
Соединение запрещено межсетевым экраном на компьютере. | Разрешите в брандмауэре Windows или стороннем межсетевом экране исходящие соединения ringo.exe с сервером по порту 443. |
sync: initial sync failed: … dial tcp <адрес>:443: i/o timeout |
Сервер недоступен из сети компьютера. | Проверьте маршрут, межсетевой экран и VPN. Если выход в интернет возможен только через прокси, откройте прямой доступ к серверу Ринго: агент не использует прокси. |
… tls: failed to verify certificate: x509: certificate is valid for …, not <домен> |
Агенту предъявлен сертификат другого сервера: запросы перехватывает SSL-inspection, или имя сервера указывает не на тот адрес (файл hosts, DNS). |
Исключите домен Ринго из инспекции. Проверьте, что Resolve-DnsName <домен> возвращает адрес сервера Ринго. |
… tls: failed to verify certificate: x509: certificate signed by unknown authority |
Агент не доверяет удостоверяющему центру, выпустившему сертификат сервера. | Установите корневой сертификат в хранилище «Доверенные корневые центры сертификации» компьютера или исправьте цепочку на прокси (см. Связь агента с сервером → шаг 3). |
sync: sending connect idle, но нет socket: connect; повторяются socket: connect error [timeout] или [fetch read error] |
Запросы HTTPS проходят, а соединение websocket — нет. | Проверьте путь /socket.io/ на прокси (см. Связь агента с сервером → шаги 1–2). |
sync: got 401, uninstalling |
Сервер не знает этот компьютер. | См. шаг 3. |
После того как связь восстановлена, перезапускать службу не нужно: агент повторяет попытки сам и подключается в течение минуты.
Чтобы проверить адреса сервера с этого компьютера, выполните проверки со страницы Связь агента с сервером. Команды curl.exe из неё работают в PowerShell без изменений.
¶ Шаг 3. Сервер принимает агента
Если сервер отвечает агенту кодом 401, агент удаляет себя: в логе агента появляется sync: got 401, uninstalling, а в логе модуля обновления — Uninstalling ringo agent... и Ringo agent was uninstalled. Сертификаты и сохранённый идентификатор устройства при этом остаются. Так бывает, если компьютер удалили в Ринго.
Чтобы вернуть агент, удалите данные прошлой установки и установите агент заново.
Проверьте, что службы агента нет:
Get-Service | Where-Object Name -match 'ringo'
Ожидаемый результат: пустой вывод. Если служба есть, сначала удалите агент командой C:\ProgramData\Ringo\Updater\updater.exe uninstall.
Найдите оставшиеся сертификаты Ринго:
Get-ChildItem Cert:\LocalMachine\My | Where-Object Issuer -match 'Ringo' | Format-List Subject, Thumbprint
Удалите каждый найденный сертификат, подставив его отпечаток:
Remove-Item Cert:\LocalMachine\My\<Thumbprint>
Удалите сохранённый идентификатор устройства:
Remove-Item HKLM:\SOFTWARE\Ringo -Recurse
Проверьте, что сертификатов Ринго не осталось:
Get-ChildItem Cert:\LocalMachine\My | Where-Object Issuer -match 'Ringo'
Ожидаемый результат: пустой вывод. Затем установите агент заново (см. Установка агента).
Ошибки при регистрации. Если установка не завершилась, найдите причину в логе backend:
docker logs roll-deploy-backend --since 2h 2>&1 | grep -E 'Checkin:|PUT /agent/checkin'
| Запись в логе backend | Что это значит | Что делать |
|---|---|---|
Checkin: failed to verify enroll challenge for device with udid "…" |
Код регистрации в архиве недействителен: архив скачан давно. | Скачайте архив заново со страницы регистрации. |
Checkin: no enroll challenge provided for device with udid "…" |
Модуль установки запущен без кода регистрации. | Устанавливайте агент через service.bat из архива. |
PUT /agent/checkin с кодом 402 |
«Достигнуто максимальное количество компьютеров»: лицензия исчерпана. | Проверьте Настройки → Лицензия. |
¶ Терминал недоступен сразу после запуска
После установки агента, а также после включения компьютера, который долго был без связи, агент сначала выполняет накопившиеся задачи: сбор сведений об устройстве, дополнительные атрибуты, политики. Соединение websocket он открывает только после этого, поэтому терминал в карточке компьютера несколько минут остаётся в ожидании. В логе агента это видно по записям command '…' received, затем sync: no more commands, ending sync и только потом socket: connect.
Подождите, пока в логе не появится socket: auth:verified, и откройте терминал снова.
¶ Редкие причины
- Пакет не устанавливается. Агент на Windows устанавливает только пакеты
.msiи.exe. Пакет.pkg, назначенный компьютеру с Windows, завершается ошибкойUnsupported installer type: .pkg. Ограничьте область политики компьютерами macOS. См. Политики и пакеты. - Подключены два агента с одним UDID. Клон виртуальной машины получает тот же идентификатор, и сервер отключает второй агент с записью
Agent connected with same udid: …, disconnecting. На клоне удалите данные прошлой установки и установите агент заново (см. шаг 3). - Терминал отключён в настройках (Настройки → Терминал). Сервер отвечает «Терминал отключен».
¶ Если проблема не решена
Обратитесь в техническую поддержку (см. Обращение в поддержку). Приложите:
- папку
C:\ProgramData\Ringo\Logsс компьютера; - вывод команды
C:\ProgramData\Ringo\Agent\ringo.exe status; - записи лога backend по UDID устройства (
Agent connected,Disconnected,Checkin:,PUT /agent/connect); - результаты проверок со страницы Связь агента с сервером, выполненных с этого компьютера.
Проверено на Ринго 3.0.5 и Windows 11 (агент 5ed51db), октябрь 2026. Тексты ошибок — Справочник ошибок, термины — Термины.