Files
homelab-infra/BOOTSTRAP.md
T
karpenokandCursor 0a56b935de
ansible-rus-central / deploy (push) Canceled after 0s
ansible-opnsense / deploy (push) Canceled after 0s
ansible-core-secrets / deploy (push) Canceled after 0s
ansible-core-net / deploy (push) Canceled after 0s
ansible-core-mon / deploy (push) Canceled after 24s
ansible-ger-nod-02 / deploy (push) Successful in 4m1s
fix(ger-nod-02): пароль как у central, HTTP-01 без ACME TXT, кавычки SECRET_KEY
Падение было на :443 — SECRET_KEY без кавычек ломал ноду.
DNS-01 убран: LE через standalone HTTP-01, старые _acme-challenge чистим.
ansible_password только из /VPS; host в плейбуке как у rus-central.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-11 23:20:02 +07:00

16 KiB
Raw Blame History

Инструкция по развертыванию инфраструктуры (Bootstrap Guide)

Плейбук называется машиной. В roles/<машина>/ лежат продукты этой машины: один каталог, один Compose, один путь /opt/<продукт>. База и кэш остаются внутри Compose этого продукта. Роль host стоит отдельно: она готовит любую машину и ни одному продукту не принадлежит.

Пайплайн подключается к машине, а применяет только роли, чьи файлы изменились (--tags). Роль host ставит пакеты, Docker и SSH. Она выполняется вместе со всеми продуктами машины, когда меняются плейбук, инвентарь или сама роль host, и при ручном запуске.

Машина Плейбук Роли Каталоги
core-net playbooks/core-net.yml roles/core-net/traefik; roles/core-net/remnawave; roles/core-net/authentik (опц., по умолчанию выкл.) /opt/traefik; /opt/remnawave; /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
rus-central playbooks/rus-central.yml roles/rus-central/netbird /opt/netbird
ger-nod-02 playbooks/ger-nod-02.yml roles/ger-nod-02/remnanode /opt/remnanode
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), 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) не входит в эту автоматизацию и не трогается.


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: многоразовый ключ регистрации узлов (создаётся и сохраняется пайплайном автоматически).
    • (Параметры 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/), сохраняется пайплайном.
  • /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. Гипервизоры и сеть

  1. Поднять OPNsense (192.168.1.1).
  2. Запустить Proxmox VE на netcore (192.168.1.100) и pve (192.168.1.2).
  3. Убедиться в доступности SSH по ключам root_home.

Шаг 2. Gitea & Gitea Actions (CT 109)

  1. Запустить CT 109 на pve.
  2. Запустить стек Gitea: docker compose up -d в каталоге Gitea.
  3. Проверить доступность UI по адресу http://192.168.1.217:3000.
  4. Убедиться, что раннер gitea-runner подключен и имеет статус idle.

Шаг 3. Хранилище секретов Infisical (CT 901)

Important

Мастер-ключи начальной загрузки Infisical (ENCRYPTION_KEY, AUTH_SECRET, POSTGRES_PASSWORD) являются первоисточником шифрования и физически не могут храниться внутри самого Infisical. Они должны быть надежно сохранены в личном оффлайн-менеджере паролей администратора (KeePassXC / Bitwarden / 1Password).

  1. Создать/запустить CT 901 (core-secrets, IP 192.168.1.102).
  2. Для первого старта вручную положить Compose Infisical в /opt/infisical/compose.yaml и подставить мастер-ключи из оффлайн-хранилища. Пайплайну эти ключи пока неоткуда прочитать.
  3. Запустить контейнеры: docker compose -f /opt/infisical/compose.yaml up -d.
  4. Проверить API: curl http://192.168.1.102:8080/api/status.
  5. В 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)

  1. Запустить пайплайн ansible-core-net в Gitea Actions. Первый прогон на новом CT должен быть полным: ручной запуск выполняет site.yml --limit core-net и ставит Docker ролью host.
  2. Раннер подключается к http://192.168.1.102:8080/api, забирает SSH-ключ раннера и ADMIN_* из Infisical. Панель Traefik (proxy.gunihome.ru) закрывается BasicAuth из /USER/ADMIN.
  3. Плейбук поднимает Traefik на CT 902. Роль Authentik в плейбуке есть, но по умолчанию выключена (authentik_enabled=false в defaults и в CI): compose не стартует, стек на cold bootstrap не нужен.
  4. Проверить https://proxy.gunihome.ru, https://gitea.gunihome.ru и https://infisical.gunihome.ru.

