deytenit
b3638f4d63
🤖 PR generated for branch `fix/cyrillic-fonts-dev-certs-and-page-head`.
### Changes Summary
- **Fonts**: Add Cyrillic glyph subsets for Lato, EB Garamond, and Fira
Code.
- **Dev**: Support remote Root CA and encrypted dev CA key in
`.env.dev`.
- **UI & Kits**: Add size variant to `Breadcrumbs` component and enlarge
`PageHead` breadcrumbs with tuned collapse scroll threshold.
- **ESLint**: Add `no-hanging-particles` i18n & markdown typography rule
with auto-fixer.
- **Content & i18n**: Apply `ru-text` editorial and typography polish
(em dashes, number ranges, «ё» restoration, non-breaking spaces) across
`services/www` and `services/docs`.
72 lines
9.1 KiB
Markdown
72 lines
9.1 KiB
Markdown
---
|
||
title: Контекст выполнения
|
||
description: ctx — единый интерфейс взаимодействия между действием и хостом.
|
||
weight: 14
|
||
---
|
||
|
||
Каждое [действие](/apex/glossary#action) получает объект `ctx` первым аргументом. Это единственный штатный способ взаимодействия с хостом: логирование, запуск процессов, рендеринг шаблонов, правка файлов, настройка межсетевого экрана и сервисов, а также отправка уведомлений — всё выполняется через него. Благодаря этому действия остаются компактными и декларативными, а общие для всего флота правила (формат логов, регламент резервного копирования, структура уведомлений) сосредоточены в одном месте — [движке](/apex/glossary#engine).
|
||
|
||
## Члены {#members}
|
||
|
||
| Член | Назначение |
|
||
|---|---|
|
||
| `ctx.log` | Логирование с префиксом: `[<node>] [<action>] [LEVEL] message`; ошибки пишутся в stderr, остальные сообщения — в stdout. |
|
||
| `ctx.sys` | Выполнение процессов (`run`, `sudo`, `ok`), вспомогательные функции для сервисов systemd и идемпотентная установка пакетов. |
|
||
| `ctx.tpl` | Рендеринг шаблонов из каталога `configs/` с помощью `string.Template.safe_substitute`. |
|
||
| `ctx.host` | Идемпотентные изменения на хосте: резервные копии с временными метками, атомарная запись файлов, внедрение блоков-маркеров, установка crontab с откатом. |
|
||
| `ctx.ufw` | Управление правилами межсетевого экрана хоста и контейнеров (см. [Концепция: Модель безопасности](/apex/concepts/security-model)). |
|
||
| `ctx.crowdsec` | Установка CrowdSec, развёртывание конфигураций и управление коллекциями. |
|
||
| `ctx.systemd` | Рендеринг и активация systemd-юнитов из `configs/systemd/`. |
|
||
| `ctx.notify` | Отправка уведомлений в Telegram; методы возвращают булево значение, позволяя действиям учитывать факт доставки в коде завершения. |
|
||
| `ctx.paths` | Разрешённые пути репозитория: `repo_root`, `commons`, `proprietaries`, `configs`, `compositions`, `core` и свойства уровней хранилища. |
|
||
| `ctx.node` | Разрешённая запись [идентичности узла](/apex/glossary#node-identity) (`name`, `subnet`, `fqdn`, `host`); принимает значение `None` в автономном чекауте commons. |
|
||
| `ctx.commons` | Доступен только в переопределяющих проприетарных действиях: вызов `ctx.commons.run(args)` делегирует управление затенённой реализации commons. |
|
||
|
||
Сигнатуры методов подробно описаны в разделе [Справочник: API движка](/apex/reference/engine-api).
|
||
|
||
## Семантика шаблонов {#templates}
|
||
|
||
Модуль `ctx.tpl` рендерит файлы из `configs/` с помощью `string.Template.safe_substitute`:
|
||
|
||
- Известные переменные `$VAR` и `${VAR}` подставляются.
|
||
- **Неизвестные переменные сохраняются буквально:** опечатка в имени переменной останется в готовом файле на виду, а не превратится незаметно в пустую строку.
|
||
- Подстановки команд shell (`$(cmd)`) не затрагиваются, что сохраняет целостность строк crontab со встроенными командами вида `$(cat ...)`.
|
||
|
||
Подстановка выполняется по словарю `ctx.vars()`: это полное окружение процесса плюс переменные `APEX_*`, предоставляемые движком (перечислены ниже). В шаблонах нет циклов и условий — вся логика ветвления находится в действиях.
|
||
|
||
## Экспорт переменных {#vars}
|
||
|
||
Функция `ctx.vars()` возвращает словарь окружения, используемый при каждом рендеринге шаблонов. Подмножество переменных `APEX_*` также передаётся в `docker compose` действиями оркестрации. На узле оно включает:
|
||
|
||
| Переменная | Значение |
|
||
|---|---|
|
||
| `APEX_COMMONS` | Абсолютный путь к каталогу commons (лаунчер расположен по пути `$APEX_COMMONS/apex`). |
|
||
| `APEX_REPO_ROOT` | Абсолютный путь к корню репозитория узла. |
|
||
| `APEX_NODE_HOST`, `APEX_NODE_FQDN`, `APEX_SUBNET` | Разрешённые поля идентичности узла. |
|
||
| `APEX_TIER1`…`APEX_TIER3` | Каталоги данных базового проекта для каждого [уровня](/apex/glossary#tier). |
|
||
| `APEX_TIER1_SHARED`…`APEX_TIER3_SHARED` | Общие области внутри каждого уровня. |
|
||
| `APEX_TIER_ROOT1`…`APEX_TIER_ROOT3` | Корневые каталоги хранилищ уровней (ссылки уровня узла). |
|
||
|
||
Полная матрица источников и потребителей переменных приведена в разделе [Справочник: Переменные окружения](/apex/reference/environment).
|
||
|
||
## Дисциплина изменения хоста {#host}
|
||
|
||
Объект `ctx.host` реализует строгие правила записи:
|
||
|
||
- **Атомарная запись:** метод `write_file` сначала формирует временный файл (права `0644`, аналогичные перенаправлению вывода из-под root) и перемещает его на место через `mv` или `sudo cp`. При перезаписи существующего файла его исходные права сохраняются.
|
||
- **Резервные копии с временной меткой:** по запросу перед записью создаётся копия старого файла рядом с целевым: `<name>.<epoch>.bak`.
|
||
- **Внедрение блоков-маркеров:** изменения внутри системных файлов (например, `/etc/ufw/before.rules`) обрамляются комментариями-маркерами начала и конца. Перед вставкой нового блока после якорной строки движок удаляет все предыдущие управляемые блоки (включая оставшиеся от старого инструментария), предотвращая накопление дубликатов при повторных запусках.
|
||
- **Откат crontab:** метод `install_crontab` делает снимок текущего crontab, отклоняет пустой результат рендеринга (код выхода `65`), показывает diff изменений и автоматически восстанавливает снимок при ошибке установки.
|
||
|
||
## Уведомления {#notifications}
|
||
|
||
Модуль `ctx.notify` отправляет сообщения в Telegram средствами стандартной библиотеки (`urllib`). Полезная нагрузка содержит имя хоста (`APEX_NODE_HOST`), статус (`firing`/`resolved`), уровень важности и текст сообщения, обрезанный до 200 символов. Методы возвращают `True` только при успешной доставке; автоматические действия трактуют сбой отправки итогового статуса как критическую ошибку (код завершения `1`), поэтому проблемы со связью сразу становятся заметны.
|
||
|
||
---
|
||
|
||
**См. также:**
|
||
|
||
- [Справочник: API движка](/apex/reference/engine-api)
|
||
- [Справочник: Переменные окружения](/apex/reference/environment)
|
||
- [Концепция: Действия и оверлей](/apex/concepts/actions-and-overlay)
|