Files
homegate/CERTIFICATES.md
DizelBadCoder 5661de72b7
All checks were successful
Test and publish Homegate / checks (push) Successful in 29s
Test and publish Homegate / publish (push) Successful in 12m43s
Add UI DNS challenge issuance and automatic home NPM renewal
2026-10-15 05:42:15 +03:00

14 KiB
Raw Blame History

Один домен дома и в интернете

Пример: мобильное приложение использует https://disk.hyperdog.dev. Снаружи публичный DNS ведёт на VDS. Дома Pi-hole возвращает LAN-IP домашнего NPM, а домашний NPM направляет запрос в локальный Nextcloud и предъявляет публичный сертификат. Установка корневого CA на телефон для такого сертификата не требуется.

Выпуск и автопродление через DNS challenge

Этот вариант не зависит от VDS: сертификат выпускает и продлевает домашний NPM. Нужен зарегистрированный публичный домен и API-доступ к его DNS-провайдеру. Публичные A/AAAA-записи продолжают указывать на VDS; для проверки владения доменом NPM временно создаёт TXT-запись _acme-challenge. Открывать домашние порты в интернет не требуется. Зоны .home, .local и другие внутренние имена для Let's Encrypt не подходят.

  1. В Настройки → Доменные зоны добавьте hyperdog.dev.
  2. Добавьте сервис с доменом disk.hyperdog.dev и локальным адресом Nextcloud.
  3. В HTTPS-сертификат → Источник выберите Let’s Encrypt — DNS challenge.
  4. Укажите домены сертификата и выберите DNS-провайдера. Скопируйте показанный шаблон в поле API-доступ DNS-провайдера, заменив значения своим токеном. Для Cloudflare используйте API Token с разрешением Zone:DNS:Edit, ограниченный нужной зоной.
  5. При необходимости задайте время ожидания DNS; пустое поле оставляет значение плагина. Подтвердите условия Let's Encrypt и нажмите Выпустить сертификат.
  6. Дождитесь результата. Форма сама выберет полученный сертификат домашнего NPM. Нажмите Добавить сервис или Сохранить — Homegate создаст локальный DNS и прокси.

Отдельный выпуск доступен в Сертификаты → Выпустить Let’s Encrypt. Можно указать несколько имён или wildcard, например *.hyperdog.dev. Он покрывает disk.hyperdog.dev, но не hyperdog.dev и не deep.disk.hyperdog.dev. После отдельного выпуска выберите сертификат в карточках нужных сервисов.

Продление и хранение токена

Домашний NPM сохраняет DNS credentials и автоматически использует их при продлении. Homegate передаёт их только в запросе выпуска и не сохраняет в своих файлах, YAML, состоянии задания или логах. В Compose и env добавлять ничего не нужно. Сертификат остаётся под тем же ID; Homegate не заменяет его сертификатом локального CA. Резервируйте данные домашнего NPM, включая /data и /etc/letsencrypt.

Для выпуска и продления домашнему NPM нужен исходящий доступ к интернету, DNS-провайдеру и Let's Encrypt. При временном отсутствии интернета уже выпущенный сертификат работает до истечения срока; локальный Nextcloud остаётся доступен. Подключение к NPM на VDS не используется и его production-конфигурация не меняется.

Современный NPM возвращает список провайдеров через API и использует email своей учётной записи. Для старых версий без этого API Homegate показывает каталог NPM 2.12.6 и дополнительное поле email. Доступность конкретного плагина зависит от версии домашнего NPM.

Выпуск идёт в фоне и может занять до 15 минут. Если соединение прервалось или Homegate перезапустился, нажмите Проверить результат: это только чтение списка сертификатов. Повторный выпуск автоматически не отправляется. Уже существующий действующий сертификат с тем же набором доменов и провайдером используется повторно. В этом случае новый токен не записывается поверх старого; ротация credentials существующего сертификата выполняется в NPM. Если выпуск отклонён, проверьте токен, права на зону и журнал домашнего NPM.

Протокол: Let's Encrypt DNS-01. Права Cloudflare: документация DNS-плагина Certbot.

Уже есть подходящий сертификат в домашнем NPM

  1. В Настройки → Доменные зоны добавьте hyperdog.dev.
  2. Добавьте или отредактируйте сервис: домен disk.hyperdog.dev, адрес локального Nextcloud, например http://192.168.0.20:8080.
  3. В HTTPS-сертификат → Источник выберите Существующий сертификат домашнего NPM.
  4. Выберите сертификат из списка и сохраните. Homegate проверит срок и соответствие домену, создаст локальную DNS-запись и прокси с выбранным ID сертификата.

