Files
homelab-infra/BOOTSTRAP.md
T
2026-11-10 19:40:54 +07:00

101 lines
6.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Инструкция по развертыванию инфраструктуры (Bootstrap Guide)
Данный документ описывает полную топологию хоумлаба, порядок холодного развертывания с нуля и структуру управления секретами через Infisical.
---
## 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` | Маршрутизатор / Шлюз | Шлюз по умолчанию |
### 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`, `:8080`), ACME Let's Encrypt |
### 1.3. Внешние узлы
| Имя | IP | Роль | Стек |
|---|---|---|---|
| **rus-central** | `45.154.185.208` | Внешний шлюз NetBird | Docker Compose: NetBird Management, Signal, Dashboard, Coturn |
---
## 2. Структура секретов в Infisical
Проект: **`infra`** (Slug: `infra-xxx`, Environment: `prod`)
API Endpoint (внутренний LAN): `http://192.168.1.102:8080/api`
Внешний URL: `https://infisical.gunihome.ru`
### Пути секретов:
- `/ci-cd`:
- `RUNNER_SSH_KEY`: приватный SSH-ключ раннера (ed25519) для деплоя на хосты.
- `TF_STATE_TOKEN`: токен доступа к HTTP State Backend Gitea.
- `/services/infisical`:
- `POSTGRES_PASSWORD`: пароль БД Infisical.
- `ENCRYPTION_KEY`: 32-байтный hex-ключ шифрования хранилища.
- `AUTH_SECRET`: base64 секрет сессий/JWT Infisical.
- `/services/traefik`:
- `TRAEFIK_DASHBOARD_AUTH`: строка basicAuth для дашборда (`user:$2y$05$...`).
- `/services/authentik`:
- `AUTHENTIK_SECRET_KEY`: случайный ключ шифрования сессий Authentik.
- `AUTHENTIK_POSTGRES_PASSWORD`: пароль БД PostgreSQL Authentik.
- `/services/netbird`:
- `COMPOSE_PROJECT_NAME`: имя docker compose проекта (`netbird`).
- `NETBIRD_DOMAIN`: домен панели NetBird.
- `NETBIRD_LETSENCRYPT_EMAIL`: email для SSL-сертификатов.
- `NETBIRD_AUTH_SECRET`: секрет auth.
- `NETBIRD_DATASTORE_KEY`: 32-байтный ключ SQLite/datastore.
- `NETBIRD_SESSION_KEY`: 32-байтный ключ веб-сессий.
- `/proxmox/netcore`:
- `PROXMOX_ENDPOINT`: `https://192.168.1.100:8006/api2/json`
- `PROXMOX_API_TOKEN`: токен `root@pam!terraform=UUID`
- `/proxmox/pve`:
- `PROXMOX_ENDPOINT`: `https://192.168.1.2:8006/api2/json`
- `PROXMOX_API_TOKEN`: токен `root@pam!terraform=UUID`
---
## 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. Развернуть `/opt/secrets/compose.yaml`, подставив мастер-ключи из оффлайн-хранилища.
3. Запустить контейнеры: `docker compose -f /opt/secrets/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`
### Шаг 4. Маршрутизатор Traefik (CT 902)
1. Запустить пайплайн **`ansible-core-net`** в Gitea Actions.
2. Раннер подключается напрямую к `http://192.168.1.102:8080/api`, забирает SSH-ключ раннера и `TRAEFIK_DASHBOARD_AUTH`, после чего накатывает конфигурацию Traefik на CT 902.
3. Проверить вход на внешние домены (`gitea.gunihome.ru`, `infisical.gunihome.ru`).
### Шаг 5. Внешние сервисы (NetBird на VPS)
1. Запустить пайплайн **`netbird-install`** в Gitea Actions.
2. Раннер считывает боевые ключи из `/services/netbird` и деплоит стек NetBird на `45.154.185.208`.