BorgBackup на сервере: частые ошибки и решения

MAATRIX

BorgBackup — один из немногих инструментов бэкапа, где дедупликация и компрессия работают из коробки, без отдельного демона и без танцев с rsync --link-dest. Но именно из-за дедупликации ошибки у него специфические: не «файл не скопировался», а «кэш не совпадает с репозиторием» или «не хватает места, чтобы освободить место». Ниже — реальные сообщения об ошибках borg, их причины и команды, которыми это чинится. Если вы ещё не настраивали borg — короткая база. Репозиторий создаётся один раз, дальше в него пишутся архивы (снимки), которые делят между собой неизменившиеся куски данных: `` borg init --encryption=repokey-blake2 ssh://user@backup-host/mnt/backup/repo export BORG_REPO='ssh://user@backup-host/mnt/backup/repo' export BORG_PASSPHRASE='ваша-парольная-фраза' borg create --stats --compression zstd,6 --exclude-caches \ ::'{hostname}-{now:%Y-%m-%d}' /etc /home /var/www `` Дальше — по частым ошибкам.

«Failed to create/acquire the lock»

Самая частая ошибка после сбоя питания или обрыва сети во время бэкапа: borg падает с Failed to create/acquire the lock (timeout) или Repository ... is already locked. Процесс, который держал блокировку, умер, не сняв её — файл lock.exclusive остался в репозитории.

Сначала убедитесь, что реально ничего не работает — иначе снятие лока во время активной записи повредит репозиторий:

ps aux | grep borg

Если процессов нет — снимайте блокировку принудительно:

borg break-lock ssh://user@backup-host/mnt/backup/repo

Частая причина, по которой это повторяется регулярно, — перекрывающиеся запуски cron: предыдущий borg create ещё работает (например, из-за медленного канала), а cron уже стартует следующий. Оборачивайте вызов в flock, чтобы второй запуск просто выходил, а не ждал и не плодил зависшие процессы:

flock -n /var/run/borg-backup.lock /usr/local/bin/borg-backup.sh

«Cache is newer than repository» и «Repository ID mismatch»

Сообщение Cache is newer than repository - this is either an attack or unsafe (multiple repos with same ID) обычно выскакивает не из-за атаки, а из-за банальной путаницы: репозиторий пересоздали по тому же пути (например, восстановили сервер из снапшота или откатили диск), а локальный кэш на клиенте — от старой версии этого же пути. Borg честно не понимает, тот ли это репозиторий, что раньше, и отказывается работать вслепую.

Если вы точно знаете, что это ваш легитимный репозиторий, а не подмена — просто сбросьте локальный кэш для него:

borg delete --cache-only ssh://user@backup-host/mnt/backup/repo

Похожая история — Repository ID mismatch после переноса репозитория на другой путь или сервер (клонирование диска, миграция хранилища). Borg хранит в ~/.config/borg/security/<repo-id>/ отпечаток и не даёт молча продолжить работу с «переехавшим» репозиторием. Если перенос осознанный:

export BORG_RELOCATED_REPO_ACCESS_IS_OK=yes

Оба сообщения — это защита от одного и того же сценария: кто-то подменил репозиторий, а borg продолжает писать в него бэкапы, думая, что ничего не изменилось. Не отключайте эти проверки автоматически в скриптах — сначала убедитесь, что перенос действительно ваш.

Обрыв SSH-канала и «borg: command not found» на удалённой стороне

Если репозиторий на другом сервере (а для бэкапов это правильная схема — хранить копию не на том же железе, что и данные), добавляется целый класс сетевых ошибок.

borg: command not found при подключении по SSH — типично для NAS и минималистичных систем, где бинарник называется не borg, а, например, borg1. Укажите путь явно:

borg create --remote-path=borg1 ssh://user@nas/volume1/backup::archive /data

Обрыв на середине передачи — Connection closed by remote host или Broken pipe — обычно от нестабильного канала или таймаута неактивности на промежуточном оборудовании. Помогает keepalive на стороне клиента в ~/.ssh/config:

Host backup-host
  ServerAliveInterval 60
  ServerAliveCountMax 3

И отдельный SSH-ключ только под бэкап, без пароля, с ограничением на удалённой стороне через authorized_keys — это заодно закрывает риск, что скомпрометированный клиент удалит историю бэкапов через prune:

