Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions
Some checks failed
Test and publish Homegate / checks (push) Has been cancelled
Test and publish Homegate / publish (push) Has been cancelled

This commit is contained in:
2026-10-14 01:40:14 +03:00
commit 357daa8915
33 changed files with 4032 additions and 0 deletions

341
README.md Normal file
View File

@@ -0,0 +1,341 @@
# Homegate 0.4
Дополнение к **существующим Pi-hole и Nginx Proxy Manager** для домашней сети:
```text
https://pve.home → NPM:443 → https://192.168.0.137:8006
```
Вы описываете сервисы в `config/services.yaml`. Homegate создаёт локальные DNS-записи,
сертификаты и Proxy Hosts, затем поддерживает их актуальными. Развёртывание — Docker Compose.
Веб-панель Homegate управляет сервисами, доменными зонами, SSH и настройками сети.
Отдельный контейнер публикует SSH-конфиг без авторизации для устройств домашней подсети.
Новое в 0.4: [один 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-синтаксис и 55 тестов: сертификаты, настоящее TLS-рукопожатие
в стандартных и кастомных зонах, продление, повторный запуск, конфликты, ошибки API,
смена CA, HTTP-обработчик выгрузки, LAN ACL и отказ опасных SSH-директив.
Подключение дополнительного файла также проверено настоящим `ssh -G` с сохранением личных настроек.
HTTP API в тестах имитируются по официальным контрактам. **Запуск образа, реальные API NPM/Pi-hole,
HTTPS-сервисы и noVNC на вашем сервере ещё не проверены:** локальная служба Docker при подготовке не работала.
## Быстрый запуск из исходников
Запуск готового образа описан отдельно в [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).