Files
homegate/WEB.md
DizelBadCoder a83d897b70
All checks were successful
Test and publish Homegate / checks (push) Successful in 29s
Test and publish Homegate / publish (push) Successful in 12m46s
Add first-run web setup and Compose without environment or secrets
2026-10-14 03:26:50 +03:00

161 lines
12 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.

# Веб-панель Homegate 0.4
Панель включена в проект и Docker Compose. Она редактирует настоящий YAML, проверяет
настройки на сервере и показывает результат синхронизации контроллера с Pi-hole/NPM.
Интерфейс на русском, адаптируется к узким экранам и работает без внешних шрифтов,
аналитики, CDN или интернет-сервисов.
## Что доступно
- **Сервисы:** поиск, добавление, редактирование, включение/выключение; адрес VM, домен,
WebSocket, проверка TLS upstream, тайм-аут и размер загрузки, SSH-доступ.
Поле «Название» сохраняется как `display_name` и используется в каталоге, поиске
и схеме соединения. Оно необязательное, до 100 символов; без него подпись определяется по домену.
- **Доменные зоны:** несколько зон одновременно; добавление и удаление с проверкой
привязанных сервисов. Расширение ограничений уже созданного CA требует его явной смены.
- **SSH:** предпросмотр и скачивание конфига, скрипт для ПК, команда подключения,
отдельные SSH-хосты без веб-сервиса. Открытая LAN-выгрузка работает через `ssh-export`.
- **Сертификаты:** публичный корневой сертификат, SHA-256, сроки и список выданных
сертификатов. Смена CA выполняется на сервере по инструкции из панели.
- **Настройки:** IP NPM, разрешённые подсети, режим DNS, интервал синхронизации,
журнал сохранений и скачивание текущего YAML.
## Локальный запуск через Sites
Использован локальный режим Sites: исходники и работающий сервер остаются на компьютере.
Регистрация в облаке и публикация в интернете для этого проекта не выполняются.
На macOS/Linux с Python 3.11+ из каталога проекта:
```sh
sh run-local.sh
```
Откройте **http://127.0.0.1:8787**. При первом запуске скрипт создаёт отдельную среду Python
и устанавливает зависимости. Рабочая копия YAML, резервные копии и данные интерфейса
хранятся в `.local/`; образец `config/services.yaml` остаётся исходным шаблоном.
Чтобы изменить порт, используйте `HOMEGATE_LOCAL_PORT=8788 sh run-local.sh`.
Остановка — Ctrl+C в терминале; повторный запуск сохраняет внесённые настройки.
Локальный режим доступен только через `127.0.0.1`, вход в нём не требуется.
Он не запускает контроллер и не изменяет Pi-hole/NPM. Кнопка «Применить» сохраняет запрос;
без контроллера панель прямо сообщает, что применения пока нет. Скачайте подготовленный
YAML через кнопку в панели и перенесите в `config/services.yaml` на Docker-хосте.
В экземпляре, запущенном при подготовке проекта, рабочая копия находится отдельно
в `work/local-ui/config/services.yaml` относительно папки задачи. Для её повторного запуска
из исходной папки задачи без повторной установки зависимостей:
```sh
HOMEGATE_LOCAL_DIR="$PWD/work/local-ui" \
HOMEGATE_PYTHON="$PWD/work/venv/bin/python" \
sh outputs/homegate/run-local.sh
```
## Панель для домашней сети через Docker
В версии 0.4.1 есть [простой Compose](SIMPLE.md): панель без логина, первичная настройка
и подключения к NPM/Pi-hole целиком в UI. `UI_ORIGIN`, LAN-IP и credentials в окружении не нужны.
Для готового образа и автоматического создания volumes используйте [один Compose-файл](REGISTRY.md).
Ниже — вариант сборки из исходников.
```sh
sh setup.sh
# Замените примеры адресов в .env и config/services.yaml своими.
docker compose build
docker compose run --rm homegate validate
docker compose up -d
```
`setup.sh` отдельно запрашивает пароль панели длиной от 12 символов.
В `.env` задайте:
```dotenv
UI_BIND_IP=192.168.0.10
UI_PORT=8098
UI_ORIGIN=http://192.168.0.10:8098
SSH_BIND_IP=192.168.0.10
SSH_PORT=8099
```
Адрес `.10` — пример LAN-IP **хоста Homegate**; он может отличаться от IP NPM.
Откройте точный `UI_ORIGIN`, войдите с паролем из `secrets/ui_password`.
Настройки сохраняются непосредственно в `config/services.yaml`, контроллер применяет их
каждые `interval_seconds`. «Применить» будит контроллер обычно в пределах двух секунд,
после чего ему требуется время на обращения к API. Статус не равнозначен доступности VM:
он сообщает об успешной настройке NPM/Pi-hole, а не о проверке приложения за прокси.
Сохранение создаёт резервную копию в `config/backups/` (последние 20 файлов).
При одновременном редактировании в двух вкладках устаревшая версия не перезаписывает новую.
Форматирование и комментарии YAML при сохранении через панель заменяются сериализованным YAML.
Для восстановления скопируйте нужный файл из `config/backups/` в `config/services.yaml`.
В панели отображаются последние восемь из двадцати сохранений, с временем без персонального аудита.
Выключение сервиса передаёт `enabled: false` в NPM. Удаление из списка прекращает управление,
но уже созданные Proxy Host и DNS-запись сохраняются: удалите их отдельно в NPM/Pi-hole.
Это поведение явно описано в диалоге удаления. Переименование домена эквивалентно созданию
нового имени и прекращению управления старым; старые объекты также остаются.
## HTTPS самой панели
Исходный порт `8098` работает по HTTP. Для HTTPS добавьте в Homegate сервис, например:
```yaml
- hostname: homegate.home
upstream: http://192.168.0.10:8098
```
После применения и установки `root-ca.crt` на клиенте измените `.env`:
```dotenv
UI_ORIGIN=https://homegate.home
```
Пересоздайте панель:
```sh
docker compose up -d --force-recreate ui
```
Теперь вход выполняется по **https://homegate.home**. Старый URL по IP намеренно перестанет
проходить проверку Host. В NPM нужно сохранять исходный Host (обычное поведение Proxy Host).
Для прямого отката измените `UI_ORIGIN` обратно и пересоздайте `ui`.
Сервис панели должен разрешать подсеть NPM в `allowed_networks`; NPM проверяет исходный
клиентский IP по тому же списку. Панель сама не доверяет `X-Forwarded-For`.
Не перенаправляйте порты через роутер и не публикуйте их через внешние туннели.
HTTP-вход используйте только в доверенной сети при первоначальной настройке;
постоянный доступ к панели лучше проводить через описанный HTTPS-маршрут.
## Изоляция компонентов
| Компонент | Доступ |
| --- | --- |
| `homegate` | YAML только для чтения, CA и реестр в `state/`, API-пароли, `control/` |
| `ui` | YAML и резервные копии, `control/`, только пароль панели |
| `ssh-export` | Только YAML для чтения; без паролей и `state/` |
`control/status.json` содержит публичные сертификаты и состояние последней синхронизации.
`control/sync-request.json` — запрос на очередной цикл. CA-ключи не попадают в эти файлы.
Контейнер панели не имеет доступа к `state/`, паролям интеграций или Docker socket.
Сессии хранятся в памяти 12 часов, после рестарта нужно войти снова. Включены проверка
Origin, CSRF-токен, HttpOnly/SameSite cookie, защита от перебора и список допустимых Host.
При HTTPS cookie также получает Secure. После смены пароля перезапустите `ui`, чтобы сбросить сессии.
Ограничение подсетей основано на видимом контейнеру адресе клиента. Рекомендуется Linux Docker
Engine; Docker Desktop или дополнительный reverse proxy могут менять этот адрес.
Проверяйте доступ с разрешённого и постороннего сегмента после установки, включая правила
хостового firewall и Docker. Публикация на конкретном LAN-IP сама по себе не отменяет NAT роутера.
## Проверки
55 тестов проходят локально: прежняя логика DNS/TLS/SSH, HTTP-вход и сессии, Origin/CSRF,
LAN ACL, скачивание, проверка YAML, резервные копии, конфликт изменений, свежесть статуса
и передача в панель только публичных данных. JavaScript и Compose проходят проверку синтаксиса.
В браузере проверены добавление сервиса, поиск, навигация, SSH-предпросмотр и адаптивная компоновка.
Реальные API вашего homelab и запуск Docker-образа на сервере пока не проверены.
```sh
python -m unittest discover -s tests -v
```