О плагине

Плагин предназначен для мониторинга и управления OLT-устройствами (Optical Line Terminal) и ONU абонентов. Выполняет Telnet-опрос OLT-оборудования, хранит данные в локальной БД BGERP и интегрируется с BGBilling для маппинга MAC→абонент.

Возможности:

  • Встроенный Telnet-опрос OLT-устройств (BdCom, GateRay, CData) с автоопределением vendor

  • Отображение данных ONU на вкладке процесса и вкладке договора BGBilling

  • Страница управления OLT — CRUD, массовый/выборочный опрос, просмотр портов/ONU

  • Импорт OLT из биллинга и автоматический маппинг MAC→абонент

  • Фильтрация OLT по биллингу, статусу, вендору + текстовый поиск (MAC/договор/ФИО/адрес)

  • Цветовая подсветка проблемных RX-сигналов (пересвет, средний, плохой)

  • Перезагрузка ONU с cooldown-защитой (5 мин)

  • Активация/замена ONU — обновление MAC-адреса в биллинге

  • Автоматическое создание записок в процессе при выполнении действий

  • Опрос по расписанию (scheduler task) с защитой от зависания статуса UPDATING

Настройка

Архитектура

Компоненты системы:

  1. BGERP — вкладки процесса и договора, страница управления OLT

  2. Telnet-опрос — встроенный Telnet-клиент для прямого подключения к OLT-устройствам

  3. BGBilling Webhooks (JSON-RPC) — импорт OLT, маппинг MAC→абонент, управление MAC/сессиями

  4. MySQL (BGERP) — локальное хранение данных OLT, портов, ONU

Поддерживаемые вендоры

Vendor Класс Описание

BDCOM

BdComDevice

BdCom GP3600-08B и аналоги

GATERAY

GateRayDevice

GateRay EPON до 2020

GATERAY2020

GateRay2020Device

GateRay EPON 2020+

CDATA

CDataDevice

CData EPON

CDATA_GPON

CDataGponDevice

CData GPON

CDATA_FD1608

CDataFD1608Device

CData FD1608S-B1

CDATA_FD1208

CDataFD1208Device

CData FD1208S-B1

Структура файлов

src/org/bgerp/plugin/bgb/getolt/
├── Plugin.java              # Регистрация плагина, миграции БД, сброс UPDATING
├── Config.java              # Конфигурация (операторы, billing, auto-discovery)
├── action/
│   ├── GetOltAction.java    # Вкладка процесса + вкладка договора
│   └── OltManageAction.java # Управление OLT: CRUD, опрос, порты/ONU
├── dao/
│   ├── Tables.java          # Константы таблиц
│   ├── OltDAO.java          # CRUD OLT-устройств
│   ├── OltPortDAO.java      # CRUD портов
│   ├── OltOnuDAO.java       # CRUD ONU
│   ├── InetMacApiClient.java # JSON-RPC к BGBilling (webhooks)
│   └── GetOltApiClient.java  # HTTP-клиент внешнего API (legacy, не используется)
├── model/
│   ├── Olt.java, OltPort.java, OltOnu.java, OltStatus.java
│   ├── OpticalInfo.java, BillingConfig.java
│   ├── OnuData.java, OnuSearchResult.java, OnuApiResponse.java
│   ├── InetService.java, MacUpdateResult.java
│   ├── RefreshResult.java, SessionDropResult.java
│   └── json/                # Jackson deserializers
├── exec/
│   ├── OltPollingTask.java  # Scheduler task (Telnet + billing mapping)
│   └── OltPollingService.java # Thread pool, per-port commit
├── telnet/
│   ├── TelnetSession.java   # Apache Commons Net TelnetClient
│   ├── TelnetCommandResult.java
│   ├── OltDevice.java       # Абстрактный OLT
│   ├── OltDeviceFactory.java # Фабрика + автодетект vendor
│   └── vendor/              # 7 вендор-классов
├── util/
│   ├── MacAddressConverter.java
│   └── TimeParserUtil.java
├── action.xml               # Права доступа
├── db.sql                   # Схема БД
└── l10n.xml                 # Локализация

webapps/WEB-INF/jspf/user/plugin/getolt/
├── process_tabs.jsp         # Регистрация вкладки процесса
├── menu_items.jsp           # Пункт меню "OLT"
├── onu_info.jsp             # UI данных ONU (общий для процесса и договора)
└── manage/
    ├── list.jsp             # Список OLT с фильтрами
    ├── edit.jsp             # Форма OLT
    ├── ports.jsp            # Таблица портов
    └── onus.jsp             # Таблица ONU

webapps/js/pl.getolt.js      # JavaScript модуль
webapps/css/plugin/style.getolt.css.jsp  # CSS стили

Активация плагина

  1. В UI Администрирование → Конфигурация → добавить или открыть конфиг:

# Включить плагин
getolt:enable=1

# Параметр процесса "Оператор" (param_list)
getolt:operator.paramId=68
getolt:operator.default=РТЦ

# Маппинг значений параметра на операторов
getolt:operator.mapping.1=Омиплат
getolt:operator.mapping.2=Омикрон
getolt:operator.mapping.3=Рокет
getolt:operator.mapping.4=РТЦ
getolt:operator.mapping.5=Флеш

# Маппинг billingId → имя оператора (для ссылок на договоры)
getolt:operator.billing.omicron=ЮТК
getolt:operator.billing.rocket=Рокет

# Общие credentials для billing webhooks (auto-discovery режим)
getolt:webhook.user=YOUR_WEBHOOK_USER
getolt:webhook.password=YOUR_WEBHOOK_PASSWORD

# Per-billing credential override (опционально)
# getolt:inetmac.rocket.user=special_user
# getolt:inetmac.rocket.password=special_pass

  1. Подключить конфиг к основному (если не подключён): #include.{id}=1

  2. Перезапустить сервер

Auto-discovery billing

При отсутствии явных getolt:inetmac.*.url конфигов плагин автоматически обнаруживает биллинг-серверы из плагина bgbilling (DBInfoManager):

  • URL webhook-ов строятся из DB URL каждого биллинга + path вебхука

  • Credentials: getolt:webhook.user/password (общие) или getolt:inetmac.{billingId}.user/password (override)

  • Ключи в конфигах = billingId (rocket, omicron…​), НЕ имена операторов

Legacy режим (explicit конфиги)

# Явные InetMac конфиги для каждого оператора (отключает auto-discovery)
getolt:inetmac.Омикрон.url=http://billing-omicron:8080/billing/api/inetmac
getolt:inetmac.Омикрон.user=admin
getolt:inetmac.Омикрон.password=secret
getolt:inetmac.Омикрон.timeout=10000

Добавление вкладки в тип процесса

В Администрирование → Типы процессов → выбрать тип → Конфигурация:

getolt:processShowTab=1

Настройка прав доступа

В Администрирование → Наборы прав → выбрать набор, найти "Plugin GetOLT":

Право Описание

getolt:null

Просмотр ONU (вкладка процесса)

getolt:contractOnu

Просмотр ONU (вкладка договора BGBilling)

getolt:refreshPort

Обновление порта OLT (Telnet)

getolt:rebootOnu

Перезагрузка ONU

getolt:activateOnu

Активация/замена ONU (обновление MAC в биллинге)

manage:null

Просмотр списка OLT (страница управления)

manage:oltGet

Получение OLT (форма)

manage:oltUpdate

Добавление/редактирование OLT

manage:oltDelete

Удаление OLT

manage:oltPoll

Запуск опроса одного OLT

manage:oltPollAll

Массовый/выборочный опрос OLT

manage:importFromApi

Импорт OLT из биллинга

manage:portList

Просмотр портов OLT

