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

Homegate 0.6.0

Дополнение к существующим Pi-hole и Nginx Proxy Manager для домашней сети:

https://pve.home  →  NPM:443  →  https://192.168.0.137:8006

Вы добавляете сервисы в веб-панели. Homegate создаёт локальные DNS-записи, сертификаты и Proxy Hosts, затем поддерживает их актуальными. Развёртывание — Docker Compose. Веб-панель Homegate управляет сервисами, доменными зонами, SSH и настройками сети. SSH-конфиг публикуется без авторизации для устройств домашней подсети.

Простой запуск 0.6.0: Compose без env и secrets, вся настройка в UI. Откройте http://IP-СЕРВЕРА:8098 и заполните адреса NPM/Pi-hole в форме. Пароль панели не нужен. Расширенный вариант с отдельными контейнерами: Compose и Gitea Actions. Также доступны: веб-панель и локальный запуск, SSH-конфиг и скрипт для ПК, кастомные доменные зоны и миграция CA.

Для публичного домена можно выпустить Let's Encrypt через DNS challenge с автопродлением в домашнем NPM, выбрать существующий сертификат или обновляемую копию с NPM на VDS — без установки CA на телефон. Настройка целиком через UI: DNS challenge, сертификаты NPM и синхронизация с VDS. Для режима Homegate — локальный CA нужно один раз установить root-ca.crt на каждое клиентское устройство. Для внутренних имён .home публичный сертификат Let's Encrypt не подходит. Установка корневого сертификата на сервер не устанавливает доверие на телефонах и компьютерах. Доверие к локальному CA описано в документации Let's Encrypt.

Зоны настраиваются списком domain_zones: например home, home.arpa, lab.internal, lab.example.net. Поддерживаются несколько зон одновременно и несколько уровней поддоменов; источник сертификата выбирается для каждого сервиса. В примере сохранено pve.home. Для новой домашней зоны стандарт рекомендует home.arpa: RFC 8375.

Как это работает

flowchart LR
  Browser[Браузер с доверенным Root CA] -->|DNS: pve.home| PiHole[Pi-hole]
  PiHole -->|192.168.0.10 — адрес NPM| Browser
  Browser -->|HTTPS :443| NPM[Nginx Proxy Manager]
  NPM -->|HTTPS :8006| PVE[Proxmox 192.168.0.137]
  Controller[Homegate] -->|DNS API| PiHole
  Controller -->|Сертификаты и Proxy Hosts| NPM

DNS указывает на NPM, а не на Proxmox. Порт и протокол целевой VM выбирает NPM по имени из запроса. Это обратный прокси, адрес в браузере остаётся https://pve.home.

Контроллер Homegate не публикует портов, не требует Docker socket и не запускает второй DNS или nginx. Сервис ssh-export публикует HTTP-порт 8099 на явно заданном LAN-IP и проверяет клиента по allowed_networks. Он не имеет доступа к state/ и паролям API. Он может работать на отдельной Linux VM с доступом к API вашего Pi-hole и NPM. compose.yaml собирает образ из исходников; compose.registry.yaml скачивает готовый образ после публикации через Gitea Actions. Для запуска только по одному файлу, без исходников и setup.sh, см. REGISTRY.md.

Требования и границы проверки

  • Linux-хост с Docker Engine и Docker Compose v2+; архитектура amd64 или arm64.
  • Существующий NPM 2.x; интеграция сверена с исходниками 2.16.0. Для других версий сначала проверьте запуск на одном имени. API NPM может меняться.
  • Pi-hole 6 для автоматического DNS. Для Pi-hole 5 или неподдерживаемого API используйте dns_mode: manual и добавьте записи через интерфейс Pi-hole.
  • Стабильные адреса Pi-hole, NPM и VM; NPM должен принимать HTTPS на LAN-порту 443.
  • Все клиенты используют Pi-hole как DNS. Публичный «резервный DNS», browser DoH, Android Private DNS и VPN могут обходить локальный DNS. В IPv6 настройте DNS через RA/DHCPv6 тоже. Используйте второй локальный Pi-hole для резервирования.
  • Если Pi-hole и NPM на одном IP, их web-порты должны различаться: например NPM 80/81/443, Pi-hole web 8080, DNS 53. Homegate этот конфликт автоматически не исправляет.

Проверяются Compose-конфигурация, shell-синтаксис и автоматические тесты: сертификаты, настоящее TLS-рукопожатие в стандартных и кастомных зонах, продление, повторный запуск, конфликты, ошибки API, смена CA, HTTP-обработчик выгрузки, LAN ACL и отказ опасных SSH-директив. Подключение дополнительного файла также проверено настоящим ssh -G с сохранением личных настроек. HTTP API в тестах имитируются по официальным контрактам. Сборка и локальный запуск контейнеров проверены отдельно. Реальные API NPM/Pi-hole, HTTPS-сервисы и noVNC на вашем сервере не проверены.

