docs: Update docs for the correctness (#13)
This commit is contained in:
deytenit authored and 
GitHub committed
1 parent
8dba55272c
commit
51a783f93a
60 files changed
+2456
-380
No files matched your search
@@ -1,12 +1,33 @@
|
||||
---
|
||||
title: 'root.ermnvldmr.com'
|
||||
description: 'Документация к инфраструктуре root.ermnvldmr.com'
|
||||
title: Documentation of ermnvldmr.com root deployment commons
|
||||
description: Документация общих модулей корневой инфраструктуры ermnvldmr.com.
|
||||
weight: 1
|
||||
type: docs
|
||||
cascade:
|
||||
type: docs
|
||||
---
|
||||
|
||||
Различные заметки, сделанные в процессе разработки этой инфраструктуры.
|
||||
Фреймворк `ermnvldmr.com-root-commons` предоставляет среду развертывания с минимальными зависимостями для независимых self-hosted проектов.
|
||||
|
||||
Общая логика, скрипты и шаблоны развертывания, используемые в различных приложениях, хранятся в репозитории [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons).
|
||||
|
||||
## Основные возможности
|
||||
|
||||
- **Smart Dispatcher**: Единая точка входа (`root`) для всех задач оркестрации.
|
||||
- **Tiered Storage**: Стандартизированная классификация для конфигураций, данных и логов.
|
||||
- **Privilege Isolation**: Изоляция привилегий через выделенных non-root пользователей для каждого проекта.
|
||||
- **Namespaced Libraries**: Явные модульные Bash-утилиты для обеспечения согласованной автоматизации.
|
||||
|
||||
## Разделы
|
||||
|
||||
- **[Рецепты](recipes/)** -- Пошаговые инструкции,
|
||||
которые мне не хочется изобретать каждый раз снова.
|
||||
{{% cards %}}
|
||||
{{< card link="concepts" title="Концепции" icon="book-open" subtitle="Теоретические основы, архитектура и модели безопасности." >}}
|
||||
{{< card link="guides" title="Руководства" icon="map" subtitle="Пошаговые инструкции по установке и разработке Action-скриптов." >}}
|
||||
{{< card link="reference" title="Справочник" icon="code" subtitle="API и технические справочники для разработчиков." >}}
|
||||
{{% /cards %}}
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons)
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Концепции
|
||||
description: Теоретические основы, архитектура и модели безопасности.
|
||||
weight: 10
|
||||
---
|
||||
|
||||
Теоретические основы, архитектура и модели безопасности общих модулей корневой инфраструктуры ermnvldmr.com.
|
||||
|
||||
{{% cards %}}
|
||||
{{< card link="principles" title="Принципы инфраструктуры" icon="book-open" subtitle="Предсказуемость, минимум зависимостей и децентрализация." >}}
|
||||
{{< card link="architecture" title="Архитектура инфраструктуры" icon="share" subtitle="Децентрализованная оркестрация и модели развертывания." >}}
|
||||
{{< card link="security-model" title="Модель безопасности и изоляция" icon="shield-check" subtitle="Изоляция привилегий и защита сети." >}}
|
||||
{{< card link="tiered-storage" title="Модель многоуровневого хранения" icon="database" subtitle="Стандартизированная классификация хранения данных сервисов." >}}
|
||||
{{% /cards %}}
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: Архитектура инфраструктуры
|
||||
description: Децентрализованная модель оркестрации и структура развертывания.
|
||||
weight: 10
|
||||
---
|
||||
|
||||
Фреймворк Root работает на децентрализованной модели оркестрации, разработанной для независимых, самодостаточных проектов. Он обеспечивает строгое разделение между оркестратором («мозгом») и задачами автоматизации («мышцами»).
|
||||
|
||||
## Основная философия {#philosophy}
|
||||
|
||||
Фреймворк построен на принципе **Smart Root, Stupid Actions** («Умный Root, глупые Action-скрипты»). Такой дизайн гарантирует, что отдельные скрипты автоматизации остаются декларативными и не знают о глобальном состоянии системы, в то время как центральный диспетчер берет на себя разрешение окружения и инициализацию библиотек.
|
||||
|
||||
### Smart Root (Диспетчер)
|
||||
|
||||
Точка входа `root` является единственным интерфейсом для пользователей. Она отвечает за:
|
||||
|
||||
- **Разрешение окружения** → Поиск репозиториев `commons` и `configs`.
|
||||
- **Подготовка библиотек** → Разовая загрузка пространств имен (modules) библиотек.
|
||||
- **Установление контекста** → Определение целевого [Узла (Node)](/root/glossary#node) и связанных с ним путей.
|
||||
|
||||
### Stupid Actions (Задачи)
|
||||
|
||||
[Action-скрипты (Actions)](/root/glossary#action) — это декларативные скрипты, расположенные в `scripts/actions/`. Они называются «глупыми», потому что:
|
||||
|
||||
- Они не вычисляют пути и не ищут репозитории.
|
||||
- Они полностью зависят от переменных окружения `ROOT_`.
|
||||
- Они фокусируются исключительно на одной атомарной задаче (например, `compose`, `ufw`).
|
||||
|
||||
## Модель развертывания {#deployment}
|
||||
|
||||
Они обычно развертываются как общий репозиторий [Commons](/root/glossary#commons), подключенный как Git-субмодуль внутри репозитория конфигураций. Движок, на котором построена эта общая инфраструктура, размещен по адресу [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons).
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="configs-repo" state="open" >}}
|
||||
{{< filetree/folder name=".operator" state="open" >}}
|
||||
{{< filetree/folder name="shared (submodule)" state="open" >}}
|
||||
{{< filetree/folder name="scripts" >}}
|
||||
{{< filetree/folder name="run" >}}
|
||||
{{< filetree/file name="root (dispatcher)" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="lib" >}}
|
||||
{{< filetree/file name="shared libraries" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="actions" >}}
|
||||
{{< filetree/file name="shared actions" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="local" state="open" >}}
|
||||
{{< filetree/folder name="scripts" >}}
|
||||
{{< filetree/folder name="actions" >}}
|
||||
{{< filetree/file name="node-specific overrides" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="daedalus (node)" >}}
|
||||
{{< filetree/file name="docker-compose.yml" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/file name="init.sh (bootstrap)" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Concept: The ROOT_ API](/root/reference/root-api)
|
||||
- [Guide: Installation](/root/guides/installation)
|
||||
- [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons)
|
||||
-commons)
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: Принципы инфраструктуры
|
||||
description: Основные принципы, обеспечивающие безопасную, предсказуемую среду с минимальными зависимостями.
|
||||
weight: 5
|
||||
---
|
||||
|
||||
Общие модули построены на ключевых принципах, предназначенных для обеспечения безопасной, предсказуемой среды с минимальными зависимостями для независимых self-hosted проектов.
|
||||
|
||||
## Предсказуемость через структуру {#predictability}
|
||||
|
||||
Ручная настройка сервера подвержена «дрейфу конфигурации» (configuration drift), когда хосты, которые должны быть идентичными, со временем начинают различаться. Общие модули решают эту проблему следующим образом:
|
||||
|
||||
- **Git как источник истины**: Каждая конфигурация, от правил UFW до crontab, хранится в репозитории.
|
||||
- **Идемпотентная автоматизация**: [Action-скрипты](/root/glossary#action) разработаны так, чтобы их можно было запускать многократно без побочных эффектов, гарантируя, что хост всегда соответствует заданному состоянию.
|
||||
|
||||
## Минимальное количество зависимостей {#minimalism}
|
||||
|
||||
Для обеспечения долгосрочной поддерживаемости общие модули избегают сложных инструментов управления конфигурацией (таких как Ansible или Salt). Вместо этого они полагаются на:
|
||||
|
||||
- **Bash**: Универсальный язык Unix-систем.
|
||||
- **Docker**: Для изоляции приложений и согласованности окружения.
|
||||
- **Стандартные инструменты Linux**: Прямое использование `systemd`, `ufw` и `cron`.
|
||||
|
||||
## Децентрализация {#decentralization}
|
||||
|
||||
Каждый [Узел (Node)](/root/glossary#node) является независимым. Хотя они используют библиотеку общих модулей ([Commons](/root/glossary#commons)), они не зависят от центрального «мастер»-сервера. Такая архитектура гарантирует, что сбой на одном хосте не повлияет на несвязанные сервисы.
|
||||
|
||||
---
|
||||
|
||||
**См. также:**
|
||||
|
||||
- [Концепция: Модель безопасности и изоляция](/root/concepts/security-model)
|
||||
- [Концепция: Модель многоуровневого хранения](/root/concepts/tiered-storage)
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Безопасность и изоляция привилегий
|
||||
description: Меры безопасности, изоляция привилегий и песочница на уровне проектов.
|
||||
weight: 20
|
||||
---
|
||||
|
||||
Безопасность в Root достигается за счет строгой изоляции привилегий и создания «песочниц» на уровне проектов для минимизации последствий в случае взлома отдельных сервисов.
|
||||
|
||||
## Принцип «No-Root» {#noroot}
|
||||
|
||||
Запуск приложений под пользователем `root` внутри контейнеров является значительным риском безопасности. Общие модули обеспечивают изоляцию с помощью действий `tiers/useradd` и `tiers/chown`.
|
||||
|
||||
### Пользователи для конкретных проектов
|
||||
|
||||
Каждому проекту, расположенному по пути `{repository root}/{node}/{project}`, назначается выделенный системный пользователь на хосте.
|
||||
|
||||
- **Изоляция**: Если контейнер будет взломан, злоумышленник получит только привилегии этого конкретного низкопривилегированного пользователя.
|
||||
- **Безопасность файловой системы**: Проекты могут читать и записывать данные только в свои собственные директории в рамках [Уровней (Tiers)](/root/glossary#tier).
|
||||
|
||||
## Защита сокета Docker {#socket-protection}
|
||||
|
||||
Прямой доступ к `/var/run/docker.sock` эквивалентен правам root на хосте. В качестве лучшей практики настоятельно рекомендуется защищать сокет Docker. Один из способов достижения этого — использование **Socket Proxy** (например, на базе `tecnativa/docker-socket-proxy`) для фильтрации и ограничения доступа к Docker API.
|
||||
|
||||
```yaml filename="docker-socket-proxy-example.yml"
|
||||
services:
|
||||
socket-proxy:
|
||||
image: tecnativa/docker-socket-proxy:0
|
||||
container_name: root-socket-proxy
|
||||
user: "0:0"
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
environment:
|
||||
CONTAINERS: 1
|
||||
SERVICES: 1
|
||||
TASKS: 1
|
||||
networks:
|
||||
socket: {}
|
||||
restart: unless-stopped
|
||||
|
||||
traefik:
|
||||
# ...
|
||||
depends_on:
|
||||
- socket-proxy
|
||||
command:
|
||||
# Использовать прокси вместо локального сокета
|
||||
- "--providers.docker.endpoint=tcp://root-socket-proxy:2375"
|
||||
networks:
|
||||
socket: {}
|
||||
```
|
||||
|
||||
## Мониторинг безопасности (CrowdSec) {#crowdsec}
|
||||
|
||||
Фреймворк интегрирует **CrowdSec** для поведенческого анализа и автоматического реагирования.
|
||||
|
||||
- **Обнаружение вторжений**: CrowdSec отслеживает логи [Traefik](https://traefik.io/) и SSH на предмет подозрительных паттернов (например, брутфорс-атаки, сканирование портов).
|
||||
- **Автоматическая блокировка**: При обнаружении угрозы **CrowdSec Firewall Bouncer** автоматически обновляет правила [UFW](https://help.ubuntu.com/community/UFW), блокируя вредоносный IP на уровне хоста.
|
||||
- **Обмен данными об угрозах**: CrowdSec делится анонимизированными данными об угрозах со своим сообществом, обеспечивая превентивную защиту от известных злоумышленников.
|
||||
|
||||
## Сетевое ужесточение {#networking}
|
||||
|
||||
Root использует `configure/ufw` для реализации политики «Запрещено по умолчанию» (Default Deny).
|
||||
|
||||
- **Внутренняя маршрутизация**: Сервисы взаимодействуют через выделенную сеть-мост `root-proxy`, которая часто настраивается как `internal: true`.
|
||||
- **Изоляция анклавов**: Исходящий трафик может быть направлен через выделенный узел выхода (egress node) для детального контроля.
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: Модель многоуровневого хранения
|
||||
description: Стандартизированная таксономия хранения данных сервисов.
|
||||
weight: 15
|
||||
---
|
||||
|
||||
Фреймворк навязывает стандартизированную таксономию хранения. Это гарантирует, что каждый сервис имеет предсказуемое местоположение для своих данных, что упрощает стратегии резервного копирования и распределение оборудования.
|
||||
|
||||
## Таксономия хранения {#taxonomy}
|
||||
|
||||
Данные разделены на три логических [Уровня (Tiers)](/root/glossary#tier) на основе их требований к производительности, жизненного цикла и важности.
|
||||
|
||||
### Уровень 1 (Tier 1): Конфигурации и Кэш
|
||||
|
||||
**Путь:** `${ROOT_NODE_DIR}/@tier1`
|
||||
|
||||
- **Содержимое**: Конфигурационные файлы, небольшие базы данных SQLite, SSL-сертификаты, кэш приложений.
|
||||
- **Характеристики**: Чрезвычайно высокая ценность, объем от низкого до среднего, требует минимальных задержек (latency).
|
||||
- **Оборудование**: Высокоскоростные SSD-накопители, обычно общие с операционной системой.
|
||||
|
||||
### Уровень 2 (Tier 2): Данные приложений
|
||||
|
||||
**Путь:** `${ROOT_NODE_DIR}/@tier2`
|
||||
|
||||
- **Содержимое**: Пользовательские загрузки, большие базы данных, постоянное состояние приложений.
|
||||
- **Характеристики**: Высокая ценность, объем от среднего до высокого, требует высокой надежности.
|
||||
- **Оборудование**: Надежные HDD-кластеры, RAID-массивы или выделенные хранилища.
|
||||
|
||||
### Уровень 3 (Tier 3): Временные файлы и объемные медиа
|
||||
|
||||
**Путь:** `${ROOT_NODE_DIR}/@tier3`
|
||||
|
||||
- **Содержимое**: Логи, временные файлы, объемные медиа (фильмы, музыка) и другие некритичные большие данные.
|
||||
- **Характеристики**: Низкая ценность, очень высокий объем.
|
||||
- **Оборудование**: HDD большой емкости, оптимизированные для непрерывной последовательной записи/чтения (например, WD Purple). Обратите внимание, что Tier 3 **слишком медленный для кэша**.
|
||||
|
||||
## Стратегия резервного копирования {#backup}
|
||||
|
||||
Общие модули не навязывают конкретную стратегию резервного копирования и не предоставляют реализацию по умолчанию, обеспечивая полную гибкость на уровне узла. Ожидается, что операторы сами реализуют логику резервного копирования.
|
||||
|
||||
### Пример: Резервное копирование с помощью Restic
|
||||
|
||||
Распространенной лучшей практикой является использование **Restic** для резервного копирования. Например, вы можете создать файл compose узла оператора для запуска Restic:
|
||||
|
||||
```yaml filename="operator-compose.yml"
|
||||
services:
|
||||
restic:
|
||||
image: restic/restic:0.18.1
|
||||
container_name: operator-restic
|
||||
volumes:
|
||||
- ./@tier2/{project}/{service}/{data}:/data/@tier2/{project}/{service}/{data}:ro
|
||||
- ./@tier1/{project}/{service}/{data}:/data/@tier1/{project}/{service}/{data}:ro
|
||||
- ./@tier1/.operator/restic/cache:/var/restic-cache
|
||||
environment:
|
||||
RESTIC_REPOSITORY: "s3:example.com/bucket"
|
||||
RESTIC_PASSWORD: ${RESTIC_PASSWORD}
|
||||
# ... учетные данные AWS/S3
|
||||
network_mode: "host"
|
||||
entrypoint: [ "restic" ]
|
||||
user: "0:0"
|
||||
```
|
||||
|
||||
### Реализация стратегии
|
||||
|
||||
Операторы могут реализовать свою стратегию, определив локальный Action в `.operator/local/scripts/actions/sync/tiers`. Диспетчер `root` затем сможет выполнить этот скрипт для запуска резервного копирования, позволяя детально контролировать способ сохранения данных.
|
||||
|
||||
## Обоснование {#justification}
|
||||
|
||||
1. **Оптимизация оборудования**: Сопоставляя уровни с конкретным оборудованием (SSD для Tier 1, RAID для Tier 2, Purples для Tier 3), мы оптимизируем как производительность, так и стоимость.
|
||||
2. **Выборочное резервное копирование**: Отделение временных логов и объемных медиа (Tier 3) от критических конфигураций (Tier 1) предотвращает трату дорогостоящего места в хранилище резервных копий.
|
||||
3. **Архитектурная ясность**: Любой оператор может проинспектировать директорию [Узла (Node)](/root/glossary#node) и сразу понять требования к хранению и приоритет его содержимого.
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: Глоссарий
|
||||
description: Терминология, используемая в рамках общих модулей корневой инфраструктуры.
|
||||
weight: 100
|
||||
---
|
||||
|
||||
Терминология, используемая в рамках общих модулей корневой инфраструктуры ermnvldmr.com.
|
||||
|
||||
## Action {#action}
|
||||
|
||||
**Action (Действие)** - Атомарная задача автоматизации, расположенная в `scripts/actions/`. Action-скрипты следуют философии "Stupid Action" («Глупое действие»), оставаясь декларативными и полагаясь на диспетчер `root` для настройки окружения.
|
||||
|
||||
## Commons {#commons}
|
||||
|
||||
**Commons (Общие модули)** - Общий репозиторий, содержащий общую логику, модульные библиотеки и стандартизированные действия автоматизации, используемые на всех узлах. Ссылка на [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons).
|
||||
|
||||
## Dispatcher {#dispatcher}
|
||||
|
||||
**Dispatcher (Диспетчер)** - Скрипт `root`, который служит точкой входа. Он разрешает пути, подготавливает окружение и выполняет запрошенный [Action](/root/glossary#action).
|
||||
|
||||
## Node {#node}
|
||||
|
||||
**Node (Узел)** - Физический или виртуальный хост, управляемый общими модулями. Каждый узел имеет выделенную директорию в репозитории конфигураций, содержащую его сервисы и локальные настройки.
|
||||
|
||||
## Root {#root}
|
||||
|
||||
**Root** - Имя утилиты командной строки, а также сервис оркестрации верхнего уровня внутри [Узла (Node)](/root/glossary#node) (обычно обрабатывающий Traefik и AdGuard).
|
||||
|
||||
## Tier {#tier}
|
||||
|
||||
**Tier (Уровень)** - Стандартизированная классификация хранения данных сервисов.
|
||||
- **Tier 1 (Уровень 1)**: Конфигурация и критическое состояние.
|
||||
- **Tier 2 (Уровень 2)**: Данные приложений и базы данных.
|
||||
- **Tier 3 (Уровень 3)**: Логи, кэши и объемные медиафайлы.
|
||||
|
||||
---
|
||||
|
||||
**См. также:**
|
||||
|
||||
- [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
|
||||
- [Концепция: Модель многоуровневого хранения](/root/concepts/tiered-storage)
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Руководства
|
||||
description: Пошаговые инструкции по установке и разработке Action-скриптов.
|
||||
weight: 20
|
||||
---
|
||||
|
||||
Пошаговые инструкции по установке и разработке в рамках общих модулей корневой инфраструктуры ermnvldmr.com.
|
||||
|
||||
{{% cards %}}
|
||||
{{< card link="first-node" title="Создание вашего первого узла" icon="map" subtitle="Практическое руководство по созданию репозитория конфигураций." >}}
|
||||
{{< card link="installation" title="Установка" icon="arrow-down" subtitle="Первоначальная настройка общих модулей на новом хосте." >}}
|
||||
{{< card link="action-development" title="Разработка Action-скриптов" icon="code" subtitle="Создание и управление атомарными задачами автоматизации." >}}
|
||||
{{% /cards %}}
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Разработка Action-скриптов
|
||||
description: Разработка атомарных задач автоматизации в рамках общих модулей.
|
||||
weight: 30
|
||||
---
|
||||
|
||||
[Action-скрипты](/root/glossary#action) — это атомарные задачи автоматизации. Следуя философии "Stupid Action" («Глупое действие»), они должны оставаться декларативными и полагаться на библиотеку для выполнения сложных операций.
|
||||
|
||||
## Создание нового Action-скрипта {#create}
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### Шаг 1: Создание файла скрипта
|
||||
|
||||
Поместите ваш скрипт в `scripts/actions/{group}/{name}`. Не используйте расширения файлов.
|
||||
|
||||
### Шаг 2: Реализация метаданных
|
||||
|
||||
Каждый Action-скрипт должен предоставлять описание и список аргументов для системы справки (help system).
|
||||
|
||||
```bash filename="scripts/actions/utils/my-action"
|
||||
action_metadata() {
|
||||
cat <<EOF
|
||||
description: "Краткое описание задачи."
|
||||
args:
|
||||
- NODE: "Имя узла"
|
||||
- PARAM: "Пользовательский параметр"
|
||||
EOF
|
||||
}
|
||||
```
|
||||
|
||||
### Шаг 3: Инициализация контекста
|
||||
|
||||
Используйте вспомогательную функцию `root_require_node` для настройки окружения. Это должно быть первым функциональным шагом в вашем скрипте.
|
||||
|
||||
```bash filename="scripts/actions/utils/my-action"
|
||||
root_require_node "${1:-}"
|
||||
shift
|
||||
```
|
||||
|
||||
### Шаг 4: Использование модульных функций
|
||||
|
||||
Выполняйте операции, используя библиотечные функции `root_*`. Полагайтесь на переменные окружения `ROOT_` для всех путей.
|
||||
|
||||
```bash filename="scripts/actions/utils/my-action"
|
||||
root_log_info "Обработка узла $ROOT_NODE"
|
||||
root_sys_restart_service "my-service"
|
||||
```
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
## Пространства имен библиотек {#libraries}
|
||||
|
||||
Action-скрипты имеют доступ к следующим модулям:
|
||||
|
||||
- `root_core_*`: Логирование и уведомления в Telegram.
|
||||
- `root_init_*`: Декларативная инициализация сервисов и управление пакетами.
|
||||
- `root_sys_*`: Управление systemd и файлами юнитов.
|
||||
- `root_template_*`: Рендеринг на основе envsubst и внедрение конфигураций.
|
||||
- `root_validate_*`: Проверка ввода, файлов и ОС.
|
||||
|
||||
---
|
||||
|
||||
**См. также:**
|
||||
|
||||
- [Справочник: Справочник ROOT_ API](/root/reference/root-api)
|
||||
- [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
|
||||
@@ -0,0 +1,190 @@
|
||||
---
|
||||
title: "Создание узла (First Node)"
|
||||
description: Практическое руководство по созданию вашего первого узла и подключению общих модулей.
|
||||
weight: 25
|
||||
---
|
||||
|
||||
**Цель:** Создать репозиторий конфигураций для вашей собственной инфраструктуры, подключить общие модули в качестве подмодуля (submodule) и запустить первый базовый узел.
|
||||
|
||||
## 1. Создание репозитория конфигураций
|
||||
|
||||
Ваша инфраструктура должна управляться из единого Git-репозитория. Этот репозиторий будет содержать конфигурации для всех ваших серверов (узлов).
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### Шаг 1: Инициализация репозитория
|
||||
|
||||
Создайте новую директорию и инициализируйте Git.
|
||||
|
||||
```bash
|
||||
mkdir my-infrastructure
|
||||
cd my-infrastructure
|
||||
git init
|
||||
```
|
||||
|
||||
### Шаг 2: Добавление общих модулей как подмодуля
|
||||
|
||||
Общие модули (`ermnvldmr.com-root-commons`) должны располагаться по пути `.operator/shared`.
|
||||
|
||||
```bash
|
||||
mkdir -p .operator
|
||||
git submodule add https://github.com/deytenit/ermnvldmr.com-root-commons.git .operator/shared
|
||||
```
|
||||
|
||||
### Шаг 3: Создание загрузочного скрипта (Bootstrap)
|
||||
|
||||
Создайте файл `init.sh` в корне вашего репозитория. Этот скрипт свяжет общие модули с вашим локальным окружением.
|
||||
|
||||
```bash filename="init.sh"
|
||||
#!/usr/bin/env bash
|
||||
# init.sh
|
||||
|
||||
# Загрузка общих утилит из подмодуля
|
||||
source "$(git -C "$(dirname "$0")" rev-parse --show-toplevel)/.operator/shared/scripts/lib/common.sh"
|
||||
|
||||
SCRIPT_NAME="init"
|
||||
|
||||
navigate_to_repo_root
|
||||
|
||||
log_info "Настройка Git hooks..."
|
||||
git config core.hooksPath .operator/shared/githooks
|
||||
git config --global --add safe.directory "${REPO_ROOT}"
|
||||
|
||||
log_info "Настройка PATH для диспетчера root..."
|
||||
ABSOLUTE_RUN_DIR="$(realpath "${REPO_ROOT}/.operator/shared/scripts/run")"
|
||||
BASHRC_ENTRY="export PATH=\"${ABSOLUTE_RUN_DIR}:\$PATH\""
|
||||
|
||||
sed -i '/\.operator\/shared\/scripts\/run/d' ~/.bashrc
|
||||
echo "$BASHRC_ENTRY" >> ~/.bashrc
|
||||
log_info "Готово. Выполните 'source ~/.bashrc' или перезайдите в терминал."
|
||||
```
|
||||
|
||||
Сделайте его исполняемым:
|
||||
```bash
|
||||
chmod +x init.sh
|
||||
```
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
## 2. Определение вашего первого узла
|
||||
|
||||
Узел (Node) — это папка в корне репозитория, которая представляет один физический или виртуальный сервер.
|
||||
|
||||
### Структура узла
|
||||
|
||||
Давайте создадим узел с именем `daedalus`. Внутри него мы определим конфигурацию оператора (например, для резервного копирования) и базовый сервис.
|
||||
|
||||
```bash
|
||||
mkdir -p daedalus/.operator/configs/{cron,crowdsec,systemd,ufw/docker,ufw/host}
|
||||
mkdir -p daedalus/root
|
||||
```
|
||||
|
||||
### Базовые настройки (Опционально)
|
||||
|
||||
Вы можете добавить файлы конфигурации (например, правила UFW или crontab) в директорию `daedalus/.operator/configs/`. Например, простой crontab:
|
||||
|
||||
```bash filename="daedalus/.operator/configs/cron/crontab.template"
|
||||
# Запуск резервного копирования каждую ночь в 3:00
|
||||
0 3 * * * root sync tiers daedalus
|
||||
```
|
||||
|
||||
## 3. Настройка сервисов (Docker Compose)
|
||||
|
||||
Фреймворк опирается на `docker-compose.yml`.
|
||||
|
||||
### Инфраструктурный уровень (Узел оператора)
|
||||
|
||||
Файл `daedalus/docker-compose.yml` запускает инфраструктурные утилиты, такие как `restic` для бекапов или VPN-агенты. Этот compose-файл имеет прямой доступ к файловой системе через монтирование директорий `@tierX`.
|
||||
|
||||
```yaml filename="daedalus/docker-compose.yml"
|
||||
name: 'operator'
|
||||
|
||||
services:
|
||||
restic:
|
||||
image: restic/restic:0.18.1
|
||||
container_name: operator-restic
|
||||
volumes:
|
||||
# Пример: монтирование данных для резервного копирования (Только для чтения)
|
||||
- ./@tier2/my-app/data:/data/@tier2/my-app/data:ro
|
||||
- ./@tier3/.operator/restic/cache:/var/restic-cache
|
||||
environment:
|
||||
RESTIC_REPOSITORY: "s3:example.com/my-bucket/daedalus"
|
||||
RESTIC_PASSWORD: "${RESTIC_PASSWORD?error}"
|
||||
# Данные AWS...
|
||||
network_mode: "host"
|
||||
entrypoint: [ "restic" ]
|
||||
```
|
||||
|
||||
### Корневой уровень (Root)
|
||||
|
||||
Проект `root` обычно содержит обратные прокси (Traefik) и сервисы, к которым обращаются другие проекты.
|
||||
|
||||
```yaml filename="daedalus/root/docker-compose.yml"
|
||||
name: root
|
||||
|
||||
services:
|
||||
socket-proxy:
|
||||
image: tecnativa/docker-socket-proxy:0
|
||||
container_name: root-socket-proxy
|
||||
user: "0:0"
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
environment:
|
||||
CONTAINERS: 1
|
||||
SERVICES: 1
|
||||
TASKS: 1
|
||||
networks:
|
||||
socket: {}
|
||||
restart: unless-stopped
|
||||
|
||||
traefik:
|
||||
image: traefik:3.6
|
||||
container_name: root-traefik
|
||||
# UID и GID подставляются автоматически фреймворком после команды 'root tiers useradd'
|
||||
user: "${UID?error}:${GID?error}"
|
||||
group_add:
|
||||
- "${SHARED_GID?error}"
|
||||
depends_on:
|
||||
- socket-proxy
|
||||
volumes:
|
||||
- ./@tier1/shared/root/traefik/letsencrypt:/letsencrypt
|
||||
- ./@tier3/traefik/logs:/logs
|
||||
- ./@tier1/traefik/dynamic:/etc/traefik/dynamic:ro
|
||||
ports:
|
||||
- '0.0.0.0:80:80'
|
||||
- '0.0.0.0:443:443'
|
||||
networks:
|
||||
proxy: {}
|
||||
socket: {}
|
||||
command:
|
||||
- "--api.dashboard=true"
|
||||
- "--providers.docker=true"
|
||||
- "--providers.docker.network=root-proxy"
|
||||
- "--providers.docker.endpoint=tcp://root-socket-proxy:2375"
|
||||
restart: unless-stopped
|
||||
|
||||
networks:
|
||||
proxy:
|
||||
name: root-proxy
|
||||
internal: true
|
||||
driver: bridge
|
||||
socket:
|
||||
name: root-socket
|
||||
internal: true
|
||||
driver: bridge
|
||||
```
|
||||
|
||||
## 4. Развертывание
|
||||
|
||||
Теперь, когда структура создана:
|
||||
|
||||
1. Закоммитьте и отправьте (push) этот репозиторий на ваш Git-сервер (например, GitHub).
|
||||
2. Зайдите на ваш VPS.
|
||||
3. Следуйте руководству по [Установке (Installation)](/root/guides/installation), используя URL вашего нового репозитория.
|
||||
|
||||
---
|
||||
|
||||
**См. также:**
|
||||
|
||||
- [Руководство: Установка на новый хост](/root/guides/installation)
|
||||
- [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
|
||||
+25
-28
@@ -41,10 +41,10 @@ groupadd wheel
|
||||
|
||||
# Создать модульный файл sudoers
|
||||
# Это позволяет членам группы 'wheel' запускать sudo без пароля
|
||||
echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/99-root-ermnvldmr
|
||||
echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/99-custom-sudoers
|
||||
|
||||
# Проверить синтаксис
|
||||
visudo -c -f /etc/sudoers.d/99-root-ermnvldmr
|
||||
visudo -c -f /etc/sudoers.d/99-custom-sudoers
|
||||
|
||||
# Добавить adam в необходимые группы
|
||||
usermod -aG wheel,docker adam
|
||||
@@ -92,10 +92,10 @@ chown -R adam:adam /home/adam/.ssh
|
||||
|
||||
```bash
|
||||
# ~/.ssh/config на стороне оператора
|
||||
Host daedalus.root.ermnvldmr.com
|
||||
Host daedalus.example.com
|
||||
Port 2222
|
||||
User adam
|
||||
IdentityFile ~/.ssh/adam_root_ermnvldmr_com_ed25519
|
||||
IdentityFile ~/.ssh/adam_example_com_ed25519
|
||||
```
|
||||
|
||||
**Усиление демона SSH**
|
||||
@@ -105,7 +105,7 @@ Host daedalus.root.ermnvldmr.com
|
||||
```bash
|
||||
# От имени root:
|
||||
# Создать выделенный файл конфигурации
|
||||
cat <<EOF > /etc/ssh/sshd_config.d/99-root-ermnvldmr.conf
|
||||
cat <<EOF > /etc/ssh/sshd_config.d/99-custom-ssh.conf
|
||||
Port 2222
|
||||
PasswordAuthentication no
|
||||
PermitEmptyPasswords no
|
||||
@@ -137,21 +137,21 @@ cat /home/adam/.ssh/github_ed25519.pub
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> Добавьте вывод выше в [GitHub: Repository Deploy Keys](https://github.com/deytenit/root.ermnvldmr.com/settings/keys) с правами **read access**.
|
||||
> Добавьте вывод выше в настройки Deploy Keys вашего репозитория инфраструктуры (например, `https://github.com/your-username/your-repo/settings/keys`) с правами **read access**.
|
||||
|
||||
### Развертывание репозитория
|
||||
|
||||
Клонируйте инфраструктурный репозиторий и инициализируйте узел.
|
||||
Клонируйте репозиторий вашей инфраструктуры и инициализируйте узел.
|
||||
|
||||
```bash
|
||||
# От имени root:
|
||||
# Настроить директорию сервиса
|
||||
export REPO_DIR="/srv/root.ermnvldmr.com"
|
||||
# Настройка директории сервиса
|
||||
export REPO_DIR="/srv/your-infrastructure-repo"
|
||||
mkdir -p $REPO_DIR
|
||||
chown adam:adam $REPO_DIR
|
||||
|
||||
# Клонировать от имени пользователя adam
|
||||
sudo -u adam git clone git@github.com:deytenit/root.ermnvldmr.com.git $REPO_DIR
|
||||
# Клонирование от имени пользователя adam
|
||||
sudo -u adam git clone git@github.com:your-username/your-repo.git $REPO_DIR
|
||||
|
||||
# Инициализировать узел (Установите имя вашего узла, например, daedalus)
|
||||
export NODE="daedalus"
|
||||
@@ -161,16 +161,15 @@ sudo -u adam ./init.sh
|
||||
|
||||
**Специфичная для узла конфигурация**
|
||||
|
||||
Запустите скрипты инициализации по порядку:
|
||||
Запустите скрипты инициализации с помощью диспетчера `root`:
|
||||
|
||||
```bash
|
||||
# От имени root:
|
||||
# Выполните последовательность для вашего конкретного узла
|
||||
cd $REPO_DIR
|
||||
./$NODE/.host/.scripts/00-base
|
||||
./$NODE/.host/.scripts/10-ufw
|
||||
./$NODE/.host/.scripts/20-crowd
|
||||
./$NODE/.host/.scripts/30-cron
|
||||
# Выполните последовательность для вашего конкретного узла (от имени пользователя 'adam')
|
||||
# Убедитесь, что вы выполнили 'source ~/.bashrc' или переподключились, если команда 'root' не найдена
|
||||
root configure base $NODE
|
||||
root configure ufw $NODE
|
||||
root configure crowdsec $NODE
|
||||
root configure cron $NODE
|
||||
```
|
||||
|
||||
### Хранение и усиление безопасности
|
||||
@@ -178,18 +177,17 @@ cd $REPO_DIR
|
||||
Определите уровни данных (tiers) и защитите среду, создав непривилегированных пользователей для контейнеризированных сервисов.
|
||||
|
||||
```bash
|
||||
# От имени root:
|
||||
# Создать (или примонтировать) директории хранилища
|
||||
mkdir -p /srv/com-ermnvldmr-root-$NODE-{tier1,tier2,tier3}
|
||||
sudo mkdir -p /srv/my-infrastructure-root-$NODE-{tier1,tier2,tier3}
|
||||
|
||||
# Настроить уровни и непривилегированных пользователей
|
||||
cd $REPO_DIR
|
||||
sudo -u adam .scripts/ops/setup-tiers $NODE
|
||||
/srv/com-ermnvldmr-root-$NODE-tier1
|
||||
/srv/com-ermnvldmr-root-$NODE-tier2
|
||||
/srv/com-ermnvldmr-root-$NODE-tier3
|
||||
root tiers link $NODE \
|
||||
/srv/my-infrastructure-root-$NODE-tier1 \
|
||||
/srv/my-infrastructure-root-$NODE-tier2 \
|
||||
/srv/my-infrastructure-root-$NODE-tier3
|
||||
|
||||
sudo -u adam .scripts/ops/setup-noroot-users $NODE
|
||||
root tiers useradd $NODE
|
||||
root tiers chown $NODE
|
||||
```
|
||||
|
||||
{{% /steps %}}
|
||||
@@ -199,4 +197,3 @@ sudo -u adam .scripts/ops/setup-noroot-users $NODE
|
||||
**См. также:**
|
||||
|
||||
- [Doc: Docker - Install on Debian](https://docs.docker.com/engine/install/debian/)
|
||||
- [GitHub: root.ermnvldmr.com](https://github.com/deytenit/root.ermnvldmr.com)
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: 'Рецепты'
|
||||
description: 'Пошаговые инструкции, которые мне не хочется изобретать каждый раз снова.'
|
||||
weight: 50
|
||||
type: docs
|
||||
---
|
||||
|
||||
Пошаговые инструкции,
|
||||
которые мне не хочется изобретать каждый раз снова.
|
||||
|
||||
## Что здесь
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: Справочник
|
||||
description: Справочные материалы и API для разработчиков.
|
||||
weight: 30
|
||||
---
|
||||
|
||||
Технические справочные материалы и API общих модулей корневой инфраструктуры ermnvldmr.com.
|
||||
|
||||
{{% cards %}}
|
||||
{{< card link="compose" title="Справочник по действиям compose" icon="play" subtitle="Высокоуровневая точка входа для оркестрации docker-compose." >}}
|
||||
{{< card link="configure" title="Справочник по действиям настройки" icon="arrow-down" subtitle="Действия для настройки системного уровня." >}}
|
||||
{{< card link="initialization" title="Справочник по действиям инициализации" icon="play" subtitle="Действия для первоначальной настройки узла." >}}
|
||||
{{< card link="root-api" title="Справочник ROOT_ API" icon="code" subtitle="Стандартизированные переменные окружения и вспомогательные функции логирования." >}}
|
||||
{{< card link="source" title="Справочник по исходным сервисам" icon="book-open" subtitle="Общие сервисы, собираемые из исходного кода." >}}
|
||||
{{< card link="sync" title="Справочник по действиям синхронизации" icon="check" subtitle="Действия для поддержания узлов в актуальном состоянии." >}}
|
||||
{{< card link="tiers" title="Справочник по действиям уровней (Tiers)" icon="archive" subtitle="Управление уровнями хранения данных." >}}
|
||||
{{< card link="utils" title="Справочник по утилитам" icon="check" subtitle="Вспомогательные скрипты и утилиты." >}}
|
||||
{{% /cards %}}
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Операции Compose
|
||||
description: Стандартизированная точка входа для оркестрации docker-compose в масштабах узла.
|
||||
weight: 54
|
||||
---
|
||||
|
||||
Действие `compose` предоставляет стандартизированную высокоуровневую точку входа для оркестрации файлов Docker Compose для всех проектов в рамках определенного узла.
|
||||
|
||||
## Основная операция Compose {#actions}
|
||||
|
||||
| Операция | Описание |
|
||||
| :--- | :--- |
|
||||
| `compose <node> <action>` | Выполняет заданную команду Docker Compose (например, `up`, `down`, `restart`) по всей инфраструктуре узла. |
|
||||
|
||||
## Порядок оркестрации {#order}
|
||||
|
||||
Для поддержания правильных зависимостей (особенно при завершении работы или запуске прокси-серверов и сетей уровня инфраструктуры), действие `compose` интеллектуально упорядочивает выполнение:
|
||||
|
||||
### Запуск (`up`, `restart`)
|
||||
При запуске или перезапуске сервисов действие использует **Прямой порядок** (Forward Order):
|
||||
1. **Инфраструктура узла (Node Infra)**: Сначала обрабатывается файл `docker-compose.yml` уровня узла (находится в корне директории узла).
|
||||
2. **Корневая инфраструктура (Root Infra)**: Затем обрабатывается проект `root/docker-compose.yml`, если он существует (обычно содержит Traefik, Socket Proxy и т.д.).
|
||||
3. **Проекты**: Наконец, в алфавитном порядке обрабатываются все остальные директории проектов.
|
||||
|
||||
### Остановка (`down`)
|
||||
При остановке сервисов действие использует **Обратный порядок** (Reverse Order), чтобы проекты корректно отключились до того, как упадет сеть или прокси:
|
||||
1. **Проекты**: Все стандартные проекты останавливаются в обратном алфавитном порядке.
|
||||
2. **Корневая инфраструктура (Root Infra)**: Проект `root/docker-compose.yml` останавливается.
|
||||
3. **Инфраструктура узла (Node Infra)**: В самом конце отключается `docker-compose.yml` уровня узла.
|
||||
|
||||
## Опции {#options}
|
||||
|
||||
Вы можете передавать стандартные аргументы Docker Compose в конец команды.
|
||||
Кроме того, действие поддерживает режим пробного запуска (dry-run):
|
||||
|
||||
- `--dry-run`: Выводит команды, которые будут выполнены, без их фактического запуска.
|
||||
|
||||
**Пример использования:**
|
||||
```bash
|
||||
root compose daedalus up -d --remove-orphans
|
||||
root compose daedalus restart --dry-run
|
||||
root compose daedalus down
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
|
||||
- [Справочник: Справочник ROOT_ API Reference](/root/reference/root-api)
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Операции настройки (Configure)
|
||||
description: Подготовка хоста, движок шаблонов и конфигурация на уровне системы.
|
||||
weight: 53
|
||||
---
|
||||
|
||||
Операции настройки используются для подготовки хоста и обслуживания системных сервисов. Они в значительной степени полагаются на встроенный движок шаблонов для генерации декларативных конфигурационных файлов.
|
||||
|
||||
## Движок шаблонов {#template-engine}
|
||||
|
||||
Общие модули используют `envsubst` (из пакета `gettext-base`) для рендеринга шаблонов. Это позволяет использовать стандартные переменные окружения Bash непосредственно в ваших конфигурационных файлах.
|
||||
|
||||
### Соглашения по шаблонам
|
||||
|
||||
- **Расширение файлов**: Шаблоны обычно используют расширение `.template` (например, `crontab.template`).
|
||||
- **Синтаксис переменных**: Используйте `${VARIABLE_NAME}` или `$VARIABLE_NAME` для подстановки значений.
|
||||
- **Автоматический поиск**: Многие действия автоматически ищут шаблоны в определенных директориях внутри репозитория [Configs](/root/glossary#configs).
|
||||
|
||||
### Вспомогательные функции рендеринга
|
||||
|
||||
Библиотека `root_template.sh` предоставляет несколько вспомогательных функций:
|
||||
|
||||
- `root_template_render <input> <output>`: Рендерит один файл.
|
||||
- `root_template_render_directory <src> <dest>`: Рекурсивно рендерит всю структуру директории.
|
||||
- `root_template_crontab <template>`: Рендерит и устанавливает crontab для текущего пользователя.
|
||||
|
||||
## Основные операции настройки {#actions}
|
||||
|
||||
| Операция | Описание |
|
||||
| :--- | :--- |
|
||||
| `configure/base` | Устанавливает основные пакеты (`sudo`, `ufw`, `docker`) и настраивает базовых системных пользователей. |
|
||||
| `configure/cron` | Рендерит и устанавливает специфичные для узла crontab-файлы. |
|
||||
| `configure/crowdsec` | Настраивает агента CrowdSec и баунсеры (bouncers). |
|
||||
| `configure/routing` | Настраивает маршрутизацию на уровне системы и сети-мосты (bridge networks). |
|
||||
| `configure/systemd` | Устанавливает и активирует юниты сервисов systemd. |
|
||||
| `configure/ufw` | Рендерит и применяет правила брандмауэра с помощью UFW и `ufw-docker`. |
|
||||
|
||||
## Пример: Шаблон Nginx {#example}
|
||||
|
||||
```nginx filename="nginx.conf.template"
|
||||
# Этот шаблон использует переменную окружения ROOT_NODE
|
||||
user nginx;
|
||||
worker_processes auto;
|
||||
|
||||
error_log /var/log/nginx/error.log notice;
|
||||
pid /var/run/nginx.pid;
|
||||
|
||||
events {
|
||||
worker_connections 1024;
|
||||
}
|
||||
|
||||
http {
|
||||
include /etc/nginx/mime.types;
|
||||
default_type application/octet-stream;
|
||||
|
||||
# Подставляется из окружения
|
||||
server_name ${ROOT_NODE}.example.com;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
|
||||
- [Справочник: Справочник ROOT_ API Reference](/root/reference/root-api)
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Инициализация системы
|
||||
description: Настройка репозитория, Git-хуки и конфигурация PATH.
|
||||
weight: 51
|
||||
---
|
||||
|
||||
Общие модули требуют однократной инициализации на каждом хосте для создания связей путей и конфигураций на уровне репозитория.
|
||||
|
||||
## Скрипт `init.sh` {#init-script}
|
||||
|
||||
Скрипт `init.sh`, расположенный в корне репозитория, является основным механизмом начальной загрузки. Он выполняет следующие критические задачи:
|
||||
|
||||
1. **Инициализация субмодулей**: Гарантирует наличие и актуальность репозитория [Commons](/root/glossary#commons).
|
||||
2. **Конфигурация Git-хуков**: Направляет `core.hooksPath` на `.operator/shared/githooks` для обеспечения стандартизированных проверок перед коммитом.
|
||||
3. **Регистрация безопасной директории (Safe Directory)**: Добавляет репозиторий в список `safe.directory` Git, что необходимо для операций, выполняемых разными пользователями (например, `root`, `adam`).
|
||||
4. **Конфигурация Vim**: Связывает стандартизированный `.vimrc` как для текущего пользователя, так и для пользователя `root` для обеспечения единообразия при редактировании.
|
||||
5. **Сохранение PATH**: Добавляет директорию `.operator/shared/scripts/run` в `~/.bashrc` пользователя, делая команду `root` доступной глобально.
|
||||
|
||||
## Git-хуки {#githooks}
|
||||
|
||||
Root обеспечивает соблюдение стандартов через Git-хуки, хранящиеся в `.operator/shared/githooks/`.
|
||||
|
||||
- **Pre-commit**: Проверяет, что все скрипты соответствуют соглашениям о пространствах имен и структуре.
|
||||
- **Commit-msg**: (Опционально) Обеспечивает соблюдение правил Conventional Commits, если это настроено.
|
||||
|
||||
## Конфигурация PATH {#path}
|
||||
|
||||
Команда `root` — это обертка (wrapper), расположенная по адресу `.operator/shared/scripts/run/root`. Добавляя эту директорию в `PATH`, диспетчер можно вызывать из любой директории в системе; он автоматически определит корень репозитория на основе текущей рабочей директории или переменных окружения.
|
||||
|
||||
```bash
|
||||
# Пример добавления PATH вручную (выполняется автоматически скриптом init.sh)
|
||||
export PATH="$HOME/repo/.operator/shared/scripts/run:$PATH"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Руководство: Начальная настройка хоста](/root/guides/installation)
|
||||
- [Справочник: Справочник ROOT_ API Reference](/root/reference/root-api)
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: Справочник ROOT_ API
|
||||
description: Стандартизированные переменные окружения и библиотеки ядра.
|
||||
weight: 50
|
||||
---
|
||||
|
||||
Каждый Action-скрипт, выполняемый через диспетчер `root`, имеет доступ к стандартизированному набору переменных окружения и Bash-библиотек. Это обеспечивает согласованный API для взаимодействия с инфраструктурой.
|
||||
|
||||
## Диспетчер `root` {#dispatcher}
|
||||
|
||||
Команда `root` (находится в `.operator/shared/scripts/run/root`) является основной точкой входа для всей оркестрации. Ее основные обязанности включают:
|
||||
|
||||
1. **Разрешение контекста**: Поиск целевого [Узла (Node)](/root/glossary#node) и связанных с ним [Уровней (Tiers)](/root/glossary#tier) хранилища.
|
||||
2. **Загрузка библиотек**: Подключение основных библиотек ядра (например, `root_core`, `root_sys`).
|
||||
3. **Выполнение Action-скриптов**: Поиск и запуск запрошенного действия, с приоритетом локальных переопределений.
|
||||
|
||||
## Переменные разрешения путей {#paths}
|
||||
|
||||
Эти переменные устанавливаются диспетчером и доступны всем Action-скриптам.
|
||||
|
||||
| Переменная | Описание |
|
||||
| :--- | :--- |
|
||||
| `ROOT_SHARED` | Абсолютный путь к репозиторию [Commons](/root/glossary#commons). |
|
||||
| `ROOT_CONFIGS` | Абсолютный путь к основному репозиторию конфигураций. |
|
||||
| `ROOT_LOCAL` | Абсолютный путь к директории локального оператора (`.operator/local`). |
|
||||
| `ROOT_ACTIONS_SHARED` | Путь к глобальным общим Action-скриптам. |
|
||||
| `ROOT_ACTIONS_LOCAL` | Путь к специфичным для узла локальным Action-скриптам. |
|
||||
|
||||
## Переменные контекста узла {#node-context}
|
||||
|
||||
Когда действие нацелено на конкретный узел, следующие переменные устанавливаются вспомогательной функцией `root_require_node`.
|
||||
|
||||
| Переменная | Описание |
|
||||
| :--- | :--- |
|
||||
| `ROOT_NODE` | Идентификатор целевого узла (например, `daedalus`). |
|
||||
| `ROOT_NODE_DIR` | Абсолютный путь к директории конфигурации узла. |
|
||||
| `ROOT_TIER1` | Абсолютный путь к директории [Уровня 1](/root/glossary#tier). |
|
||||
| `ROOT_TIER2` | Абсолютный путь к директории Уровня 2. |
|
||||
| `ROOT_TIER3` | Абсолютный путь к директории Уровня 3. |
|
||||
|
||||
## Основные функции логирования {#logging}
|
||||
|
||||
Стандартизированное логирование обеспечивает согласованный вывод всех действий.
|
||||
|
||||
- `root_log_info`: Стандартный информационный вывод.
|
||||
- `root_log_warn`: Предупреждения, требующие внимания.
|
||||
- `root_log_error`: Критические ошибки, отправляемые в `stderr`.
|
||||
- `root_log_success`: Подтверждение успешного завершения задачи.
|
||||
|
||||
## Система помощи {#help}
|
||||
|
||||
Диспетчер предоставляет встроенную систему помощи, парся блок `action_metadata` в начале каждого скрипта. Это позволяет скриптам оставаться декларативными без реализации собственной обработки аргументов командной строки.
|
||||
|
||||
```bash filename="example-action-metadata"
|
||||
action_metadata() {
|
||||
cat <<EOF
|
||||
description: "Краткое описание действия."
|
||||
args:
|
||||
- NODE: "Имя целевого узла."
|
||||
EOF
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Директория `source/`
|
||||
description: Концептуальный обзор структуры изолированной директории исходного кода.
|
||||
weight: 52
|
||||
---
|
||||
|
||||
Директория `source/` в корне репозитория содержит основные компоненты и проекты, которыми управляют общие модули. Она разработана для максимальной изоляции и самодостаточности.
|
||||
|
||||
## Основная философия {#philosophy}
|
||||
|
||||
Директория `source/` — это не просто место для хранения кода; это коллекция независимых [Проектов](/root/glossary#project). Каждый проект в этой директории должен следовать следующим принципам:
|
||||
|
||||
1. **Изоляция**: Каждый проект живет в своей поддиректории (например, `source/my-app/`).
|
||||
2. **Самодокументируемость**: Каждая директория проекта **ОБЯЗАНА** содержать собственный файл `README.md`, описывающий его назначение, зависимости и конфигурацию.
|
||||
3. **Внутренняя логика**: Проекты сами управляют своими процессами сборки, Docker-файлами и внутренними конфигурациями. [Action-скрипты](/root/glossary#action) фреймворка Root просто оркеструют эти существующие компоненты.
|
||||
|
||||
## Структура директории {#structure}
|
||||
|
||||
Типичный проект в директории `source/` может выглядеть следующим образом:
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="source" state="open" >}}
|
||||
{{< filetree/folder name="happ-subscription-generator" state="open" >}}
|
||||
{{< filetree/file name="Dockerfile" >}}
|
||||
{{< filetree/file name="generator.py" >}}
|
||||
{{< filetree/file name="README.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
## Связь с Action-скриптами {#actions}
|
||||
|
||||
Action-скрипты (такие как `compose` или `sync`) взаимодействуют с директорией `source/`, ссылаясь на пути внутри нее. Например, действие `compose` может использовать файл `docker-compose.yml`, который указывает на `Dockerfile`, расположенный в `source/app/`.
|
||||
|
||||
Такое разделение ответственности гарантирует, что логика оркестрации (Action-скрипты) остается отвязанной от деталей реализации (Source).
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
|
||||
- [Справочник: Справочник ROOT_ API Reference](/root/reference/root-api)
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Операции синхронизации (Sync)
|
||||
description: Обновление репозитория, синхронизация пакетов и резервное копирование данных.
|
||||
weight: 54
|
||||
---
|
||||
|
||||
Операции синхронизации гарантируют, что состояние хоста соответствует конфигурациям, определенным в удаленных репозиториях.
|
||||
|
||||
## Основные операции синхронизации {#actions}
|
||||
|
||||
| Операция | Описание |
|
||||
| :--- | :--- |
|
||||
| `sync/packages` | Синхронизирует пакеты узлов и их конфигурации по всей системе. |
|
||||
| `sync/repository` | Обновляет основной репозиторий конфигураций до последней версии из GitHub. |
|
||||
| `sync/tiers` | Запускает стратегию резервного копирования для настроенных [Уровней (Tiers)](/root/glossary#tier). |
|
||||
|
||||
## Синхронизация репозитория (`sync/repository`) {#repository}
|
||||
|
||||
Действие `sync/repository` отвечает за поддержание репозитория конфигураций хоста в актуальном состоянии. Оно обычно выполняет `git pull` в основном репозитории конфигураций и может опционально запускать обновление субмодулей для репозитория [Commons](/root/glossary#commons).
|
||||
|
||||
Это гарантирует, что любые изменения в конфигурациях узлов, действиях или исходных файлах будут корректно загружены на целевой хост.
|
||||
|
||||
## Синхронизация бэкапов (`sync/tiers`) {#tiers}
|
||||
|
||||
Действие `sync/tiers` является основной точкой входа для стратегии резервного копирования узла.
|
||||
|
||||
- **Нет реализации по умолчанию**: Сами общие модули не предоставляют механизма резервного копирования по умолчанию, позволяя операторам разработать пользовательскую стратегию, подходящую для их нужд.
|
||||
- **Пользовательские переопределения**: Будучи действием диспетчера, его можно переопределить, поместив собственный скрипт в `.operator/local/scripts/actions/sync/tiers` для реализации специфичной для узла логики резервного копирования.
|
||||
- **Пример реализации**: Распространенной практикой является использование такого инструмента, как [Restic](https://restic.net/), в рамках этого пользовательского скрипта для выполнения удаленного резервного копирования критически важных данных (Tiers 1 и 2) в S3-совместимое хранилище.
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Концепция: Модель многоуровневого хранения](/root/concepts/tiered-storage)
|
||||
- [Справочник: Справочник ROOT_ API Reference](/root/reference/root-api)
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Операции управления уровнями (Tiers)
|
||||
description: Классификация хранилища, символические ссылки и изоляция привилегий.
|
||||
weight: 55
|
||||
---
|
||||
|
||||
Операции управления уровнями отвечают за соблюдение [Модели многоуровневого хранения](/root/concepts/tiered-storage) и обеспечение корректного владения файловой системой и изоляции.
|
||||
|
||||
## Основные операции с уровнями (Tier Actions) {#actions}
|
||||
|
||||
| Операция | Описание |
|
||||
| :--- | :--- |
|
||||
| `tiers/chown` | Устанавливает корректного владельца файловой системы для [Пользователей проекта](#useradd). |
|
||||
| `tiers/link` | Управляет символическими ссылками между директориями проекта и их соответствующими [Уровнями (Tiers)](/root/glossary#tier). |
|
||||
| `tiers/useradd` | Создает уникального системного пользователя для каждого проекта для обеспечения [Изоляции привилегий](/root/concepts/security-model). |
|
||||
|
||||
## Управление пользователями (`tiers/useradd`) {#useradd}
|
||||
|
||||
Действие `tiers/useradd` создает выделенного низкопривилегированного системного пользователя для каждого проекта внутри узла. Этот пользователь затем используется для запуска контейнеров проекта, гарантируя, что компрометация одного проекта не даст злоумышленнику доступ ко всему хосту.
|
||||
|
||||
- **Соглашение об именовании**: Пользователи обычно называются в честь проекта.
|
||||
- **Членство в группах**: Пользователи могут быть опционально добавлены в группу `docker` или взаимодействовать с Docker другими безопасно настроенными способами по выбору оператора.
|
||||
|
||||
## Привязка хранилища (`tiers/link`) {#link}
|
||||
|
||||
Действие `tiers/link` создает структуру символических ссылок, необходимую для модели многоуровневого хранения. Оно гарантирует, что директории `config`, `data` и `logs` внутри папки проекта указывают на их физическое местоположение в `@tier1`, `@tier2` и `@tier3` соответственно.
|
||||
|
||||
```bash
|
||||
# Пример структуры ссылок, созданной tiers/link
|
||||
/srv/root/icarus/synapse/config -> /srv/storage/@tier1/synapse
|
||||
/srv/root/icarus/synapse/data -> /srv/storage/@tier2/synapse
|
||||
/srv/root/icarus/synapse/logs -> /srv/storage/@tier3/synapse
|
||||
```
|
||||
|
||||
## Управление владельцами (`tiers/chown`) {#chown}
|
||||
|
||||
После того как уровни и ссылки созданы, действие `tiers/chown` гарантирует, что физические директории на каждом уровне принадлежат правильному пользователю проекта. Это критически важно для предотвращения ошибок доступа и гарантии того, что проекты могут обращаться только к своим собственным данным.
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Концепция: Модель многоуровневого хранения](/root/concepts/tiered-storage)
|
||||
- [Концепция: Безопасность и изоляция привилегий](/root/concepts/security-model)
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Вспомогательные операции (Utils)
|
||||
description: Общие вспомогательные скрипты для обслуживания, валидации и управления сертификатами.
|
||||
weight: 56
|
||||
---
|
||||
|
||||
Вспомогательные операции предоставляют общие функции для обслуживания узлов, валидации и выполнения специфических задач проектов.
|
||||
|
||||
## Основные вспомогательные операции {#actions}
|
||||
|
||||
| Операция | Описание |
|
||||
| :--- | :--- |
|
||||
| `utils/extract-traefik-certs` | Извлекает сертификаты SSL/TLS и приватные ключи из хранилища Traefik `acme.json`. |
|
||||
| `utils/generate-happ-subscriptions` | Автоматически генерирует файлы подписки HApp на основе текущих метаданных проекта. |
|
||||
| `utils/lint-docker-compose` | Выполняет статический анализ всех файлов `docker-compose.yml` на соответствие стандартам общих модулей. |
|
||||
|
||||
## Управление сертификатами (`utils/extract-traefik-certs`) {#certificates}
|
||||
|
||||
Traefik сохраняет свои сертификаты, выпущенные через ACME (например, от Let's Encrypt), в одном файле `acme.json`. Действие `utils/extract-traefik-certs` парсит этот файл и извлекает отдельные файлы `fullchain.pem` и `privkey.pem`.
|
||||
|
||||
Это особенно полезно, когда другим сервисам (например, почтовым серверам или приложениям вне Docker) требуются те же SSL-сертификаты.
|
||||
|
||||
## Контроль качества (`utils/lint-docker-compose`) {#linting}
|
||||
|
||||
Для поддержания согласованности и безопасности действие `utils/lint-docker-compose` проверяет все compose-файлы в инфраструктуре. Оно проверяет:
|
||||
|
||||
- **Стандарты именования**: Гарантирует, что имена проектов и контейнеров соответствуют соглашению `{node}-{project}`.
|
||||
- **Контекст безопасности**: Отмечает контейнеры, работающие под пользователем `root` без обоснованного переопределения.
|
||||
- **Ограничения ресурсов**: Идентифицирует сервисы, у которых отсутствуют лимиты CPU или памяти.
|
||||
- **Стандарты Label**: Проверяет наличие необходимых меток (labels) для маршрутизации (например, [Traefik](https://traefik.io/)) и [CrowdSec](/root/concepts/security-model#crowdsec).
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
|
||||
- [Концепция: Принципы инфраструктуры](/root/concepts/principles)
|
||||
- [Концепция: Безопасность и изоляция привилегий](/root/concepts/security-model)
|
||||
Reference in new issue
Block a user