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

12 KiB
Raw Blame History

Веб-панель 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 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 относительно папки задачи. Для её повторного запуска из исходной папки задачи без повторной установки зависимостей:

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: панель без логина, первичная настройка и подключения к NPM/Pi-hole целиком в UI. UI_ORIGIN, LAN-IP и credentials в окружении не нужны.

Для готового образа и автоматического создания volumes используйте один Compose-файл. Ниже — вариант сборки из исходников.

sh setup.sh
# Замените примеры адресов в .env и config/services.yaml своими.
docker compose build
docker compose run --rm homegate validate
docker compose up -d

setup.sh отдельно запрашивает пароль панели длиной от 12 символов. В .env задайте:

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 сервис, например:

- hostname: homegate.home
  upstream: http://192.168.0.10:8098

После применения и установки root-ca.crt на клиенте измените .env:

UI_ORIGIN=https://homegate.home

Пересоздайте панель:

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-образа на сервере пока не проверены.

python -m unittest discover -s tests -v