Быстрый запуск из исходников

Запуск готового образа описан отдельно в REGISTRY.md.

Распакуйте каталог homegate на сервере и перейдите в него. Команды ниже выполняются из этого каталога.

1. Подготовьте конфигурацию и пароли

sh setup.sh

Скрипт создаёт .env, secrets/, state/ и control/, запрашивает пароли скрытым вводом, записывает UID/GID текущего пользователя. Он не подключается к вашему homelab. Для NPM используйте учётную запись с правами управления Proxy Hosts и сертификатами; администратор имеет нужные права. В NPM_IDENTITY укажите её email.

Измените .env; адреса .10 и .2 ниже — примеры, замените их своими:

NPM_URL=http://192.168.0.10:81
NPM_IDENTITY=admin@example.com
PIHOLE_URL=http://192.168.0.2
SSH_BIND_IP=192.168.0.10
SSH_PORT=8099
UI_BIND_IP=192.168.0.10
UI_PORT=8098
UI_ORIGIN=http://192.168.0.10:8098

SSH_BIND_IP — LAN-IP Docker-хоста Homegate, который может отличаться от IP NPM. NPM_URL и PIHOLE_URL — адреса административных интерфейсов, без /api и /admin. Если Pi-hole web на порту 8080, укажите http://192.168.0.2:8080. localhost внутри контейнера означает сам Homegate. Для управления через HTTPS скопируйте доверенный PEM CA bundle в config/ и задайте API_CA_BUNDLE=/config/management-ca.pem. Проверка TLS у API всегда включена. HTTP передаёт пароли и сертификаты без шифрования; используйте его только внутри доверенной сети управления или общей закрытой Docker-сети. Для изолированной Docker-сети добавьте её как external network в Compose и используйте имена контейнеров.

Для Pi-hole application password нужно разрешение на изменение конфигурации. В существующий Compose Pi-hole добавьте:

environment:
  FTLCONF_webserver_api_app_sudo: "true"

Затем пересоздайте только сервис Pi-hole из его собственного Compose-проекта. Альтернатива — обычный пароль администратора без 2FA. При 2FA нужен application password. app_sudo даёт приложению широкие права изменения настроек, а не только DNS; это свойство API Pi-hole. Не задавайте FTLCONF_dns_hosts через environment Pi-hole при автоматическом управлении: такая настройка становится read-only для API.

2. Опишите маршруты

В config/services.yaml замените proxy_ip на LAN-IP NPM и allowed_networks на вашу подсеть:

proxy_ip: 192.168.0.10
domain_zones: [home, home.arpa, lab.internal]
allowed_networks:
  - 192.168.0.0/24
dns_mode: pihole6
interval_seconds: 60

services:
  - hostname: pve.home
    upstream: https://192.168.0.137:8006
    upstream_tls_verify: false
    websocket: true
    timeout_seconds: 3600
    max_body_mb: 10240
    ssh:
      alias: pve
      user: root
      port: 22

  - hostname: grafana.home
    upstream: http://192.168.0.120:3000

VM-адреса в этой версии — IPv4, RFC1918. Upstream должен быть веб-сервисом HTTP(S), без пути, query и встроенного пароля. Для SSH, базы данных и произвольного TCP такая конфигурация не подходит. Локальные IPv6 ULA можно использовать в proxy_ip и списке допустимых сетей; для dual-stack DNS дополнительные записи задаются вручную в manual-режиме.

3. Соберите и запустите

docker compose build
docker compose run --rm homegate validate
docker compose up -d
docker compose logs -f --tail=100 homegate

validate проверяет только файл и ничего не меняет в Pi-hole/NPM. Панель открывается по UI_ORIGIN, вход — паролем панели, заданным в setup.sh. Подробнее: веб-панель, резервные копии и HTTPS.

После старта ожидаются сообщения Created local root CA, Configured https://pve.home ... и DNS: pve.home -> .... Сертификат для клиентов появится в state/root-ca.crt. healthy означает успешную синхронизацию API, а не доступность целевой VM.

Первичная сборка скачивает базовый образ и Python-зависимости из интернета. После сборки работа и продление сертификатов не требуют интернета, публичного DNS или публичного ACME. Для полностью офлайн-сервера предварительно соберите образ на машине той же архитектуры и перенесите через docker save homegate:0.4.0 / docker load, затем используйте docker compose up -d --no-build.

4. Установите корневой сертификат на клиенты

Копируйте на устройства только state/root-ca.crt через доверенный канал, например SCP. Сверьте SHA-256 с сервером:

docker compose exec homegate python /app/homegate.py fingerprint

