344 lines
27 KiB
Markdown
344 lines
27 KiB
Markdown
# 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).
|