Files
buryan-infra/ops/home/SERVICE-STANDARD.md
T

113 lines
6.9 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 (зафиксировано 30.10.2026)
Владелец: «всё делаем в нашем стиле — сразу SSO и база на 151».
Это правило для любого нового сервиса, в том числе для 3D-панели дома.
## 1. Доступ — только через единый вход (Authentik)
1. В Authentik создаётся **Application** + **Provider** (proxy).
2. Перед сервисом ставится **oauth2-proxy** (как у остальных сервисов):
контейнер в том же CT, конфиг — в `deploy/ctNNN/docker-compose.yml`.
3. nginx (локальный хост + VPS) добавляет `auth_request /oauth2/auth`
и `error_page 401 = /oauth2/sign_in`.
4. Сертификат — из Let's Encrypt на VPS, синхронизируется
`sync_certs.py` (Tailscale), локальный nginx работает с валидным сертом.
Исключения (осознанные): API-эндпоинты, которые не могут пройти SSO
(Matrix client API, HA API с токеном) — для них SSO отключён точечно.
## 2. Данные — только на основном PostgreSQL 192.168.1.151
1. Отдельная **база** и **роль** под сервис (никакого общего superuser).
2. Пароль — в `/root/.<service>-db.env` (права 600), в репозиторий не попадает.
3. Локальный SQLite — только как временное исключение (HA recorder — см. п. 4).
4. Дампы — через существующий `db_dumps.py`, хранение в `/mnt/archive/backups/db`.
Уже заведено для 3D-панели:
| Параметр | Значение |
|---|---|
| База | `house3d` |
| Роль | `house3d` |
| Хост | `192.168.1.151:5432` |
| Креды | `/root/.house3d-db.env` (600) |
## 3. Эксплуатация (как у всех)
* compose в `deploy/ctNNN/docker-compose.yml`, образ с пином;
* сервис в `ops/update-manager/services.yaml`;
* мониторинг: цель в Prometheus + монитор в Uptime Kuma;
* бэкап: дампы БД + конфиги в общий контур;
* документация в `ops/<тема>/` и коммит с ID.
## 4. Открытый вопрос по HA
Сейчас история HA пишется в локальный SQLite (recorder). По новому правилу
её место — Postgres на 151 (отдельная база `homeassistant`). Переезд
возможен, но требует аккуратной миграции и остановки записи; решение за
владельцем.
## 5. 3D-панель дома — предварительный план
| Компонент | Где |
|---|---|
| Рендер/сцена | Blender на хосте (артефакты — PNG/SVG в репозитории) |
| Веб-панель (three.js) | контейнер в CT110 (office-lxc) или новый CT |
| Данные (комнаты, устройства, сцены) | Postgres `house3d` на 151 |
| Доступ | Authentik + oauth2-proxy, домен (предложить `3d.buryans.ru`) |
| Мониторинг | Prometheus + Kuma |
## SSO для 3D-панели (30.10.2026)
Создано в Authentik (через API, провайдер по образцу Home Assistant):
| Параметр | Значение |
|---|---|
| Application | **3D Дом**, slug `3d` |
| Provider | OAuth2/OIDC, pk 61 |
| client_id | `3d-proxy` |
| redirect URI | `https://3d.buryans.ru/oauth2/callback` |
| Issuer | `https://authentik.buryans.ru/application/o/3d/` |
| Секреты | `/root/.house3d-sso.env` (600) |
| База данных | `house3d` на 192.168.1.151, креды `/root/.house3d-db.env` (600) |
## Что осталось для внешнего доступа
1. **DNS**: A-запись `3d.buryans.ru` → `193.233.210.184` (в Beget).
2. После DNS — выпуск LE-сертификата на VPS и vhost `3d.buryans.ru`
(nginx + oauth2-proxy → контейнер в CT110).
3. Развёртывание стека в CT110: статическая галерея рендеров + oauth2-proxy.
Проверка локально (LAN, без внешнего домена): `http://192.168.1.110:8080`.
## 3D-панель развёрнута (31.10.2026)
| Слой | Что сделано | Проверка |
|---|---|---|
| DNS (внешний) | A-запись `3d.buryans.ru` → 193.233.210.184 | `dig @8.8.8.8` = 193.233.210.184 |
| DNS (домашний) | AdGuard rewrite `3d.buryans.ru` → 192.168.1.10 | `dig @192.168.1.107` = 192.168.1.10 |
| Сертификат | Let's Encrypt на VPS, CN=3d.buryans.ru, до 28.01.2027 | `openssl s_client` |
| VPS nginx | vhost 3d: SSO `auth_request` → oauth2-proxy, proxy → 8093 | локально на VPS: 302 на Authentik |
| Локальный nginx | `conf.d/3d-local.conf`, серт синхронизируется `sync_certs` (49 доменов) | 302 на Authentik |
| Приложение | `house3d-web` (nginx, порт 8093) — галерея рендеров и палитры | 200 |
| SSO | `oauth2-proxy-3d` (порт 9131), client `3d-proxy`, callback `https://3d.buryans.ru/oauth2/callback` | 302 с правильным client_id |
| Мониторинг | Kuma: «3D Панель (house3d)» 200 OK и «3D Панель (публичный вход)» 302 Found | heartbeat: up |
| Проверки | check-services: web + проверка client_id в редиректе | 58 проверок OK |
| БД | `house3d` на 192.168.1.151 | создана |
### Ловушки
* Порт **8080 в CT110 занят Firefly** — панель перенесена на 8093.
Прямой заход на :8080 даёт ошибку Firefly `HTTP_X_FORWARDED_USER` — это
защита, а не поломка: заходить надо через `https://finance.buryans.ru`.
* `oauth2-proxy` по умолчанию строит callback из Host запроса — нужен
`OAUTH2_PROXY_REDIRECT_URL=https://3d.buryans.ru/oauth2/callback`, иначе
Authentik отвергнет redirect_uri.
* Rewrites в AdGuard лежат в `dns.rewrites` (вложенно), а не top-level —
top-level блок молча отбрасывается при перезапуске.
* Kuma в CT107 резолвил через 1.1.1.1 и из-за этого ходил на VPS (путь
нестабилен). Переключили DNS CT107 на AdGuard — 6 «висевших» мониторов
сразу стали зелёными.
* Монитор публичного URL надо ставить с `maxredirects=0`: иначе Kuma идёт
по редиректу в Authentik и получает 403 от его собственного SSO.