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

175
SSH.md Normal file
View File

@@ -0,0 +1,175 @@
# Общий SSH-конфиг в локальной сети
Добавьте секцию `ssh` к нужному веб-сервису. SSH-адрес по умолчанию берётся из IP
его `upstream`; при необходимости задайте другой `ssh.host`:
```yaml
services:
- hostname: pve.home
upstream: https://192.168.0.137:8006
upstream_tls_verify: false
ssh:
alias: pve
user: root
port: 22
```
Выгрузка содержит:
```sshconfig
Host pve pve.home
HostName 192.168.0.137
Port 22
User root
StrictHostKeyChecking ask
```
`ssh pve` и `ssh pve.home` подключаются **напрямую к VM**, а не к NPM.
Без этого Include обычное DNS-разрешение `pve.home` возвращает NPM, предназначенный для HTTPS.
Это не SSH-прокси и не SSH-сервер: на целевой машине должен уже работать `sshd`, а ключи
авторизации и доступ из LAN на нужный порт настраиваются отдельно.
Для машин без веб-сервиса есть независимый список. DNS/Proxy Host для них не создаётся:
```yaml
ssh_hosts:
- aliases: [backup, backup.lab.internal]
host: 192.168.0.150
port: 2222
user: admin
```
Секция `ssh` необязательна. Если её нет, сервис не включается в выгрузку. `user` тоже
необязателен: тогда применяется личный SSH-конфиг/имя пользователя ПК. Для отключения
экспорта одного сервиса используйте `ssh.enabled: false`; `enabled: false` у веб-сервиса
также исключает его из SSH-конфига. Записи `ssh_hosts` поддерживают собственный `enabled`.
Алиасы должны быть уникальными, без wildcard, пробелов и управляющих конструкций.
SSH HostName может быть RFC1918 IPv4 или ULA IPv6.
## Адрес выгрузки
В `.env` укажите IP **Docker-хоста Homegate**, который может отличаться от IP NPM:
```dotenv
SSH_BIND_IP=192.168.0.10
SSH_PORT=8099
```
В `config/services.yaml` задайте свою подсеть:
```yaml
allowed_networks:
- 192.168.0.0/24
```
После `docker compose up -d --build` файл доступен по адресу:
```text
http://192.168.0.10:8099/ssh-config
```
Замените `.10` своим адресом. Список генерируется при каждом запросе из текущего YAML,
поэтому изменение адреса/порта или удаление SSH-записи отражается сразу и не требует
доступных Pi-hole/NPM. При невалидной конфигурации сервер возвращает HTTP 503.
Для просмотра без HTTP можно выполнить `docker compose run --rm homegate ssh-config`;
эта команда не использует API и не блокирует работающий контроллер.
Выгрузка открыта без логина **только разрешённым IP**. Она содержит топологию сети и
имена пользователей, но не приватные ключи, пароли, CA или SSH host keys.
Сервер не раздаёт каталоги и игнорирует `X-Forwarded-For` при проверке клиента.
В контейнер `ssh-export` вообще не монтируются ключ CA и пароли управления.
Docker публикует порт на конкретном адресе хоста; это описано в
[документации Docker](https://docs.docker.com/engine/network/port-publishing/).
Не пробрасывайте этот порт из WAN и не включайте для него UPnP. Привязка IP и ACL
не заменяют firewall, если перед сервером стоит NAT, подменяющий внешний IP разрешённым
LAN-адресом. На Docker Desktop источник может выглядеть иначе, чем на Linux;
эта конфигурация рассчитана на Linux-хост с сохранением исходного IP клиента.
## Подключение на ПК
Скопируйте `sync_ssh.py` из проекта на ПК. Нужны Python 3.9+ и OpenSSH;
дополнительные Python-пакеты не требуются. Первый запуск на Linux/macOS:
```sh
python3 sync_ssh.py http://192.168.0.10:8099/ssh-config --install
ssh pve
```
На Windows с Python и OpenSSH Client:
```powershell
py -3 sync_ssh.py http://192.168.0.10:8099/ssh-config --install
ssh pve
```
Скрипт сохраняет отдельный файл `~/.ssh/config.d/homegate.conf`. Флаг `--install` один раз
добавляет в конец основного `~/.ssh/config` блок `Host *` с `Include` на абсолютный путь
этого файла. Перед изменением основной файл копируется в `config.before-homegate-*`.
Повторный запуск не дублирует Include. На Windows используется `.ssh` в профиле пользователя.
Другой каталог можно задать через `--ssh-dir`; OpenSSH сам должен быть настроен читать
находящийся там основной конфиг, например через `ssh -F /path/config pve`.
Существующие настройки имеют приоритет по правилу первого значения OpenSSH.
Приватные ключи и `IdentityFile` задавайте в личном конфиге:
```sshconfig
Host pve
IdentityFile ~/.ssh/id_ed25519_homelab
IdentitiesOnly yes
```
Этот блок разместите **до** Homegate Include. Если прежде был `Host *` с `User` или
`Port`, он также имеет приоритет перед загруженными значениями. При необходимости
переместите весь блок Homegate Include выше общих настроек, сохранив его маркеры.
Проверить результат без подключения: `ssh -G pve`.
OpenSSH описывает [порядок применения и Include](https://man.openbsd.org/ssh_config#Include).
Скрипт не меняет NTFS ACL на Windows: используйте обычный приватный каталог профиля,
не общую сетевую папку. Windows-вариант написан на стандартной библиотеке Python,
но отдельно на Windows не запускался. Symlink основного конфига автоматически не
перезаписывается: в таком случае добавьте Include вручную и запускайте скрипт без `--install`.
## Обновление
Для последующих обновлений достаточно той же команды без `--install`:
```sh
python3 sync_ssh.py http://192.168.0.10:8099/ssh-config
```
Обновление атомарное: при ошибке сети или проверок старый файл сохраняется. Удалённые
SSH-записи исчезают из дополнительного файла при следующем успешном обновлении.
Основной конфиг и `known_hosts` при обновлении не меняются. Файл на ПК обновляется
только при запуске скрипта; автоматическое расписание не создаётся.
На Linux/macOS файл получает права `0600`, каталог — `0700`.
Скрипт принимает только `Host`, `HostName`, `Port`, `User` и `StrictHostKeyChecking ask`,
проверяет значения и заново собирает текст перед записью. Скачанные `ProxyCommand`,
`Match exec`, вложенные `Include`, глобальные wildcard-настройки и выключение проверки
SSH host key отклоняются. Первый SSH-вход требует проверки отпечатка ключа
сервера обычным способом. Скрипт не выполняет скачанный код, не следует HTTP-редиректам
и не использует прокси из переменных окружения.
## HTTPS для загрузки
HTTP не защищает список адресов от подмены внутри LAN. Для аутентифицированной загрузки
добавьте HTTPS Proxy Host через существующий NPM на exporter, включив в `services`:
```yaml
- hostname: config.home
upstream: http://192.168.0.10:8099
```
Тогда на ПК:
```sh
python3 sync_ssh.py https://config.home/ssh-config --ca-file root-ca.crt --install
```
Это опциональный маршрут; домен должен входить в `domain_zones`.
NPM применяет LAN ACL к клиенту; exporter должен видеть разрешённый LAN-IP NPM.
Если Docker NAT показывает другой адрес, настройте сетевой путь или узкое правило
для этого конкретного адреса, не разрешайте весь Docker subnet без необходимости.
Проверка HTTPS у скрипта всегда включена. Корневой сертификат берите по доверенному
каналу из `state/root-ca.crt`. Ни HTTP-, ни HTTPS-вариант не требует логина для скачивания из LAN.