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

Update docs and drop AI workspace docs

Browse Source
This commit is contained in:
Artem Kokos
2026-05-16 15:50:40 +07:00
parent 0fd64307b7
commit 85c840ba1b
2 changed files with 122 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

198
README.md
View File

@@ -1,84 +1,98 @@
# Ignis Core # Ignis Core
Локальный FastAPI-сервер для управления лампами WiZ. `ignis-core` — локальный FastAPI-сервер для WiZ-ламп и домашней автоматики вокруг них.
## Что есть ## Что есть сейчас
- discovery устройств в локальной сети - discovery ламп по локальной сети с `startup`, `manual` и background refresh;
- группы устройств - управление отдельной лампой и группой;
- команды для device/group - реальные `status`-опросы и `blink` для идентификации;
- one-shot и cron расписания - группы в SQLite;
- guest/admin/master API-ключи - one-shot и cron-расписания;
- event log и базовая статистика - persisted metadata расписаний поверх APScheduler;
- встроенный UI в `static/index.html` - роли `master`, `admin`, `guest`;
- встроенный UI без внешних CDN - гостевые API-ключи с revoke/activate;
- event log и простая stats summary;
- встроенный локальный UI из `static/`;
- OpenAPI-экспорт в `openapi.json`.
## Запуск ## Архитектура
- `main.py` — инициализация FastAPI, security headers, router wiring, startup lifecycle.
- `app/api/routes/*` — HTTP-маршруты.
- `app/core/discovery.py` — выбор подсетей и UDP discovery WiZ.
- `app/core/state.py` — in-memory runtime-state устройств и групп.
- `app/core/scheduler.py` — APScheduler, reconciliation и cleanup old events.
- `app/models/*` — SQLAlchemy-модели и Pydantic-схемы.
- `static/` — встроенный web UI без внешних CDN.
## Запуск локально
```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 .env.example .env cp deploy/ignis-core.env.example .env
uvicorn main:app --host 0.0.0.0 --port 8000 uvicorn main:app --host 0.0.0.0 --port 8000
``` ```
UI: `http://<host>:8000/` UI: `http://<host>:8000/`
Готовые deployment-файлы для `systemd`: [deploy/README.md](/home/kokos/workspace/ignis/ignis-core/deploy/README.md:1) Готовые файлы для `systemd`: `deploy/README.md`
## Конфигурация ## Конфигурация
Минимум: Минимальный набор:
```env ```env
IGNIS_API_KEY=change-me IGNIS_API_KEY=change-me
APP_TIMEZONE=Asia/Novosibirsk APP_TIMEZONE=Asia/Novosibirsk
SCAN_NETWORK=
DISCOVERY_INTERVAL_SECONDS=600
DISCOVERY_BACKGROUND_MISSING_THRESHOLD=2
LOG_LEVEL=INFO LOG_LEVEL=INFO
EVENT_LOG_RETENTION_DAYS=30
```
БД:
```env
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
``` ```
Замечание по discovery: Параметры discovery:
- если `SCAN_NETWORK` не задан, сервер сам выбирает private IPv4-подсети обычных интерфейсов и старается не сканировать VPN / docker / tunnel-интерфейсы ```env
- если на хосте есть VPN или несколько интерфейсов, всё равно лучше явно задать `SCAN_NETWORK` SCAN_NETWORK=192.168.0.0/24
- формат: `192.168.0.0/24` или список через запятую DISCOVERY_INTERVAL_SECONDS=600
- startup scan выполняется до старта фонового цикла DISCOVERY_BACKGROUND_MISSING_THRESHOLD=2
- background refresh по умолчанию удаляет устройство только после двух подряд промахов discovery DISCOVERY_ENV_MIN_PREFIX_LEN=16
- manual `POST /devices/rescan` удаляет оффлайн-устройства сразу и возвращает summary (`found`, `added`, `updated`, `removed_offline`, `pending_removal`, `online`) DISCOVERY_AUTO_MIN_PREFIX_LEN=24
```
## Авторизация Параметры retention:
```env
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` Заголовок: `X-API-Key`
Роли: - `master` — значение `IGNIS_API_KEY`, полный доступ.
- `admin` — ключ из БД, доступ к группам, расписаниям, stats и `rescan`.
- `guest` — чтение и обычное управление светом.
- `master`: значение из `IGNIS_API_KEY`, полный доступ Сервер работает в `fail-closed`: если `IGNIS_API_KEY` не задан, защищённые маршруты отвечают `503`.
- `admin`: ключ из БД, доступ к группам, расписаниям, stats и rescan
- `guest`: обычное управление и чтение
Сервер работает в `fail-closed`: если `IGNIS_API_KEY` не задан, защищённые маршруты недоступны. ## HTTP API
Встроенный UI:
- использует только локальные статические ассеты
- по умолчанию не сохраняет API-ключ между перезагрузками
- может запомнить ключ только в рамках текущей вкладки браузера
## API
Основные маршруты: Основные маршруты:
- `GET /auth/me`
- `GET /devices` - `GET /devices`
- `GET /devices/groups` - `GET /devices/groups`
- `GET /devices/scenes` - `GET /devices/scenes`
@@ -100,11 +114,10 @@ IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db
- `POST /api-keys/activate` - `POST /api-keys/activate`
- `GET /stats/summary` - `GET /stats/summary`
- `GET /stats/log` - `GET /stats/log`
- `GET /auth/me`
`control` и `schedules` принимают JSON body. `control/*` и `schedules/*` принимают JSON body.
Поддерживаемые параметры команд: Поддерживаемые параметры команды:
- `state` - `state`
- `brightness` - `brightness`
@@ -112,50 +125,48 @@ IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db
- `temp` - `temp`
- `r`, `g`, `b` - `r`, `g`, `b`
Примеры:
```bash
curl -X POST 'http://localhost:8000/control/device/dev-1' \
-H 'X-API-Key: change-me' \
-H 'Content-Type: application/json' \
-d '{"temp": 4200}'
```
```bash
curl -X POST 'http://localhost:8000/schedules/once' \
-H 'X-API-Key: change-me' \
-H 'Content-Type: application/json' \
-d '{"target_id":"bedroom","hours_from_now":2,"is_group":true,"temp":3200}'
```
Валидация: Валидация:
- `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` - для `schedules/once` нужно передать ровно одно из `run_at` или `hours_from_now`
## API keys Пример:
- список ключей возвращает публичный `key` / `key_id` ```bash
- полный секрет возвращается только при создании curl -X POST http://127.0.0.1:8000/control/group/bedroom \
- маршруты `/api-keys/*` доступны только `master` -H 'X-API-Key: change-me' \
-H 'Content-Type: application/json' \
-d '{"state":true,"brightness":60}'
```
## Встроенный UI
- лежит в `static/index.html`, `static/app.js`, `static/ui.css`;
- использует только локальные ассеты;
- не использует `localStorage`;
- может хранить API-ключ только в `sessionStorage` текущей вкладки;
- умеет базовое управление группами, расписания, API-ключи, stats/log и быстрый таймер на 4 часа.
## Хранилище ## Хранилище
Основные таблицы: SQLite-таблицы:
- `groups` - `groups`
- `api_keys` - `api_keys`
- `event_log` - `event_log`
- `schedules` - `schedules`
- `apscheduler_jobs` - `apscheduler_jobs`
- `devices`
Важно: реальным runtime-источником истины для онлайн-устройств остаётся in-memory `state_manager.devices`. Таблица `devices` пока не используется как полноценный persistent source of truth.
## OpenAPI ## OpenAPI
Актуальная схема лежит в `openapi.json`. Актуальная схема хранится в `openapi.json`.
Перегенерация: Перегенерация:
@@ -165,34 +176,33 @@ curl -X POST 'http://localhost:8000/schedules/once' \
## Тесты ## Тесты
Проверка синтаксиса: На 2026-05-16 в `tests/` лежит 27 `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;
- security headers и локальные UI-ассеты;
- stats summary без двойного счёта `*_requested`.
Команды:
```bash ```bash
.venv/bin/python -m compileall app tests main.py .venv/bin/python -m compileall app tests main.py
```
Полный прогон:
```bash
timeout 120s .venv/bin/python -m unittest discover -s tests -v timeout 120s .venv/bin/python -m unittest discover -s tests -v
``` ```
Сейчас есть 27 тестов. Покрыты: ## Известные ограничения
- auth и роли - discovery по-прежнему основан на переборе IP в подсетях;
- lifecycle API-ключей - миграций схемы БД нет, используется `Base.metadata.create_all()`;
- control/status ошибки и partial success - runtime-state устройств живёт в памяти процесса;
- валидация scene - встроенный UI остаётся монолитным файлом без отдельной frontend-сборки;
- one-shot и cron расписания - stats — это audit/summary, а не полноценная аналитика.
- миграция legacy jobs
- auto-subnet selection для discovery
- background offline cleanup threshold
- manual rescan summary и immediate cleanup
- security headers и локальные UI-ассеты
- агрегация stats без двойного счёта `*_requested`
## Ограничения
- discovery всё ещё основан на переборе IP по подсетям
- UI остаётся монолитным файлом
- stats пока простые и не заменяют нормальную аналитику

37
deploy/README.md
View File

@@ -1,30 +1,28 @@
# Deploy # Deploy
Практичный минимум для запуска `ignis-core` как `systemd`-сервиса. Минимальный `systemd`-деплой для `ignis-core`.
В папке: В каталоге:
- `ignis-core.service` -- шаблон unit-файла - `ignis-core.service` — unit-файл;
- `ignis-core.env.example` -- пример переменных окружения - `ignis-core.env.example` — пример env-конфига.
## Предположения ## Предполагаемая раскладка
Ниже используется такая раскладка: - код: `/opt/ignis/ignis-core`
- env: `/etc/ignis-core/ignis-core.env`
- пользователь: `ignis`
- SQLite: `/var/lib/ignis-core/ignis.db`
- код проекта: `/opt/ignis/ignis-core` Если у вас другие пути, поправьте unit и env-файл.
- env-файл: `/etc/ignis-core/ignis-core.env`
- Unix-пользователь: `ignis`
- SQLite БД: `/var/lib/ignis-core/ignis.db`
Если у вас другие пути, просто поправьте 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
@@ -45,12 +43,12 @@ 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`
- `SCAN_NETWORK` - `SCAN_NETWORK`
Для домашней сети лучше задавать `SCAN_NETWORK` явно, особенно если на хосте есть VPN или несколько интерфейсов. Для машин с VPN или несколькими интерфейсами `SCAN_NETWORK` лучше задавать явно.
## 4. Установить unit ## 4. Установить unit
@@ -60,7 +58,7 @@ sudo systemctl daemon-reload
sudo systemctl enable --now ignis-core.service sudo systemctl enable --now ignis-core.service
``` ```
## 5. Проверка ## 5. Проверить запуск
```bash ```bash
sudo systemctl status ignis-core.service sudo systemctl status ignis-core.service
@@ -79,6 +77,7 @@ sudo systemctl restart ignis-core.service
## Замечания ## Замечания
- `StateDirectory=ignis-core` в unit создаёт `/var/lib/ignis-core` автоматически. - `StateDirectory=ignis-core` в unit создаёт `/var/lib/ignis-core`.
- По умолчанию сервис слушает `0.0.0.0:8000`. - По умолчанию сервис слушает `0.0.0.0:8000`.
- Если нужен reverse proxy, его проще ставить перед `ignis-core`, а сам сервис оставить на локальном порту. - Reverse proxy проще ставить перед сервисом, а не внутрь него.
- Перед обновлением backend-контракта полезно перегенерировать `openapi.json` и прогнать `unittest`.