Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions
Some checks failed
Test and publish Homegate / checks (push) Has been cancelled
Test and publish Homegate / publish (push) Has been cancelled

This commit is contained in:
2026-10-14 01:40:14 +03:00
commit 357daa8915
33 changed files with 4032 additions and 0 deletions

81
DOMAINS.md Normal file
View File

@@ -0,0 +1,81 @@
# Кастомные доменные зоны
До первого запуска задайте все нужные зоны в `config/services.yaml`:
```yaml
domain_zones:
- home
- home.arpa
- lab.internal
- dev.example.net
```
После этого допустимы, например, `pve.home`, `nas.home.arpa`, `grafana.lab.internal`
и `git.dev.example.net`. Поддерживаются поддомены любой глубины и apex зоны с точкой,
например `dev.example.net`. Wildcard-сертификаты и wildcard DNS не создаются;
каждый веб-сервис имеет отдельное имя, DNS-запись и сертификат.
Если `domain_zones` отсутствует в старом конфиге, сохраняются прежние `home` и `home.arpa`.
Начальная/конечная точка зоны и регистр нормализуются; имена самих сервисов должны быть
в нижнем регистре. IDN задавайте в ASCII/punycode. Проверяются границы DNS-меток:
зона `home` не разрешает `pve.evilhome`.
При использовании реального домена выбирайте принадлежащую вам зону. Записи остаются
локальными в Pi-hole; регистрации домена или публикации публичного DNS Homegate не делает.
Публичный сертификат автоматически не появляется: все зоны обслуживает локальный CA.
Для домашнего использования предпочтительна `home.arpa` по
[RFC 8375](https://www.rfc-editor.org/rfc/rfc8375.html).
Избегайте `.local`, зарезервированной для [mDNS](https://www.rfc-editor.org/rfc/rfc6762.html#section-3)
и обрабатываемой клиентами иначе, чем обычный DNS.
Новый корневой CA содержит ограничения `NameConstraints` для зон первого запуска.
Добавление нового хоста или дочерней зоны внутри уже разрешённого суффикса не меняет CA.
Удаление зоны сужает политику выпуска Homegate, но не отзывает старые сертификаты и
не меняет доверие уже установленного корня. Удаляемые из зоны маршруты нужно также
убрать из YAML; правила сохранения/ручного удаления NPM-объектов описаны в README.
## Добавление зоны за пределами существующего CA
Если CA уже создан и новая зона **вне его ограничений**, Homegate не выпускает для неё
заведомо недоверенный сертификат. Смена корневого сертификата никогда не запускается
автоматически. Для расширения выполните явную миграцию:
```sh
# Сначала измените domain_zones и маршруты в config/services.yaml.
docker compose stop homegate
docker compose run --rm homegate rotate-ca
# Скопируйте новый state/root-ca.crt на клиенты и установите доверие.
docker compose up -d homegate
```
`rotate-ca` сохраняет прежние `ca.json` и `root-ca.crt` в `state/ca-history/`, создаёт
новый ключ/корень и сохраняет `registry.json`, поэтому объекты NPM остаются теми же.
При следующем запуске сертификаты активных маршрутов перевыпускаются под новым корнем
и nginx перечитывает их. Установите новый корень на клиенты перед возобновлением контроллера;
до этого NPM продолжает отдавать прежние сертификаты. После перехода удалите доверие к
старому CA. Для удалённых из YAML маршрутов сертификаты не перевыпускаются автоматически.
Резервная копия CA содержит приватный ключ и должна оставаться защищённой.
Для установки, которая ещё не запускалась, достаточно изменить `domain_zones` до
первого `docker compose up`: менять CA и устанавливать его второй раз не потребуется.
## Обновление с 0.1
Замените исходники, Dockerfile и Compose. Сохраните свои `.env`, `config/`, `state/`
и `secrets/`; не заменяйте настроенный YAML примером из архива. Добавьте в `.env`:
```dotenv
SSH_BIND_IP=192.168.0.10
SSH_PORT=8099
```
Замените IP на LAN-IP Docker-хоста Homegate и выполните:
```sh
docker compose up -d --build
```
Новые зоны добавляйте намеренно. Старый конфиг без `domain_zones` продолжает работать.
Существующий CA 0.1 разрешает `home` и `home.arpa`; для `lab.internal` или иной новой
зоны примените миграцию выше. Настройки SSH в существующих сервисах добавляются отдельно
по [инструкции](SSH.md).