139 lines
14 KiB
Markdown
139 lines
14 KiB
Markdown
# Один домен дома и в интернете
|
||
|
||
Пример: мобильное приложение использует `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 при разработке не выполнялись.
|