Перейти к содержанию

Управление агентом системы: руководство пользователя

Агент - это программа-посредник, которая связывает ваш веб-браузер с физическим оборудованием на столе (считывателем карт). Она работает в фоновом режиме, принимает команды от сервера и управляет записью карт

Важное примечание

Агент - это "проводник команд". Он только выполняет инструкции от основного сервера, но сам не принимает решений и не хранит данные

Пошаговое руководство

Шаг 1: Проверка требований к компьютеру

Перед установкой убедитесь, что компьютер соответствует требованиям:

Параметр Минимальные требования
Операционная система Windows 7/10/11 или Linux (Ubuntu, Manjaro, Debian)
Java (JRE) Версия 17 или выше (рекомендуется JDK 21)
Сеть Подключение к локальной сети отеля
Порты Доступ к порту 8080 сервера
Оборудование Считыватель карт Mifare (энкодер) через USB

Шаг 2: Установка Java (JDK) и настройка переменных среды (только для Windows)

Этот шаг необходим для корректной работы агента на Windows 10/11.

2.1 Скачать и установить JDK 21

  1. Скачайте JDK 21 с официального сайта Oracle: https://www.oracle.com/java/technologies/javase/jdk21-archive-downloads.html
  2. Установите полноценную версию (например, jdk-21.0.10), не лёгкий образ
  3. Установите в место по умолчанию: C:\Program Files\Java\jdk-21

2.2 Настройка переменной Path

  1. Перейдите в: Пуск → Параметры → Система → О системе → Дополнительные параметры системы → Переменные среды
  2. В разделе "Системные переменные" найдите переменную Path, нажмите "Изменить"
  3. Если есть старая запись вида C:\Program Files\Java\jdk-1.8.1\bin - выделите её
  4. Нажмите "Обзор" и укажите путь до папки bin новой версии JDK: C:\Program Files\Java\jdk-21\bin
  5. Нажмите "Ок", чтобы сохранить изменения

2.3 Настройка переменной JAVA_HOME

  1. В том же окне "Системные переменные" нажмите "Создать" (если переменная JAVA_HOME уже существует - нажмите "Изменить")
  2. Имя переменной: JAVA_HOME
  3. Значение переменной: нажмите "Обзор каталога" и укажите путь до папки JDK: C:\Program Files\Java\jdk-21
  4. Нажмите "Ок", затем ещё дважды "Ок" для сохранения всех изменений

Шаг 3: Подключение считывателя карт (энкодера)

3.1 Подключение устройства

  1. Подключите энкодер к компьютеру через USB
  2. Драйверы должны установиться автоматически

Важно для Linux

На Linux считыватель карт становится виден системе только если при подключении на нём уже лежит карта. Если карты нет - устройство останется неактивным. Перед подключением положите карту на считыватель

3.2 Проверка на Windows - видит ли компьютер энкодер

  1. Нажмите правой кнопкой мыши по Пуск → выберите Диспетчер устройств
  2. Найдите раздел "Устройства чтения смарт-карт" и разверните его
  3. Вы должны увидеть ваш энкодер (например, ACR122 Smart Card Reader)

Если устройство не обнаружено на Windows

Новые версии Windows 11 могут не докачивать драйверы автоматически. Установите официальный драйвер с сайта производителя Пример для ACR122: https://www.acs.com.hk/en/driver/3/acr122u-usb-nfc-reader/

Шаг 4: Установка и запуск агента

Для Windows

  1. Скачайте последнюю версию агента
  2. Запустите файл agent.exe
  3. Агент запустится и свернётся в трей (правый нижний угол, рядом с часами)

После запуска перейдите к Шагу 5 для настройки IP-адреса сервера.

Для Linux

На Linux установка агента требует нескольких дополнительных шагов: нужно установить службу работы со смарт-картами и Java, а IP-адрес сервера задаётся через файл настроек. Выберите инструкцию для вашей операционной системы

Ubuntu

1. Обновите систему:

sudo apt update

2. Установите пакеты для работы со смарт-картами:

sudo apt install pcscd pcsc-tools libpcsclite1

3. Отключите встроенный NFC-драйвер (он блокирует связь с энкодером):

sudo modprobe -r pn533_usb pn533 nfc

4. (Необязательно) Проверьте, видит ли система энкодер:

pcsc_scan

Если считыватель определился - в выводе появится его название. Нажмите Ctrl+C для выхода.

5. Установите Java 21:

sudo apt install openjdk-21-jre

6. Скачайте файл агента. По умолчанию он загрузится в папку ~/Downloads/.

7. Перейдите в папку с агентом:

cd ~/Downloads

8. Дайте права на запуск:

