deytenit
9ee672504f
🤖 Pull request created from `various-fixes` containing PageHead
breadcrumbs and navigation alignment fixes, Umami analytics proxy, and
infrastructure updates.
14 KiB
title, description, weight
| title | description | weight |
|---|---|---|
| Справочник действий | Каждое действие commons: аргументы и поведение. | 32 |
Шестнадцать действий «commons» (общего репозитория), разбитых по группам. Аргументы показаны в том виде, в котором их принимает парсер; необязательные аргументы заключены в квадратные скобки. Коды возврата следуют соглашению движка.
configure
configure
apex configure [--dry-run]
Запускает весь набор в фиксированном порядке (base, ufw, crowdsec, cron, systemd, routing) и останавливается на первом неудачном шаге, возвращая его код возврата. Флаг --dry-run передаётся шагам, которые его поддерживают.
configure/base
apex configure/base
Проверяет, что операционная система — Debian (иначе завершается с кодом 1). Обновляет индекс пакетов, устанавливает необходимые пакеты (curl, wget, git, rsyslog), проверяет статус службы rsyslog, устанавливает ufw, если его нет, и загружает вспомогательную утилиту ufw-docker в ~/.local/bin/ufw-docker (если утилита уже есть, загрузка пропускается).
configure/ufw
apex configure/ufw [--dry-run]
Применяет правила межсетевого экрана узла из configs/ufw/: host/host.rules через штатный ufw, host/before.rules и after.rules как самовосстанавливающиеся блоки внутри /etc/ufw/, а docker/*.rules — через ufw-docker. Завершается с кодом 1, если отсутствует корень конфигурации, с кодом 66 — если отсутствует ровно один из каталогов docker/ или host/, и с кодом 1 — если целевой файл в /etc/ufw не существует. Требует предварительного выполнения configure/base (проверяет наличие ufw и ufw-docker). В конце выводит напоминание о необходимости перезагрузки правил.
configure/crowdsec
apex configure/crowdsec [--dry-run]
Устанавливает CrowdSec через официальный скрипт, если cscli отсутствует. Рендерит шаблоны из configs/crowdsec/ в /etc/crowdsec/ (создавая резервные копии перезаписываемых файлов), устанавливает коллекции crowdsecurity/linux и crowdsecurity/traefik, а также устанавливает firewall-баунсер iptables, если файл configs/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.local существует, а пакет ещё не установлен. Флаг --dry-run выполняет рендеринг без записи на диск и пропускает установку.
configure/cron
apex configure/cron [--dry-run]
Рендерит configs/cron/crontab с помощью ctx.vars() и устанавливает полученное расписание через crontab -. Если исходный файл отсутствует, действие завершается с кодом 1. Если результат рендеринга пуст, возвращается код 65, а предыдущий crontab сохраняется. При сбое установки восстанавливается прежний crontab и возвращается код 1. Результат рендеринга всегда выводится для проверки.
configure/systemd
apex configure/systemd [--dry-run]
Рендерит каждый открытый файл (кроме скрытых) верхнего уровня из configs/systemd/ в /etc/systemd/system/<name>. Для каждого сервиса .service выполняет daemon-reload и активирует его командой с флагом --now. Если каталог конфигурации отсутствует, завершается с кодом 1.
configure/routing
apex configure/routing
Включает net.ipv4.ip_forward, настраивает правило политики fwmark 0x1 → routing-table-100 и локальный маршрут по умолчанию в этой таблице. Обе операции идемпотентны: повторные запуски ничего не меняют.
sync
sync/repository
apex sync/repository <telegram_bot_url>
Коммит «capture-up» (фиксация локальных изменений): переключается на ветку sync/<node> (или создаёт её), индексирует всё дерево вместе с обновлённым указателем на подмодуль commons, создаёт коммит от имени бота (если есть изменения), выполняет rebase на origin/main, обновляет подмодули и отправляет изменения командой с флагом --force-with-lease. Прерывается с кодом 1, если подмодуль commons содержит незакоммиченные правки или отсутствует каталог compositions/. При конфликте во время rebase операция отменяется и отправляется оповещение в Telegram. Об успехе и каждом сбое отправляется уведомление; сбой при отправке уведомления об успехе также завершает команду с кодом 1.
sync/packages
apex sync/packages <telegram_bot_url>
Только для Debian. Собирает список доступных обновлений apt (--just-print) и устаревших образов запущенных контейнеров (сравнивая локальный RepoDigest с дайджестом в реестре через skopeo), после чего отправляет единую сводку в Telegram. Работает исключительно в режиме чтения: пакеты и образы не изменяются. При необработанных сбоях отправляет оповещение в Telegram и завершается с кодом 1; так же действие ведёт себя и при ошибке доставки сводки.
backup
backup/run
apex backup/run <telegram_bot_url>
Управляет однократным запуском основного сервиса resticontainer, работающего по меткам (профиль manual). Проверяет доступность репозитория (при необходимости выполняет инициализацию), затем запускает процедуру backup. При этом resticontainer находит каждый сервис с метками compose вида restic.*, вызывает их предварительные хуки, останавливает контейнеры с меткой restic.backup.stop, сопоставляет пути монтирования контейнеров с путями на хосте и создаёт единый снимок за один вызов restic. Снимок помечается флагами --host <APEX_NODE_HOST>, --tag biweekly, --compression max. Затем защитная проверка удостоверяется, что свежий снимок для этого хоста действительно создан: если метки restic.* не были найдены, резервное копирование завершилось бы вхолостую, поэтому действие откажется сообщать об успехе. Следом применяется политика хранения forget --prune (7 daily / 4 weekly / 12 monthly). При любом сбое restic отправляет оповещение и завершается с кодом 1. При успешном завершении также отправляется оповещение, а ошибка его доставки приводит к выходу с кодом 1.
tiers
tiers/link
apex tiers/link <tier1_path> <tier2_path> <tier3_path>
Создаёт полную структуру символьных ссылок для уровней хранения: ссылки уровня узла compositions/@tierN, каталоги уровней для каждого проекта, общие области shared/ с обратными ссылками, проектные ссылки @tierN и символьную ссылку .env на первый уровень (если файл назначения отсутствует, он создаётся). Если существующий путь не является символьной ссылкой, действие запрашивает подтверждение; отказ пропускает создание ссылки.
tiers/useradd
apex tiers/useradd
Проверяет наличие группы noroot-shared, затем создаёт по одному заблокированному системному пользователю noroot-<project> для каждого проекта композиций (собственная основная группа, без домашнего каталога, оболочка nologin, участник общей группы) и прописывает переменные APEX_UID/APEX_GID/APEX_SHARED_GID в .env каждого проекта между служебными маркерами.
tiers/chown
apex tiers/chown [tier1_path] [tier2_path] [tier3_path]
Применяет матрицу прав владения (см. Концепция: Многоуровневое хранилище) к корням уровней — по умолчанию используются ссылки уровней узла. Требует наличия группы noroot-shared (иначе завершается с кодом 1); проекты с неполными идентификаторами в .env пропускаются с предупреждением.
utils
utils/extract-traefik-certs
apex utils/extract-traefik-certs <source_acme> <dest_dir> [telegram_bot_url]
Извлекает сертификаты из хранилища ACME в файлы fullchain.pem/privkey.pem для каждого домена с помощью контейнера-дампера, выставляет права chmod 600 на ключи и передаёт права владения выходным каталогом вызывающему пользователю. Если исходный файл отсутствует, действие завершается с кодом 1. При ошибках извлечения отправляет оповещение в Telegram (если указан URL).
utils/lint-docker-compose
apex utils/lint-docker-compose [--hook]
Выполняется в два этапа: (1) проверка якорных IP в compositions/*/docker-compose.yml на корректность формата, уникальность и принадлежность подсети узла; (2) запуск compose-линтера dclint с флагом --fix в контейнере по всему репозиторию (за исключением ссылок уровней, .env и подмодуля commons). Флаг --hook ограничивает второй этап файлами compose в индексе git и повторно добавляет в индекс исправленные файлы. Код возврата отражает результаты обоих этапов.
compose
compose
apex compose <action> [--dry-run] [extra...]
Оркеструет запуск docker compose <action> по всему узлу: сначала основной проект, затем сервисы в алфавитном порядке (в обратном — для команды down). Команда up по умолчанию использует ключ -d; файлы .env и apex.env подключаются для каждого проекта при их наличии; дополнительные аргументы пробрасываются дальше; флаг --dry-run (принимается в любой позиции) выводит сформированные команды без их выполнения.
См. также: