Развёртывание и запуск PTL
Установка Linux-бинаря, настройка контроллеров и проверка сервиса. Docker не требуется.
Требования
- Linux x86_64 — Ubuntu 22.04+ или любой современный дистрибутив
- Redis 7+ — состояние модулей, подписки на события, история
- Сетевой доступ к контроллерам по протоколу Modbus TCP (порт 502)
- Права root для установки: systemd, каталоги, пользователь
ptl
Быстрый старт
Одна команда скачивает бинарь, проверяет контрольную сумму, создаёт systemd-сервис и запускает его:
curl -fsSL https://pkg.whsoft.ru/ptl_api/install.sh | sudo sh # указать redis_url и контроллеры sudo nano /etc/ptl_api/config.json # применить конфигурацию sudo systemctl restart ptl-api # проверить curl http://127.0.0.1:8000/_ping
Установщик поддерживает PTL_VERSION=3.0 (закрепить версию) и PTL_NO_START=1 (не запускать сервис).
Что делает install.sh. Проверяет SHA256 (и minisign, если установлен), создаёт пользователя ptl и каталоги /opt/ptl_api, /etc/ptl_api, /var/lib/ptl_api, ставит бинарь, конфиг-пример и unit ptl-api.service, затем проверяет Redis.
Конфигурация
Настройки задаются через JSON-файл. По умолчанию сервис ищет файл по пути /etc/ptl_api/config.json. Путь можно переопределить переменной APP_CONFIG или флагом -config.
Пример файла конфигурации
{
"controllers": [
{
"ip": "192.168.0.199",
"port": 502,
"start_id": 1,
"end_id": 30,
"device_type": "2Sub_4Count"
}
],
"redis_url": "redis://127.0.0.1:6379",
"demo": false,
"debug": false,
"clean_ptl_on_startup": true,
"api_host": "0.0.0.0",
"api_port": 8000,
"telemetry_enabled": true,
"telemetry_url": "https://telemetry.whsoft.ru"
} Основные параметры
| Параметр | По умолчанию | Описание |
|---|---|---|
controllers | [] | Список контроллеров (см. ниже) |
redis_url | redis://127.0.0.1:6379 | Адрес подключения к Redis |
demo | false | Демо-режим без оборудования |
debug | false | Режим отладки |
log_level | info | Уровень журнала: debug, info, warn, error |
log_file | — | Путь к файлу журнала (по умолчанию — stdout) |
clean_ptl_on_startup | false | Погасить все модули при старте |
api_host | 0.0.0.0 | Адрес прослушивания |
api_port | 8000 | Порт прослушивания |
telemetry_enabled | true | Отправлять обезличенную телеметрию |
telemetry_url | https://telemetry.whsoft.ru | Адрес сервера телеметрии |
Параметры фоновых процессов
| Параметр | По умолчанию | Описание |
|---|---|---|
poll_interval_ms | 250 | Интервал опроса оборудования (мс) |
poll_only_active | true | Опрашивать только активные модули |
apply_timeout_sec | 10 | Тайм-аут записи на контроллер (сек.) |
modbus_timeout_sec | 2 | Тайм-аут Modbus-соединения (сек.) |
broadcast_delay_ms | 1000 | Задержка широковещательных операций (мс) |
monitor_interval_sec | 5 | Интервал пинга контроллеров (сек.) |
task_concurrency | parallel | Режим выполнения задач: parallel или exclusive |
unit_degrade_threshold | 5 | Количество последовательных ошибок до статуса «degraded» |
unit_unreachable_threshold | 30 | Количество ошибок до статуса «unreachable» |
health_scan_interval_sec | 0 | Интервал сканирования здоровья всех модулей (0 = отключено) |
log_max_size_mb | 100 | Максимальный размер файла журнала (МБ) |
log_max_files | 5 | Количество ротируемых файлов журнала |
Настройка контроллеров
Каждый контроллер — это Ethernet-шлюз Modbus, к которому подключены световые модули. В массиве controllers описывается каждый шлюз и диапазон адресов его устройств.
{
"controllers": [
{
"ip": "192.168.0.199",
"port": 502,
"start_id": 1,
"end_id": 30,
"device_type": "2Sub_4Count"
},
{
"ip": "192.168.0.100",
"port": 502,
"start_id": 1,
"end_id": 102,
"device_type": "0Sub_6Count"
}
]
} | Поле | Описание |
|---|---|
ip | IP-адрес контроллера |
port | Порт Modbus (обычно 502) |
start_id | Начальный адрес модуля |
end_id | Конечный адрес модуля (макс. 247) |
ids | Явный список адресов (вместо start_id/end_id) |
device_type | Тип устройства (см. ниже), по умолчанию 2Sub_4Count |
Типы устройств
| Тип | Основное табло | Дополнительное |
|---|---|---|
2Sub_4Count | 4 разряда | 2 разряда |
0Sub_6Count | 6 разрядов | нет |
0Sub_4Count | 4 разряда | нет |
0Sub_3Count | 3 разряда | нет |
0Sub_2Count | 2 разряда | нет |
Запуск и systemd
Установщик создаёт unit ptl-api.service. Управление сервисом:
sudo systemctl status ptl-api sudo systemctl restart ptl-api sudo journalctl -u ptl-api -f
Ручной запуск без systemd:
APP_CONFIG=/etc/ptl_api/config.json /opt/ptl_api/ptl-api # с указанием хоста и порта APP_CONFIG=/etc/ptl_api/config.json /opt/ptl_api/ptl-api -host 0.0.0.0 -port 8000
Флаги командной строки
| Флаг | По умолчанию | Описание |
|---|---|---|
-config | /etc/ptl_api/config.json | Путь к файлу конфигурации |
-host | 0.0.0.0 | Адрес прослушивания |
-port | 8000 | Порт прослушивания |
Переменные окружения
| Переменная | По умолчанию | Описание |
|---|---|---|
APP_CONFIG | /etc/ptl_api/config.json | Путь к файлу конфигурации |
REDIS_URL | redis://127.0.0.1:6379 | Адрес подключения к Redis |
API_HOST | 0.0.0.0 | Адрес прослушивания |
API_PORT | 8000 | Порт прослушивания |
DEBUG | false | Режим отладки (true или 1) |
LOG_LEVEL | info | Уровень журнала |
TELEMETRY | 1 | 0 или false — отключить телеметрию |
TELEMETRY_URL | https://telemetry.whsoft.ru | Адрес сервера телеметрии |
TELEMETRY_STATE_FILE | /var/lib/ptl_api/telemetry.json | Файл состояния телеметрии (в systemd) |
Приоритет применения настроек (от низшего к высшему):
- Значения по умолчанию в коде
- JSON-файл конфигурации
- Переменные окружения
- Флаги командной строки
Проверка работоспособности
# Быстрая проверка curl http://127.0.0.1:8000/_ping # Ответ: pong # Версия, вшитая при сборке curl http://127.0.0.1:8000/version # Доступность контроллеров curl http://127.0.0.1:8000/alive # Список контроллеров и статус curl http://127.0.0.1:8000/controllers # Метрики (Prometheus) curl http://127.0.0.1:8000/metrics # OpenAPI 3.0 curl http://127.0.0.1:8000/openapi.yaml
Обновление
Повторно запустите установщик. Конфиг /etc/ptl_api/config.json и состояние телеметрии сохраняются:
curl -fsSL https://pkg.whsoft.ru/ptl_api/install.sh | sudo sh # или закрепить конкретную версию curl -fsSL https://pkg.whsoft.ru/ptl_api/install.sh | sudo env PTL_VERSION=3.0 sh
Вебхуки
Система может отправлять HTTP POST-уведомления о событиях на внешние URL. Вебхуки настраиваются глобально и/или для каждого контроллера отдельно.
Поддерживаемые события
| Событие | Описание |
|---|---|
button | Оператор нажал кнопку на PTL-модуле |
task_confirmed | Все модули задачи подтверждены |
task_completed | Задача завершена |
task_timeout | Задача не выполнена в срок |
task_cancelled | Задача отменена |
controller_online | Контроллер стал доступен |
controller_offline | Контроллер перестал отвечать |
Тайм-аут запроса — 5 секунд. Отправка выполняется асинхронно и не блокирует основной процесс.
Фоновые процессы
PTL запускает несколько фоновых процессов для работы с оборудованием:
Опросчик (Poller)
Периодически считывает состояние модулей с контроллеров. Обнаруживает нажатия кнопок и публикует события.
- Интервал:
poll_interval_ms(по умолчанию 250 мс) - Если
poll_only_activeвключён — опрашиваются только активные модули - В демо-режиме опрос не выполняется
Планировщик шины (Bus Scheduler)
Управляет очередью Modbus-операций записи для каждого контроллера. Один планировщик на каждый контроллер.
Монитор (Monitor)
Пингует контроллеры каждые monitor_interval_sec секунд и обновляет статус online/offline; формирует вебхуки controller_online/controller_offline.
Сканер здоровья (Health Scanner)
Опрашивает все модули и ведёт статусы ok/degraded/unreachable. Включается параметром health_scan_interval_sec (0 — отключён).
Движок сценариев
Выполняет задачи и демо-программы, подтверждает нажатия и отправляет вебхуки.
Телеметрия
Раз в сутки отправляет обезличенный отчёт на telemetry.whsoft.ru. Не блокирует работу и отключается в UI или через TELEMETRY=0.
Демо-режим
Для тестирования без оборудования установите "demo": true в конфигурации. В этом режиме:
- Modbus-подключения не создаются
- Опрос оборудования отключён
- Состояние модулей хранится только в Redis
- Доступен эндпоинт
POST /pressдля эмуляции нажатия кнопки
Для быстрого старта. Включите демо-режим, чтобы протестировать интеграцию до поставки оборудования.
Телеметрия
Сервис отправляет обезличенную телеметрию, чтобы улучшать продукт: версия, ОС, число контроллеров и unit'ов, счётчики использования функций и базовая надёжность. IP-адреса, данные оборудования, URL вебхуков и содержимое дисплеев не передаются.
- Включена по умолчанию, легко отключается: тумблер «Отправлять обезличенную телеметрию» в разделе «О приложении».
- Или переменной окружения
TELEMETRY=0. - Состояние:
/var/lib/ptl_api/telemetry.json.
Подробнее — Политика телеметрии.
Важные замечания
Redis обязателен. Без Redis сервис не запустится. Redis используется для хранения состояния, подписок на события и потоковой записи истории.
- Порт 502. Контроллеры работают по стандартному порту Modbus TCP. Убедитесь, что между сервером PTL и контроллерами нет сетевых ограничений.
- Адреса устройств. Максимум 247 устройств на контроллер (
end_id≤ 247). Диапазоны разных контроллеров могут пересекаться. - Очистка при старте.
clean_ptl_on_startupотправляет clear на модули и удаляет legacy-ключи состояния в Redis. Рекомендуется при первичной настройке. - Журналирование. По умолчанию журнал выводится в stdout. Для записи в файл укажите
log_file. Ротация — по размеру (100 МБ) и количеству (5 файлов). - Docker не требуется. Релиз поставляется как Linux-бинарь; Docker-образ в поставку не входит.