command="borg serve --restrict-to-path /mnt/backup/repo --append-only",restrict ssh-ed25519 AAAA... backup-client

В режиме --append-only клиент может только дописывать новые архивы, но не может стереть старые — реальный prune и compact тогда делаются локально на сервере хранения, отдельным ключом с полным доступом. О том, как вообще правильно раздавать ключи вместо паролей и не путаться потом с правами — в статье SSH-ключи вместо пароля на сервере: частые ошибки и решения.

Не хватает места на compact и prune

Здесь путаница чаще всего процедурная. prune только помечает старые архивы как удалённые, реальное место освобождает compact — а ему для этого временно нужно ещё немного свободного места, чтобы переписать сегменты хранилища. На забитом под ноль диске это выглядит как парадокс: «удаляю бэкапы, чтобы освободить место, но освободить место не получается, потому что нет места»:

borg prune --list --keep-daily 7 --keep-weekly 4 --keep-monthly 6 \
  ssh://user@backup-host/mnt/backup/repo
borg compact ssh://user@backup-host/mnt/backup/repo

Практический выход — держать постоянный резерв на самом репозитории, чтобы до нуля он не заполнялся никогда:

borg config ssh://user@backup-host/mnt/backup/repo additional_free_space 2G

Если резерв не выставили заранее и диск уже забит — временно освободите место любым способом (унесите что-то некритичное, подключите запасной том), выполните compact, а потом уже настраивайте резерв на будущее. Отдельно следите за самим диском под бэкапы — ориентир по объёму и типичные грабли разобраны в статье Закончилось место на диске VPS, а для целого сервера-хранилища под терабайты архивов обычно выгоднее выделенный сервер с большим RAID-массивом, чем растущий VPS-диск.

Забытая парольная фраза и повреждённый репозиторий

Здесь важно понимать: у borg нет «бэкдора» для восстановления парольной фразы. Если репозиторий зашифрован (а его стоит шифровать всегда, если он лежит на чужой инфраструктуре) и вы потеряли и парольную фразу, и файл ключа — данные не восстановить никак, это не блеф производителя, а честная криптография. Поэтому ключ обязательно выгружайте и храните отдельно от сервера:

borg key export ssh://user@backup-host/mnt/backup/repo /safe/place/repo.key

Если репозиторий действительно повреждён — например, сервер хранения перезагрузили жёстко посреди записи — первым делом диагностика без изменений:

borg check ssh://user@backup-host/mnt/backup/repo

И только если check подтвердил проблему, а не просто снял устаревшую блокировку — восстановление, причём лучше на копии репозитория, а не на единственном экземпляре:

borg check --repair ssh://user@backup-host/mnt/backup/repo

--repair может удалить повреждённые части архивов безвозвратно, поэтому это последний шаг, а не первый. Если данные критичны, а репозиторий один — сначала скопируйте его целиком (rsync -a) и экспериментируйте с repair на копии.

Как ловить проблему раньше, чем через месяц

Худший сценарий с borg — не ошибка, а её отсутствие: cron перестал запускаться месяц назад, никто не заметил, а когда бэкап реально понадобился — его просто нет. Код завершения важно проверять осмысленно: 0 — всё чисто, 1 — были предупреждения (например, не прочитался один файл из-за прав, но архив создан), 2 — настоящая ошибка. Слепой && echo OK по нулевому коду пропустит единичку и создаст ложное чувство спокойствия.

Рабочая схема — пинговать внешний сторож только при успешном завершении всей цепочки:

borg create ... && borg prune ... && borg compact ... \
  && curl -fsS -m 10 https://hc-ping.com/ваш-uuid

Если пинг не пришёл вовремя — сторож сам напишет в Telegram или на почту. Настройка такого механизма под cron-задачи подробно разобрана в статье Healthchecks.io: мониторинг cron-задач. Отдельно, раз в месяц, стоит гонять более дорогую проверку — не просто «архив есть в списке», а что данные внутри реально читаются: borg check --verify-data перечитывает и проверяет каждый чанк, а не только метаданные. Это медленно и грузит диск, поэтому не каждую ночь, но именно она ловит тихое повреждение хранилища, которое обычный check может пропустить.

Частые вопросы