artem.kokos/ignis-core
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Refresh project documentation

Browse Source
This commit is contained in:
Artem Kokos
2026-05-21 22:19:29 +07:00
parent 928e4c71b7
commit e4e7d9029f
3 changed files with 185 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files

238
README.md
View File

@@ -1,112 +1,95 @@
# Ignis Core # Ignis Core
`ignis-core` — локальный FastAPI-сервер для WiZ-ламп и домашней автоматики вокруг них. Локальный FastAPI-сервер для WiZ-ламп: discovery, управление, группы, расписания, API-ключи, аудит и встроенная веб-морда.
## Что есть сейчас ## Что умеет
- discovery ламп по локальной сети с `startup`, `manual` и background refresh; - искать лампы в локальной сети при старте, вручную и в фоне;
- управление отдельной лампой и группой; - управлять лампой или группой;
- реальные `status`-опросы и `blink` для идентификации; - мигать лампой (`blink`) и читать живой статус;
- группы в SQLite; - хранить группы, ключи, события и расписания в SQLite;
- one-shot и cron-расписания; - выполнять `one-shot` и `cron`-задачи через APScheduler;
- persisted metadata расписаний поверх APScheduler; - разделять доступ на `master`, `admin`, `guest`;
- роли `master`, `admin`, `guest`; - отдавать встроенный web UI из `static/`;
- гостевые API-ключи с revoke/activate; - публиковать OpenAPI.
- event log и простая stats summary;
- встроенный локальный UI из `static/`;
- OpenAPI-экспорт в `openapi.json`.
## Архитектура ## Структура
- `main.py` — инициализация FastAPI, security headers, router wiring, startup lifecycle. - `main.py` — FastAPI, middleware, lifecycle, статика.
- `app/api/routes/*` — HTTP-маршруты. - `app/api/routes/` — HTTP API.
- `app/core/discovery.py` — выбор подсетей и UDP discovery WiZ. - `app/core/discovery.py` — discovery и выбор подсетей.
- `app/core/state.py` — in-memory runtime-state устройств и групп. - `app/core/scheduler.py` — расписания и reconciliation.
- `app/core/scheduler.py` — APScheduler, reconciliation и cleanup old events. - `app/core/state.py` — runtime-state устройств и групп.
- `app/models/*` — SQLAlchemy-модели и Pydantic-схемы. - `app/models/` — SQLAlchemy и схемы данных.
- `static/` — встроенный web UI без внешних CDN. - `static/` — встроенный UI.
- `deploy/` — `systemd`-деплой и пример env.
## Запуск локально ## Быстрый старт
```bash ```bash
python3 -m venv .venv python3 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
pip install -r requirements.txt pip install -r requirements.txt
cp deploy/ignis-core.env.example .env cp deploy/ignis-core.env.example .env
uvicorn main:app --host 0.0.0.0 --port 8000 .venv/bin/python -m uvicorn main:app --host 0.0.0.0 --port 8000
``` ```
UI: `http://<host>:8000/` - UI: `http://127.0.0.1:8000/`
- OpenAPI runtime: `http://127.0.0.1:8000/openapi.json`
- Коммитнутый экспорт: [openapi.json](openapi.json)
Готовые файлы для `systemd`: `deploy/README.md` `python-dotenv` подхватывает `.env` автоматически.
## Конфигурация ## Конфиг
Минимальный набор: Минимум:
```env ```env
IGNIS_API_KEY=change-me IGNIS_API_KEY=change-me
IGNIS_INSTANCE_NAME=Home IGNIS_INSTANCE_NAME=Home
APP_TIMEZONE=Asia/Novosibirsk APP_TIMEZONE=Asia/Novosibirsk
LOG_LEVEL=INFO SCAN_NETWORK=192.168.0.0/24
IGNIS_DATABASE_URL=sqlite+aiosqlite:///./ignis.db IGNIS_DATABASE_URL=sqlite+aiosqlite:///./ignis.db
IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db
``` ```
Параметры server metadata / versioning: Основные переменные:
```env - `IGNIS_API_KEY` — мастер-ключ. Без него сервер работает в `fail-closed` и защищённые маршруты отвечают `503`.
IGNIS_PUBLIC_BASE_URL=https://ignis.example.local - `IGNIS_INSTANCE_NAME` — имя инстанса в UI и `GET /system/info`.
IGNIS_BUILD_VERSION=1.0.0 - `APP_TIMEZONE` — таймзона расписаний.
IGNIS_BUILD_DATE=2026-05-21T12:00:00Z - `SCAN_NETWORK` — подсеть или список подсетей для discovery. На хостах с VPN или несколькими NIC лучше задавать явно.
IGNIS_GIT_SHA=abc1234def56 - `DISCOVERY_INTERVAL_SECONDS` — период фонового refresh.
``` - `DISCOVERY_BACKGROUND_MISSING_THRESHOLD` — сколько циклов подряд лампа может не отвечать до удаления.
- `DISCOVERY_ENV_MIN_PREFIX_LEN` — минимально допустимая маска для `SCAN_NETWORK`.
- `DISCOVERY_AUTO_MIN_PREFIX_LEN` — минимально допустимая маска для auto-discovery.
- `EVENT_LOG_RETENTION_DAYS` — срок хранения event log.
- `IGNIS_PUBLIC_BASE_URL` — внешний URL, если сервер стоит за reverse proxy.
- `IGNIS_BUILD_VERSION`, `IGNIS_BUILD_DATE`, `IGNIS_GIT_SHA` — build metadata для диагностики.
- `IGNIS_INSTANCE_NAME` — человекочитаемое имя инстанса, которое видно в UI и `GET /system/info`. Полный пример: [deploy/ignis-core.env.example](deploy/ignis-core.env.example)
- `IGNIS_PUBLIC_BASE_URL` — внешний URL сервера, если он стоит за reverse proxy или доступен по доменному имени.
- `IGNIS_BUILD_VERSION`, `IGNIS_BUILD_DATE`, `IGNIS_GIT_SHA` — build metadata установленного сервера для диагностики и сверки версий.
Параметры discovery: ## Discovery
```env - при старте выполняется `startup_refresh()`;
SCAN_NETWORK=192.168.0.0/24 - `POST /devices/rescan` делает ручной refresh и сразу убирает оффлайн-устройства;
DISCOVERY_INTERVAL_SECONDS=600 - фоновый refresh удаляет устройство только после `DISCOVERY_BACKGROUND_MISSING_THRESHOLD` подряд промахов;
DISCOVERY_BACKGROUND_MISSING_THRESHOLD=2 - если `SCAN_NETWORK` пуст, сервер сам выбирает private IPv4 подсети и старается не лезть в `docker`, `tun`, `wg`, `tailscale` и похожие интерфейсы.
DISCOVERY_ENV_MIN_PREFIX_LEN=16
DISCOVERY_AUTO_MIN_PREFIX_LEN=24
```
Параметры retention: ## Роли
```env Заголовок авторизации: `X-API-Key`
EVENT_LOG_RETENTION_DAYS=30
```
## Как работает discovery
- Если `SCAN_NETWORK` задан, сервер сканирует только указанные подсети.
- Если `SCAN_NETWORK` пуст, `DiscoveryService` пытается выбрать private IPv4-сегменты обычных интерфейсов и избегает `docker`, `tun`, `wg`, `tailscale` и похожих интерфейсов.
- При старте выполняется `startup_refresh()`.
- `POST /devices/rescan` делает ручной refresh и сразу удаляет оффлайн-устройства.
- Background refresh работает циклически и удаляет устройство только после `DISCOVERY_BACKGROUND_MISSING_THRESHOLD` подряд пропусков.
Для хостов с VPN, несколькими NIC или нетипичной маршрутизацией `SCAN_NETWORK` лучше задавать явно.
## Авторизация и роли
Заголовок: `X-API-Key`
- `master` — значение `IGNIS_API_KEY`, полный доступ. - `master` — значение `IGNIS_API_KEY`, полный доступ.
- `admin` — ключ из БД, доступ к группам, расписаниям, stats и `rescan`. - `admin` — ключ из БД с `is_admin=true`, доступ к группам, рескану, расписаниям, stats и расширенному `system/info`.
- `guest` — чтение и обычное управление светом. - `guest` — управление светом и чтение безопасной части API.
Сервер работает в `fail-closed`: если `IGNIS_API_KEY` не задан, защищённые маршруты отвечают `503`. `GET /auth/me` возвращает текущую роль и имя ключа.
## HTTP API ## HTTP API
Основные маршруты: Основные группы маршрутов:
- `GET /auth/me`
- `GET /devices` - `GET /devices`
- `GET /devices/groups` - `GET /devices/groups`
- `GET /devices/scenes` - `GET /devices/scenes`
@@ -130,42 +113,83 @@ EVENT_LOG_RETENTION_DAYS=30
- `GET /stats/log` - `GET /stats/log`
- `GET /system/info` - `GET /system/info`
`control/*` и `schedules/*` принимают JSON body. Ролевые ограничения:
Поддерживаемые параметры команды: - `guest`: чтение устройств/групп/сцен, управление светом, `status`, `blink`, безопасный `system/info`.
- `admin`: всё выше плюс создание/удаление групп, `rescan`, расписания, stats/log, расширенный `system/info`.
- `master`: всё выше плюс управление API-ключами.
- `state` Формат основных тел:
- `brightness`
- `scene` ```json
- `temp` {"state": true}
- `r`, `g`, `b` ```
```json
{"brightness": 60}
```
```json
{"temp": 3200}
```
```json
{"r": 255, "g": 180, "b": 120}
```
```json
{"scene": "Cozy"}
```
Валидация: Валидация:
- `brightness`: `10..100` - `brightness`: `10..100`
- `temp`: `2200..6500` - `temp`: `2200..6500`
- `r/g/b`: `0..255` - `r/g/b`: `0..255`
- `scene`, `temp` и `rgb` взаимоисключаемы - можно передать только один режим из `scene`, `temp` или `rgb`
- `r`, `g`, `b` нужно передавать полной тройкой - `r/g/b` нужно передавать полной тройкой
- для `schedules/once` нужно передать ровно одно из `run_at` или `hours_from_now` - для `POST /schedules/once` нужно передать ровно одно из `run_at` или `hours_from_now`
Пример: Примеры:
```bash ```bash
curl -X POST http://127.0.0.1:8000/control/group/bedroom \ curl -sS http://127.0.0.1:8000/control/group/bedroom \
-H 'X-API-Key: change-me' \ -H 'X-API-Key: change-me' \
-H 'Content-Type: application/json' \ -H 'Content-Type: application/json' \
-d '{"state":true,"brightness":60}' -d '{"state":true,"brightness":60}'
``` ```
```bash
curl -sS http://127.0.0.1:8000/api-keys \
-H 'X-API-Key: change-me'
```
Замечания по ключам:
- `GET /api-keys` возвращает публичные `key_id`, а не полный секрет;
- `POST /api-keys` показывает полный секрет только один раз;
- `POST /api-keys/revoke` и `POST /api-keys/activate` принимают JSON вида `{"key":"<secret-or-public-id>"}`.
## Встроенный UI ## Встроенный UI
- лежит в `static/index.html`, `static/app.js`, `static/ui.css`; UI лежит в `static/` и не требует отдельной сборки.
Что есть сейчас:
- вход по API-ключу;
- роль-зависимые вкладки;
- пульт групп со сценами, яркостью, температурой, цветом и таймером на 4 часа;
- список устройств и сборка групп;
- one-shot и cron;
- серверная вкладка с метаданными инстанса;
- аудит, stats и API-ключи для нужных ролей.
Свойства UI:
- использует только локальные ассеты; - использует только локальные ассеты;
- не использует `localStorage`; - не использует `localStorage`;
- может хранить API-ключ только в `sessionStorage` текущей вкладки; - может хранить ключ только в `sessionStorage` текущей вкладки;
- показывает build/server metadata текущего инстанса; - гость не видит чувствительные поля `system/info`.
- умеет базовое управление группами, расписания, API-ключи, stats/log и быстрый таймер на 4 часа.
## Хранилище ## Хранилище
@@ -178,11 +202,15 @@ SQLite-таблицы:
- `apscheduler_jobs` - `apscheduler_jobs`
- `devices` - `devices`
Важно: реальным runtime-источником истины для онлайн-устройств остаётся in-memory `state_manager.devices`. Таблица `devices` пока не используется как полноценный persistent source of truth. Важно:
- онлайн-устройства и статусы живут в runtime-памяти процесса;
- таблица `devices` пока не является полноценным source of truth;
- миграций схемы нет, используется `Base.metadata.create_all()`.
## OpenAPI ## OpenAPI
Актуальная схема хранится в `openapi.json`. Актуальная схема закоммичена в `openapi.json`.
Перегенерация: Перегенерация:
@@ -192,34 +220,22 @@ SQLite-таблицы:
## Тесты ## Тесты
На 2026-05-21 в `tests/` лежит 29 `unittest`-сценариев. Основная команда:
Покрыто:
- fail-closed auth и role checks;
- lifecycle API-ключей;
- control/status error handling и partial success;
- validation для scene, control body и schedules body;
- one-shot и cron-расписания;
- reconciliation и миграция legacy jobs;
- auto subnet selection для discovery;
- background offline cleanup threshold;
- manual rescan summary;
- server metadata endpoint и отсутствие утечки секретов в нём;
- security headers и локальные UI-ассеты;
- stats summary без двойного счёта `*_requested`.
Команды:
```bash ```bash
.venv/bin/python -m compileall app tests main.py
timeout 120s .venv/bin/python -m unittest discover -s tests -v timeout 120s .venv/bin/python -m unittest discover -s tests -v
``` ```
## Известные ограничения Дополнительно:
- discovery по-прежнему основан на переборе IP в подсетях; ```bash
- миграций схемы БД нет, используется `Base.metadata.create_all()`; .venv/bin/python -m compileall app tests main.py
node --check static/app.js
```
## Ограничения
- discovery всё ещё сетевой перебор внутри выбранных подсетей;
- runtime-state устройств живёт в памяти процесса; - runtime-state устройств живёт в памяти процесса;
- встроенный UI остаётся монолитным файлом без отдельной frontend-сборки; - UI монолитный, без отдельного frontend-build step;
- stats — это audit/summary, а не полноценная аналитика. - stats — это аудит и summary, а не полноценная аналитика.

