Создание резервной копии

komrad-cli backup create создаёт зашифрованный набор резервных копий для одного узла KOMRAD. Набор содержит данные всех активных поверхностей и может быть сохранён локально, на SFTP-сервере или в S3-совместимом хранилище.

Быстрый старт

komrad-cli backup create \
  --to /var/backups/komrad \
  --passphrase "секретная_фраза"

После выполнения в /var/backups/komrad появляется директория набора с именем komrad-<хост>-<метка_времени> (например, komrad-node1-20260630T120000Z), содержащая манифест и зашифрованные блобы.

Что включается в резервную копию

Поверхность	Данные	Механизм
PostgreSQL	все базы данных KOMRAD	pg_dump -Fc через echelonpg
События ClickHouse	таблица komrad_events	нативный BACKUP ClickHouse
NATS JetStream	очереди komrad-bus	JetStream snapshot
Конфигурации	*.yaml сервисов	tar + zstd
Сертификаты и ключи	TLS-материал, учётные данные NATS	tar + zstd

Поверхности обнаруживаются автоматически через конфигурационные файлы сервисов. Для исключения поверхности используйте --no-pg, --no-ch, --no-natsjs, --no-events или --exclude <поверхность>.

Учётные данные PostgreSQL

Пароль подключения к PostgreSQL берётся в следующем порядке:

1. Пароль из конфигурационных файлов сервисов KOMRAD (если задан).
2. Переменная окружения PGPASSWORD.
3. Файл паролей libpq: PGPASSFILE или ~/.pgpass (совпадение по хосту, порту, базе и пользователю).

Пароль нигде не сохраняется — используется только в памяти на время выполнения. При ошибке аутентификации (SQLSTATE класс 28) команда подсказывает настроить PGPASSWORD или ~/.pgpass.

Диск резервных копий ClickHouse

Нативный BACKUP ClickHouse пишет на диск komrad_backup с корнем /var/lib/komrad/backups/clickhouse. Инсталлятор KOMRAD создаёт эту директорию автоматически (владелец clickhouse:clickhouse, права 0750). На узлах, установленных более старым инсталлятором, создайте её вручную:

sudo mkdir -p /var/lib/komrad/backups/clickhouse
sudo chown clickhouse:clickhouse /var/lib/komrad/backups/clickhouse
sudo chmod 0750 /var/lib/komrad/backups/clickhouse

Если диск не объявлен в конфигурации ClickHouse, добавьте в /etc/clickhouse-server/config.d/komrad_backup.yaml и перезапустите clickhouse-server:

storage_configuration:
  disks:
    komrad_backup:
      type: local
      path: /var/lib/komrad/backups/clickhouse/
backups:
  allowed_disk: komrad_backup

Хранилища

Флаг --to задаёт одно или несколько хранилищ (флаг повторяется):

# Локальная директория
komrad-cli backup create --to /var/backups/komrad --passphrase "..."

# SFTP / S3 — только голый токен типа или @N вместе с --config.
# Формы sftp:host/path и s3:bucket/prefix не поддерживаются.
komrad-cli backup create --to sftp --config /etc/echelon/komrad/komrad-backup.yaml \
  --passphrase "..."
komrad-cli backup create --to @0 --config /etc/echelon/komrad/komrad-backup.yaml \
  --passphrase "..."

Для настройки параметров подключения к SFTP или S3 укажите komrad-backup.yaml через --config:

targets:
  - type: sftp
    host: backup-server
    user: komrad
    key_file: /etc/echelon/komrad/keys/backup_id_ed25519
    path: /backups/komrad
  - type: s3
    endpoint: https://s3.example.com
    bucket: komrad-backups
    access_key: AKIAIOSFODNN7EXAMPLE
    secret_key: wJalrXUtnFEMI/K7MDENG
    prefix: komrad

В строковых значениях конфига поддерживается подстановка ${ИМЯ_ПЕРЕМЕННОЙ} из окружения, а секреты можно выносить в отдельные файлы через ключи *_file (password_file, secret_key_file и т. д.). Полная схема komrad-backup.yaml — в справочнике.

Шифрование

Резервные копии всегда шифруются. По умолчанию используется age.

Бэкенд	Флаг	Применение
age (умолчание)	--cipher age	Универсальный; pure-Go
aes-gcm	--cipher aes-gcm	Pure-Go AEAD
openssl	--cipher openssl	ГОСТ на Astra Linux / REDOS
jacarta	--cipher jacarta	Аппаратный токен JaCarta (ГОСТ)

Фраза-пароль задаётся тремя способами (в порядке приоритета):

1. --passphrase "фраза"
2. Переменная окружения KOMRAD_BACKUP_PASSPHRASE
3. cipher.passphrase в komrad-backup.yaml

примечание

Бэкенд jacarta фразу-пароль игнорирует: ключ шифрования защищается аппаратным токеном, а --passphrase при восстановлении играет роль запасной escrow-фразы. См. Шифрование токеном JaCarta.

