Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions
This commit is contained in:
157
WEB.md
Normal file
157
WEB.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# Веб-панель 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
|
||||
|
||||
Для готового образа и автоматического создания 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
|
||||
```
|
||||
Reference in New Issue
Block a user