Files
buryan-infra/docs/HUB-CORE-PROJECT.md
buryan-agent 92bc3aa4e9 Проект Buryan Hub Core: один механизм вместо 35 сервисов
Описана архитектура связующего слоя: шина событий, граф сущностей,
сверка с реальностью, интеллект поверх общего индекса.

Слои: сервисы (источник правды) → ядро (события, граф, правила) →
интеллект (разбор запросов, поиск, действия) → интерфейс (Matrix, панель).

План из четырёх шагов с проверками на каждом: ядро данных в PostgreSQL,
шина событий, сверка и действия с подтверждением, затем AI.

Принципы: сервисы остаются источником правды, одно направление записи,
идемпотентность, деградация без поломки, сначала предложение — потом действие.
2026-10-19 18:04:10 +03:00

235 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Buryan Hub Core: один механизм вместо 35 сервисов
Проект связующего слоя. Цель — чтобы сервисы работали как один организм:
одно действие в одном месте видно везде, данные не расходятся, а человек
получает одну картину, а не 35 вкладок.
---
## 1. Проблема, которую решаем
Сейчас есть 35 доменов и 30 контейнеров. Каждый живёт сам:
| Симптом | Пример из нашей практики |
|---|---|
| Данные расходятся | фильм есть в Seerr, но не в Radarr; заявка висит, потому что нет загрузчика |
| Нет общей картины | «что у нас есть?» — надо обойти 6 сервисов |
| Одно и то же в трёх местах | фильм в Jellyfin, Radarr и Plex — три разных записи |
| Нет истории | «когда это появилось и почему?» — нигде не записано |
| Настройки дублируются | nginx на двух узлах, списки пользователей в 6 сервисах |
| События не доходят | скачалось — узнаёшь, только если сам откроешь |
Вывод: нужен не ещё один сервис, а **слой**, который держит общую модель
данных и общий поток событий.
---
## 2. Архитектура: четыре слоя
```
┌─────────────────────────────────────────────────────────────┐
│ 4. Интерфейс: Matrix (личка с ботами), единая панель │
├─────────────────────────────────────────────────────────────┤
│ 3. Интеллект: разбор запросов, поиск, сводки, действия │
├─────────────────────────────────────────────────────────────┤
│ 2. Ядро: события, граф сущностей, синхронизация, правила │
├─────────────────────────────────────────────────────────────┤
│ 1. Сервисы: Jellyfin, *arr, Immich, Calibre, HA, Frigate… │
└─────────────────────────────────────────────────────────────┘
```
### Слой 1. Сервисы (уже есть)
Ничего не меняем. Они остаются источниками правды для своего домена.
### Слой 2. Ядро — то, чего сейчас нет
Три вещи:
**2.1. Шина событий.** Каждый сервис шлёт вебхук в одну точку. Мы
приводим их к одному формату:
```json
{
"at": "2026-10-19T18:00:00Z",
"source": "radarr",
"type": "media.imported",
"entity": {"kind": "фильм", "key": "tmdb:693134", "title": "Дюна 2"},
"payload": {"path": "/data/movies/Дюна 2 (2024)", "size": 42},
"actor": "system"
}
```
Одна таблица `events` в общем PostgreSQL (CT 151) + публикация в Matrix.
Любой сервис, бот или сценарий читает один поток вместо семи.
**2.2. Граф сущностей.** Одна запись «Дюна 2» со связями:
```
фильм «Дюна 2»
├─ tmdb:693134 (внешний ключ)
├─ в Radarr: id 12 (статус: скачан)
├─ в Jellyfin: item (можно смотреть)
├─ заявка в Seerr: 7 (просил Роман)
├─ файл: /data/... (42 ГБ)
└─ книга-первоисточник → Calibre id 88
```
Это и есть «полная синхронизация»: не копирование данных между сервисами,
а **одна карточка, которая знает, где что лежит**.
**2.3. Правила и сверка.** Раз в сутки сверяем модель с реальностью:
* заявка одобрена, но файла нет → предупредить;
* файл есть, но Jellyfin не видит → запустить сканирование;
* пользователь есть в Authentik, но не в Gitea → создать;
* nginx на двух узлах разошёлся → показать diff.
Это то, что мы уже делали руками (выравнивание nginx, users-sync), только
автоматически и с отчётом.
### Слой 3. Интеллект
| Задача | Решение | Почему так |
|---|---|---|
| Понимать «покажи, что появилось за неделю» | LLM разбирает намерение → вызов инструмента | правила не покроют формулировки |
| Искать «фильм про пустыню с Тимоти» | семантический поиск по индексу (эмбеддинги) | по словам не найдётся |
| Сводки и объяснения | LLM поверх событий | «почему не качается» — это анализ |
| Действия (заказать, тегировать) | план → подтверждение → выполнение | без подтверждения опасно |
**Модель:** локальная (Ollama, Qwen 2.5 7B на CPU) — без внешних
зависимостей и утечек; либо облачный API по ключу, если нужна скорость.
Начать с локальной: приватность и предсказуемость.
### Слой 4. Интерфейс
* **Matrix** — единственная точка входа. Личка с ботами, кнопки-подтверждения
(реакции), уведомления.
* **Панель (Dashy)** — витрина: статусы из Prometheus, ссылки, «что нового».
* Никаких «зайди в Sonarr, посмотри очередь» — всё через диалог.
---
## 3. Как это выглядит для человека
**Пример 1. Заявка на фильм**
```
вы: хочу посмотреть Дюну 2
бот: нашёл в каталоге. Заказать? [да / нет]
вы: да
бот: заказал. Ищу источник…
бот: (через час) качается, 40%. Место есть.
бот: (через два часа) готово, доступно в Jellyfin. Смотреть?
```
**Пример 2. Утро**
```
бот: за ночь: 2 фильма скачались, 1 серия не нашлась (нет источника),
место 71%, тревог нет. Фото загружено 12. Книга новая: «Дюна».
```
**Пример 3. Проблема**
```
бот: заявка «Дюна 2» висит сутки. Причина: нет индексатора для этого
типа. Предлагаю: добавить Jackett-источник. Сделать?
```
То есть бот не «показывает статистику», а **ведёт задачу до результата**
и говорит причину, когда что-то не работает.
---
## 4. Что уже есть и чего не хватает
| Компонент | Состояние |
|---|---|
| Единый вход (Authentik, 35 приложений) | **есть** |
| Общая база PostgreSQL (CT 151) | **есть** |
| Шина событий | **нет** — есть разрозненные вебхуки (Seerr → Matrix, Alertmanager → Matrix) |
| Индекс контента (9 источников) | **есть**, но плоский (SQLite, без связей и истории) |
| Боты (8) | **есть**, но без модели данных: отвечают «здесь и сейчас» |
| Автоматизация (n8n, 7 сценариев) | **есть**, но не связана с ядром |
| Наблюдаемость (Prometheus, Loki, Grafana) | **есть** |
| AI | **нет** |
---
## 5. План: четыре шага
### Шаг 1. Ядро данных (2–3 дня работы)
* Перенести индекс из SQLite в PostgreSQL: `entities`, `entity_links`,
`events`, `sync_state`.
* Схема сущности: `kind`, `external_ids` (jsonb), `title`, `status`,
`source_of_truth`, `updated_at`.
* Связи: `entity_links(from, to, relation)` — «экра­низация», «заявка на»,
«файл от».
* История: каждое изменение → строка в `events`.
**Проверка:** `!карточка дюна` показывает одну карточку со всеми связями.
### Шаг 2. Шина событий (1–2 дня)
* Приёмник `/events` (расширение текущего вебхука ботов).
* Подключить: Sonarr, Radarr, Seerr, Jellyfin, Immich, Paperless, Calibre,
Uptime Kuma, Alertmanager.
* Нормализация в один формат, запись в `events`, публикация в Matrix.
**Проверка:** скачался фильм → в личке появляется событие → оно есть в
таблице.
### Шаг 3. Сверка и действия (2–3 дня)
* Правила-«дрифты»: заявка без файла, файл без записи в Jellyfin,
пользователь без доступа, расхождение конфигов.
* Действия: запустить сканирование, создать пользователя, создать заявку.
* Каждое действие — с подтверждением в Matrix.
**Проверка:** искусственно ломаем (удаляем запись в Jellyfin) → ядро
замечает и предлагает починить.
### Шаг 4. Интеллект (3–5 дней)
* Ollama + Qwen в CT, инструмент-вызовы: `search`, `order`, `status`,
`explain`, `run_action`.
* Боты перестают быть «командами», становятся диалогом.
* Память: предпочтения («не люблю ужасы», «озвучка — Дубляж»).
**Проверка:** «что-нибудь лёгкое на вечер» → предложение из библиотеки с
учётом истории просмотров.
---
## 6. Принципы, чтобы не сломать то, что работает
1. **Сервисы остаются источником правды** для своих данных. Ядро не
переписывает их, а связывает.
2. **Одно направление записи.** События идут в ядро; действия — из ядра
в сервисы через их API, с подтверждением.
3. **Идемпотентность.** Любой сценарий можно запустить дважды без вреда.
4. **Деградация.** Ядро упало — сервисы работают как раньше.
5. **Ничего не удаляем сразу.** Сначала предложение и отчёт, потом действие.
---
## 7. Что нужно от вас
| Что | Зачем |
|---|---|
| Решение по AI: локальная модель или облако (ключ) | выбрать поведение и приватность |
| Список Telegram-каналов | мониторинг (Telethon) |
| `api_id`/`api_hash` | Telethon |
| Готовность к «действиям с подтверждением» | какой уровень автономии дать ядру |
| Приоритет: медиа или все домены сразу | влияет на порядок шагов |
---
## 8. Итог одной фразой
Не «ещё один сервис», а **одна карточка на каждый объект** (фильм, книга,
фото, документ), **один поток событий** и **один диалог** — с ботами,
которые доводят задачу до конца и объясняют причины, когда что-то не так.