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

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

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

Требования

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

Установка
curl -fsSL https://pkg.whsoft.ru/lighthouse_api/install.sh | sudo sh

# указать Redis, реле и маяки
sudo nano /etc/lighthouse_api/config.json

sudo systemctl restart lighthouse-api
curl http://127.0.0.1:8010/_ping

Установщик поддерживает LIGHTHOUSE_VERSION=3.0 (закрепить версию) и LIGHTHOUSE_NO_START=1 (не запускать сервис).

Что делает install.sh. Проверяет SHA256 (и minisign, если установлен), создаёт пользователя lighthouse и каталоги /opt/lighthouse_api, /etc/lighthouse_api, /var/lib/lighthouse_api, ставит бинарь, конфиг-пример и unit lighthouse-api.service, затем проверяет Redis.

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

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

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

config.json
{
    "redis_url": "redis://127.0.0.1:6379",
    "api_host": "0.0.0.0",
    "api_port": 8010,
    "log_level": "info",
    "debug": false,
    "relay_auth_user": "admin",
    "relay_auth_pass": "change-me",
    "relay_http_timeout": 2,
    "ping_interval": 5,
    "reconcile_interval": 3,
    "apply_timeout": 5,
    "clean_on_startup": true,
    "telemetry_enabled": true,
    "telemetry_url": "https://telemetry.whsoft.ru",
    "relays": [
        {
            "relay_ip": "10.107.191.100",
            "relay_port": 8080,
            "lighthouses": [
                {
                    "id": "mezz-aisle-1",
                    "colors": {"red": 0, "green": 1},
                    "zone": "Мезонин",
                    "label": "Проход 1"
                }
            ]
        }
    ]
}

Все параметры

ПараметрПо умолчаниюОписание
redis_urlredis://127.0.0.1:6379Адрес подключения к Redis
api_host0.0.0.0Адрес прослушивания
api_port8010Порт прослушивания
log_levelinfoУровень журнала: debug, info, warn, error
log_file—Путь к файлу журнала (по умолчанию stdout)
log_max_size_mb100Максимальный размер файла журнала (МБ)
log_max_files5Количество ротируемых файлов
debugfalseРежим отладки
relay_auth_useradminИмя пользователя для Basic Auth к реле
relay_auth_passadminПароль для Basic Auth к реле
relay_http_timeout2Тайм-аут HTTP-запроса к реле (сек.)
ping_interval5Интервал опроса реле (сек.)
reconcile_interval3Интервал синхронизации состояния (сек.)
apply_timeout5Тайм-аут применения команды (сек.)
clean_on_startuptrueВыключить все выходы при старте
telemetry_enabledtrueОтправлять обезличенную телеметрию
telemetry_urlhttps://telemetry.whsoft.ruАдрес сервера телеметрии
relays[]Массив конфигураций реле (см. ниже)

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

Каждый элемент массива relays описывает один релейный модуль и подключённые к нему маяки:

ПараметрОписание
relay_ipIP-адрес релейного модуля
relay_portПорт релейного модуля
lighthousesМассив маяков: id, colors (номера выходов), zone, label

Запуск и systemd

Установщик создаёт unit lighthouse-api.service:

systemd
sudo systemctl status lighthouse-api
sudo systemctl restart lighthouse-api
sudo journalctl -u lighthouse-api -f

Ручной запуск:

Запуск
APP_CONFIG=/etc/lighthouse_api/config.json /opt/lighthouse_api/lighthouse-api

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

ФлагПо умолчаниюОписание
--config/etc/lighthouse_api/config.jsonПуть к файлу конфигурации
--host0.0.0.0Адрес прослушивания
--port8010Порт прослушивания

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

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

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

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

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

Терминал
curl http://127.0.0.1:8010/_ping
# Ответ: {"pong": "pong"}

curl http://127.0.0.1:8010/health
curl http://127.0.0.1:8010/lighthouses
curl http://127.0.0.1:8010/relays
curl http://127.0.0.1:8010/metrics
curl http://127.0.0.1:8010/openapi.yaml

Коды ответа

АдресКодОписание
/_ping200Сервис запущен
/health200Redis доступен, реле сконфигурированы
/health503Redis недоступен или нет сконфигурированных реле

Обновление

Повторно запустите установщик — конфиг и состояние сохраняются:

Обновление
curl -fsSL https://pkg.whsoft.ru/lighthouse_api/install.sh | sudo sh

# или закрепить конкретную версию
curl -fsSL https://pkg.whsoft.ru/lighthouse_api/install.sh | sudo env LIGHTHOUSE_VERSION=3.0 sh

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

Телеметрия

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

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

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

Учётные данные реле. Параметры relay_auth_user и relay_auth_pass по умолчанию установлены в admin/admin. Обязательно измените их в рабочей среде.