Публичный корень также можно скачать в панели на странице «Сертификаты». Сверяйте его отпечаток с сервером. Никогда не передавайте клиентам ca.json, issued/, registry.json или весь state/: там находятся закрытые ключи.

Клиент Установка доверия
Windows Импорт root-ca.crt в «Доверенные корневые центры сертификации» для нужного пользователя или компьютера. Перезапустите браузер.
macOS «Связка ключей» → System → импорт сертификата → Trust → SSL: Always Trust. Потребуются права администратора.
Debian / Ubuntu sudo cp root-ca.crt /usr/local/share/ca-certificates/homegate.crt и sudo update-ca-certificates.
iPhone / iPad Установите профиль сертификата; затем Settings → General → About → Certificate Trust Settings → Enable Full Trust для Homegate.
Android Настройки безопасности → установка сертификата CA; путь зависит от производителя. Некоторые приложения не доверяют пользовательским CA.
Firefox / отдельные приложения Если системное доверие не подхватилось, импортируйте CA в собственное хранилище Authorities приложения с доверием для сайтов.

На iOS одного импорта недостаточно: Apple описывает отдельное включение SSL-доверия. Результат зависит от хранилища доверия конкретного браузера/приложения; некоторые устройства не позволяют добавлять CA. В этом случае вариант — принадлежащий вам публичный домен и DNS-01 сертификат с локальными DNS-записями; такое имя будет, например, pve.lab.your-domain.example, а не pve.home. DNS-01 не требует публикации самого сервиса в интернет: Let's Encrypt.

5. Проверьте маршрут

На клиенте, заменив адреса Pi-hole и NPM на реальные:

nslookup pve.home 192.168.0.2
curl --cacert root-ca.crt --resolve pve.home:443:192.168.0.10 https://pve.home/ -I
curl --cacert root-ca.crt https://pve.home/ -I

DNS должен вернуть IP NPM. Первая команда curl проверяет HTTPS независимо от DNS; вторая — вместе с DNS. Не используйте -k: он скрывает ошибки доверия. Откройте https://pve.home, выполните вход в Proxmox и проверьте noVNC/Shell.

Особенности Proxmox и TLS

WebSocket, часовые proxy-timeouts, отключение буферизации и лимит тела 10 GiB уже заданы в примере. Лимит можно увеличить через max_body_mb. NPM передаёт имя запроса и заголовки прокси штатным шаблоном. При необходимости доверенных прокси или корректного внешнего URL в других приложениях настройте эти приложения отдельно.

У HTTPS есть два участка:

  1. Браузер → NPM: сертификат pve.home, подписанный Homegate CA; клиент проверяет имя и цепочку после установки CA.
  2. NPM → Proxmox: TLS со штатным сертификатом Proxmox. В примере проверка этого сертификата явно выключена через upstream_tls_verify: false. Шифрование есть, но подлинность upstream не проверяется. Это не меняет доверие браузера к NPM.

Для проверки обоих участков скопируйте публичный CA Proxmox из /etc/pve/pve-root-ca.pem в постоянный каталог NPM, например /data/custom-trust/pve-root-ca.pem внутри контейнера. Проверьте SAN серверного сертификата Proxmox и укажите соответствующее имя:

- hostname: pve.home
  upstream: https://192.168.0.137:8006
  upstream_tls_verify: true
  upstream_tls_name: pve.your-existing-lan-domain
  upstream_ca_file: /data/custom-trust/pve-root-ca.pem

Здесь upstream_tls_name — существующее имя из сертификата Proxmox, оно не обязано быть pve.home. Путь читается NPM, не Homegate. При собственном сертификате Proxmox используйте его издателя. Для остальных HTTPS upstream проверка по умолчанию включена.

Доступ только из домашней сети

Homegate добавляет в каждый свой Proxy Host allow <ваши подсети>; deny all;. ACL применяется к IP, который видит NPM. Никаких правил проброса портов на роутере не нужно. Оставьте WAN-вход закрытым для 80, 443, 81, 53, порта web Pi-hole и SSH_PORT (8099), включая IPv6 и автоматические пробросы UPnP. При Docker применяйте firewall-правила с учётом Docker forwarding; одного обычного UFW INPUT-правила может быть недостаточно.

Если перед NPM стоит другой прокси/NAT, который заменяет адрес источника на разрешённый LAN-IP, ACL уже не различает внешних и домашних клиентов. Ограничение на роутере/межсетевом экране остаётся необходимым. Не включайте доверие произвольным X-Forwarded-For. DNS-имя .home само по себе не является ограничением доступа.