Правка только роли traefik ставит эту роль, без повторной подготовки машины.

Authentik (опционально, не часть cold bootstrap)

Стек оставляем в репозитории на будущее: SSO/forwardAuth для выбранных приложений, не для всего edge сразу.

Чтобы включить:

  1. Положить секреты в Infisical /services/authentik (AUTHENTIK_SECRET_KEY, AUTHENTIK_POSTGRES_PASSWORD).
  2. Убрать принудительный -e authentik_enabled=false из ansible/ci/deploy-machine.sh (или передать authentik_enabled=true при ручном прогоне) и выставить authentik_enabled: true.
  3. Прогнать ansible-core-net (или --tags authentik): стек слушает 127.0.0.1:9000, снаружи — https://auth.gunihome.ru. Blueprints заводят группы admins/family и пользователей karpenok/ksynia; пароли blueprint не задаёт. Первый запуск создаёт akadmin (пароль в логе authentik-server).
  4. На нужных роутерах Traefik повесить middleware authentik (forwardAuth из roles/core-net/traefik/files/dynamic/authentik.yml) — точечно, не на все сервисы.

Remnawave Panel + Subscription (на core-net)

Новая панель рядом с Traefik. Старый remna.gunihome.ru на Голове не затрагивается.

  1. В Infisical положить:
    • /ci-cd → CLOUDFLARE_API
    • /VPS → PASS_GER_NOD_02 (пароль нового VPS)
  2. Запустить ansible-core-net (полный прогон или --tags remnawave после того, как Traefik уже с роутами rw/sub).
  3. Роль поднимает /opt/remnawave (panel+db+redis) и /opt/remnawave/subscription, создаёт REMNAWAVE_ADMIN_*, API-токен infra-automation, config profile DE-Yali, ноду Ger-nod-02, host yali.gunis.top, пишет токен и REMNANODE_SECRET_KEY в Infisical.
  4. Проверить https://rw.gunihome.ru и https://sub.gunihome.ru.

Important

Логи и новые установки Remnawave: задача bootstrap всегда с no_log: true. В stderr скрипта ответы API с privateKey / SECRET_KEY / JWT / API-токеном редáctятся ([REDACTED]). При отладке не снимать no_log и не printf сырой JSON keygen/x25519/tokens в CI — иначе Reality-ключи и токены утекут в Gitea Actions. Admin JWT к API v3 требует заголовок X-Remnawave-Client-Type: browser; постоянная автоматизация — только через REMNAWAVE_API_TOKEN (scopes *).

Шаг 4b. Remnawave Node ger-nod-02 (SelfSteal)

  1. После успешного ansible-core-net (чтобы в Infisical был REMNANODE_SECRET_KEY) запустить ansible-ger-nod-02.
  2. Первый прогон: как у 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.
  3. В панели нода должна стать зелёной; браузер на https://yali.gunis.top — маскировочный сайт.

Шаг 5. NetBird (rus-central) и связка с OPNsense

  1. Запустить пайплайн ansible-rus-central в Gitea Actions. Ручной запуск сверяет машину целиком. Push в roles/rus-central/netbird ставит только NetBird.
  2. Раннер считывает ключи из /services/netbird, деплоит стек в /opt/netbird на 45.154.185.208, автоматически регистрирует первого суперпользователя (POST /api/setup), создаёт сервисный токен (NETBIRD_API_TOKEN), группу homelab-routers, маршрут к подсети 192.168.1.0/24 и многоразовый ключ установки (NETBIRD_SETUP_KEY), после чего сохраняет NETBIRD_API_TOKEN и NETBIRD_SETUP_KEY в Infisical.
  3. Запустить пайплайн ansible-opnsense в Gitea Actions. Раннер обращается по HTTPS REST API к 192.168.1.1, проверяет/устанавливает плагин os-netbird, включает службу и регистрирует шлюз OPNsense на https://central.gunihome.ru:443 по NETBIRD_SETUP_KEY.