Продукты
АКС Комплекс PTL RID Световые маяки Все продукты
Услуги Загрузки Оборудование Документация FAQ
Контакты
Документация · версия 3.0

Развёртывание и запуск PTL

Установка Linux-бинаря, настройка контроллеров и проверка сервиса. Docker не требуется.

Требования

Быстрый старт

Одна команда скачивает бинарь, проверяет контрольную сумму, создаёт 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.

Пример файла конфигурации

config.json
{
    "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_urlredis://127.0.0.1:6379Адрес подключения к Redis
demofalseДемо-режим без оборудования
debugfalseРежим отладки
log_levelinfoУровень журнала: debug, info, warn, error
log_file—Путь к файлу журнала (по умолчанию — stdout)
clean_ptl_on_startupfalseПогасить все модули при старте
api_host0.0.0.0Адрес прослушивания
api_port8000Порт прослушивания
telemetry_enabledtrueОтправлять обезличенную телеметрию
telemetry_urlhttps://telemetry.whsoft.ruАдрес сервера телеметрии

Параметры фоновых процессов

ПараметрПо умолчаниюОписание
poll_interval_ms250Интервал опроса оборудования (мс)
poll_only_activetrueОпрашивать только активные модули
apply_timeout_sec10Тайм-аут записи на контроллер (сек.)
modbus_timeout_sec2Тайм-аут Modbus-соединения (сек.)
broadcast_delay_ms1000Задержка широковещательных операций (мс)
monitor_interval_sec5Интервал пинга контроллеров (сек.)
task_concurrencyparallelРежим выполнения задач: parallel или exclusive
unit_degrade_threshold5Количество последовательных ошибок до статуса «degraded»
unit_unreachable_threshold30Количество ошибок до статуса «unreachable»
health_scan_interval_sec0Интервал сканирования здоровья всех модулей (0 = отключено)
log_max_size_mb100Максимальный размер файла журнала (МБ)
log_max_files5Количество ротируемых файлов журнала

Настройка контроллеров

Каждый контроллер — это 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"
        }
    ]
}
ПолеОписание
ipIP-адрес контроллера
portПорт Modbus (обычно 502)
start_idНачальный адрес модуля
end_idКонечный адрес модуля (макс. 247)
idsЯвный список адресов (вместо start_id/end_id)
device_typeТип устройства (см. ниже), по умолчанию 2Sub_4Count

Типы устройств

ТипОсновное таблоДополнительное
2Sub_4Count4 разряда2 разряда
0Sub_6Count6 разрядовнет
0Sub_4Count4 разряданет
0Sub_3Count3 разряданет
0Sub_2Count2 разряданет

Запуск и systemd

Установщик создаёт unit ptl-api.service. Управление сервисом:

systemd
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Путь к файлу конфигурации
-host0.0.0.0Адрес прослушивания
-port8000Порт прослушивания

Переменные окружения

ПеременнаяПо умолчаниюОписание
APP_CONFIG/etc/ptl_api/config.jsonПуть к файлу конфигурации
REDIS_URLredis://127.0.0.1:6379Адрес подключения к Redis
API_HOST0.0.0.0Адрес прослушивания
API_PORT8000Порт прослушивания
DEBUGfalseРежим отладки (true или 1)
LOG_LEVELinfoУровень журнала
TELEMETRY10 или false — отключить телеметрию
TELEMETRY_URLhttps://telemetry.whsoft.ruАдрес сервера телеметрии
TELEMETRY_STATE_FILE/var/lib/ptl_api/telemetry.jsonФайл состояния телеметрии (в systemd)

Приоритет применения настроек (от низшего к высшему):

  1. Значения по умолчанию в коде
  2. JSON-файл конфигурации
  3. Переменные окружения
  4. Флаги командной строки

Проверка работоспособности

Терминал
# Быстрая проверка
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)

Периодически считывает состояние модулей с контроллеров. Обнаруживает нажатия кнопок и публикует события.

Планировщик шины (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 в конфигурации. В этом режиме:

Для быстрого старта. Включите демо-режим, чтобы протестировать интеграцию до поставки оборудования.

Телеметрия

Сервис отправляет обезличенную телеметрию, чтобы улучшать продукт: версия, ОС, число контроллеров и unit'ов, счётчики использования функций и базовая надёжность. IP-адреса, данные оборудования, URL вебхуков и содержимое дисплеев не передаются.

Подробнее — Политика телеметрии.

Важные замечания

Redis обязателен. Без Redis сервис не запустится. Redis используется для хранения состояния, подписок на события и потоковой записи истории.