140 lines
16 KiB
Markdown
140 lines
16 KiB
Markdown
---
|
||
title: Справочник действий
|
||
description: "Каждое действие commons: аргументы и поведение."
|
||
weight: 32
|
||
---
|
||
|
||
Действия [commons](/apex/glossary#commons) по группам. Аргументы показаны в том виде, в котором их принимает парсер; необязательные аргументы заключены в квадратные скобки. Коды возврата следуют [соглашению движка](/apex/reference/cli#exit-codes).
|
||
|
||
## configure {#configure}
|
||
|
||
### configure
|
||
|
||
`apex configure [--dry-run]`
|
||
|
||
Запускает `base`, `timezone`, `ufw`, `crowdsec`, `cron`, `systemd`, `routing`, затем дополнительные действия узла. Ошибка шага даёт ненулевой итоговый код; последующие шаги могут продолжить работу. Флаг `--dry-run` передаётся только тем шагам, которые его поддерживают, поэтому не гарантирует отсутствие изменений для всей команды.
|
||
|
||
### configure/base
|
||
|
||
`apex configure/base`
|
||
|
||
Проверяет, что операционная система — Debian; иначе завершается с кодом `1`. Проверяет состояние пакетов `curl`, `wget`, `git`, `rsyslog` и `ufw`, устанавливает недостающие и запускает rsyslog. Отклоняет план APT с обновлениями или удалениями и использует `--no-upgrade --no-remove`. Не запускайте другие пакетные операции одновременно: проверка плана и установка выполняются отдельно. Перед запуском `/usr/local/bin/ufw-docker` от root проверяет закреплённую ревизию и SHA-256. Небезопасные пути и непроверенные загрузки отклоняются; одних прав на исполнение недостаточно.
|
||
|
||
### configure/timezone
|
||
|
||
`apex configure/timezone [--dry-run]`
|
||
|
||
Применяет часовой пояс IANA из `configs/timezone` и перезапускает активную службу cron после изменения. Если файла нет, сохраняет текущий пояс; неверное имя приводит к ошибке до внесения изменений.
|
||
|
||
### 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}
|
||
|
||
### sync/repository
|
||
|
||
`apex sync/repository <telegram_bot_url>`
|
||
|
||
Коммит [«capture-up»](/apex/glossary#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}
|
||
|
||
### 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}
|
||
|
||
### tiers/link
|
||
|
||
`apex tiers/link <tier1_path> <tier2_path> <tier3_path>`
|
||
|
||
Создаёт полную структуру символьных ссылок для [уровней хранения](/apex/glossary#tier): ссылки уровня узла `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]`
|
||
|
||
Применяет матрицу прав владения (см. [Концепция: Многоуровневое хранилище](/apex/concepts/tiered-storage#ownership)) к корням уровней — по умолчанию используются ссылки уровней узла. Требует наличия группы `noroot-shared` (иначе завершается с кодом `1`); проекты с неполными идентификаторами в `.env` пропускаются с предупреждением.
|
||
|
||
## utils {#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](/apex/glossary#anchor-ip) в `compositions/*/docker-compose.yml` на корректность формата, уникальность и принадлежность подсети узла; (2) запуск compose-линтера `dclint` с флагом `--fix` в контейнере по всему репозиторию (за исключением ссылок уровней, `.env` и подмодуля commons). Флаг `--hook` ограничивает второй этап файлами compose в индексе git и повторно добавляет в индекс исправленные файлы. Код возврата отражает результаты обоих этапов.
|
||
|
||
## compose {#compose}
|
||
|
||
### compose
|
||
|
||
`apex compose [-p <composition>] [--dry-run] <action> [extra...]`
|
||
|
||
Без цели обходит сначала core, затем остальные композиции по алфавиту; для `down` порядок обратный. Параметр `-p` выбирает одну композицию или `all`. Команда `up` по умолчанию добавляет `-d`; файлы `.env` и `apex.env` подключаются в этом порядке, вычисленные значения узла и путей передаются через окружение. Параметры APEX ставятся перед действием, остальные аргументы передаются Docker Compose. Флаг `--dry-run` печатает команды без запуска.
|
||
|
||
Сохраняются формы `apex compose restart apex traefik` и `apex compose up -d apex`. Используйте `-p`, чтобы явно отличить композицию от сервиса или значения параметра.
|
||
|
||
## env {#env}
|
||
|
||
`apex env [--export | --dotenv | --write <path> | --sync]`
|
||
|
||
По умолчанию выводит экспорты APEX для `eval "$(apex env)"` с экранированием оболочки. `--dotenv` выводит формат dotenv; `--write` записывает вычисленные значения в отдельный файл, в том числе по относительному пути. Эти режимы не читают секреты композиции и не объединяют `apex.env`.
|
||
|
||
Режим `--sync` сохраняет пользовательский текст `compositions/apex/.env` и обновляет управляемый блок: сначала настройки `apex.env`, затем вычисленные значения. В блок входят `COMPOSE_PROFILES` и `TZ`, поэтому Compose можно запускать напрямую из каталога core. Ссылки tier сохраняются, файл получает права `0600`. Повторяйте синхронизацию после изменения исходных настроек или путей. Некорректные маркеры останавливают запись; переменные оболочки сохраняют приоритет Docker Compose.
|
||
|
||
---
|
||
|
||
**См. также:**
|
||
|
||
- [Справочник: CLI](/apex/reference/cli)
|
||
- [Руководство: Эксплуатация узла](/apex/guides/host-operations)
|
||
- [GitHub: apex.ermnvldmr.com](https://github.com/deytenit/apex.ermnvldmr.com)
|