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

139 lines
14 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.

# Один домен дома и в интернете
Пример: мобильное приложение использует `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](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge).
Права Cloudflare: [документация DNS-плагина Certbot](https://certbot-dns-cloudflare.readthedocs.io/en/stable/).
## Уже есть подходящий сертификат в домашнем 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](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.12.6/backend/internal/certificate.js).
Тесты используют изолированные HTTP-заглушки и настоящие X.509 сертификаты.
Реальные credentials и сертификаты production VDS для разработки не использовались.
DNS challenge проверен по контрактам NPM
[2.12.6](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.12.6/backend/routes/nginx/certificates.js)
и [2.16.0](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.16.0/backend/routes/nginx/certificates.js).
Тесты проверяют фоновый выпуск, восстановление после таймаута, отсутствие повторного
ACME-запроса, фильтрацию credentials и запрет записи на VDS. Интерфейс проверен
с локальной заглушкой NPM; реальный ACME-выпуск и изменение публичного DNS при разработке не выполнялись.