From 4a23e17290741c924c16f26f5c0519afeb74d5b2 Mon Sep 17 00:00:00 2001 From: karpenok Date: Sat, 7 Nov 2026 23:35:46 +0700 Subject: [PATCH] up --- AGENTS.md | 13 ++++--- INVENTORY.md | 71 ---------------------------------- README.md | 25 ++++++------ docs/netbird/design.md | 78 ++++++++++++++++++-------------------- hosts/.gitkeep | 0 services/netbird/README.md | 12 +++--- 6 files changed, 62 insertions(+), 137 deletions(-) delete mode 100644 INVENTORY.md delete mode 100644 hosts/.gitkeep diff --git a/AGENTS.md b/AGENTS.md index 0e353dd..74a52b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,10 +4,11 @@ ## Контекст -- Репозиторий `homelab-infra` — единственный источник правды об инфраструктуре. -- Инфраструктура строится вокруг overlay-сети **NetBird**: новые хосты и сервисы сначала подключаются к сети, потом получают роли. -- Хосты и группы сервисов **меняются со временем**. Не закрепляй конфигурацию за конкретными именами машин, если это не обязательно. Сервисы первичны. -- Человекочитаемая документация живёт в Trilium (MCP-сервер `trilium` доступен в сессии) — дерево «Хоумлаб». +- Репозиторий `homelab-infra` описывает **новую** инфраструктуру. Это единственный источник правды о том, что разворачивается отсюда. +- Прежний homelab, текущие VPS и их поломки — вне скоупа. Не инвентаризируй их, не предлагай починку и не переноси в этот репозиторий, пока пользователь явно не попросил. +- Инфраструктура строится вокруг overlay-сети **NetBird**: новый хост сначала входит в сеть, потом получает роль. +- Сервисы первичны. Хост и набор сервисов на нём меняются. Не создавай каталог на каждую машину и не привязывай манифест к имени хоста, если цель доставки можно задать иначе. +- Trilium, дерево «Хоумлаб», — архив прежней лабы. Читать его только по прямой просьбе. Ветку «Работа» не читать. ## Границы (критически важно) @@ -29,13 +30,13 @@ Формат: `<тип>(<область>): <описание>` на русском. - `feat(netbird): ...` — новая функциональность -- `fix(hosts): ...` — исправление +- `fix(netbird): ...` — исправление - `docs(design): ...` — только документация - `chore(repo): ...` — обслуживание репозитория Примеры: - `feat(netbird): набросок архитектуры management-сервера` -- `docs(inventory): актуализация карты VPS-нод` +- `docs(netbird): требования к VPS management` ## Ветвление diff --git a/INVENTORY.md b/INVENTORY.md deleted file mode 100644 index d813555..0000000 --- a/INVENTORY.md +++ /dev/null @@ -1,71 +0,0 @@ -# INVENTORY — карта инфраструктуры - -Исходный срез на момент 2026-11-07 (разведка по SSH + документация Trilium). -Служит отправной точкой. Устаревшие записи удалять по мере миграции в новую сеть NetBird. - -Обозначения статуса: ✅ жив и доступен · ⚠️ жив, проблема с доступом · ❌ недоступен/выключен - -## Внешние VPS - -| Хост | IP | Локация | Роль | Статус | -| --- | --- | --- | --- | --- | -| ger-nod-01 | 64.188.69.164 | DE | Remnawave панель + нода, danted (SOCKS5) | ✅ | -| fin-nod-01 | 144.31.18.31 | FI | Remnawave нода | ✅ | -| ned-nod-01 | 144.31.233.33 | NL | Remnawave нода (origin под CDN) | ⚠️ SSH: ключ не авторизован | -| pol-nod-01 | 217.60.25.148 | PL | неизвестно | ⚠️ SSH: ключ не авторизован | -| rus-nod-01 | 46.149.71.142 | RU | Remnawave RU-вход (осознанно выключен) | ❌ | -| rus-nod-02 | 79.174.91.54 | RU | неизвестно | ❌ | -| ger-nod-02 | 150.241.64.209 | DE | **пустой резерв** — кандидат под пилоты | ✅ | -| yandex-01 | 84.201.128.176 | RU (Yandex Cloud) | RU-hop Remnawave, диск 84% | ✅ | - -## Домашний контур (сеть 192.168.1.0/24, шлюз OPNsense .1) - -### Ядро - -| Хост | IP | Роль | Статус | -| --- | --- | --- | --- | -| opnsense | 192.168.1.1 | шлюз, DNS, DHCP | ⚠️ SSH: ключ не авторизован | -| pve | 192.168.1.2 | Proxmox VE 9.1.4 (i3-12100T, 54G RAM, ~19 гостей) | ✅ | -| nas | 192.168.1.54 | TrueNAS SCALE 25.04 (ZFS shara 32.7T, backup 2.7T) | ✅ | -| pbs-lab | 192.168.1.49 | Proxmox Backup Server | ⚠️ SSH: ключ не авторизован | -| netcore | 192.168.1.100 | роль неизвестна | ⚠️ SSH: ключ не авторизован | -| golova | 192.168.1.201 | NetBird server + Traefik + Remnawave + Portainer (control plane) | ✅ | - -### Гости PVE (LXC/VM) - -| Хост | IP | Роль | Статус | -| --- | --- | --- | --- | -| gitea | 192.168.1.217 | Gitea 1.25.3 + PostgreSQL 14 (без act_runner) | ✅ | -| jellyfin | 192.168.1.213 | Jellyfin (нативно, без Docker), диск 86% | ✅ | -| arr-stack | 192.168.1.204 | Matrix, TriliumNext, Navidrome, UISP, qBittorrent | ✅ | -| arr | 192.168.1.228 | *arr-стек + open-webui, диск 75% | ✅ | -| pass | 192.168.1.206 | Vaultwarden | ✅ | -| cloud | 192.168.1.209 | Nextcloud AIO (~22 конт.) + TriliumNext + coturn | ✅ | -| homeassistant | 192.168.1.233 | HA + Frigate + Mosquitto + ESPHome | ✅ | -| youtube | 192.168.1.229 | TubeArchivist | ✅ | -| tunetide | 192.168.1.237 | AudioMuse + Navidrome + PostgreSQL | ✅ | -| booksdw | 192.168.1.211 | пустый Docker-хост | ✅ | -| yandex-auto-up | 192.168.1.236 | служебная ВМ без Docker | ✅ | -| audiobookshelf | 192.168.1.210 | LXC работает | ⚠️ SSH: ключ не авторизован | -| plex (LXC 105) | 192.168.1.205 | Plex | ❌ выключен | -| lampac (LXC 110) | 192.168.1.212 | Lampac | ❌ выключен | -| musicdown (LXC 114) | 192.168.1.220 | Navidrome/Deemix | ❌ выключен | -| monitoring | 192.168.1.208 | стек мониторинга (мёртв, к развёртыванию заново) | ❌ | -| test-lab / userside-lab / audiomuse / navidrome / feishin / courses / boosty / soulsync / kima-hub / media / trilium | .215/.219/.221/.223/.225/.226/.227/.230/.231/.235/.200 | разное | ❌ не пингуются | - -### VIP без гостя (DNS `.internal` — вероятно прокси на OPNsense) - -navidrome.internal→.223 · qbittorrent.internal→.207 · feishin.internal→.225 · audiomuse.internal→.221 · boosty-downloader.internal→.227 · test.internal→.215 · monitoring.internal→.208 (down) - -## Известные проблемы (наследие) - -1. RAM PVE переподписана: 44/54G занято, swap 7.9/8G. -2. Диски в красной зоне: jellyfin 86%, yandex-01 84%, arr-stack 79%, golova 78%, arr 75%. -3. Мониторинга нет (хост мёртв). -4. Дубли сервисов: TriliumNext ×2, qBittorrent ×2, Navidrome/AudioMuse ×2, Traefik ×2. -5. Docker-версии плавают (27.x–29.x), почти все образы на `:latest`, часть контейнеров вне compose. -6. Ключ `~/.ssh/root_home` перегенерирован 2026-11-06 — не разложен на части хостов. - -## Целевая архитектура (этап 0) - -Новый арендованный VPS → NetBird management (см. `docs/netbird/design.md`). Существующая сеть 192.168.1.0/24 временно считается legacy-контуром; миграция хостов планируется отдельно, этот файл при миграции переписывается. diff --git a/README.md b/README.md index 8c0b489..784f3e3 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,34 @@ # homelab-infra -Инфраструктура как код для личной сети: домашний homelab, внешние VPS и overlay-сеть на базе NetBird. +Инфраструктура как код для новой личной сети. Репозиторий описывает то, что мы разворачиваем с этого момента. Прежний homelab и текущие VPS сюда не переносятся. ## Идея -Репозиторий — единственный источник правды о состоянии инфраструктуры. Правки на хостах вручную по SSH не вносятся: изменения коммитятся сюда, доставка — через Gitea Actions (GitOps). +Репозиторий — единственный источник правды. Изменение коммитится сюда и доставляется через Gitea Actions. Правки на хостах вручную по SSH не являются способом ведения инфраструктуры. -**Принцип: сервисы первичны, хосты — заменяемы.** Конфигурация сервисов не привязана к конкретным машинам. Хосты и группы сервисов на них будут меняться — структура каталогов это учитывает. +**Сервисы первичны, хосты заменяемы.** Каталог сервиса не называется именем машины. Хост, на котором сервис окажется, и состав группы на этом хосте могут смениться без перестройки репозитория. + +Первый сервис — overlay-сеть **NetBird**. Новый хост сначала входит в неё, потом получает роль. ## Структура ``` homelab-infra/ -├── AGENTS.md # правила для AI-агентов, работающих в этом репозитории -├── INVENTORY.md # карта инфраструктуры (хосты, IP, роли, статусы) +├── AGENTS.md # правила для AI-агентов ├── docs/ -│ └── netbird/ # архитектура overlay-сети NetBird +│ └── netbird/ # архитектура NetBird ├── services/ -│ └── netbird/ # манифесты NetBird (management, signal, relay) -├── hosts/ # описания хостов (по одному каталогу на узел) +│ └── netbird/ # манифесты management, signal, relay, dashboard └── .gitea/ └── workflows/ # пайплайны Gitea Actions ``` -## Текущий фокус +Новый сервис — это каталог `services/<имя>/` и, когда решение уже принято, страница в `docs/<имя>/`. Привязка к конкретному хосту появляется в манифесте только там, где без неё нельзя доставить сервис. -Этап 0: проектирование и подготовка к развёртыванию **NetBird management** на новом арендованном VPS. См. `docs/netbird/design.md`. +## Сейчас -## Связанные ресурсы +Проектируем **NetBird management** на новом арендованном VPS. Решения и состав компонентов — в `docs/netbird/design.md`. Манифесты появятся в `services/netbird/` после аренды VPS. + +## Ресурсы -- Вики и разборы: Trilium → «Хоумлаб» (человекочитаемая документация) - Git: `https://gitea.gunihome.ru/karpenok/homelab-infra` diff --git a/docs/netbird/design.md b/docs/netbird/design.md index 656c5c1..758d2e5 100644 --- a/docs/netbird/design.md +++ b/docs/netbird/design.md @@ -1,69 +1,63 @@ # NetBird: архитектура overlay-сети -Статус: **проект (этап 0)**. VPS ещё не арендован — документ фиксирует принципы и открытые решения до начала развёртывания. +Статус: **проект**. VPS ещё не арендован. Документ фиксирует состав сервиса и решения, которые нужны до развёртывания. ## Задача -Построить overlay-сеть WireGuard (NetBird) как транспортный фундамент будущей инфраструктуры. Любой новый хост (VPS, LXC, ВМ, ноутбук) сначала вступает в сеть NetBird и только потом получает сервисы. Прямые SSH-связки «по белым IP» между хостами становятся необязательными. +NetBird — транспортный фундамент новой инфраструктуры. Новый хост (VPS, LXC, ВМ, ноутбук) сначала вступает в overlay и только потом получает сервисы. -## Компоненты NetBird (что разворачиваем на VPS) +Сервис не привязан к имени будущей машины. Меняется хост — меняется цель доставки, состав `services/netbird/` остаётся тем же. + +## Компоненты | Компонент | Назначение | Порты | | --- | --- | --- | | Management | control plane: пиры, политики, ключи, координация | 443/tcp, 33073/tcp (gRPC) | | Signal | обмен метаданными для установления соединений | 10000/tcp | -| Relay (TURN) | ретрансляция при невозможности p2p | 3478/udp | -| Dashboard | веб-панель управления | 443/tcp | -| IdP | аутентификация (встроенный Zitadel из официального установщика — по умолчанию) | — | +| Relay (TURN) | ретрансляция, если p2p не собрался | 3478/udp | +| Dashboard | веб-панель | 443/tcp | +| IdP | аутентификация. На старте — встроенный Zitadel | — | -Официальный путь развёртывания — скрипт `getting-started-with-zitadel.sh` + Docker Compose. Манифесты будут жить в `services/netbird/` и адаптированы под GitOps-доставку (Gitea Actions), а не запускаться руками. +Манифесты живут в `services/netbird/` и рассчитаны на доставку через Gitea Actions. Официальный установщик — ориентир по составу контейнеров, не способ запуска в проде. -## Требования к арендуемому VPS +## Требования к VPS | Параметр | Минимум | Комментарий | | --- | --- | --- | -| CPU / RAM | 1 vCPU / 1 ГБ | management лёгкий; запас — 2 vCPU / 2 ГБ | -| Диск | 20 ГБ | БД management (SQLite/Postgres) растёт медленно | -| Сеть | белый IP, IPv4 | стабильность важнее локации; пинг до дома < 100 мс желательно | -| ОС | Ubuntu 24.04 / Debian 12+ | под baseline-роль | -| Порты | 80, 443, 33073/tcp; 3478/udp | 10000/tcp если signal на том же хосте | +| CPU / RAM | 1 vCPU / 1 ГБ | запас — 2 vCPU / 2 ГБ | +| Диск | 20 ГБ | база management растёт медленно | +| Сеть | белый IPv4 | стабильность важнее локации | +| ОС | Ubuntu 24.04 или Debian 12+ | baseline хоста тоже из этого репозитория | +| Порты | 80, 443, 33073/tcp; 3478/udp | 10000/tcp, если signal на том же хосте | -80/tcp нужен только на выпуск Let's Encrypt; далее весь трафик — 443. +80/tcp нужен на выпуск Let's Encrypt. Дальше трафик панели и management идёт на 443. -## Принципы адресации и групп +## Адресация и группы -Overlay-адреса NetBird (100.64.0.0/10) не пересекаются с LAN 192.168.1.0/24 — конфликтов маршрутизации не будет. +Overlay NetBird — `100.64.0.0/10`. -Группы (проект, подлежит уточнению при первом развёртывании): +Группы описывают роль пира, не имя хоста. Состав группы меняется без смены политики. -| Группа | Содержимое (будущее) | Политика (проект) | +| Группа | Кто в ней | Политика | | --- | --- | --- | -| `infra-core` | management VPS, будущие управляющие узлы | доступно всем группам (DNS/маршруты) | -| `servers` | боевые VPS | SSH из `admin` | -| `homelab` | домашние LXC/ВМ после миграции | SSH из `admin`, сервисы внутри группы | -| `workstations` | ПК, ноутбуки | доступ к `servers` и `homelab` по ACL | -| `iot` | умный дом, камеры | изолированно, только нужное | +| `infra-core` | management и будущие управляющие узлы | DNS и маршруты, которые нужны остальным группам | +| `servers` | VPS с сервисами | SSH из `admin` | +| `workstations` | ПК и ноутбуки | доступ к `servers` по ACL | +| `iot` | умный дом, камеры | только явно разрешённые направления | -Политики по умолчанию: запрет всего, что не разрешено явно (default-deny). +Политика по умолчанию — default-deny. -## Открытые решения (принять до развёртывания) +## Решения до аренды VPS -1. **Домен** — поддомен `gunihome.ru` (например, `nb.gunihome.ru`). Кто добавляет DNS-запись: вручную или через API провайдера (для будущей автоматизации)? -2. **IdP** — встроенный Zitadel (проще, рекомендация для старта) или внешний (Keycloak/Authentik — позже, если появится единый SSO). -3. **Хостинг** — провайдер и локация выбраны? Влияет только на пинг/цену. -4. **Бэкапы management** — SQLite/Postgres management: периодический снимок в существующий PBS (`192.168.1.49`) или внешнее хранилище. Решить до продакшн-нагрузки. +1. **Домен.** Поддомен `gunihome.ru` для management и dashboard. Кто создаёт DNS-запись: вручную или через API. +2. **IdP.** На старте встроенный Zitadel. Внешний IdP — отдельное решение, когда появится общий SSO. +3. **Хостинг.** Провайдер и локация. На состав сервиса не влияют. +4. **Бэкап базы management.** Куда складывать снимок и как часто. Решить до появления пиров кроме рабочей станции. -## План развёртывания (кратко) +## Развёртывание -1. Аренда VPS → запись в `INVENTORY.md` + hosts/. -2. Baseline хоста: пользователь `deploy`, SSH-ключ, firewall (только нужные порты), Docker — **через код** (первый Ansible-плейбук или bootstrap-скрипт репозитория). -3. `services/netbird/` → commit → доставка на VPS (на этапе 1 — вручную через SSH по готовому runbook, Gitea Actions подключаем сразу после). -4. Выпуск сертификата, вход в dashboard, создание групп и политик из раздела выше. -5. Первый пир — рабочая станция (CachyOS). Проверка: пинг по overlay-адресу, SSH через NetBird IP. -6. Только после этого — подключение остальных хостов по одному. - -## Что сознательно не делаем сейчас - -- Миграция существующих сервисов и хостов в overlay — отдельный этап, отдельный план. -- Отказ от старой сети 192.168.1.0/24 — нет, она остаётся legacy до миграции. -- Развёртывание NetBird на `golova` (там уже есть инстанс) — не трогаем; новый management поднимаем на чистом VPS. +1. Аренда VPS. В репозитории появляется цель доставки, не отдельный каталог «хост». +2. Baseline через код: пользователь `deploy`, SSH-ключ, firewall на порты из таблицы выше, Docker. +3. Манифесты `services/netbird/` коммитятся и доставляются на VPS. Пока runner не подключён — по runbook из `services/netbird/README.md`, сразу следом — Gitea Actions. +4. Сертификат, вход в dashboard, группы и политики из этого документа. +5. Первый пир — рабочая станция. Проверка: пинг по overlay-адресу и SSH на management по адресу NetBird. diff --git a/hosts/.gitkeep b/hosts/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/services/netbird/README.md b/services/netbird/README.md index 1cda1ea..5d4a8d2 100644 --- a/services/netbird/README.md +++ b/services/netbird/README.md @@ -1,11 +1,11 @@ # services/netbird -Манифесты NetBird management (compose, конфигурационные шаблоны). +Манифесты NetBird: management, signal, relay, dashboard. -Появятся на этапе развёртывания — после аренды VPS и принятия решений из `docs/netbird/design.md`. Здесь будут: +Появятся после аренды VPS и ответов на вопросы из `docs/netbird/design.md`: -- `docker-compose.yml` — management, signal, dashboard, coturn -- `management.json.template` — шаблон конфигурации с переменными `${VAR}` (секреты подставляются из Gitea Actions Secrets) -- `README.md` — runbook развёртывания +- `docker-compose.yml` — сервисы NetBird +- `management.json.template` — конфигурация с плейсхолдерами `${VAR}` +- runbook развёртывания в этом файле -Секреты (домен, ключи шифрования, пароли TURN, IdP) — только через переменные окружения, значения — в Gitea Actions Secrets. См. `AGENTS.md`. +Секреты (домен, ключи шифрования, пароли TURN, IdP) задаются переменными. Значения лежат в Gitea Actions Secrets или в локальном `.env`, который не коммитится.