chore(repo): первоначальный скелет — правила агентов, инвентарь, дизайн-документ NetBird

This commit is contained in:
karpenok committed 2026-11-07 22:47:20 +07:00
commit e5f1ca24e5
8 files changed
+251

No files matched your search

View File
Whitespace-only changes.
+23
View File
@@ -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
+44
View File
@@ -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/<имя>`.
+71
View File
@@ -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-контуром; миграция хостов планируется отдельно, этот файл при миграции переписывается.
+33
View File
@@ -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`
+69
View File
@@ -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.
View File
Whitespace-only changes.
+11
View File
@@ -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`.