Для OpenSSL/ГОСТ укажите параметры в конфиге:

cipher:
  backend: openssl
  passphrase: "секретная_фраза"
  openssl:
    cipher: kuznyechik-ctr  # обязательный параметр
    mac: hmac-sha256        # умолчание; также gost-mac | magma-mac
    engine: auto            # auto | engine | provider | none
    iter: 600000            # итерации PBKDF2 (умолчание 600000)

Резервное копирование событий (ClickHouse)

По умолчанию создаётся полная копия таблицы komrad_events (--ch-mode full). Для крупных инсталляций доступны инкрементальная цепочка и ограничение по периоду.

Инкрементальный режим

--ch-mode incremental строит нативную цепочку ClickHouse на диске komrad_backup: метки base-<метка_времени> и inc-<метка_времени>. Каждый следующий запуск либо продолжает цепочку от текущего кончика, либо начинает новую базовую копию.

Как выбирается база (двусторонняя discovery):

1. Если среди --to есть локальный каталог, берётся покрытие ClickHouse из манифеста самого нового опубликованного набора; его метка должна физически присутствовать на диске komrad_backup (иначе цепочку строить нельзя — SETTINGS base_backup ссылается только на локальный диск).
2. Если локального кончика нет (только SFTP/S3, пустой каталог или манифест без CH), берётся новейшая нативная метка base-*/inc-* на диске — упорядочивание по разобранной метке времени, а не по строке; метки export-* в выбор не попадают.
3. Если подходящей метки нет, кончик отсутствует на диске, метка времени не разбирается или возраст кончика превысил --ch-base-rotate (умолчание 7d), создаётся новая полная база. При вынужденном полном запуске поверх уже существующих меток в выводе может появиться предупреждение вида clickhouse: starting a new full base (...).

Инкрементальный режим не применяется вместе с --exact (логический экспорт) и --no-events. Для расписания инкрементальный режим удобно задать так:

# в KOMRAD_BACKUP_EXTRA_ARGS или вручную:
komrad-cli backup create \
  --ch-mode incremental \
  --ch-base-rotate 7d \
  --to /var/backups/komrad --passphrase "..."

примечание

Восстановление инкрементального набора требует, чтобы базовая метка всё ещё лежала на диске komrad_backup. Не удаляйте каталоги стейджинга вручную и не чистите наборы через find/rm — используйте backup prune: он не удалит базу, пока от неё зависит сохраняемый инкремент. См. также восстановление.

# Полная копия (умолчание)
komrad-cli backup create \
  --ch-mode full \
  --to /var/backups/komrad --passphrase "..."

# Инкрементальная цепочка (первая ночь — база, далее — инкременты;
# после --ch-base-rotate снова база)
komrad-cli backup create \
  --ch-mode incremental \
  --to /var/backups/komrad --passphrase "..."

# Только события за последние 30 дней
komrad-cli backup create \
  --events-window 30d \
  --to /var/backups/komrad --passphrase "..."

# Только события за заданный период
komrad-cli backup create \
  --events-since 2026-01-01 \
  --events-until 2026-06-30 \
  --to /var/backups/komrad --passphrase "..."

# Без событий (только настройки и инциденты)
komrad-cli backup create \
  --no-events \
  --to /var/backups/komrad --passphrase "..."

Расписание

systemd-таймер

sudo tee /etc/systemd/system/komrad-backup.service <<'EOF'
[Unit]
Description=KOMRAD backup

[Service]
Type=oneshot
ExecStart=/opt/echelon/komrad/bin/komrad-cli backup create \
  --to /var/backups/komrad \
  --config /etc/echelon/komrad/komrad-backup.yaml
EnvironmentFile=/etc/echelon/komrad/backup.env
EOF

sudo tee /etc/systemd/system/komrad-backup.timer <<'EOF'
[Unit]
Description=KOMRAD backup — ежедневно в 02:00

[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true

[Install]
WantedBy=timers.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now komrad-backup.timer

Пакет komrad-server уже устанавливает /etc/echelon/komrad/backup.env (права 0600, владелец root:root) — не создавайте файл заново, а отредактируйте установленный и задайте в нём KOMRAD_BACKUP_PASSPHRASE:

KOMRAD_BACKUP_PASSPHRASE=секретная_фраза

Полная схема файла (остальные ключи) — в справочнике.

cron

Пакет komrad-server устанавливает готовый фрагмент /etc/cron.d/komrad-backup и скрипт-обёртку. Пароль хранится в отдельном файле /etc/echelon/komrad/backup.env с правами 0600 и никогда не попадает ни в crontab, ни в аргументы процесса.

Полная процедура — в разделе Периодическое резервное копирование по расписанию.

Проверка резервной копии

После создания копии проверьте целостность:

komrad-cli backup verify /var/backups/komrad/komrad-node1-20260630T120000Z \
  --passphrase "секретная_фраза"

Команда проверяет манифест и sha256-контрольные суммы всех блобов. Включите проверку в расписание или запускайте вручную после каждого backup create.