66
deploy/README.md
View File

@@ -2,27 +2,29 @@
Минимальный `systemd`-деплой для `ignis-core`. Минимальный `systemd`-деплой для `ignis-core`.
В каталоге: Файлы:
- `ignis-core.service` — unit-файл; - `ignis-core.service` — unit-файл
- `ignis-core.env.example` — пример env-конфига. - `ignis-core.env.example` — пример env-конфига
## Предполагаемая раскладка ## Ожидаемая раскладка
- код: `/opt/ignis/ignis-core` - код: `/opt/ignis/ignis-core`
- env: `/etc/ignis-core/ignis-core.env` - env: `/etc/ignis-core/ignis-core.env`
- пользователь: `ignis` - пользователь: `ignis`
- SQLite: `/var/lib/ignis-core/ignis.db` - база: `/var/lib/ignis-core/ignis.db`
Если у вас другие пути, поправьте unit и env-файл. Если пути другие, поправьте unit и env.
## 1. Создать системного пользователя ## Установка
### 1. Пользователь
```bash ```bash
sudo useradd --system --home /opt/ignis --shell /usr/sbin/nologin ignis sudo useradd --system --home /opt/ignis --shell /usr/sbin/nologin ignis
``` ```
## 2. Разложить проект и зависимости ### 2. Код и зависимости
```bash ```bash
sudo mkdir -p /opt/ignis sudo mkdir -p /opt/ignis
@@ -34,7 +36,7 @@ pip install -r requirements.txt
sudo chown -R ignis:ignis /opt/ignis sudo chown -R ignis:ignis /opt/ignis
``` ```
## 3. Подготовить env-файл ### 3. Env-файл
```bash ```bash
sudo mkdir -p /etc/ignis-core sudo mkdir -p /etc/ignis-core
@@ -43,14 +45,13 @@ sudo chmod 640 /etc/ignis-core/ignis-core.env
sudo chown root:ignis /etc/ignis-core/ignis-core.env sudo chown root:ignis /etc/ignis-core/ignis-core.env
``` ```
Минимум, который надо заполнить руками: Минимум, который надо заполнить:
- `IGNIS_API_KEY` - `IGNIS_API_KEY`
- `IGNIS_INSTANCE_NAME`
- `SCAN_NETWORK` - `SCAN_NETWORK`
Для машин с VPN или несколькими интерфейсами `SCAN_NETWORK` лучше задавать явно. ### 4. Unit
## 4. Установить unit
```bash ```bash
sudo cp deploy/ignis-core.service /etc/systemd/system/ignis-core.service sudo cp deploy/ignis-core.service /etc/systemd/system/ignis-core.service
@@ -58,14 +59,17 @@ sudo systemctl daemon-reload
sudo systemctl enable --now ignis-core.service sudo systemctl enable --now ignis-core.service
``` ```
## 5. Проверить запуск ## Проверка
```bash ```bash
sudo systemctl status ignis-core.service sudo systemctl status ignis-core.service
sudo journalctl -u ignis-core.service -n 100 --no-pager sudo journalctl -u ignis-core.service -n 100 --no-pager
curl -H 'X-API-Key: <master-key>' http://127.0.0.1:8000/auth/me curl -sS http://127.0.0.1:8000/auth/me -H 'X-API-Key: <master-key>'
curl -sS http://127.0.0.1:8000/system/info -H 'X-API-Key: <master-key>'
``` ```
Если сервис стоит за reverse proxy, имеет смысл задать `IGNIS_PUBLIC_BASE_URL`.
## Обновление ## Обновление
```bash ```bash
@@ -75,9 +79,31 @@ pip install -r requirements.txt
sudo systemctl restart ignis-core.service sudo systemctl restart ignis-core.service
``` ```
## Замечания Если менялся env:
- `StateDirectory=ignis-core` в unit создаёт `/var/lib/ignis-core`. ```bash
- По умолчанию сервис слушает `0.0.0.0:8000`. sudo systemctl restart ignis-core.service
- Reverse proxy проще ставить перед сервисом, а не внутрь него. ```
- Перед обновлением backend-контракта полезно перегенерировать `openapi.json` и прогнать `unittest`.
Если менялся unit:
```bash
sudo systemctl daemon-reload
sudo systemctl restart ignis-core.service
```
## Что делает unit
Текущий [ignis-core.service](ignis-core.service):
- запускает `python -m uvicorn main:app --host 0.0.0.0 --port 8000`
- читает `/etc/ignis-core/ignis-core.env`
- рестартует сервис при падении
- пишет состояние в `/var/lib/ignis-core`
- даёт записи в `/opt/ignis/ignis-core` и `/var/lib/ignis-core`
## Практические замечания
- для хостов с VPN, Docker или несколькими интерфейсами лучше всегда задавать `SCAN_NETWORK` явно;
- перед релизом полезно перегенерировать `openapi.json` и прогнать `unittest`;
- reverse proxy лучше ставить перед сервисом, а не встраивать в него.

