Конфигурация

Эта страница охватывает переменные окружения контейнера, монтирования, которые предоставляет шаблон, резервное копирование VM через SSH и настройку внешней копии. Пути репозиториев резервного копирования настраиваются внутри приложения (Настройки, Хранилище, Пути резервных копий), а не через переменные окружения.

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

Переменная	Обязательна	Описание
APP_KEY	Да	32-байтовый hex-секрет (64 hex-символа), используемый для вывода пароля репозитория restic. Сгенерируйте командой openssl rand -hex 32. Храните надёжно: его потеря делает зашифрованные резервные копии невосстановимыми.
LIBVIRT_HOST	Для VM	Хост Unraid, достигаемый через SSH для резервного копирования VM (по умолчанию host.docker.internal; шаблон предзаполняет заглушку с LAN-IP). Используйте LAN-IP вашего Unraid, обязательно в пользовательской сети br0.x. Используется и для копий наборов данных ZFS (поле шаблона Host SSH: Address); заполнитель 192.168.x.x считается незаданным.
LIBVIRT_SSH_PORT	Нет	SSH-порт хоста для резервного копирования VM (по умолчанию 22). Поле шаблона Host SSH: Port, также для наборов данных ZFS.
LIBVIRT_SSH_USER	Нет	SSH-пользователь на хосте для резервного копирования VM (по умолчанию root). Поле шаблона Host SSH: User, также для наборов данных ZFS.
LIBVIRT_URI	Нет	Полный URI подключения libvirt, используется дословно вместо построения его из трёх LIBVIRT_* переменных выше (которые тогда игнорируются для строки подключения). По умолчанию не задан. Нужен на TrueNAS Scale, чей libvirtd слушает на нестандартном сокете, который построенная форма выразить не может: qemu+ssh://<user>@<truenas-host>/system?socket=/run/truenas_libvirt/libvirt-sock. См. раздел про TrueNAS Scale в docs/vm-backup-ssh-setup.md. Если это URI qemu+ssh://, каждая из переменных LIBVIRT_HOST, LIBVIRT_SSH_USER и LIBVIRT_SSH_PORT, которая не задана, берётся из него, в том числе для собственных SSH-команд BombVault (передача NVRAM, наборы данных ZFS).
PORT	Нет	HTTP-порт (по умолчанию 3000; используется только с HTTP_ONLY=true).
HTTPS_PORT	Нет	HTTPS-порт (по умолчанию 3443; шаблон публикует его 1:1, поэтому WebUI отвечает на https://<ip>:3443).
HTTP_ONLY	Нет	Установите true, чтобы отключить самоподписанный HTTPS-слушатель и обслуживать только обычный HTTP (для использования за обратным прокси, завершающим TLS).
BIND_HOST	Нет	Адрес, на котором слушает WebUI (по умолчанию 0.0.0.0, все интерфейсы). В контейнере не задавайте его: опубликованным портам нужны все интерфейсы; 127.0.0.1 подходит для запуска вне Docker. Healthcheck обращается к тому же адресу.
TRUSTED_PROXY	Нет	Разделённые запятыми адреса или диапазоны CIDR обратного прокси перед BombVault (например, 192.168.20.11 или 10.0.0.0/8). Только с этих узлов заголовку X-Forwarded-For доверяют, и тогда ограничитель входа считает неудачи по реальному клиенту, а не сваливает всех за прокси в одну корзину. Не задано (по умолчанию) значит не доверять никому: безусловно принимаемый заголовок позволил бы любому выбрать себе корзину.
HOST_SOURCE_ROOT	Нет	Путь хоста, смонтированный как Host Data (по умолчанию /mnt). BombVault переводит источники bind-монтирований, о которых сообщает Docker, в пути под этим монтированием. Меняйте только если вы смонтировали другой корень хоста.
DATA_ROOT_SEGMENTS	Нет	Разделённые запятыми имена сегментов пути, которые помечают источник bind-монтирования как данные резервного копирования (по умолчанию appdata, в соответствии с конвенцией Unraid /mnt/user/appdata/<container>). Bind-монтирование контейнера автоматически выбирается для резервного копирования, если ЛЮБОЙ из перечисленных сегментов встречается как полный сегмент пути в его источнике на хосте, например DATA_ROOT_SEGMENTS=appdata,config также подхватит bind вида .../config. См. Обнаружение источников резервного копирования для других, всегда активных способов, которыми находится папка данных контейнера.
PLATFORM	Нет	Принудительно задаёт платформу, на которой BombVault считает себя запущенным, вместо автоопределения: unraid, generic или truenas (по умолчанию не задано: автоматически определяет Unraid, проверяя наличие его маркера dockerMan под flash-монтированием, иначе generic; нераспознанное значение тоже откатывается на generic, с записью в лог). Задавайте её явно на обычном Docker-хосте или TrueNAS Scale, вместо того чтобы полагаться на автоопределение, работающее только для Unraid: именно так и поступает универсальный compose-файл. Меняет конвенцию резервного пути appdata, значения назначения восстановления по умолчанию при межэкземплярном восстановлении и то, предпринимаются ли вообще шаги уведомлений и плагина-компаньона, доступные только на Unraid (см. internal/platform).
BOMBVAULT_SELF_CONTAINER	Нет	Имя самого контейнера BombVault, чтобы он никогда не резервировал (и тем самым не останавливал) сам себя.
BACKUP_MAX_HOURS	Нет	Максимальное число часов реального времени, в течение которого один запуск резервного копирования может удерживать блокировку своего домена, прежде чем он будет принудительно отменён (защита, чтобы зависший запуск не мог заблокировать домен навсегда). Пусто (по умолчанию) использует 48. Повысьте для очень больших или медленных облачных резервных копий (запуск, отменённый на пределе, завершается с context deadline exceeded). Установите 0, чтобы полностью отключить предел.
BACKUP_STALL_HOURS	Нет	Часы, в течение которых резервное копирование может совсем не продвигаться, прежде чем оно будет отменено. Пусто (по умолчанию) означает 2; установите 0, чтобы никогда не отменять при зависании. Это более тонкая из двух защит и обычно именно она срабатывает: она следит за тем, происходит ли ещё что-нибудь, а не за тем, сколько длится запуск, поэтому медленная, но исправная резервная копия на несколько терабайт остаётся в покое, а зависшая на неотвечающем общем ресурсе останавливается за часы, а не за дни. Предупреждение записывается в лог после 30 минут тишины, до какой-либо отмены. Сканирование считается продвижением: restic не пишет байтов, пока обходит большое дерево, и эта фаза отслеживается по его итогам файлов и байтов, а не по записанным байтам. Две переменные независимы, и BACKUP_MAX_HOURS по-прежнему ограничивает фазы после самого резервного копирования (хранение, статистика, внешняя копия), где нет счётчиков для наблюдения.
DB_DUMP_MAX_HOURS	Нет	Часы, которые один автоматический дамп базы данных может выполняться до остановки. Пусто (по умолчанию) означает 6; допустимы значения от 1 до 48, и предел держится на час ниже BACKUP_MAX_HOURS (на половине его, если он меньше двух часов), чтобы длинный дамп обрывался своим собственным пределом и так и сообщался, а не утягивал за собой всё резервное копирование. Дамп, переставший продвигаться, останавливается раньше, через BACKUP_STALL_HOURS. Остановленный дамп считается неудачным сам по себе, а резервное копирование контейнера продолжается. На Unraid переменная добавляется к контейнеру BombVault через Add another Path, Port, Variable.
TZ	Нет	Часовой пояс для планировщика (например Europe/Berlin). Если не задана, все расписания выполняются в UTC: расписание на 02:30 запустится в 02:30 UTC, а не по местному времени. В Unraid это никогда не задаётся вручную: система передаёт свой часовой пояс в каждый контейнер. Журнал запуска показывает, какой пояс был определён. Пояс с переходом на летнее время пропускает один запуск весной и выполняет один дважды осенью, а UTC не делает ни того, ни другого, зато дважды в год сдвигается на час относительно ваших часов.

Монтирования

Смонтируйте сокет Docker, flash (/boot) и корень Host Data (/mnt), как показано в шаблоне CA. Источники и назначения резервного копирования оба находятся под Host Data, и он монтируется slave, поэтому удалённый общий ресурс, который монтируется после запуска контейнера (например под /mnt/remotes), становится видимым без перезапуска.

Копиям наборов данных ZFS тоже нужен этот режим: хост монтирует снимок набора данных только после запуска контейнера. См. Наборы данных ZFS.

Пути репозиториев резервного копирования по умолчанию, это /mnt/user/bombvault/{container,vms,flash,config,files,zfs}, создаваемые при первой резервной копии. Измените расположение в любой момент в Настройки, Хранилище, Пути резервных копий. У каждого поля пути есть также встроенный переключатель Локально / Удалённо: путь может быть удалённым хранилищем restic (s3:..., rest:..., sftp:..., rclone:...) вместо локальной папки, и резервное копирование идёт прямо туда без отдельной локальной копии; см. Удалённые основные репозитории.

Проверка интеграции с хостом

Откройте /spike в веб-интерфейсе после запуска контейнера. Она проверяет каждое монтирование и CLI (сокет Docker, libvirt, restic, qemu-img, rclone) и сообщает о любых недостающих частях.

Определение источников резервной копии

Для каждого контейнера BombVault сам выбирает, какие bind-монтирования и именованные тома попадут в копию. Путь берётся, как только выполняется любой из пунктов ниже (результат всегда можно переопределить для конкретного контейнера в его разделе Папки для резервного копирования):

• Совпадение с сегментом корня данных: источник bind-монтирования на хосте содержит один из сегментов DATA_ROOT_SEGMENTS как полную составляющую пути (по умолчанию только appdata).
• Именованные тома Docker включаются всегда, потому что одноразового эквивалента у них нет и фильтровать нечего, но только если реальный путь хранения тома на хосте сам достижим через монтирование Host Data, ровно как любой другой путь хоста, который копирует BombVault. Стандартный драйвер локальных томов кладёт том под корень данных самого демона, то есть /var/lib/docker/volumes/<имя>/_data, если это не изменено (проверьте командой docker info -f '{{.DockerRootDir}}'). Это место НЕ покрыто узким монтированием Host Data из одного каталога, которое по умолчанию использует обычный docker-compose.yml. Недостижимый том молча пропускается, это не ошибка. Чтобы именованные тома на обычном хосте действительно копировались, направьте Host Data (и HOST_SOURCE_ROOT) на общего родителя, охватывающего и корень данных Docker: компромисс описан в комментарии Host Data файла compose (Unraid обходит это, монтируя по той же причине весь /mnt, собственное универсальное соглашение верхнего уровня).
• Каталог проекта Docker Compose: если контейнер несёт обычную метку com.docker.compose.project.working_dir (её автоматически ставит docker compose up), этот каталог добавляется тоже, независимо от того, совпало ли какое-нибудь bind-монтирование с сегментом корня данных.
• Переопределение меткой bombvault.data: поставьте контейнеру метку bombvault.data=true, чтобы включить ВСЕ его bind-монтирования, для раскладки, которую не ловит ни одно из двух соглашений выше (например одиночное монтирование /srv/plex/config без проекта Compose). Любое непустое значение, кроме false, считается истинным; отсутствующая метка или bombvault.data=false не меняют ничего.
• Метка bombvault.dbdump: поставьте контейнеру bombvault.dbdump=false, чтобы выключить его автоматический дамп базы данных (0, no и off делают то же самое), или назовите движок (postgres, mysql, mariadb), чтобы снимать дамп с контейнера, который BombVault сам не распознаёт. Метка перебивает переключатель на карточке контейнера, который на Unraid и есть обычный путь.

Модель безопасности

Управление хостом с правами root

Через сокет Docker BombVault может останавливать, удалять и пересоздавать контейнеры, а также читать и записывать appdata, а для резервного копирования VM он входит на хост через SSH (qemu+ssh://, root по умолчанию) для выполнения virsh. Любой, кто может достучаться до его веб-интерфейса, фактически получает root на хосте.

• Необязательная защита паролем (Настройки, Безопасность): задайте пароль, чтобы требовать вход, очистите его, чтобы отключить. По умолчанию выключено для доверенной локальной сети. Пароль хранится с Argon2id поверх значения, приправленного APP_KEY, поэтому скопированный /config без ключа бесполезен, а с ключом атака медленная. Новый пароль должен быть не короче 12 символов; уже заданный более короткий продолжает работать, пока его не сменят. Сеансы подписаны (HMAC, производный от APP_KEY), смена пароля их аннулирует; входы ограничены пятью неудачами в минуту на клиента.
• Двухфакторная аутентификация (Настройки): временной код из приложения-аутентификатора в дополнение к паролю и восемь одноразовых резервных кодов, которые выдаются один раз при включении. Общий секрет хранится зашифрованным ключом APP_KEY, а отключение требует действующего кода.
• Ключи доступа (WebAuthn) находятся на отдельной карточке, как только задан пароль, и действуют вместе с паролем, а не вместо него, поэтому удаление всех ключей доступа никого не запирает. Им нужно настоящее доменное имя и сертификат, которому доверяет браузер. Стандартный https://<ip>:3443, это ровно то, что WebAuthn отклоняет, и карточка так и говорит, вместо того чтобы предлагать кнопку, которая не сработает.
• Изменения только в JSON. Запрос, который что-то меняет, должен отправлять Content-Type: application/json и не должен быть помечен браузером как межсайтовый, поэтому страница на другом сайте не может заставить ваш браузер менять настройки по адресу в локальной сети. Скрипт, работающий с API, отправляет этот заголовок; всё остальное отклоняется с 415.
• Поскольку защита включается по желанию, когда она не задана, весь интерфейс и API (включая настройку внешней копии, маршруты теста на подделку и набор для восстановления) достижимы любым, кто может достучаться до порта. Включите защиту, как только используются внешние, неизменяемые резервные копии или шифрование.
• Запускайте BombVault только в доверенной, не открытой наружу сети. Для удалённого доступа поместите его за обратный прокси, добавляющий аутентификацию и TLS. Ответы несут базовые заголовки безопасности (CSP, nosniff, X-Frame-Options, Referrer-Policy).
• За обратным прокси каждый запрос несёт адрес прокси, поэтому без TRUSTED_PROXY ограничитель считает всех клиентов вместе, и неудачи злоумышленника блокируют и вас. Укажите прокси в TRUSTED_PROXY, чтобы вернуть подсчёт по клиентам.
• Обратный прокси перед BombVault должен передавать заголовок Authorization или X-API-Key на /mcp и не должен буферизовать ответы, иначе ассистенты не смогут подключиться. См. Сервер MCP.
• Конечная точка MCP /mcp отвечает 404, пока не создан ключ или не включён вход через OAuth, и требует от каждого клиента ключ или токен даже при выключенном пароле входа; ни один адрес не исключён, даже localhost. Инструментов восстановления или удаления у неё нет, а восстановление резервной копии конфигурации отзывает все ключи. См. Сервер MCP.
• С HTTP_ONLY=true cookie сессии теряет флаг Secure (это необходимо, чтобы работать по обычному HTTP), поэтому включайте пароль за прокси, завершающим TLS, только если важна конфиденциальность.
• SSH-соединение резервного копирования VM доверяет ключу хоста при первом подключении (TOFU) и закрепляет его после. Проверьте ключ хоста по независимому каналу, если ваш путь от контейнера к хосту не доверенный.
• Резервные копии шифруются restic, когда шифрование включено (Настройки; по умолчанию включено), с ключом, производным от APP_KEY.

Сервер MCP

Серверу MCP не нужна переменная окружения. Вы включаете его, создав ключ в Настройки, Интеграции, Сервер MCP, и он отвечает по пути /mcp на том же порту, что и веб-интерфейс (например, https://192.168.1.10:3443/mcp). Без активного ключа этот путь отвечает 404. Клиенты, сертификаты и ограничения описаны на странице Сервер MCP.

Резервное копирование VM через SSH

BombVault резервирует виртуальные машины KVM/libvirt без монтирования какого-либо пути libvirt. Он выполняет virsh на хосте через SSH (qemu+ssh://), поэтому никогда не может повлиять на ваш VM Manager хоста.

Монтировать сокет libvirt хоста в контейнер на Unraid ненадёжно: этими путями владеет VM Manager, и переключение "Enable VMs" может оставить libvirt неспособным запуститься. SSH-ключ даёт root на хосте, это тот же уровень доверия, что и у сокета Docker, который BombVault уже использует.

Быстрая настройка:

1. Настройки, Интеграции, SSH хоста: скопируйте показанный публичный ключ.
2. Добавьте его в /root/.ssh/authorized_keys в Unraid (также сохраняется на flash, чтобы пережить перезагрузки).
3. Нажмите Проверить соединение.

Шаблон добавляет --add-host=host.docker.internal:host-gateway, чтобы контейнер мог достучаться до хоста. Установите LIBVIRT_HOST на LAN-IP вашего Unraid, если это имя не разрешается (например когда контейнер работает в пользовательской сети br0.x). Если вы изменили SSH-порт Unraid, установите LIBVIRT_SSH_PORT в соответствие. Живым снимкам дополнительно нужен qemu guest agent в VM и диск на /mnt/cache (не /mnt/user).

Полное руководство по настройке VM и сети

Полное пошаговое руководство (включение SSH, постоянная авторизация ключа, маршрутизация пользовательской сети и VLAN, метод для каждой VM и устранение неполадок на стороне хоста) находится по адресу docs/vm-backup-ssh-setup.md на GitHub.

Настройка внешней копии

Настройте внешнюю реплику на странице Настройки, Внешнее. Полный рабочий процесс (неизменяемость/append-only, тестирование на подделку и учебные DR) см. в Внешняя копия и восстановление. Вкратце:

• Бэкенды: SMB/CIFS и NFS (смонтируйте общий ресурс и укажите на него Путь резервных копий), нативные бэкенды restic без rclone (s3:..., rest:http://host:8000/repo, sftp:user@host:/repo) или любое удалённое хранилище rclone (rclone:<remote>:<bucket>/path). У Backblaze B2 здесь нет собственного бэкенда: подключайся к нему через его точку S3 (s3:https://s3.<region>.backblazeb2.com/<bucket>/<path>), указав идентификатор ключа и ключ приложения как учётные данные S3.
• Общие облачные учётные данные хранятся в зашифрованном виде в Настройки, Облачный доступ, Общие облачные учётные данные.
• Целям SSH ничего не нужно устанавливать на дальней стороне. sftp: требует лишь SSH-сервера. Добавьте публичный ключ из Настройки, Интеграции, SSH хоста (также в /config/ssh/id_ed25519.pub) в ~/.ssh/authorized_keys пользователя цели.
• Внешняя копия: BombVault реплицирует новые снимки через restic copy по принципу максимальных усилий, поверх основного репозитория (обычно локального). У каждого домена своё расписание внешней копии, плюс кнопка Реплицировать сейчас.
• Несколько внешних целей на домен: каждый домен может реплицироваться сразу в несколько внешних назначений. Добавляйте дополнительные цели в Настройки, Внешнее, каждую со своим репозиторием, классом хранения S3, флагом append-only, хранением и бюджетом роста; все они реплицируются по расписанию внешней копии этого домена. Существующая настройка одной внешней копии переносится как первая цель.
• Места назначения: внешние места назначения настраиваются один раз в Настройки, Внешнее, Места назначения, через мастер, который перечисляет все поддерживаемые сервисы. См. Места назначения.
• Размещение для каждого элемента: у каждого контейнера, VM и набора папок подсвечены Локально и цели, которые получают его резервные копии. Настройки, Хранилище, Размещение по умолчанию задаёт это по доменам для элементов без собственного выбора. См. Размещение для каждого элемента.
• Хранение для каждого источника: локальная и внешняя политики обе живут в Настройки, Хранение (оставьте политику внешней копии со всеми нулями, чтобы никогда автоматически не обрезать внешние снимки). В карточках Локальное хранение и Внешнее хранение есть Правила хранения по источникам, которые задают контейнерам, VM, flash, папкам, ZFS или самокопии собственные правила хранения, для их локальных копий и для их внешнего репозитория. Источник без своих правил следует общим, а хранение после каждой копии, внешнее копирование, ручная очистка и предпросмотр хранения используют правила того источника, с которым работают. Дополнительные внешние цели сохраняют правила, заданные для них в Настройки, Внешнее.
• Ограничения пропускной способности: ограничьте скорость выгрузки/загрузки restic в Настройки, Внешнее.
• Сначала стриминг: в Настройки, Внешнее выбери медиасерверы (Plex, Jellyfin и Emby выбраны заранее по имени образа), скорость отправки, с которой сервер считается ведущим стриминг, лимит отдачи во время стриминга и через сколько после потока возвращается обычный лимит.
• Холодный и архивный класс хранения (S3): для нативного внешнего репозитория S3 выберите уровень, читаемый для восстановления (Standard, Standard-IA, One Zone-IA, Intelligent-Tiering, Glacier Instant Retrieval). Удалённые хранилища rclone задают свой класс в конфигурации rclone.
• Удалённый основной репозиторий вместо локального: сам Путь резервных копий домена может быть одним из бэкендов выше, без локальной копии и без шага репликации; встроенный переключатель Локально/Удалённо и его настройки безопасности (пропускная способность, append-only, бюджет роста) описаны в Удалённые основные репозитории.

Аномалии

Обнаружение аномалий настраивается на карточке Аномалии в разделе Настройки, Целостность. Каждый элемент управления сохраняется сразу после изменения, а три под переключателем скрыты, пока обнаружение выключено.

Параметр	По умолчанию	Что делает
Обнаруживать аномалии	Вкл.	Сравнивает каждую копию с собственной историей элемента. В выключенном состоянии ничего нового не проверяется, а пункт Аномалии исчезает из боковой панели; карточка по-прежнему ведёт к прежним находкам.
Чувствительность	Сбалансированная	Строгая сообщает и о небольших изменениях, Мягкая только о крупных.
Отправлять уведомление для	Только критические находки	Минимальная важность, при которой сообщение отправляется по каналам, настроенным в Уведомления. Повторные сбои копий и дампов и неудачные плановые проверки восстановления уже отправляют своё сообщение и не отправляются дважды.
Сохранять старые копии, если источник резко уменьшился или был перезаписан	Вкл.	Пока у элемента есть открытая находка о почти пустом источнике, сильном уменьшении или заново сохранённой большей части данных, хранение и очистка не трогают его старые копии. Подтвердите находку или отметьте её как ожидаемую, чтобы их отпустить.

У каждого элемента может быть своя чувствительность и свой минимум уведомлений. Задайте их на странице Аномалии: у элемента с открытыми находками они в разделе Наблюдение на его карточке, любой другой элемент открывает их из карточки Ничего не открыто. Их также можно задать в панели самого элемента: в разделе папок контейнера и в настройках ВМ (оба в расширенном режиме), в редакторе папок набора папок и на страницах Flash и Автобэкап. Для элемента ZFS они находятся в его редакторе на странице ZFS и действуют для каждого набора данных его дерева.

Переносимые настройки (экспорт и импорт)

Карточка Экспорт / импорт настроек на странице Настройки, Система записывает всю вашу конфигурацию BombVault (настройки доменов, внешние цели, расписания, хранение, уведомления) в переносимый файл JSON, который вы можете импортировать на другой экземпляр, поэтому переезд на новую машину или клонирование установки не означает повторный ручной ввод всего. Импорт показывает предпросмотр и запрашивает подтверждение, и он никогда не трогает ваши данные резервных копий или историю.

Экспорт может содержать учётные данные

Вы выбираете, включать ли в файл учётные данные внешней копии, уведомлений и MQTT-брокера. С включёнными учётными данными экспорт так же чувствителен, как ваш набор для восстановления, поэтому храните его в надёжном месте. Без них файл содержит только несекретные настройки.