Развёртывание и запуск Lighthouse API
Установка Linux-бинаря, настройка реле и маяков, проверка сервиса. Docker не требуется.
Требования
- Linux x86_64 — Ubuntu 22.04+ или любой современный дистрибутив
- Redis 7+ — состояние, подписки и история
- HTTP-реле управления маяками, доступные по сети
- Права root для установки: systemd, каталоги, пользователь
lighthouse
Быстрый старт
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.
Пример файла конфигурации
{
"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_url | redis://127.0.0.1:6379 | Адрес подключения к Redis |
api_host | 0.0.0.0 | Адрес прослушивания |
api_port | 8010 | Порт прослушивания |
log_level | info | Уровень журнала: debug, info, warn, error |
log_file | — | Путь к файлу журнала (по умолчанию stdout) |
log_max_size_mb | 100 | Максимальный размер файла журнала (МБ) |
log_max_files | 5 | Количество ротируемых файлов |
debug | false | Режим отладки |
relay_auth_user | admin | Имя пользователя для Basic Auth к реле |
relay_auth_pass | admin | Пароль для Basic Auth к реле |
relay_http_timeout | 2 | Тайм-аут HTTP-запроса к реле (сек.) |
ping_interval | 5 | Интервал опроса реле (сек.) |
reconcile_interval | 3 | Интервал синхронизации состояния (сек.) |
apply_timeout | 5 | Тайм-аут применения команды (сек.) |
clean_on_startup | true | Выключить все выходы при старте |
telemetry_enabled | true | Отправлять обезличенную телеметрию |
telemetry_url | https://telemetry.whsoft.ru | Адрес сервера телеметрии |
relays | [] | Массив конфигураций реле (см. ниже) |
Настройка реле
Каждый элемент массива relays описывает один релейный модуль и подключённые к нему маяки:
| Параметр | Описание |
|---|---|
relay_ip | IP-адрес релейного модуля |
relay_port | Порт релейного модуля |
lighthouses | Массив маяков: id, colors (номера выходов), zone, label |
Запуск и systemd
Установщик создаёт unit lighthouse-api.service:
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 | Путь к файлу конфигурации |
--host | 0.0.0.0 | Адрес прослушивания |
--port | 8010 | Порт прослушивания |
Переменные окружения
| Переменная | По умолчанию | Описание |
|---|---|---|
APP_CONFIG | /etc/lighthouse_api/config.json | Путь к файлу конфигурации |
REDIS_URL | redis://127.0.0.1:6379 | Адрес подключения к Redis |
API_HOST | 0.0.0.0 | Адрес прослушивания |
API_PORT | 8010 | Порт прослушивания |
DEBUG | false | Режим отладки (true или 1) |
LOG_LEVEL | info | Уровень журнала |
TELEMETRY | 1 | 0 или false — отключить телеметрию |
TELEMETRY_URL | https://telemetry.whsoft.ru | Адрес сервера телеметрии |
TELEMETRY_STATE_FILE | /var/lib/lighthouse_api/telemetry.json | Файл состояния телеметрии (в systemd) |
Приоритет применения настроек (от низшего к высшему):
- Значения по умолчанию в коде
- JSON-файл конфигурации
- Переменные окружения
- Флаги командной строки
Проверка работоспособности
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
Коды ответа
| Адрес | Код | Описание |
|---|---|---|
/_ping | 200 | Сервис запущен |
/health | 200 | Redis доступен, реле сконфигурированы |
/health | 503 | Redis недоступен или нет сконфигурированных реле |
Обновление
Повторно запустите установщик — конфиг и состояние сохраняются:
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
Фоновые процессы
- API Server — REST API и встроенный Web UI.
- Reconciler — сравнивает desired и applied в Redis и отправляет команды на реле.
- Monitor — пингует реле и отслеживает переходы online/offline.
- WebSocket Hub — обновления состояния в реальном времени.
- Telemetry — раз в сутки отправляет обезличенный отчёт.
Телеметрия
Сервис отправляет обезличенную телеметрию, чтобы улучшать продукт: версия, ОС, число реле и маяков, счётчики использования и базовая надёжность. IP-адреса, данные оборудования и содержимое команд не передаются.
- Включена по умолчанию, отключается тумблером «Отправлять обезличенную телеметрию» в разделе «О приложении».
- Или переменной окружения
TELEMETRY=0. - Состояние:
/var/lib/lighthouse_api/telemetry.json.
Подробнее — Политика телеметрии.
Важные замечания
Учётные данные реле. Параметры relay_auth_user и relay_auth_pass по умолчанию установлены в admin/admin. Обязательно измените их в рабочей среде.
- Redis обязателен. Без Redis сервис не запустится.
- Docker не требуется. Релиз поставляется как Linux-бинарь; Docker-образ в поставку не входит.