Развёртывание и запуск RID API
Установка Linux-бинаря, настройка LED-дисплеев и проверка сервиса. Docker не требуется.
Требования
- Linux x86_64 — Ubuntu 22.04+ или любой современный дистрибутив
- Redis 7+ — состояние, подписки и история
- LED-дисплеи, доступные по TCP (Modbus, порт 502)
- Права root для установки: systemd, каталоги, пользователь
rid
Быстрый старт
curl -fsSL https://pkg.whsoft.ru/rid_api/install.sh | sudo sh # указать Redis и дисплеи sudo nano /etc/rid_api/config.json sudo systemctl restart rid-api curl http://127.0.0.1:8000/_ping
Установщик поддерживает RID_VERSION=3.0 (закрепить версию) и RID_NO_START=1 (не запускать сервис).
Что делает install.sh. Проверяет SHA256 (и minisign, если установлен), создаёт пользователя rid и каталоги /opt/rid_api, /etc/rid_api, /var/lib/rid_api, ставит бинарь, конфиг-пример и unit rid-api.service, затем проверяет Redis.
Конфигурация
Настройки задаются через JSON-файл. По умолчанию сервис ищет файл по пути /etc/rid_api/config.json. Путь можно переопределить переменной APP_CONFIG или флагом -config.
Пример файла конфигурации
{
"redis_url": "redis://127.0.0.1:6379",
"displays": [
{
"display_ip": "192.168.0.195",
"display_port": 502
}
],
"clean_displays_on_startup": false,
"debug": false,
"log_level": "info",
"api_host": "0.0.0.0",
"api_port": 8000,
"telemetry_enabled": true,
"telemetry_url": "https://telemetry.whsoft.ru"
} Все параметры
| Параметр | По умолчанию | Описание |
|---|---|---|
redis_url | redis://127.0.0.1:6379 | Адрес подключения к Redis |
displays | [] | Список дисплеев: display_ip, display_port |
clean_displays_on_startup | false | Очищать дисплеи при старте |
debug | false | Режим отладки |
log_level | info | Уровень журнала: debug, info, warn, error |
log_file | — | Путь к файлу журнала (по умолчанию stdout) |
log_max_size_mb | 100 | Максимальный размер файла журнала (МБ) |
log_max_files | 5 | Количество ротируемых файлов |
api_host | 0.0.0.0 | Адрес прослушивания |
api_port | 8000 | Порт прослушивания |
displays_ping_interval | 2 | Интервал опроса дисплеев (сек.) |
displays_ping_timeout | 1 | Тайм-аут опроса (сек.) |
displays_ping_threshold | 0.3 | Порог медленного ответа (сек.) |
reconcile_interval | 5 | Интервал синхронизации состояния (сек.) |
apply_timeout | 10 | Тайм-аут применения команды (сек.) |
telemetry_enabled | true | Отправлять обезличенную телеметрию |
telemetry_url | https://telemetry.whsoft.ru | Адрес сервера телеметрии |
Запуск и systemd
Установщик создаёт unit rid-api.service:
sudo systemctl status rid-api sudo systemctl restart rid-api sudo journalctl -u rid-api -f
Ручной запуск:
APP_CONFIG=/etc/rid_api/config.json /opt/rid_api/rid-api Флаги командной строки
| Флаг | По умолчанию | Описание |
|---|---|---|
-config | /etc/rid_api/config.json | Путь к файлу конфигурации (или URL) |
-host | 0.0.0.0 | Адрес прослушивания |
-port | 8000 | Порт прослушивания |
Переменные окружения
| Переменная | По умолчанию | Описание |
|---|---|---|
APP_CONFIG | /etc/rid_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/rid_api/telemetry.json | Файл состояния телеметрии (в systemd) |
Приоритет применения настроек (от низшего к высшему):
- Значения по умолчанию в коде
- JSON-файл конфигурации
- Переменные окружения
- Флаги командной строки
Проверка работоспособности
curl http://127.0.0.1:8000/_ping # Ответ: {"pong": "pong"} curl http://127.0.0.1:8000/health curl http://127.0.0.1:8000/dashboard curl http://127.0.0.1:8000/displays curl http://127.0.0.1:8000/metrics
Коды ответа
| Адрес | Код | Описание |
|---|---|---|
/_ping | 200 | Сервис запущен |
/health | 200 | Redis доступен, дисплеи сконфигурированы |
/health | 503 | Redis недоступен или нет сконфигурированных дисплеев |
Обновление
Повторно запустите установщик — конфиг и состояние сохраняются:
curl -fsSL https://pkg.whsoft.ru/rid_api/install.sh | sudo sh # или закрепить конкретную версию curl -fsSL https://pkg.whsoft.ru/rid_api/install.sh | sudo env RID_VERSION=3.0 sh
Фоновые процессы
- API Server — REST API и встроенный Web UI.
- Reconciler — применяет desired state к дисплеям.
- Monitor — опрашивает дисплеи и отслеживает online/offline.
- WebSocket Hub — обновления состояния в реальном времени.
- Telemetry — раз в сутки отправляет обезличенный отчёт.
Телеметрия
Сервис отправляет обезличенную телеметрию, чтобы улучшать продукт: версия, ОС, число дисплеев, счётчики использования и базовая надёжность. IP-адреса, данные оборудования и содержимое экранов не передаются.
- Включена по умолчанию, отключается тумблером «Отправлять обезличенную телеметрию» в разделе «О приложении».
- Или переменной окружения
TELEMETRY=0. - Состояние:
/var/lib/rid_api/telemetry.json.
Подробнее — Политика телеметрии.
Важные замечания
Только один экземпляр сервиса. Каждый дисплей поддерживает только одно Modbus-подключение. Запуск нескольких экземпляров RID, работающих с одними и теми же дисплеями, приведёт к ошибкам соединения.
- Redis обязателен. Без Redis сервис не запустится — в нём хранится всё состояние дисплеев.
- Порт 502. Дисплеи общаются по стандартному порту Modbus TCP. Убедитесь, что сетевой экран не блокирует этот порт.
- Очистка при старте.
clean_displays_on_startupсбрасывает дисплеи в выключенное состояние. - Журналирование. По умолчанию журнал выводится в stdout. Для записи в файл укажите
log_file. - Docker не требуется. Релиз поставляется как Linux-бинарь; Docker-образ в поставку не входит.