# Homegate 0.5.0 Дополнение к **существующим Pi-hole и Nginx Proxy Manager** для домашней сети: ```text https://pve.home → NPM:443 → https://192.168.0.137:8006 ``` Вы добавляете сервисы в веб-панели. Homegate создаёт локальные DNS-записи, сертификаты и Proxy Hosts, затем поддерживает их актуальными. Развёртывание — Docker Compose. Веб-панель Homegate управляет сервисами, доменными зонами, SSH и настройками сети. SSH-конфиг публикуется без авторизации для устройств домашней подсети. **Простой запуск 0.5.0: [Compose без env и secrets, вся настройка в UI](SIMPLE.md).** Откройте `http://IP-СЕРВЕРА:8098` и заполните адреса NPM/Pi-hole в форме. Пароль панели не нужен. Расширенный вариант с отдельными контейнерами: [Compose и Gitea Actions](REGISTRY.md). Также доступны: [веб-панель и локальный запуск](WEB.md), [SSH-конфиг и скрипт для ПК](SSH.md), [кастомные доменные зоны и миграция CA](DOMAINS.md). **Для публичного домена можно выбрать существующий сертификат NPM или обновляемую копию с NPM на VDS — без установки CA на телефон.** Настройка целиком через UI: [сертификаты NPM и синхронизация с VDS](CERTIFICATES.md). Для режима **Homegate — локальный CA** нужно один раз установить `root-ca.crt` на каждое клиентское устройство. Для внутренних имён `.home` публичный сертификат Let's Encrypt не подходит. Установка корневого сертификата на сервер не устанавливает доверие на телефонах и компьютерах. Доверие к локальному CA описано в [документации Let's Encrypt](https://letsencrypt.org/docs/certificates-for-localhost/). Зоны настраиваются списком `domain_zones`: например `home`, `home.arpa`, `lab.internal`, `lab.example.net`. Поддерживаются несколько зон одновременно и несколько уровней поддоменов; источник сертификата выбирается для каждого сервиса. В примере сохранено `pve.home`. Для новой домашней зоны стандарт рекомендует `home.arpa`: [RFC 8375](https://www.rfc-editor.org/rfc/rfc8375.html). ## Как это работает ```mermaid 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](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](REGISTRY.md). Распакуйте каталог `homegate` на сервере и перейдите в него. Команды ниже выполняются из этого каталога. ### 1. Подготовьте конфигурацию и пароли ```sh sh setup.sh ``` Скрипт создаёт `.env`, `secrets/`, `state/` и `control/`, запрашивает пароли скрытым вводом, записывает UID/GID текущего пользователя. Он не подключается к вашему homelab. Для NPM используйте учётную запись с правами управления Proxy Hosts и сертификатами; администратор имеет нужные права. В `NPM_IDENTITY` укажите её email. Измените `.env`; адреса `.10` и `.2` ниже — **примеры**, замените их своими: ```dotenv 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 добавьте: ```yaml environment: FTLCONF_webserver_api_app_sudo: "true" ``` Затем пересоздайте только сервис Pi-hole из его собственного Compose-проекта. Альтернатива — обычный пароль администратора без 2FA. При 2FA нужен application password. `app_sudo` даёт приложению широкие права изменения настроек, а не только DNS; это свойство [API Pi-hole](https://docs.pi-hole.net/ftldns/configfile/#app_sudo). Не задавайте `FTLCONF_dns_hosts` через environment Pi-hole при автоматическом управлении: такая настройка становится read-only для API. ### 2. Опишите маршруты В `config/services.yaml` замените `proxy_ip` на LAN-IP NPM и `allowed_networks` на вашу подсеть: ```yaml 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. Соберите и запустите ```sh 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](WEB.md). После старта ожидаются сообщения `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 с сервером: ```sh 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-доверия](https://support.apple.com/en-gb/102390). Результат зависит от хранилища доверия конкретного браузера/приложения; некоторые устройства не позволяют добавлять CA. В этом случае вариант — принадлежащий вам публичный домен и DNS-01 сертификат с локальными DNS-записями; такое имя будет, например, `pve.lab.your-domain.example`, а не `pve.home`. DNS-01 не требует публикации самого сервиса в интернет: [Let's Encrypt](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge). ### 5. Проверьте маршрут На клиенте, заменив адреса Pi-hole и NPM на реальные: ```sh 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 и укажите соответствующее имя: ```yaml - 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 показывает отказ, но сам по себе не перезапускает контейнер. | ## Проверки разработчика ```sh 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](https://docs.pi-hole.net/api/), [Pi-hole authentication](https://docs.pi-hole.net/api/auth/), [NPM certificates API 2.16.0](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.16.0/backend/routes/nginx/certificates.js), [NPM certificate upload implementation](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.16.0/backend/internal/certificate.js), [NPM Proxy Hosts API 2.16.0](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.16.0/backend/routes/nginx/proxy_hosts.js).