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

Требования

Для запуска PTL необходимы:

• Docker и Docker Compose (рекомендуется)
• Redis 7+ — хранение состояния модулей, подписки на события
• Сетевой доступ к контроллерам по протоколу Modbus TCP (порт 502)

Если планируется сборка без Docker:

• Go 1.25 или новее
• ОС: Linux (рекомендуется)

Конфигурация

Настройки задаются через JSON-файл. По умолчанию сервис ищет файл по пути /etc/fontera_ptl/config.json. Путь можно переопределить переменной APP_CONFIG или флагом -config.

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

{
    "controllers": [
        {
            "ip": "192.168.0.199",
            "port": 502,
            "start_id": 1,
            "end_id": 30
        }
    ],
    "redis_url": "redis://127.0.0.1:6379",
    "demo": false,
    "debug": false,
    "clean_ptl_on_startup": true,
    "poll_interval_ms": 250,
    "reconcile_interval_sec": 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"
        }
    ]
}

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

Запуск через Docker

Docker Compose (с Redis)

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    deploy:
      resources:
        limits:
          memory: 128M

  ptl:
    image: ptl-api:3.0
    ports:
      - "8001:8000"
    environment:
      APP_CONFIG: /etc/fontera_ptl/config.json
      REDIS_URL: redis://redis:6379
    volumes:
      - ./config.json:/etc/fontera_ptl/config.json:ro
    depends_on:
      - redis
    deploy:
      resources:
        limits:
          memory: 256M
    restart: unless-stopped

docker compose up -d

Сборка образа

# Через Makefile
make docker

# Или вручную
docker build -t ptl-api:3.0 .

Запуск без Docker

# Сборка
make build

# Запуск
./bin/ptl-api -config ./config.json

# С указанием хоста и порта
./bin/ptl-api -config ./config.json -host 0.0.0.0 -port 8000

Флаги командной строки

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

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

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

Вебхуки

Система может отправлять HTTP POST-уведомления о событиях на внешние URL. Вебхуки настраиваются глобально и/или для каждого контроллера отдельно.

Поддерживаемые события

Тайм-аут запроса — 5 секунд. Отправка выполняется асинхронно и не блокирует основной процесс.

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

# Быстрая проверка
curl http://localhost:8000/_ping
# Ответ: pong

# Доступность контроллеров
curl http://localhost:8000/alive
# Ответ:
# [
#   {"controller_ip": "192.168.0.199", "controller_port": 502, "reachable": true},
#   {"controller_ip": "192.168.0.100", "controller_port": 502, "reachable": false}
# ]

# Список контроллеров и статус
curl http://localhost:8000/controllers

# Метрики (Prometheus)
curl http://localhost:8000/metrics

Фоновые процессы

PTL запускает несколько фоновых процессов для работы с оборудованием:

Опросчик (Poller)

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

• Интервал: poll_interval_ms (по умолчанию 250 мс)
• Если poll_only_active включён — опрашиваются только модули с заданным целевым состоянием
• Не запускается в демо-режиме

Синхронизатор (Reconciler)

Сравнивает целевое и фактическое состояние модулей. Если есть расхождение — записывает нужное значение на контроллер.

• Срабатывает по подписке или каждые reconcile_interval_sec секунд
• Тайм-аут записи: apply_timeout_sec (по умолчанию 10 сек.)

Планировщик шины (Bus Scheduler)

Управляет очередью Modbus-операций записи для каждого контроллера. Один планировщик на каждый контроллер.

Демо-режим

Для тестирования без оборудования установите "demo": true в конфигурации. В этом режиме:

• Опрос оборудования отключён
• Modbus-подключения не создаются
• Состояние модулей хранится только в Redis
• Доступен эндпоинт POST /press для эмуляции нажатия кнопки

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

• Порт 502. Контроллеры работают по стандартному порту Modbus TCP. Убедитесь, что между сервером PTL и контроллерами нет сетевых ограничений.
• Адреса устройств. Максимум 247 устройств на контроллер (end_id ≤ 247). Диапазоны разных контроллеров могут пересекаться.
• Очистка при старте. Параметр clean_ptl_on_startup удаляет все записи состояния в Redis. Рекомендуется при первичной настройке.
• Журналирование. По умолчанию журнал выводится в stdout. Для записи в файл укажите log_file. Ротация — по размеру (100 МБ) и количеству (5 файлов).
• Часовой пояс. В Docker-контейнере установлен Europe/Moscow.
• Ограничение памяти. В Docker Compose рекомендуется ограничение 256 МБ для сервиса и 128 МБ для Redis.