Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions
This commit is contained in:
81
DOMAINS.md
Normal file
81
DOMAINS.md
Normal 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).
|
||||
Reference in New Issue
Block a user