chmod +x agent-*.jar

9. Запустите агент первый раз (будет ошибка - это нормально, цель этого запуска - создать файл настроек):

java -Djava.awt.headless=FALSE -jar agent-*.jar

Дождитесь появления ошибки или сообщений в консоли, затем закройте агент (Ctrl+C).

10. Откройте файл настроек и укажите IP-адрес сервера:

nano ~/Downloads/agent.properties

Найдите строку app.main-server-url= и впишите адрес вашего сервера, например:

app.main-server-url=http://192.168.12.128:8080

Сохраните файл: Ctrl+O, затем Enter, затем Ctrl+X.

11. Запустите агент повторно:

java -Djava.awt.headless=FALSE -jar agent-*.jar

В консоли появится лог успешного запуска. Агент готов к работе.

12. Проверьте в Ауре: перейдите в приложение → левый нижний угол → иконка настройки рабочего места (компьютер и шестерёнка). Считыватель карт должен гореть зелёным.

Manjaro

1. Обновите систему:

sudo pacman -Syu

2. Установите пакеты для работы со смарт-картами:

sudo pacman -S ccid pcsclite

3. Включите системную службу смарт-карт:

sudo systemctl enable --now pcscd

4. (Необязательно) Установите утилиту для проверки связи с энкодером:

sudo pacman -S pcsc-tools

5. Отключите встроенный NFC-драйвер (он блокирует связь с энкодером):

sudo modprobe -r pn533_usb pn533 nfc

6. Перезапустите службу смарт-карт:

sudo systemctl restart pcscd

7. (Необязательно) Проверьте, видит ли система энкодер:

pcsc_scan

Если считыватель определился - в выводе появится его название. Нажмите Ctrl+C для выхода.

8. Установите Java 21:

sudo pacman -S jdk21-openjdk

9. Скачайте файл агента и перейдите в папку, куда он был загружен

10. Запустите агент первый раз (будет ошибка - это нормально, цель - создать файл настроек):

java -Djava.awt.headless=FALSE -jar agent-*.jar

Дождитесь появления ошибки или сообщений в консоли, затем закройте агент (Ctrl+C)

11. Откройте файл настроек и укажите IP-адрес сервера:

nano agent.properties

Найдите строку app.main-server-url= и впишите адрес вашего сервера, например:

app.main-server-url=http://192.168.12.128:8080

Сохраните файл: Ctrl+O, затем Enter, затем Ctrl+X

12. Запустите агент повторно:

java -Djava.awt.headless=FALSE -jar agent-*.jar

В консоли появится лог успешного запуска. Агент готов к работе

13. Проверьте в Ауре: перейдите в приложение → левый нижний угол → иконка настройки рабочего места (компьютер и шестерёнка). Считыватель карт должен гореть зелёным.

Debian

На Debian 12 (GNOME 43+) агент по умолчанию завершается с ошибкой System tray is not supported !!!. Это связано с тем, что современный Debian использует протокол отрисовки Wayland, который блокирует прямой доступ приложений к системной панели. Стандартный запуск через системный трей здесь не работает.

Решение: запускать агент с флагом, который переводит его в фоновый режим без трея.

Шаги подготовки (установка пакетов и Java) - аналогичны Ubuntu (см. выше, шаги 1–8), с той лишь разницей, что используется менеджер пакетов apt.

После того как файл агента скачан и ему выданы права, выполните:

1. Первый запуск для создания файла настроек:

java -jar agent-*.jar --spring.main.web-application-type=servlet

Дождитесь появления сообщений в консоли, затем закройте агент (Ctrl+C).

2. Откройте файл настроек и укажите IP-адрес сервера:

nano agent.properties

Найдите строку app.main-server-url= и впишите адрес вашего сервера, например:

app.main-server-url=http://192.168.12.128:8080

Сохраните файл: Ctrl+O, затем Enter, затем Ctrl+X.

3. Запустите агент повторно:

java -jar agent-*.jar --spring.main.web-application-type=servlet

В консоли появится лог успешного запуска. Агент готов к работе.

4. Проверьте в Ауре: перейдите в приложение → левый нижний угол → иконка настройки рабочего места (компьютер и шестерёнка). Считыватель карт должен гореть зелёным.

Важно для Debian

На Debian агент работает в фоновом режиме без значка в системном трее. Все проверки (статус подключения, список устройств) выполняются только через веб-интерфейс Ауры.

На одном компьютере может работать только один экземпляр агента

Шаг 5: Настройка IP-адреса сервера (только для Windows)