manage:portRefresh

Обновление одного порта

manage:onuList

Просмотр ONU порта

manage:billingMapping

Ручной запуск маппинга MAC→абонент

Scheduler task (автоматический опрос)

scheduler.task.oltPoll.class=OltPollingTask
scheduler.task.oltPoll.hours=*
scheduler.task.oltPoll.minutes=0,30
scheduler.task.oltPoll.batchSize=10
scheduler.task.oltPoll.staleMinutes=60

Использование

Вкладка GetOLT (процесс)

process tab overview

Вкладка отображается на странице процесса при выполнении условий:

  1. Плагин включён (getolt:enable=1)

  2. Тип процесса имеет настройку getolt:processShowTab=1

  3. У пользователя есть право getolt:null

  4. К процессу привязан договор (contract link)

Вкладка GetOLT (договор BGBilling)

Вкладка появляется на карточке договора BGBilling при:

  1. Плагин включён (getolt:enable=1)

  2. У пользователя есть право getolt:contractOnu

Данные ONU ищутся напрямую по operator + contractId/numDogovor — без привязки к процессу.

Карточка ONU

onu card full

Карточка отображает:

  • Заголовок: MAC-адрес, статус (ONLINE/OFFLINE), время последнего обновления

  • Кнопки: Обновить порт, Перезагрузить ONU (при наличии прав)

  • Данные:

    • OLT IP

    • Порт / ONU ID

    • Сигнал RX/TX (с цветовой индикацией качества)

    • Дистанция (м)

    • Температура (°C)

    • Напряжение (V)

    • MAC за ONU (список)

    • Соседи по порту (таблица)

Соседи по порту

port neighbors table

Таблица соседей отображает все ONU на том же порту OLT. Текущая ONU абонента выделена жёлтым цветом. Качество сигнала (RX) подсвечивается цветом.

Индикация качества сигнала

Подсвечиваются только проблемные значения RX. Нормальный сигнал — без подсветки. TX и температура не подсвечиваются.

Качество RX диапазон Цвет

Засвет (overexposed)

> -15 dBm

