From e5f1ca24e5cfca584c1819c64c6489c6f9f6ba38 Mon Sep 17 00:00:00 2001 From: karpenok Date: Sat, 7 Nov 2026 22:47:20 +0700 Subject: [PATCH] =?UTF-8?q?chore(repo):=20=D0=BF=D0=B5=D1=80=D0=B2=D0=BE?= =?UTF-8?q?=D0=BD=D0=B0=D1=87=D0=B0=D0=BB=D1=8C=D0=BD=D1=8B=D0=B9=20=D1=81?= =?UTF-8?q?=D0=BA=D0=B5=D0=BB=D0=B5=D1=82=20=E2=80=94=20=D0=BF=D1=80=D0=B0?= =?UTF-8?q?=D0=B2=D0=B8=D0=BB=D0=B0=20=D0=B0=D0=B3=D0=B5=D0=BD=D1=82=D0=BE?= =?UTF-8?q?=D0=B2,=20=D0=B8=D0=BD=D0=B2=D0=B5=D0=BD=D1=82=D0=B0=D1=80?= =?UTF-8?q?=D1=8C,=20=D0=B4=D0=B8=D0=B7=D0=B0=D0=B9=D0=BD-=D0=B4=D0=BE?= =?UTF-8?q?=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=20NetBird?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/.gitkeep | 0 .gitignore | 23 ++++++++++++ AGENTS.md | 44 +++++++++++++++++++++++ INVENTORY.md | 71 ++++++++++++++++++++++++++++++++++++++ README.md | 33 ++++++++++++++++++ docs/netbird/design.md | 69 ++++++++++++++++++++++++++++++++++++ hosts/.gitkeep | 0 services/netbird/README.md | 11 ++++++ 8 files changed, 251 insertions(+) create mode 100644 .gitea/workflows/.gitkeep create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 INVENTORY.md create mode 100644 README.md create mode 100644 docs/netbird/design.md create mode 100644 hosts/.gitkeep create mode 100644 services/netbird/README.md diff --git a/.gitea/workflows/.gitkeep b/.gitea/workflows/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..162dcdb --- /dev/null +++ b/.gitignore @@ -0,0 +1,23 @@ +# Секреты и локальные файлы +.env +.env.* +!.env.example +*.key +*.pem +id_rsa* +*.token +secrets/ +vault_pass.txt + +# Инфраструктурные артефакты +*.tfstate +*.tfstate.* +.terraform/ +*.tfvars + +# Служебное +.DS_Store +*.log +*.bak +*.tmp +.kimi-code/local.toml diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0e353dd --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,44 @@ +# Правила для AI-агентов + +Ты — DevOps/SRE-ассистент, управляющий личной инфраструктурой на базе Docker Compose и GitOps (Gitea Actions). Этот файл — системные инструкции. Соблюдай их без напоминаний. + +## Контекст + +- Репозиторий `homelab-infra` — единственный источник правды об инфраструктуре. +- Инфраструктура строится вокруг overlay-сети **NetBird**: новые хосты и сервисы сначала подключаются к сети, потом получают роли. +- Хосты и группы сервисов **меняются со временем**. Не закрепляй конфигурацию за конкретными именами машин, если это не обязательно. Сервисы первичны. +- Человекочитаемая документация живёт в Trilium (MCP-сервер `trilium` доступен в сессии) — дерево «Хоумлаб». + +## Границы (критически важно) + +1. **Рабочая инфраструктура (Iterika) — запретная зона.** Не подключайся и не изменяй хосты из рабочего SSH-конфига (`pve203`, `pve215`, `pve216`, `stata`, `bastion`, `billing` и остальные из `~/.ssh/config.d/work.conf`). Не читай заметки Trilium из ветки «Работа». +2. **Секреты не хардкодить.** Никаких паролей, токенов, приватных ключей в манифестах и документах. Используй переменные окружения (`${VAR}`) и шаблоны (`*.template`). Реальные значения — только в Gitea Actions Secrets или локально в `.env` (в `.gitignore`). +3. **Ничего не исполнять на хостах напрямую**, кроме явно read-only команд диагностики (`docker ps`, `df -h`, `systemctl status` и т.п.), и только после подтверждения пользователем. +4. Деструктивные действия (удаление данных, рестарты боевых сервисов, правка фаервола) — только с явного подтверждения пользователя (human-in-the-loop). + +## Технические стандарты + +- Только **Docker Compose v2** (`docker compose`, не `docker-compose`). Ключ `version:` в compose-файлах не указывать. +- Образы **пинить по версии**, не использовать `:latest` в новых манифестах. +- Служебные порты (БД, кэши, админки) не публиковать наружу (`0.0.0.0`): только `127.0.0.1` или внутренние Docker-сети. +- Перед коммитом compose-манифеста проверять синтаксис: `docker compose -f <путь> config > /dev/null`. +- Документация и комментарии — на русском, идентификаторы — на английском. + +## Коммиты (Conventional Commits) + +Формат: `<тип>(<область>): <описание>` на русском. + +- `feat(netbird): ...` — новая функциональность +- `fix(hosts): ...` — исправление +- `docs(design): ...` — только документация +- `chore(repo): ...` — обслуживание репозитория + +Примеры: +- `feat(netbird): набросок архитектуры management-сервера` +- `docs(inventory): актуализация карты VPS-нод` + +## Ветвление + +- `main` — рабочее состояние. Прямой push в main допустим на этапе 0 (проектирование). +- Для изменений, затрагивающих развёрнутые сервисы, — ветка `feature/<имя>` → pull request → проверка diff → merge. +- Черновики и незаконченное — ветки `wip/<имя>`. diff --git a/INVENTORY.md b/INVENTORY.md new file mode 100644 index 0000000..d813555 --- /dev/null +++ b/INVENTORY.md @@ -0,0 +1,71 @@ +# 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 new file mode 100644 index 0000000..8c0b489 --- /dev/null +++ b/README.md @@ -0,0 +1,33 @@ +# homelab-infra + +Инфраструктура как код для личной сети: домашний homelab, внешние VPS и overlay-сеть на базе NetBird. + +## Идея + +Репозиторий — единственный источник правды о состоянии инфраструктуры. Правки на хостах вручную по SSH не вносятся: изменения коммитятся сюда, доставка — через Gitea Actions (GitOps). + +**Принцип: сервисы первичны, хосты — заменяемы.** Конфигурация сервисов не привязана к конкретным машинам. Хосты и группы сервисов на них будут меняться — структура каталогов это учитывает. + +## Структура + +``` +homelab-infra/ +├── AGENTS.md # правила для AI-агентов, работающих в этом репозитории +├── INVENTORY.md # карта инфраструктуры (хосты, IP, роли, статусы) +├── docs/ +│ └── netbird/ # архитектура overlay-сети NetBird +├── services/ +│ └── netbird/ # манифесты NetBird (management, signal, relay) +├── hosts/ # описания хостов (по одному каталогу на узел) +└── .gitea/ + └── workflows/ # пайплайны Gitea Actions +``` + +## Текущий фокус + +Этап 0: проектирование и подготовка к развёртыванию **NetBird management** на новом арендованном VPS. См. `docs/netbird/design.md`. + +## Связанные ресурсы + +- Вики и разборы: Trilium → «Хоумлаб» (человекочитаемая документация) +- Git: `https://gitea.gunihome.ru/karpenok/homelab-infra` diff --git a/docs/netbird/design.md b/docs/netbird/design.md new file mode 100644 index 0000000..656c5c1 --- /dev/null +++ b/docs/netbird/design.md @@ -0,0 +1,69 @@ +# NetBird: архитектура overlay-сети + +Статус: **проект (этап 0)**. VPS ещё не арендован — документ фиксирует принципы и открытые решения до начала развёртывания. + +## Задача + +Построить overlay-сеть WireGuard (NetBird) как транспортный фундамент будущей инфраструктуры. Любой новый хост (VPS, LXC, ВМ, ноутбук) сначала вступает в сеть NetBird и только потом получает сервисы. Прямые SSH-связки «по белым IP» между хостами становятся необязательными. + +## Компоненты NetBird (что разворачиваем на VPS) + +| Компонент | Назначение | Порты | +| --- | --- | --- | +| Management | control plane: пиры, политики, ключи, координация | 443/tcp, 33073/tcp (gRPC) | +| Signal | обмен метаданными для установления соединений | 10000/tcp | +| Relay (TURN) | ретрансляция при невозможности p2p | 3478/udp | +| Dashboard | веб-панель управления | 443/tcp | +| IdP | аутентификация (встроенный Zitadel из официального установщика — по умолчанию) | — | + +Официальный путь развёртывания — скрипт `getting-started-with-zitadel.sh` + Docker Compose. Манифесты будут жить в `services/netbird/` и адаптированы под GitOps-доставку (Gitea Actions), а не запускаться руками. + +## Требования к арендуемому 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 на том же хосте | + +80/tcp нужен только на выпуск Let's Encrypt; далее весь трафик — 443. + +## Принципы адресации и групп + +Overlay-адреса NetBird (100.64.0.0/10) не пересекаются с LAN 192.168.1.0/24 — конфликтов маршрутизации не будет. + +Группы (проект, подлежит уточнению при первом развёртывании): + +| Группа | Содержимое (будущее) | Политика (проект) | +| --- | --- | --- | +| `infra-core` | management VPS, будущие управляющие узлы | доступно всем группам (DNS/маршруты) | +| `servers` | боевые VPS | SSH из `admin` | +| `homelab` | домашние LXC/ВМ после миграции | SSH из `admin`, сервисы внутри группы | +| `workstations` | ПК, ноутбуки | доступ к `servers` и `homelab` по ACL | +| `iot` | умный дом, камеры | изолированно, только нужное | + +Политики по умолчанию: запрет всего, что не разрешено явно (default-deny). + +## Открытые решения (принять до развёртывания) + +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. Аренда 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. diff --git a/hosts/.gitkeep b/hosts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/services/netbird/README.md b/services/netbird/README.md new file mode 100644 index 0000000..1cda1ea --- /dev/null +++ b/services/netbird/README.md @@ -0,0 +1,11 @@ +# services/netbird + +Манифесты NetBird management (compose, конфигурационные шаблоны). + +Появятся на этапе развёртывания — после аренды VPS и принятия решений из `docs/netbird/design.md`. Здесь будут: + +- `docker-compose.yml` — management, signal, dashboard, coturn +- `management.json.template` — шаблон конфигурации с переменными `${VAR}` (секреты подставляются из Gitea Actions Secrets) +- `README.md` — runbook развёртывания + +Секреты (домен, ключи шифрования, пароли TURN, IdP) — только через переменные окружения, значения — в Gitea Actions Secrets. См. `AGENTS.md`.