На Linux IP-адрес задаётся через файл agent.properties при первом запуске (см. Шаг 4). На Windows настройка выполняется через интерфейс агента:

  1. Нажмите правой кнопкой мыши на иконке агента в системном трее
  2. Выберите пункт "Settings" (Настройки)
  3. Введите правильный IP-адрес вашего сервера (например, 192.168.12.128)
  4. Нажмите "OK" для сохранения
  5. Появится предупреждение о перезагрузке агента - нажмите "ОК"

Важно

Без правильной настройки IP-адреса агент не сможет подключиться к системе отеля

Шаг 6: Проверка статуса через веб-интерфейс

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

  1. Зайдите в основное приложение "Аура"
  2. В левом нижнем углу нажмите иконку настройки рабочего места (компьютер и шестерёнка)
  3. Откроется окно "Компьютеры и считыватели карт"

Что вы должны увидеть:

  • Имя агента (ID) - уникальное имя компьютера (например, reception или REC-01)
  • Оборудование - список устройств. Если считыватель подключён верно, вы увидите его название (например, ACR 122U)

Если список пуст

Агент не запущен или не может связаться с сервером. Перейдите к Шагу 7 для диагностики

Шаг 7: Диагностика через системный трей (только Windows и Ubuntu/Manjaro)

Если веб-интерфейс не видит считыватель, проверьте сам агент через трей.

На Debian системного трея нет

Диагностика выполняется только через веб-интерфейс Ауры.

  1. Нажмите правой кнопкой мыши на иконку агента в трее
  2. Используйте меню для проверки:

А. Проверка связи (Websocket status)

  • Выберите Websocket status
  • Успех: окно "Websocket is connected. Restart websocket?". Нажмите "No"
  • Ошибка: если подключения нет, нажмите "Yes" - соединение перезапустится

Б. Проверка USB-считывателя (Devices)

  • Выберите Devices
  • Успех: появится окно с названием считывателя

  • Ошибка: сообщение "No USB card readers found!"

  • Решение: проверьте USB-кабель, попробуйте другой порт. На Linux убедитесь, что при подключении энкодера на нём лежала карта

В. Узнать свой ID (AgentId)

  • Выберите AgentId
  • Сообщите появившееся имя (например, reception_1) системному администратору

Шаг 8: Повседневная работа (выдача карт)

Вам не нужно каждый раз открывать настройки. Агент работает автоматически.

  1. Администратор выписывает карты через менеджер карт
  2. Система отправляет команду агенту
  3. Агент активирует считыватель и передаёт команды на запись

Готово! Данные на карту успешно записаны

Возможные проблемы и решения

"Считыватель не найден" (в веб-интерфейсе)

Причины:

  • Агент выключен
  • Отошёл USB-кабель
  • Не установлен драйвер (Windows 11)
  • На Linux: не запущена служба pcscd, или при подключении на энкодере не было карты

Решение:

  1. Проверьте трей - есть ли там иконка агента? Если нет - запустите
  2. Нажмите правой кнопкой → Devices: если пишет "No USB card readers found" - переподключите устройство в другой порт
  3. На Windows 11 при необходимости установите драйвер вручную (см. Шаг 3)
  4. На Linux проверьте службу: sudo systemctl status pcscd. Если не запущена - sudo systemctl start pcscd

"Ключ не записывается" (ошибка при выдаче)

Причины:

  • Карта приложена неровно
  • Потеряна связь с сервером

Решение:

  1. Убедитесь, что карта лежит на считывателе ровно
  2. Проверьте соединение: правая кнопка в трее → Websocket status. Нажмите Yes, чтобы перезапустить соединение

Агент не запускается

Причины:

  • Уже работает (скрыт в трее)
  • Недостаточно прав на компьютере
  • Не установлена или устаревшая версия Java

Решение:

  1. Проверьте скрытые значки в трее (стрелочка ^ вверх)
  2. Запустите приложение с правами администратора (Windows) или через sudo (Linux)
  3. Установите или обновите JDK 21 (см. Шаг 2 / Шаг 4)

На Debian: агент запускается, но сразу завершается

Это происходит из-за отсутствия поддержки системного трея в Debian 12. Запускайте агент строго с флагом:

java -jar agent-*.jar --spring.main.web-application-type=servlet

Без этого флага агент завершится с ошибкой System tray is not supported !!!

Важная информация

  • Безопасность: агент не хранит данные гостей. Вся информация записывается сразу на карту и сохраняется на сервере
  • ID агента: если вы меняете компьютер, обязательно сообщите системному администратору новый AgentId, чтобы привязать его к вашей стойке регистрации
  • Имя файла агента: файл агента имеет вид agent-X.X.X-XXXXXXXX.XXXXXX-XX.jar. При обновлении агента имя файла может измениться - используйте актуальную версию, полученную от администратора