Эксплуатация

Команды и переменные

Каждая команда, каждый флаг, каждая переменная окружения и что значит каждый код возврата.

Один бинарник, девять команд. Каждая команда, работающая с конфигурацией, берёт путь к ней первым аргументом: у Unruin нет понятия «текущая» конфигурация — файл и есть единственная правда, и вы всегда говорите, о каком идёт речь.

Внутри образа Docker всё то же самое, но с приставкой docker compose exec unruin.

unruin validate <config.yaml> [--preflight]
unruin run <config.yaml> <job>
unruin serve <config.yaml>
unruin prune <config.yaml> <job> [--dry-run]
unruin unlock <config.yaml> <job> [--remove-all]
unruin restore-guide <config.yaml> <job>
unruin restore <config.yaml> <job> [snapshot] [--dest name] [--to dir]
unruin secret set|ls|rm <name>
unruin mcp

validate

Проверка на бумаге: ссылки разрешаются, параметры источников осмысленны, расписания разбираются, правила хранения согласованы, у каждого задания есть все нужные доступы. Неизвестные ключи отвергаются, поэтому опечатка падает громко, а не игнорируется.

unruin validate /config/jobs.yaml
# config OK: 3 server(s), 2 destination(s), 5 job(s)

--preflight добавляет живую половину: разрешает каждый секрет по-настоящему, открывает соединение SSH с каждым сервером и щупает каждое хранилище.

unruin validate /config/jobs.yaml --preflight
# preflight (live connectivity):
#   [OK  ] server vps-prod-1
#   [FAIL] destination nas — ssh: connect to host nas-01 port 22: i/o timeout

Проверку на бумаге стоит гонять в CI на репозитории с конфигурацией; --preflight — после смены ключа, хоста или ведра. Это разница между «файл разбирается» и «это действительно пойдёт сегодня ночью».

run

Одно задание, прямо сейчас, от начала до конца: копия → параллельная рассылка restic copy по вторым хранилищам → контрольное восстановление, если задание его просит. Запуск записывается в историю, оповещения уходят по notify.on задания.

unruin run /config/jobs.yaml billing-db
# job "billing-db": success

Запуск «с оговорками» возвращает 0. Оговорочная копия — годная копия: она видна и в выводе, и в панели, и в оповещениях, но останавливать из-за неё ваш скрипт не нужно. Единицу возвращает только failed. См. что считается успехом.

serve

Демон: планировщик, панель, JSON API, уборка по расписанию, пределы времени и оповещения одним процессом.

unruin serve /config/jobs.yaml
# unruin: dashboard on http://127.0.0.1:8080
# unruin: scheduling 5 job(s), tick every 1m0s (Ctrl-C to stop)

Он не стартует на негодной конфигурации и не стартует на адресе не-loopback без настроенного доступа — см. вход и выставление наружу.

При старте он приводит в порядок запуски, оставшиеся в состоянии running после падения или перезапуска: убитый процесс не должен вечно блокировать собственное задание проверкой на наложение. По SIGINT/SIGTERM он сначала перестаёт принимать соединения, а потом доводит до конца то, что уже идёт.

prune

Применяет правила хранения задания к его хранилищам, беря prune_access там, где хранилище его задаёт. Идёт в очереди по метке занятости, поэтому не может столкнуться с копированием в то же хранилище.

unruin prune /config/jobs.yaml billing-db --dry-run
unruin prune /config/jobs.yaml billing-db

На хранилище, которое вам дорого, всегда сначала --dry-run: уборка — единственная операция в Unruin, которая удаляет данные намеренно.

serve делает это по расписанию, когда у задания задан prune_schedule.

unlock

Снимает метки занятости, оставленные упавшим запуском. Без флага снимает только те, которые restic считает брошенными: процесса, который их держал, больше нет.

unruin unlock /config/jobs.yaml billing-db
unruin unlock /config/jobs.yaml billing-db --remove-all

--remove-all снимает и живые. Пользуйтесь им, только когда вы точно знаете, что тот процесс мёртв, а restic этого понять не может. Метку уборки не снимает сама ни одна ветка кода: сорвать её, пока уборка действительно идёт, — это способ уничтожить хранилище.

restore-guide

Печатает готовый лист восстановления для задания: где лежит хранилище, какая метка у точек восстановления, и команды, специфичные для типа источника, — всё подставлено.

unruin restore-guide /config/jobs.yaml billing-db

Вывод английский намеренно: это набор команд, которые вы будете набирать руками, а команды не переводят. Распечатайте лист сейчас и положите туда, где не эта машина: вся ценность листа в том, что он читается, когда машины, которая его печатает, уже нет.

restore

Разворачивает точку восстановления задания в папку на исходном хосте. На оркестратор ничего не скачивается, и ничего не перезаписывается: цель — всегда новая папка.

unruin restore /config/jobs.yaml billing-db                       # последняя
unruin restore /config/jobs.yaml billing-db 4a7b9c1d              # конкретная
unruin restore /config/jobs.yaml billing-db --dest nas --to /srv/restore

Положить данные туда, где их ждёт приложение, остаётся ручным шагом — намеренно. В каждой стянутой копии лежит сгенерированный restore.sh, который это автоматизирует, а значения для подстановки собраны у него наверху. Но останавливать ваш контейнер и переписывать живой том Unruin сам не станет.

secret

Встроенное шифрованное хранилище. Значения читаются со стандартного ввода, а не из аргументов, поэтому в список процессов они не попадают.

unruin secret set restic/minio-primary          # ввести, затем Ctrl-D
printf %s 'сам-пароль' | unruin secret set restic/minio-primary
unruin secret set ssh/vps-prod-1 < ~/.ssh/id_ed25519_backup
unruin secret ls
unruin secret rm restic/old-repo

Ввод сохраняется дословно, вместе с переводом строки на конце — команда печатает, сколько байт сохранила, так что заметить это можно. Подробности и то, что держать отдельно, — на странице секреты.

mcp

Поднимает сервер MCP на стандартном вводе-выводе, чтобы помощник с искусственным интеллектом мог настроить Unruin и управлять им. Это мост к работающему unruin serve через его HTTP API, поэтому всё, что помощник делает, проходит ту же проверку, ту же атомарную запись и тот же вход, что и панель.

UNRUIN_API_URL=http://127.0.0.1:8080 UNRUIN_API_TOKEN=… unruin mcp

См. настройку через ИИ.

Коды возврата

Переменные окружения

Везде

serve

Доставка restic на цели

mcp