13
deploy/ignis-core.env.example
View File

@@ -1,14 +1,25 @@
# Auth and instance
IGNIS_API_KEY=change-me IGNIS_API_KEY=change-me
IGNIS_INSTANCE_NAME=Home IGNIS_INSTANCE_NAME=Home
APP_TIMEZONE=Asia/Novosibirsk
# Optional external URL and build metadata
IGNIS_PUBLIC_BASE_URL= IGNIS_PUBLIC_BASE_URL=
IGNIS_BUILD_VERSION=1.0.0 IGNIS_BUILD_VERSION=1.0.0
IGNIS_BUILD_DATE= IGNIS_BUILD_DATE=
IGNIS_GIT_SHA= IGNIS_GIT_SHA=
APP_TIMEZONE=Asia/Novosibirsk
# Discovery
SCAN_NETWORK=192.168.0.0/24 SCAN_NETWORK=192.168.0.0/24
DISCOVERY_INTERVAL_SECONDS=600 DISCOVERY_INTERVAL_SECONDS=600
DISCOVERY_BACKGROUND_MISSING_THRESHOLD=2 DISCOVERY_BACKGROUND_MISSING_THRESHOLD=2
DISCOVERY_ENV_MIN_PREFIX_LEN=16
DISCOVERY_AUTO_MIN_PREFIX_LEN=24
# Logging and retention
LOG_LEVEL=INFO LOG_LEVEL=INFO
EVENT_LOG_RETENTION_DAYS=30 EVENT_LOG_RETENTION_DAYS=30
# SQLite
IGNIS_DATABASE_URL=sqlite+aiosqlite:////var/lib/ignis-core/ignis.db IGNIS_DATABASE_URL=sqlite+aiosqlite:////var/lib/ignis-core/ignis.db
IGNIS_SYNC_DATABASE_URL=sqlite:////var/lib/ignis-core/ignis.db IGNIS_SYNC_DATABASE_URL=sqlite:////var/lib/ignis-core/ignis.db