Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions
This commit is contained in:
341
README.md
Normal file
341
README.md
Normal 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).
|
||||
Reference in New Issue
Block a user