docs: Update docs for the correctness (#13)

This commit is contained in:
deytenit authored and GitHub committed 2026-04-15 00:48:06 +03:00
1 parent 8dba55272c
commit 51a783f93a
60 files changed
+2456 -380

No files matched your search

@@ -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)