В этом режиме Homegate не выпускает и не загружает сертификат вместо выбранного. Let’s Encrypt автоматически продлевает домашний NPM по своей текущей конфигурации. Для Custom сертификата обновлением занимается его издатель; для автоматического копирования с VDS используйте следующий режим. Смена CA Homegate для новой зоны не нужна.

Автоматическая копия сертификата с NPM на VDS

  1. В Настройки → Сертификаты с NPM на VDS укажите HTTPS URL панели NPM на VDS без /api, логин и пароль существующей учётной записи с доступом к чтению и скачиванию нужного сертификата. Сохраните настройки. Пароль остаётся на сервере и не возвращается в UI.
  2. В карточке сервиса выберите Копия из NPM на VDS — автообновление.
  3. В списке Сертификат на VDS выберите существующий сертификат Let’s Encrypt.
  4. В поле Сертификат домашнего NPM оставьте Создать новую копию в домашнем NPM либо выберите существующий Custom, содержимое которого нужно обновлять этой копией.
  5. Сохраните. После успешной синхронизации в разделе Сертификаты появятся срок действия, источник и время проверки копии.

Оба NPM должны быть разными серверами. При первом успешном копировании Homegate скачивает сертификат, цепочку и ключ с VDS и загружает их только в домашний NPM. Ключ обрабатывается в памяти; он не появляется в логах, публичном API, YAML, SSH-конфиге или registry.json. Сам домашний NPM сохраняет ключ для TLS, как при обычном импорте Custom сертификата.

Production NPM на VDS: только чтение

Код отдельного клиента VDS разрешает только:

  • POST /api/tokens — обычная авторизация;
  • GET /api/nginx/certificates — список сертификатов;
  • GET /api/nginx/certificates/<id>/download — скачивание выбранного сертификата.

Homegate не создаёт, не редактирует и не удаляет прокси, сертификаты или настройки на VDS и не вызывает там renew. Выпуск и продление продолжаются по уже существующей конфигурации NPM на VDS. Это ограничение проверяется автоматическими тестами. Настраивать Actions, cron, SSH-доступ или скрипт на VDS для копирования не нужно.

Как обновляется домашняя копия

Каждый цикл контроллер читает метаданные источника. При изменении сертификата он скачивает новую версию; дополнительно содержимое проверяется скачиванием раз в сутки. До загрузки проверяются домены всех локальных прокси, использующих копию, срок действия, цепочка и соответствие приватного ключа. Обновление применяется к тому же Custom ID, после чего домашний nginx перезагружается через API NPM. Неудачная перезагрузка повторяется.

Если интернет или API VDS недоступны, последняя копия остаётся в домашнем NPM. Локальные DNS и прокси продолжают обслуживаться; ошибка копирования видна в UI. HTTPS работает до истечения сохранённого сертификата. Для получения новой версии с VDS нужен доступ к его API. Homegate не переходит на свой локальный CA при ошибке.

Штатный экспорт NPM поддерживает скачивание сертификатов Let’s Encrypt; Custom сертификаты VDS в списке источников не показываются. Нельзя синхронизировать копию поверх Let’s Encrypt сертификата домашнего NPM: для неё нужен отдельный Custom.

DNS и Nextcloud

Телефон дома должен использовать Pi-hole как DNS. VPN, Private DNS/DoH и публичный резервный DNS могут обходить локальную запись. Публичную DNS-запись на VDS менять не нужно. Сам Nextcloud и его данные должны быть доступны дома без VDS; его trusted_domains должен содержать выбранное имя, а настройки trusted proxies должны учитывать домашний NPM.

Проверка реализации

Контракты списка, ZIP-экспорта и multipart-загрузки сверены с исходниками NPM 2.12.6. Тесты используют изолированные HTTP-заглушки и настоящие X.509 сертификаты. Реальные credentials и сертификаты production VDS для разработки не использовались. DNS challenge проверен по контрактам NPM 2.12.6 и 2.16.0. Тесты проверяют фоновый выпуск, восстановление после таймаута, отсутствие повторного ACME-запроса, фильтрацию credentials и запрет записи на VDS. Интерфейс проверен с локальной заглушкой NPM; реальный ACME-выпуск и изменение публичного DNS при разработке не выполнялись.