From 85c840ba1bf27224aff6d84e31e1eb56efc0a143 Mon Sep 17 00:00:00 2001 From: Artem Kokos Date: Sat, 16 May 2026 15:50:40 +0700 Subject: [PATCH] Update docs and drop AI workspace docs --- README.md | 198 +++++++++++++++++++++++++---------------------- deploy/README.md | 37 +++++---- 2 files changed, 122 insertions(+), 113 deletions(-) diff --git a/README.md b/README.md index 2871add..09fa357 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,98 @@ # Ignis Core -Локальный FastAPI-сервер для управления лампами WiZ. +`ignis-core` — локальный FastAPI-сервер для WiZ-ламп и домашней автоматики вокруг них. -## Что есть +## Что есть сейчас -- discovery устройств в локальной сети -- группы устройств -- команды для device/group -- one-shot и cron расписания -- guest/admin/master API-ключи -- event log и базовая статистика -- встроенный UI в `static/index.html` -- встроенный UI без внешних CDN +- discovery ламп по локальной сети с `startup`, `manual` и background refresh; +- управление отдельной лампой и группой; +- реальные `status`-опросы и `blink` для идентификации; +- группы в SQLite; +- one-shot и cron-расписания; +- persisted metadata расписаний поверх APScheduler; +- роли `master`, `admin`, `guest`; +- гостевые 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 python3 -m venv .venv source .venv/bin/activate 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 ``` UI: `http://:8000/` -Готовые deployment-файлы для `systemd`: [deploy/README.md](/home/kokos/workspace/ignis/ignis-core/deploy/README.md:1) +Готовые файлы для `systemd`: `deploy/README.md` ## Конфигурация -Минимум: +Минимальный набор: ```env IGNIS_API_KEY=change-me APP_TIMEZONE=Asia/Novosibirsk -SCAN_NETWORK= -DISCOVERY_INTERVAL_SECONDS=600 -DISCOVERY_BACKGROUND_MISSING_THRESHOLD=2 LOG_LEVEL=INFO -EVENT_LOG_RETENTION_DAYS=30 -``` - -БД: - -```env IGNIS_DATABASE_URL=sqlite+aiosqlite:///./ignis.db IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db ``` -Замечание по discovery: +Параметры discovery: -- если `SCAN_NETWORK` не задан, сервер сам выбирает private IPv4-подсети обычных интерфейсов и старается не сканировать VPN / docker / tunnel-интерфейсы -- если на хосте есть VPN или несколько интерфейсов, всё равно лучше явно задать `SCAN_NETWORK` -- формат: `192.168.0.0/24` или список через запятую -- startup scan выполняется до старта фонового цикла -- background refresh по умолчанию удаляет устройство только после двух подряд промахов discovery -- manual `POST /devices/rescan` удаляет оффлайн-устройства сразу и возвращает summary (`found`, `added`, `updated`, `removed_offline`, `pending_removal`, `online`) +```env +SCAN_NETWORK=192.168.0.0/24 +DISCOVERY_INTERVAL_SECONDS=600 +DISCOVERY_BACKGROUND_MISSING_THRESHOLD=2 +DISCOVERY_ENV_MIN_PREFIX_LEN=16 +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` -Роли: +- `master` — значение `IGNIS_API_KEY`, полный доступ. +- `admin` — ключ из БД, доступ к группам, расписаниям, stats и `rescan`. +- `guest` — чтение и обычное управление светом. -- `master`: значение из `IGNIS_API_KEY`, полный доступ -- `admin`: ключ из БД, доступ к группам, расписаниям, stats и rescan -- `guest`: обычное управление и чтение +Сервер работает в `fail-closed`: если `IGNIS_API_KEY` не задан, защищённые маршруты отвечают `503`. -Сервер работает в `fail-closed`: если `IGNIS_API_KEY` не задан, защищённые маршруты недоступны. - -Встроенный UI: - -- использует только локальные статические ассеты -- по умолчанию не сохраняет API-ключ между перезагрузками -- может запомнить ключ только в рамках текущей вкладки браузера - -## API +## HTTP API Основные маршруты: +- `GET /auth/me` - `GET /devices` - `GET /devices/groups` - `GET /devices/scenes` @@ -100,11 +114,10 @@ IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db - `POST /api-keys/activate` - `GET /stats/summary` - `GET /stats/log` -- `GET /auth/me` -`control` и `schedules` принимают JSON body. +`control/*` и `schedules/*` принимают JSON body. -Поддерживаемые параметры команд: +Поддерживаемые параметры команды: - `state` - `brightness` @@ -112,50 +125,48 @@ IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db - `temp` - `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` - `temp`: `2200..6500` - `r/g/b`: `0..255` - `scene`, `temp` и `rgb` взаимоисключаемы -- `r`, `g`, `b` нужно передавать только полной тройкой +- `r`, `g`, `b` нужно передавать полной тройкой - для `schedules/once` нужно передать ровно одно из `run_at` или `hours_from_now` -## API keys +Пример: -- список ключей возвращает публичный `key` / `key_id` -- полный секрет возвращается только при создании -- маршруты `/api-keys/*` доступны только `master` +```bash +curl -X POST http://127.0.0.1:8000/control/group/bedroom \ + -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` - `api_keys` - `event_log` - `schedules` - `apscheduler_jobs` +- `devices` + +Важно: реальным runtime-источником истины для онлайн-устройств остаётся in-memory `state_manager.devices`. Таблица `devices` пока не используется как полноценный persistent source of truth. ## 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 .venv/bin/python -m compileall app tests main.py -``` - -Полный прогон: - -```bash timeout 120s .venv/bin/python -m unittest discover -s tests -v ``` -Сейчас есть 27 тестов. Покрыты: +## Известные ограничения -- auth и роли -- lifecycle API-ключей -- control/status ошибки и partial success -- валидация scene -- one-shot и cron расписания -- миграция legacy jobs -- auto-subnet selection для discovery -- background offline cleanup threshold -- manual rescan summary и immediate cleanup -- security headers и локальные UI-ассеты -- агрегация stats без двойного счёта `*_requested` - -## Ограничения - -- discovery всё ещё основан на переборе IP по подсетям -- UI остаётся монолитным файлом -- stats пока простые и не заменяют нормальную аналитику +- discovery по-прежнему основан на переборе IP в подсетях; +- миграций схемы БД нет, используется `Base.metadata.create_all()`; +- runtime-state устройств живёт в памяти процесса; +- встроенный UI остаётся монолитным файлом без отдельной frontend-сборки; +- stats — это audit/summary, а не полноценная аналитика. diff --git a/deploy/README.md b/deploy/README.md index 9fc8148..90065ac 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -1,30 +1,28 @@ # Deploy -Практичный минимум для запуска `ignis-core` как `systemd`-сервиса. +Минимальный `systemd`-деплой для `ignis-core`. -В папке: +В каталоге: -- `ignis-core.service` -- шаблон unit-файла -- `ignis-core.env.example` -- пример переменных окружения +- `ignis-core.service` — unit-файл; +- `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` -- env-файл: `/etc/ignis-core/ignis-core.env` -- Unix-пользователь: `ignis` -- SQLite БД: `/var/lib/ignis-core/ignis.db` +Если у вас другие пути, поправьте unit и env-файл. -Если у вас другие пути, просто поправьте unit и env-файл. - -## 1. Подготовить пользователя +## 1. Создать системного пользователя ```bash sudo useradd --system --home /opt/ignis --shell /usr/sbin/nologin ignis ``` -## 2. Разложить проект +## 2. Разложить проект и зависимости ```bash 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 ``` -Что важно заполнить обязательно: +Минимум, который надо заполнить руками: - `IGNIS_API_KEY` - `SCAN_NETWORK` -Для домашней сети лучше задавать `SCAN_NETWORK` явно, особенно если на хосте есть VPN или несколько интерфейсов. +Для машин с VPN или несколькими интерфейсами `SCAN_NETWORK` лучше задавать явно. ## 4. Установить unit @@ -60,7 +58,7 @@ sudo systemctl daemon-reload sudo systemctl enable --now ignis-core.service ``` -## 5. Проверка +## 5. Проверить запуск ```bash 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`. -- Если нужен reverse proxy, его проще ставить перед `ignis-core`, а сам сервис оставить на локальном порту. +- Reverse proxy проще ставить перед сервисом, а не внутрь него. +- Перед обновлением backend-контракта полезно перегенерировать `openapi.json` и прогнать `unittest`.