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

6.9 KiB
Raw Blame History

Стандарт для новых сервисов 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.