Prometheus остаётся для LAN. Нода отдаёт метрики через vmagent, а панель ходит на неё по отдельному ключу NetBird, не через группу роутеров. Co-authored-by: Cursor <cursoragent@cursor.com>
19 KiB
Инструкция по развертыванию инфраструктуры (Bootstrap Guide)
Плейбук называется машиной. В roles/<машина>/ лежат продукты этой машины: один каталог, один Compose, один путь /opt/<продукт>. База и кэш остаются внутри Compose этого продукта. Роль host стоит отдельно: она готовит любую машину и ни одному продукту не принадлежит.
Пайплайн подключается к машине, а применяет только роли, чьи файлы изменились (--tags). Роль host ставит пакеты, Docker и SSH. Она вызывается только из playbooks/host.yml, который подключает site.yml. Полный прогон и ручной запуск идут через site.yml --limit <машина>, поэтому подготовка машины выполняется один раз вместе с продуктами. Плейбук отдельной машины продукты ставит, машину не готовит.
| Машина | Плейбук | Роли | Каталоги |
|---|---|---|---|
core-net |
playbooks/core-net.yml |
roles/core-net/traefik; roles/core-net/netbird; roles/core-net/remnawave; roles/core-net/vmagent; roles/core-net/authentik (опц., по умолчанию выкл.) |
/opt/traefik; клиент NetBird; /opt/remnawave; /opt/vmagent; /opt/authentik (если включён) |
core-secrets |
playbooks/core-secrets.yml |
roles/core-secrets/infisical, roles/core-secrets/vaultwarden |
/opt/infisical, /opt/vaultwarden |
core-mon |
playbooks/core-mon.yml |
roles/core-mon/monitoring |
/opt/monitoring (Prometheus и VictoriaMetrics) |
rus-central |
playbooks/rus-central.yml |
roles/rus-central/netbird |
/opt/netbird |
ger-nod-02 |
playbooks/ger-nod-02.yml |
roles/ger-nod-02/netbird; roles/ger-nod-02/remnanode; roles/ger-nod-02/vmagent |
клиент NetBird; /opt/remnanode; /opt/vmagent |
opnsense |
playbooks/opnsense.yml |
roles/opnsense/netbird |
REST API (192.168.1.1) |
Полная сверка одной машины: ansible-playbook playbooks/site.yml --limit <машина>. Gitea в автоматизацию не входит: без неё не запустить пайплайны.
1. Топология инфраструктуры
1.1. Физические узлы и гипервизоры (Proxmox VE)
| Узел | IP | Роль | SSH / Доступ |
|---|---|---|---|
| netcore | 192.168.1.100:8006 |
PVE Cluster Node / Core CTs | root@192.168.1.100 (LAN only) |
| pve | 192.168.1.2:8006 |
PVE Main Node / Services | root@192.168.1.2 (LAN only) |
| opnsense | 192.168.1.1 |
Маршрутизатор / Шлюз | Шлюз по умолчанию |
Terraform в этом репозитории описывает только узел netcore. Узел pve и CT 109 поднимаются отдельно.
1.2. Базовые управляющие контейнеры (LXC / Debian 13)
| CT ID | Хост PVE | IP | Имя хоста | Продукты |
|---|---|---|---|---|
| CT 109 | pve |
192.168.1.217 |
gitea |
Gitea (:3000), Postgres (:5432), Gitea Actions Runner (dind) |
| CT 901 | netcore |
192.168.1.102 |
core-secrets |
Infisical (:8080), Postgres, Redis, Vaultwarden (:8000) |
| CT 902 | netcore |
192.168.1.104 |
core-net |
Traefik (:80, :443); Remnawave Panel (127.0.0.1:3000) + Subscription (127.0.0.1:3010); Authentik (127.0.0.1:9000) — опционально, по умолчанию выкл. |
| CT 903 | netcore |
192.168.1.108 |
core-mon |
Prometheus (:9090), VictoriaMetrics (:8428), Alertmanager (:9093), Grafana (:3000), Ntfy (:80) |
1.3. Внешние узлы
| Имя | IP | Роль | Стек |
|---|---|---|---|
| rus-central | 45.154.185.208 |
Внешний шлюз NetBird | /opt/netbird: NetBird и его собственный Traefik |
| ger-nod-02 | 150.241.64.209 |
Remnawave Node (DE) + SelfSteal | /opt/remnanode: remnanode + nginx (yali.gunis.top) |
Домен панели NetBird задаётся в ansible/inventories/prod/host_vars/rus-central.yml.
Старая панель на Голове (remna.gunihome.ru) не входит в эту автоматизацию и не трогается.
ansible/roles/core-net/traefik/files/dynamic/ — известный бардак: плоский список старых и новых маршрутов. Имена вроде tv.yml — это поддомены, а не описание сервиса. Каталог разбирается после того, как вся старая инфраструктура переедет на роли машин. До этого файлы оттуда не переименовывать и не раскладывать. Подробности — в README.md внутри каталога.
2. Структура секретов в Infisical
Проект: infra (Slug: infra-xxx, Environment: prod)
API Endpoint (внутренний LAN): http://192.168.1.102:8080/api
Внешний URL: https://infisical.gunihome.ru
Пути секретов:
/USER/ADMIN:ADMIN_USER: имя администратора хоумлаба (по умолчаниюkarpenok).ADMIN_PASSWORD: единый пароль администратора (Traefik Dashboard, Grafana, Ntfy, NetBird).MAIL_ADMIN_USER: почта администратора (для Grafana, NetBird и алертов).
/ci-cd:RUNNER_SSH_KEY: приватный SSH-ключ раннера (ed25519) для деплоя на хосты.TF_STATE_TOKEN: токен доступа к HTTP State Backend Gitea.CLOUDFLARE_API: API-токен Cloudflare (Zone DNS Edit дляgunis.top, DNS-01 сертификаты ноды).
/VPS:PASS_GER_NOD_02: первичный root-парольger-nod-02(только bootstrap; после ролиhostвход по ключу).
/services/infisical:POSTGRES_PASSWORD: пароль БД Infisical.ENCRYPTION_KEY: 32-байтный hex-ключ шифрования хранилища.AUTH_SECRET: base64 секрет сессий/JWT Infisical.
/services/authentik(нужен только если включите Authentik):AUTHENTIK_SECRET_KEY: случайный ключ шифрования сессий Authentik.AUTHENTIK_POSTGRES_PASSWORD: пароль БД PostgreSQL Authentik.
/services/netbird:NETBIRD_LETSENCRYPT_EMAIL: почта для сертификата. Если секрета нет, берётсяletsencrypt_emailизgroup_vars/all.ymlилиMAIL_ADMIN_USER.NETBIRD_AUTH_SECRET: секрет auth.NETBIRD_DATASTORE_KEY: 32-байтный ключ SQLite/datastore.NETBIRD_SESSION_KEY: 32-байтный ключ веб-сессий.NETBIRD_API_TOKEN: сервисный API-токен управления (создаётся и сохраняется пайплайном автоматически).NETBIRD_SETUP_KEY: многоразовый ключ регистрации роутеров (homelab-routers). Панель и ноды им не пользуются.NETBIRD_REMNAWAVE_SETUP_KEY: многоразовый ключremnawave-peersдля core-net и ger-nod-02. В группу роутеров не входит.- (Параметры
NETBIRD_ADMIN_NAME,NETBIRD_ADMIN_PASSWORD,NETBIRD_ADMIN_EMAILнаследуются из/USER/ADMIN).
/services/opnsense:OPNSENSE_API_KEY: API-ключ администратора OPNsense.OPNSENSE_API_SECRET: API-секрет администратора OPNsense.
/services/remnawave:REMNAWAVE_ADMIN_USER/REMNAWAVE_ADMIN_PASSWORD: логин панели (Remnawave v3 требует пароль ≥24 с upper+lower+digit). Генерируются пайплайном при первом прогоне; не путать с/USER/ADMIN.REMNAWAVE_APP_SECRET,REMNAWAVE_POSTGRES_PASSWORD,REMNAWAVE_METRICS_PASS,REMNAWAVE_WEBHOOK_SECRET_HEADER: генерируются пайплайном при первом прогоне, если пусто.REMNAWAVE_API_TOKEN: сервисный API-токен панели (infra-automation, scopes*), создаётся и сохраняется пайплайном (при сбое — создать в UI и положить сюда вручную).REMNANODE_SECRET_KEY: SECRET_KEY ноды Ger-nod-02 (GET /api/keygen/), сохраняется пайплайном.XRAY_CHECKER_SUBSCRIPTION_URL: ссылка подписки пользователяhomelabдля Xray Checker на core-mon. В лог не пишется.
/proxmox/netcore:PROXMOX_ENDPOINT:https://192.168.1.100:8006/PROXMOX_API_TOKEN: токенroot@pam!terraform=UUID
Провайдер Proxmox сам дописывает /api2/json. В секрет его класть не нужно. Секреты /proxmox/pve этот репозиторий не читает: Terraform описывает только узел netcore.
3. Последовательность холодного старта (Cold Bootstrap)
При полном отказе всех систем порядок восстановления следующий:
Шаг 1. Гипервизоры и сеть
- Поднять OPNsense (
192.168.1.1). - Запустить Proxmox VE на
netcore(192.168.1.100) иpve(192.168.1.2). - Убедиться в доступности SSH по ключам
root_home.
Шаг 2. Gitea & Gitea Actions (CT 109)
- Запустить CT 109 на
pve. - Запустить стек Gitea:
docker compose up -dв каталоге Gitea. - Проверить доступность UI по адресу
http://192.168.1.217:3000. - Убедиться, что раннер
gitea-runnerподключен и имеет статусidle.
Шаг 3. Хранилище секретов Infisical (CT 901)
Important
Мастер-ключи начальной загрузки Infisical (
ENCRYPTION_KEY,AUTH_SECRET,POSTGRES_PASSWORD) являются первоисточником шифрования и физически не могут храниться внутри самого Infisical. Они должны быть надежно сохранены в личном оффлайн-менеджере паролей администратора (KeePassXC / Bitwarden / 1Password).
- Создать/запустить CT 901 (
core-secrets, IP192.168.1.102). - Для первого старта вручную положить Compose Infisical в
/opt/infisical/compose.yamlи подставить мастер-ключи из оффлайн-хранилища. Пайплайну эти ключи пока неоткуда прочитать. - Запустить контейнеры:
docker compose -f /opt/infisical/compose.yaml up -d. - Проверить API:
curl http://192.168.1.102:8080/api/status. - В Gitea Settings → Secrets добавить репозиторные секреты:
INFISICAL_CLIENT_ID(Machine Identity:ci-cd-runner)INFISICAL_CLIENT_SECRET
Дальше стек ведёт пайплайн ansible-core-secrets: Infisical в /opt/infisical, Vaultwarden в /opt/vaultwarden.
Шаг 4. Traefik (CT 902)
- Запустить пайплайн
ansible-core-netв Gitea Actions. Первый прогон на новом CT должен быть полным: ручной запуск выполняетsite.yml --limit core-netи ставит Docker рольюhost. - Раннер подключается к
http://192.168.1.102:8080/api, забирает SSH-ключ раннера иADMIN_*из Infisical. Панель Traefik (proxy.gunihome.ru) закрывается BasicAuth из/USER/ADMIN. - Плейбук поднимает Traefik на CT 902. Роль Authentik в плейбуке есть, но по умолчанию выключена (
authentik_enabled=falseв defaults и в CI): compose не стартует, стек на cold bootstrap не нужен. - Проверить
https://proxy.gunihome.ru,https://gitea.gunihome.ruиhttps://infisical.gunihome.ru.
Правка только роли traefik ставит эту роль, без повторной подготовки машины.
Authentik (опционально, не часть cold bootstrap)
Стек оставляем в репозитории на будущее: SSO/forwardAuth для выбранных приложений, не для всего edge сразу.
Чтобы включить:
- Положить секреты в Infisical
/services/authentik(AUTHENTIK_SECRET_KEY,AUTHENTIK_POSTGRES_PASSWORD). - Убрать принудительный
-e authentik_enabled=falseизansible/ci/deploy-machine.sh(или передатьauthentik_enabled=trueпри ручном прогоне) и выставитьauthentik_enabled: true. - Прогнать
ansible-core-net(или--tags authentik): стек слушает127.0.0.1:9000, снаружи —https://auth.gunihome.ru. Blueprints заводят группыadmins/familyи пользователейkarpenok/ksynia; пароли blueprint не задаёт. Первый запуск создаётakadmin(пароль в логеauthentik-server). - На нужных роутерах Traefik повесить middleware
authentik(forwardAuth изroles/core-net/traefik/files/dynamic/authentik.yml) — точечно, не на все сервисы.
Remnawave Panel + Subscription (на core-net)
Новая панель рядом с Traefik. Старый remna.gunihome.ru на Голове не затрагивается.
- В Infisical положить:
/ci-cd→CLOUDFLARE_API/VPS→PASS_GER_NOD_02(пароль нового VPS)
- Запустить
ansible-core-net(полный прогон или--tags remnawaveпосле того, как Traefik уже с роутамиrw/sub). - Роль поднимает
/opt/remnawave(panel+db+redis) и/opt/remnawave/subscription, создаётREMNAWAVE_ADMIN_*, каждый прогон перевыпускает API-токенinfra-automationи кладёт его в Infisical (старый сразу недействителен). Config profileDE-Yali, сквадDefault-Squadна inbound Steal-Yali, нодаGer-nod-02, hostyali.gunis.top. Пользователи — файлansible/roles/core-net/remnawave/files/users.yml(добавление/изменение/удаление = правка файла). Когда peerger-nod-02уже есть в NetBird, адрес ноды в панели меняется на его NetBird IP. Пока peer нет, остаётся150.241.64.209. Ссылка подпискиhomelabпишется вXRAY_CHECKER_SUBSCRIPTION_URLи в лог не попадает. - Проверить
https://rw.gunihome.ruиhttps://sub.gunihome.ru.
Important
Логи: шаги bootstrap и ошибки API видны в CI. Значения ключей туда не пишутся: stdout — только статус, секреты лежат в
/opt/remnawave/.bootstrap-secrets.json(0600).no_logтолько у чтения этого файла, записи в Infisical и шаблона.env. В stderr поляtoken/SECRET_KEY/privateKey/shortUuid/ пароли клиентов заменяются на[REDACTED].
Шаг 4b. Remnawave Node ger-nod-02 (SelfSteal)
- После успешного
ansible-core-net(чтобы в Infisical былREMNANODE_SECRET_KEY) запуститьansible-ger-nod-02. - Первый прогон: как у rus-central —
ansible_passwordиз/VPS→PASS_GER_NOD_02; рольhostкладёт ключ и отключает пароль. Рольremnanodeдержит A-записьyali.gunis.topв Cloudflare, выпускает LE по HTTP-01 (порт 80, без TXT_acme-challengeв зоне), поднимает remnanode + nginx SelfSteal. - В панели нода должна стать зелёной; браузер на
https://yali.gunis.top— маскировочный сайт. - Клиент NetBird ходит на
https://central.gunihome.ruключомremnawave-peers. Пока peer панели не виден,NODE_PORT2222 остаётся открыт для WAN egress панели. Когда peercore-netесть, 2222 разрешён только с его NetBird IP. Публичный:9100закрыт: метрики ноды уходят vmagent-ом в VictoriaMetrics на192.168.1.108:8428через маршрутhomelab-lan. В Prometheus эта нода больше не входит.
Шаг 5. NetBird (rus-central) и связка с OPNsense
- Запустить пайплайн
ansible-rus-centralв Gitea Actions. Ручной запуск сверяет машину целиком. Push вroles/rus-central/netbirdставит только NetBird. - Раннер считывает ключи из
/services/netbird, деплоит стек в/opt/netbirdна45.154.185.208, автоматически регистрирует первого суперпользователя (POST /api/setup), создаёт сервисный токен (NETBIRD_API_TOKEN), группуhomelab-routers, маршрут к подсети192.168.1.0/24и многоразовый ключ установки (NETBIRD_SETUP_KEY). Отдельно создаётся группаremnawaveи ключremnawave-peers(NETBIRD_REMNAWAVE_SETUP_KEY): он не добавляет peer вhomelab-routers. Оба ключа сохраняются в Infisical. - Запустить пайплайн
ansible-opnsenseв Gitea Actions. Раннер обращается по HTTPS REST API к192.168.1.1, проверяет/устанавливает плагинos-netbird, включает службу и регистрирует шлюз OPNsense наhttps://central.gunihome.ru:443поNETBIRD_SETUP_KEY.