5.7 KiB
Кастомные доменные зоны
До первого запуска задайте все нужные зоны в config/services.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.
Избегайте .local, зарезервированной для mDNS
и обрабатываемой клиентами иначе, чем обычный DNS.
Новый корневой CA содержит ограничения NameConstraints для зон первого запуска.
Добавление нового хоста или дочерней зоны внутри уже разрешённого суффикса не меняет CA.
Удаление зоны сужает политику выпуска Homegate, но не отзывает старые сертификаты и
не меняет доверие уже установленного корня. Удаляемые из зоны маршруты нужно также
убрать из YAML; правила сохранения/ручного удаления NPM-объектов описаны в README.
Добавление зоны за пределами существующего CA
Если CA уже создан и новая зона вне его ограничений, Homegate не выпускает для неё заведомо недоверенный сертификат. Смена корневого сертификата никогда не запускается автоматически. Для расширения выполните явную миграцию:
# Сначала измените 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:
SSH_BIND_IP=192.168.0.10
SSH_PORT=8099
Замените IP на LAN-IP Docker-хоста Homegate и выполните:
docker compose up -d --build
Новые зоны добавляйте намеренно. Старый конфиг без domain_zones продолжает работать.
Существующий CA 0.1 разрешает home и home.arpa; для lab.internal или иной новой
зоны примените миграцию выше. Настройки SSH в существующих сервисах добавляются отдельно
по инструкции.