Голубой (#17a2b8)

Хороший (good)

-15 до -25 dBm

(без подсветки)

Средний (medium)

-25 до -27 dBm

Оранжевый (#e6a000)

Плохой (poor)

< -27 dBm

Красный (#dc3545)

Управление OLT

Страница доступна через меню "OLT" (право manage:null).

Функции:

  • Таблица OLT — IP, vendor, billing, порты, ONU (active/total), статус, last update

  • Фильтры — биллинг, статус, vendor (combo-check) + текстовый поиск

  • CRUD — создание, редактирование, удаление OLT

  • Опрос — ручной опрос одного OLT или массовый (чекбоксы + кнопка "Обновить все/N")

  • Порты/ONU — expandable rows с детальной информацией

  • Импорт — загрузка списка OLT из биллинга

  • Маппинг — ручной запуск сопоставления MAC→абонент

Форма активации ONU

При наличии права activateOnu отображается форма:

  • Поле ввода MAC: автоформатирование, валидация, защита от кириллицы

  • Кнопка "Активировать": отправляет запрос на обновление MAC в биллинге

Если у договора несколько интернет-услуг, появляется модальное окно выбора услуги.

Cooldown перезагрузки

После успешной перезагрузки ONU кнопка блокируется на 5 минут. Состояние сохраняется в localStorage браузера.

Billing Webhooks (JSON-RPC)

Плагин использует BGBilling webhooks для:

Webhook Назначение

GetOltList → ru.webHooks.OltList/GetOltListInterface

Импорт списка OLT из биллинга

GetInetMacList → ru.webHooks.InetMacList/GetInetMacListInterface

Маппинг MAC→абонент (operator, contractId, numDogovor, FIO, addr)

InetMac → ru.webHooks.InetMac/InetMacInterface

getServicesByContractId, updateMacAddress, dropSession

URL webhook-ов строятся заменой path в базовом InetMac URL. Все используют одни credentials из конфига.

Записки в процессе

При выполнении действий плагин автоматически создаёт записки (MessageTypeNote):

Обновление порта

Обновлены данные порта OLT
OLT: 192.168.1.1
Порт: 3

Перезагрузка ONU

Выполнена перезагрузка ONU
Порт/ONU ID: 3/12
MAC: AA:BB:CC:DD:EE:FF

Активация/замена ONU

Активация/замена ONU
Договор: 123456
Старый MAC: AA:BB:CC:DD:EE:FF
Новый MAC: 11:22:33:44:55:66
Сессия: сброшена

Определение оператора

Плагин определяет оператора в следующем порядке:

  1. Параметр процесса "Оператор" (param_list)

    • ID параметра: getolt:operator.paramId

    • Маппинг значений: getolt:operator.mapping.{valueId}

  2. Billing ID из contract link

    • Формат link: contract:{billingId}

    • Маппинг: getolt:operator.billing.{billingId}

  3. Значение по умолчанию

    • getolt:operator.default

Отладка

Логирование

# Telnet-опрос
grep "OltPollingService\|OltPollingTask" log/bgerp.log

# Действия пользователя
grep "GetOltAction\|OltManageAction" log/bgerp.log

# Billing webhooks
grep "InetMacApiClient" log/bgerp.log

Типичные проблемы

Проблема Причина Решение

Вкладка процесса не появляется

Плагин не включён или нет прав

Проверить getolt:enable=1, processShowTab=1 и право getolt:null

"Нет привязанных договоров"

У процесса нет contract link

Привязать договор к процессу

"ONU не найдена"

OLT не опрошен или маппинг не выполнен

Запустить опрос OLT + маппинг на странице управления

OLT завис в UPDATING

Ошибка при опросе (перезапуск сервера сбросит)

Перезапустить BGERP или подождать следующий цикл scheduler

500 при фильтрах OLT

Отсутствует синоним :unspecified в action.xml

Проверить manage:null,manage:unspecified в action.xml

Пустой vendor после импорта

Vendor определяется отдельным циклом

Подождать следующий цикл scheduler или запустить опрос вручную

Кнопка перезагрузки заблокирована

Cooldown 5 мин после предыдущей перезагрузки

Подождать 5 минут или очистить localStorage

Проверка конфигурации

-- Проверить, что плагин включён
SELECT * FROM config_global WHERE config LIKE '%getolt:enable%';

-- Проверить настройки типа процесса
SELECT id, title, config FROM process_type
WHERE config LIKE '%getolt:processShowTab%';

-- Проверить права
SELECT pp.permset_id, pt.title, pp.action
FROM user_permset_permission pp
JOIN user_permset_title pt ON pp.permset_id = pt.id
WHERE pp.action LIKE '%getolt%';

-- Проверить OLT в БД
SELECT id, ip, vendor, billing, status, last_update FROM getolt_olt ORDER BY ip;

-- Количество ONU
SELECT o.ip, COUNT(onu.id) AS onu_count
FROM getolt_olt o LEFT JOIN getolt_olt_onu onu ON o.id = onu.olt_id
GROUP BY o.id ORDER BY o.ip;

Безопасность

Валидация MAC

  • Проверка формата: XX:XX:XX:XX:XX:XX

  • Нормализация различных форматов (дефисы, точки, пробелы, без разделителей)

  • Защита от кириллических символов (А, В, С, Е похожи на латинские)

  • Преобразование в верхний регистр

Маскировка паролей

TelnetSession поддерживает sensitiveMode — при setSensitiveMode(true) перед отправкой пароля все данные маскируются в логах (*).

Rate Limiting

  • Перезагрузка ONU: cooldown 5 минут (localStorage на фронтенде)

  • Scheduler: AtomicBoolean предотвращает параллельный запуск опроса