Files
homegate/README.md
DizelBadCoder b305cc1ba8
All checks were successful
Test and publish Homegate / publish (push) Successful in 12m49s
Test and publish Homegate / checks (push) Successful in 29s
Support passwordless Pi-hole authentication and UI settings
2026-10-14 18:12:10 +03:00

344 lines
27 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.

# Homegate 0.4.2
Дополнение к **существующим 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.4.2: [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).
**Для HTTPS без предупреждений нужно один раз установить `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-синтаксис и 63 теста: сертификаты, настоящее 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).