Files
homegate/DOMAINS.md
DizelBadCoder 357daa8915
Some checks failed
Test and publish Homegate / checks (push) Has been cancelled
Test and publish Homegate / publish (push) Has been cancelled
Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions
2026-10-14 01:40:14 +03:00

82 lines
5.7 KiB
Markdown
Raw 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.

# Кастомные доменные зоны
До первого запуска задайте все нужные зоны в `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).