Изменения, продление и восстановление

  • Новый сервис: добавьте блок в config/services.yaml; изменения подхватятся за 60 секунд. Контейнер перечитывает каталог конфигурации, в том числе после атомарного сохранения редактором.
  • Сертификат выдаётся на 90 дней и заменяется, когда осталось менее 30. Homegate загружает его в NPM и обновляет Proxy Host, чтобы nginx перечитал сертификат. Перезапуск контейнера сохраняет CA и идентификатор владельца.
  • Если Pi-hole недоступен, Homegate продолжает обслуживание сертификатов/прокси и показывает нездоровый статус синхронизации. Каждый цикл повторяет неуспешные операции. При отказе NPM DNS-запись нового сервиса не публикуется.
  • Отключение: задайте enabled: false; NPM выключит соответствующий Proxy Host, DNS останется.
  • Удаление записи из файла не удаляет ресурсы. Для окончательного удаления сначала уберите блок из файла, затем удалите Proxy Host, его сертификат и DNS в интерфейсах NPM/Pi-hole. До ручного удаления прежний маршрут продолжает работать; продление удалённого из файла сервиса прекращается. Это также относится к переименованию сервиса.
  • Уже существующий чужой Proxy Host с тем же именем или конфликтующий DNS-адрес не перезаписывается. Используйте новое имя или заранее перенесите старую запись вручную. NPM-хосты этого проекта редактируйте через YAML: ручные изменения управляемых полей будут восстановлены. Не удаляйте строку # homegate:... из Advanced.
  • При смене LAN-IP NPM поправьте proxy_ip, затем вручную удалите/исправьте прежние конфликтующие DNS-записи. Homegate добавляет записи по одной, не заменяет весь DNS-список.
  • Для Pi-hole 5 выберите dns_mode: manual, в его Local DNS добавьте pve.home → IP_NPM. Сертификаты и NPM остаются автоматическими.
  • Держите только один экземпляр контроллера на state/. Файловая блокировка не даёт одновременно запускать run и once. Для ручного прохода остановите сервис и выполните docker compose run --rm homegate once, затем docker compose up -d.

Для резервной копии остановите Homegate, сохраните .env, config/, secrets/, state/ в защищённом хранилище и запустите снова. Отдельно резервируйте NPM (его /data и /etc/letsencrypt) и Pi-hole. Закрытый ключ CA хранится в state/ca.json без шифрования с правами 0600, каталог state/ — 0700; используйте шифрование диска/backup. Это простой онлайн-CA для homelab, без офлайн-корня, CRL и OCSP. При компрометации CA нужно удалить доверие к старому корню на всех клиентах и развернуть новый CA. Корень действует 10 лет; за 91 день до истечения выпуск блокируется и требуется миграция доверия.

Потеря всего state/ означает потерю CA и владельца объектов. Восстанавливайте backup: новый CA потребует повторной установки доверия, а старые NPM-объекты не будут присвоены новому контроллеру автоматически. Ключ CA никогда не импортируется в NPM: туда попадают только сертификаты отдельных сервисов и их ключи.

Диагностика

Симптом Что проверить
NXDOMAIN Клиент использует Pi-hole; запись указывает на NPM; отключён обход DNS через DoH/VPN; очистите DNS-кэш.
Сертификат не доверен CA установлен именно на клиенте и в хранилище этого браузера; на iOS включён Full Trust; дата/время верны.
Ошибка имени сертификата Открывайте https://pve.home, не IP NPM; проверьте SNI и привязанный в NPM сертификат.
HTTP 403 от NPM IP клиента, видимый NPM, должен входить в allowed_networks; проверьте VLAN, IPv6 и наличие внешнего NAT.
HTTP 502 NPM достигает IP:port VM; выбран HTTPS для Proxmox; при upstream_tls_verify: true корректны CA и SAN.
Pi-hole API HTTP 401/403 Версия 6, правильный пароль; application password с app_sudo; для 2FA — application password.
Pi-hole API HTTP 400 Проверьте /api/docs вашей версии и что dns.hosts не задан read-only через FTLCONF_dns_hosts.
NPM API HTTP 401/403 Email, пароль и разрешения учётной записи; URL содержит административный порт 81.
nginx configuration Посмотрите статус хоста и ошибку в NPM; проверьте наличие upstream_ca_file внутри NPM.
conflicting Pi-hole record DNS для этого имени уже ведёт на другой IP; исправьте его вручную.
not managed by this instance Имя занято в NPM или потерян registry.json; восстановите state либо выберите другое имя.
Сервис unhealthy docker compose logs --tail=100 homegate; Docker healthcheck показывает отказ, но сам по себе не перезапускает контейнер.

Проверки разработчика

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m unittest discover -s tests -v
docker compose --env-file .env.example config --quiet

Протоколы интеграции: Pi-hole API, Pi-hole authentication, NPM certificates API 2.16.0, NPM certificate upload implementation, NPM Proxy Hosts API 2.16.0.

Description
No description provided
Readme 493 KiB
Languages
Python 97.2%
Shell 2.5%
Dockerfile 0.3%