Files
buryan-infra/docs/SERVICE-STANDARD.md
T

271 lines
16 KiB
Markdown
Raw 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.
# ЕДИНЫЙ СТАНДАРТ СЕРВИСА Buryans Hub
Дата: 07.11.2026. Проверка автоматическая: `/tmp/standard_check.py`,
отчёт: `/tmp/standard-report.csv`. Сервисов проверено: **64**.
## 1. Пять требований
| # | Требование | Как проверяется |
|---|---|---|
| S1 | **Идентичность** — вход через Authentik | есть свой oauth2-proxy или нативный OIDC |
| S2 | **Данные** — есть бэкап | архив в `/mnt/backups` (сервисный, БД или общий) |
| S3 | **Здоровье** — сервис отвечает | HTTP < 500 по `/`, `/health`, `/api/health` и др. |
| S4 | **Документация** — есть описание | каталог `deploy/ctNNN` в репозитории |
| S5 | **Уникальность** — нет дубля роли | ручная проверка при добавлении |
## 2. Текущее соответствие
| Требование | Соответствует | Процент |
|---|---|---|
| S1 идентичность | 32 / 64 | **50%** |
| S2 бэкап данных | 60 / 64 | **94%** |
| S3 здоровье | 40 / 64 | **62%** |
| S4 документация | 64 / 64 | **100%** |
| **полный стандарт (4/4)** | **19 / 64** | **30%** |
## 3. Что уже приведено к стандарту полностью (4/4)
bazarr (CT120), beszel (CT110), docmost (CT103), element-web (CT155), firefly (CT110), grocy (CT110), house3d-web (CT110), monica (CT110), n8n (CT108), nextcloud (CT109), node_red (CT108), paperless (CT105), podfetch (CT103), prometheus (CT134), prowlarr (CT119), radarr (CT118), sonarr (CT117), uptime_kuma (CT107), vaultwarden (CT109)
## 4. Где не хватает идентичности (S1)
Это внутренние сервисы, боты, экспортёры и те, что ещё не закрыты SSO:
adguard (CT107), alertmanager (CT134), authentik-security-server-1 (CT114), authentik-security-worker-1 (CT114), book-bot (CT111), buryan-alert-webhook (CT134), duplicati (CT111), exportarr-bazarr (CT134), exportarr-prowlarr (CT134), exportarr-radarr (CT134), exportarr-sonarr (CT134), frigate (CT126), gitea-runner (CT140), grafana (CT113), ha-strip (CT106), homebox (CT110), jackett (CT124), jellystat (CT103), kavita (CT111), lidarr (CT111), livekit (CT155), loki (CT113), matrix-coturn (CT155), matrix-synapse (CT155), mautrix-telegram (CT155), mealie (CT110), memos (CT110), mosquitto (CT107), seerr (CT121), syncthing (CT139), tg-admin-bot (CT108), vikunja (CT110)
## 5. Где не подтверждено здоровье (S3)
Часть сервисов не отдаёт HTTP на порту (внутренние экспортёры, MQTT, coturn,
livekit) — для них нужен отдельный тип проверки (TCP/процесс), а не HTTP.
adguard (CT107), alertmanager (CT134), audiobookshelf (CT111), authentik-security-worker-1 (CT114), book-bot (CT111), buryan-alert-webhook (CT134), calibre-web (CT111), catalog (CT111), dashy (CT102), dozzle (CT110), duplicati (CT111), freshrss (CT111), gitea (CT140), gitea-runner (CT140), homeassistant (CT106), jellyfin (CT103), lidarr (CT111), livekit (CT155), matrix-coturn (CT155), mosquitto (CT107), navidrome (CT125), openclaw (CT115), stirling-pdf (CT110), tg-admin-bot (CT108)
## 6. Что сделано для стандарта в эту ночь
| Требование | Действие | Результат |
|---|---|---|
| S2 | Ночной бэкап данных сервисов: `/usr/local/bin/hub-services-backup.sh`, таймер 03:45, ротация 7 дней | **28% → 94%** |
| S2 | Ежемесячные restore-учения (таймер) + проверка Immich/Paperless | работает |
| S1 | SSO для Nextcloud, Gitea, Jellyfin, Paperless, Vaultwarden | 5 сервисов |
| S4 | deploy/ для всех CT, удалён deploy/ct116 | 100% |
| S5 | Удалены Plex, Tautulli, Paperless-дубль, Mosquitto-дубль, Kavita | дублей нет |
## 7. Следующие шаги по стандарту (от центра к периферии)
| Приоритет | Что | Требование |
|---|---|---|
| 1 | TCP-проверки для MQTT, coturn, livekit, экспортёров | S3 |
| 2 | SSO для внутренних веб-сервисов (adguard, jackett, seerr, syncthing, frigate) | S1 |
| 3 | Бэкап медиа-метаданных (Jellyfin, Frigate записи) | S2 |
| 4 | Реестр сервисов в одном файле (роль, владелец, бэкап, SSO) | S4 |
| 5 | Автопроверка стандарта в CI (Gitea Actions) | все |
## 8. Правило приёмки нового сервиса
```
Сервис не добавляется, пока не выполнены S1–S4:
S1 — вход через Authentik
S2 — бэкап данных в /mnt/backups
S3 — health-проверка (HTTP или TCP)
S4 — deploy/ctNNN с compose и описанием
```
## 9. Как проверять
```bash
python3 /tmp/standard_check.py # таблица + сводка
cat /tmp/standard-report.csv # машинный отчёт
```
---
## ПРОДОЛЖЕНИЕ: TCP-ПРОВЕРКИ И SSO ВНУТРЕННИХ (07.11, 10:55)
### Сделано
| Что | Результат |
|---|---|
| TCP-проверки (S3) | добавлены в автопроверку; сервисы без портов помечаются «неприменимо» |
| **S3 здоровье** | **85%** от применимых (было 62%) |
| SSO для seerr | провайдер `seerrproxy2` + приложение + прокси на 4190 (CT110) |
| SSO для adguard | провайдер `adguardproxy2` + приложение + прокси на 4191 (CT110) |
| nginx | ombi.buryans.ru → 110:4190, adguard.buryans.ru → 110:4191 |
| Проверка гейтов | **403 «Sign In»** на портах 4190 и 4191 |
### Найдено и исправлено по ходу
- Приложение Authentik не создавалось через API без полей `meta_launch_url` и
`policy_engine_mode` → discovery отдавал 404 → прокси падал в рестарт-цикл.
- После добавления полей: `201 Created`, discovery `200`, прокси `Up`.
### Ограничение (то же, что с Vaultwarden)
Публичные домены (ombi, adguard, vault) обслуживаются **VPS** (193.233.210.184),
а не nginx хоста. VPS по SSH недоступен — изменения там применить нельзя.
Поэтому публично ответы прежние (307/302), а SSO-гейт действует на уровне хоста
и LAN-портов. Когда VPS оживёт — переключить три домена на прокси.
### Текущие цифры стандарта
| Требование | Соответствие |
|---|---|
| S1 идентичность | 32 / 64 (50%) |
| S2 бэкап | 60 / 64 (94%) |
| S3 здоровье | 41 / 41TOTAL (85%) |
| S4 документация | 64 / 64 (100%) |
| **полный стандарт** | **24 / 64 (38%)** |
### Осталось по стандарту
1. SSO для frigate, jackett, syncthing (по той же схеме)
2. Переключить три домена на VPS, когда он станет доступен
3. Автопроверка стандарта в CI Gitea
---
## ЗАКРЫТИЕ: ПУБЛИЧНЫЙ SSO ЧЕРЕЗ VPS (07.11, 11:05)
### VPS восстановил доступность
```
ping: 2/2 | порт 22 открыт | порт 443 открыт | маршрут 192.168.1.0/24 через wg0
```
### Что сделано на VPS (`/etc/nginx/conf.d/buryans-all.conf`)
| Домен | Было | Стало |
|---|---|---|
| vault.buryans.ru | → 192.168.1.109:8081 (напрямую) | → **109:4180** (SSO-прокси) |
| ombi.buryans.ru | → 192.168.1.121:5055 | → **110:4190** (SSO-прокси) |
| adguard.buryans.ru | → 192.168.1.107:3000 | → **110:4191** (SSO-прокси) |
Конфиг проверен (`nginx -t`), перезагружен, бэкап рядом.
### Проверено снаружи
```
vault.buryans.ru -> 403 (Sign In → Authentik)
ombi.buryans.ru -> 403
adguard.buryans.ru -> 403
docs.buryans.ru -> 302 (нативный OIDC Paperless)
files.buryans.ru -> 302 (нативный OIDC Nextcloud)
```
Сервисы при этом живы напрямую (200/307/302) — мобильные клиенты не затронуты.
### Ответ на вопрос «SSO-проблемы от VPS или всё починили?»
| Категория | Статус |
|---|---|
| **Починено в конфигах** (Nextcloud 5 поломок, Paperless, Jellyfin, Gitea, дубли провайдеров) | ✅ закрыто |
| **Зависело от VPS** (публичный вход для vault/ombi/adguard) | ✅ **теперь закрыто** — VPS доступен |
| **Ещё не сделано** (frigate, jackett, syncthing и внутренние: mqtt, livekit, coturn, экспортёры, боты) | ⏳ в работе |
### Итоговые цифры стандарта
| Требование | Соответствие |
|---|---|
| S1 идентичность | 32 / 64 (50%) |
| S2 бэкап | 60 / 64 (94%) |
| S3 здоровье | 41 / 41T (85%) |
| S4 документация | 64 / 64 (100%) |
| **полный стандарт** | **24 / 64 (38%)** |
### Уточнённые цифры (после появления новых SSO-прокси)
| Требование | Соответствие |
|---|---|
| S1 идентичность | 34 / 64 (53%) |
| S2 бэкап | 60 / 64 (94%) |
| S3 здоровье | 41 / 48 (85%) |
| S4 документация | 64 / 64 (100%) |
| **полный стандарт** | **26 / 64 (41%)** |
| всего сервисов в проверке | 64 |
---
## SYNCTHING: SSO ЗАКРЫТ (07.11, 11:15)
| Шаг | Результат |
|---|---|
| Провайдер Authentik | `syncthingproxy` + приложение, discovery 200 |
| Прокси | CT110, host-network, порт **4192**, upstream `192.168.1.139:8384` |
| Хост-nginx `sync.buryans.ru` | → 110:4192 |
| VPS `sync.buryans.ru` | → 110:4192 |
| Проверка | хост **403**, публично **403** (Sign In → Authentik), Syncthing напрямую **200** |
⚠️ Синхронизация устройств идёт по порту **22000** — он не тронут, обмен файлами работает.
### Сознательно НЕ закрываем SSO-гейтом
| Сервис | Почему |
|---|---|
| **Frigate** | доступ через мобильное приложение и Home Assistant по API — гейт сломает клиентов |
| **Jackett** | служебный, ходит только по API из *arr-стека |
| **Mosquitto, LiveKit, coturn** | не веб-сервисы |
| **exportarr ×4, alertmanager, buryan-alert-webhook** | технические экспортёры/вебхуки |
| **tg-admin-bot, book-bot, gitea-runner** | боты и раннеры без веб-интерфейса |
### Цифры после Syncthing
| Требование | Соответствие |
|---|---|
| S1 идентичность | 35 / 64 (55%) |
| S2 бэкап | 60 / 64 (94%) |
| S3 здоровье | 41 / 41T (85%) |
| S4 документация | 64 / 64 (100%) |
| **полный стандарт** | **27 / 64 (42%)** |
### Следующие кандидаты на SSO (есть провайдеры, нет прокси)
`vikunja`, `memos`, `mealie`, `homebox`, `duplicati`, `grafana`, `loki`, `lidarr`, `jellystat`
---
## ПАКЕТ SSO: VIKUNJA, MEMOS, MEALIE, HOMEBOX (07.11, 11:25)
| Сервис | Провайдер | Прокси | Гейт LAN | Публично |
|---|---|---|---|---|
| Vikunja | `vikunjaproxy` | CT110:4193 | 403 | домена на VPS нет |
| Memos | `memosproxy` | CT110:4194 | 403 | домена на VPS нет |
| **Mealie** | `mealieproxy` | CT110:4195 | 403 | **403** (meals.buryans.ru) |
| Homebox | `homeboxproxy` | CT110:4196 | 403 | домена на VPS нет |
Вывод: на VPS из этой четвёрки есть только `meals.buryans.ru` — он и закрыт.
Остальные три домена существуют только в LAN, поэтому гейт действует на портах.
### Итоговые цифры стандарта
| Требование | Соответствие |
|---|---|
| S1 идентичность | 39 / 64 (61%) |
| S2 бэкап | 60 / 64 (94%) |
| S3 здоровье | 41 / 41T (85%) |
| S4 документация | 64 / 64 (100%) |
| **полный стандарт** | **31 / 64 (48%)** |
### Закрыто SSO за сутки (9 сервисов)
Nextcloud, Gitea, Jellyfin, Paperless, Vaultwarden, Seerr, AdGuard, Syncthing,
Vikunja, Memos, Mealie, Homebox — гейты или нативный OIDC.
### Осталось (сознательно или по приоритету)
Сознательно без гейта: Frigate, Jackett, MQTT, LiveKit, coturn, exportarr, боты.
По приоритету: duplicati, grafana, loki, lidarr, jellystat.
---
## FRIGATE: УДАЛЁННЫЙ ДОСТУП + SSO (07.11, 13:10)
### Что сделано
| Шаг | Результат |
|---|---|
| Провайдер Authentik | `frigateproxy` + приложение «Frigate (камеры)», redirect `https://cams.buryans.ru/oauth2/callback` |
| SSO-прокси | CT110, порт **4197**, upstream `192.168.1.126:5000`, проверено: **403 Sign In** |
| Конфиг nginx | подготовлен `/etc/nginx/conf.d/cams.buryans.ru.conf` (HTTP→HTTPS, websocket, 2 ГБ тела) |
| Frigate напрямую | **200**, не тронут (HA и мобильные клиенты работают) |
### Чего не хватает для публичного доступа (действия владельца)
1. **DNS-запись**: `cams.buryans.ru` → `193.233.210.184` (A-record у регистратора).
Wildcard-записи нет: `test-zzz.buryans.ru` не резолвится.
2. После появления DNS — выпустить сертификат на VPS (certbot) и включить блок
(конфиг уже написан).
### Как смотреть камеры снаружи прямо сейчас (без DNS)
| Способ | Как | Плюсы |
|---|---|---|
| **Tailscale на телефоне** | устройство `s25-ultra` уже в tailnet (сейчас offline 25 дней) — включить приложение, открыть `http://192.168.1.126:5000` | без публикации в интернет, прямой канал, без нагрузки на VPS |
| **Home Assistant** | `home.buryans.ru` уже за SSO, камеры Frigate доступны через интеграцию | один вход, ничего не открываем |
### Важное предупреждение
- Порт **5000** (API) остаётся только в LAN — публично не выставляется.
- Живое видео через VPS расходует трафик; для регулярного просмотра лучше Tailscale.
- WebRTC-поток Frigate может требовать прямого канала; при проблемах с live-view
через прокси использовать HLS/MSE-режим в интерфейсе.