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

MAATRIX

Restic — один из немногих бэкап-инструментов, которые действительно приятно использовать: дедупликация из коробки, шифрование по умолчанию, единая утилита под локальный диск, SFTP и S3-совместимое хранилище. Но именно из-за гибкости бэкендов и не самого очевидного поведения кэша с ним чаще всего спотыкаются не на самой команде backup, а на инициализации репозитория, правах доступа к хранилищу и неожиданном росте объёма данных. Разберём частые ошибки restic на сервере по симптому, причине и решению — с командами.

Ошибка при инициализации репозитория

Первая проблема встречается ещё до первого бэкапа: команда init отказывается создавать репозиторий или, наоборот, backup падает с сообщением, что репозитория не существует. Чаще всего причина в синтаксисе URL бэкенда — restic различает схемы для локального пути, SFTP и S3, и перепутанный префикс приводит к непонятной ошибке вместо явного «неверный адрес».

restic init --repo /mnt/backup/repo
restic init --repo sftp:user@host:/srv/restic-repo
restic init --repo s3:https://s3.amazonaws.com/my-bucket/repo

Обратите внимание: для локального пути префикс не нужен, для SFTP — sftp:, для S3 — s3: с полным URL эндпоинта. Вторая частая ошибка — попытка инициализировать репозиторий, который уже существует: restic сообщает repository master key and config already initialized. Это не всегда плохо — если вы не создавали его сами, значит, кто-то (или предыдущий запуск скрипта) уже это сделал, и повторный init не нужен. Проверьте содержимое перед тем, как расследовать дальше:

restic -r <repo> snapshots

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

Локальный диск как бэкенд: права и путь

Простейший бэкенд restic — обычный путь в файловой системе, и именно поэтому на нём чаще всего забывают про базовые вещи: права доступа и то, что «диск» на самом деле смонтирован не туда. Backup падает с permission denied или репозиторий необъяснимо пустеет после перезагрузки.

mount | grep /mnt/backup
ls -la /mnt/backup
whoami

Если restic запускается от отдельного пользователя (что правильно — не стоит гонять бэкап от root без необходимости), убедитесь, что у этого пользователя есть права на запись в каталог репозитория, а не только на чтение. Вторая ловушка — точка монтирования: если внешний диск или сетевой раздел не смонтирован, каталог /mnt/backup существует как пустая директория на корневом разделе, restic init успешно создаёт в ней репозиторий, и всё выглядит нормально, пока не выяснится, что бэкапы годами писались мимо реального хранилища на системный диск, который потом переполнился. Добавьте в скрипт бэкапа проверку, что точка монтирования действительно смонтирована, прежде чем запускать restic:

mountpoint -q /mnt/backup || { echo "backup disk not mounted"; exit 1; }

Эта одна строка спасает от самой обидной категории ошибок — бэкапа в пустоту.

SFTP: не удаётся подключиться к серверу-хранилищу

SFTP — удобный бэкенд, когда под бэкапы выделен отдельный сервер по SSH, но именно с ним больше всего проблем с подключением, потому что restic для SFTP использует не встроенный SSH-клиент, а системную команду ssh и отдельный restic-sftp-server на удалённой стороне.

restic -r sftp:user@host:/srv/restic-repo snapshots

Если появляется ошибка вида unable to start ssh или command not found, restic не может стартовать SFTP-подсистему на удалённом сервере. Причина обычно одна из трёх. Во-первых, на удалённой машине не настроен доступ по SSH-ключу без пароля — restic не умеет вводить пароль интерактивно в неинтерактивном режиме, поэтому нужен ключ и ssh-agent или ключ без passphrase, добавленный в ~/.ssh/authorized_keys под тем пользователем, от которого идёт бэкап. Во-вторых, на удалённой стороне не установлен пакет с SFTP-подсистемой sshd (обычно она встроена в openssh-server, но в минимальных образах может быть урезана). Проверьте вручную:

ssh user@host sftp-server

В-третьих, путь на удалённой машине не существует и не создаётся автоматически при первом подключении — создайте каталог заранее и проверьте, что у пользователя есть права записи в него. Отдельно стоит проверить голое SSH-соединение без restic — если ssh user@host подключается с ошибками (например, из-за смены отпечатка ключа хоста после переустановки сервера), restic унаследует ту же проблему.

S3 и S3-совместимые хранилища: доступ и настройка

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

export AWS_ACCESS_KEY_ID=<key>
export AWS_SECRET_ACCESS_KEY=<secret>
restic -r s3:https://s3.amazonaws.com/my-bucket/repo init

Если restic сообщает Access Denied при инициализации или бэкапе, а сами ключи верны — скорее всего, у прикреплённой политики IAM нет прав на s3:PutObject, s3:GetObject, s3:ListBucket и s3:DeleteObject одновременно. Restic использует все четыре операции: список объектов для чтения снимков, запись новых блоков, чтение при восстановлении и удаление при prune. Урезанная политика «только на чтение» пройдёт init, но упадёт на первом реальном бэкапе. Для S3-совместимых хранилищ (не Amazon) отдельная частая ошибка — неверный эндпоинт: полный URL должен указывать именно на API хранилища, а не на веб-панель управления, и часто требует региона в переменной окружения:

export AWS_DEFAULT_REGION=us-east-1

Если провайдер использует нестандартный порт или требует явного отключения TLS-проверки для тестового стенда, добавляется -o s3.connections=<N> для управления параллелизмом соединений и AWS_ENDPOINT_URL в новых версиях restic — но полагаться на отключение проверки сертификата в проде не стоит: это открывает канал бэкапа для перехвата. Держать S3-хранилище под копии на отдельном сервере, физически не связанном с бэкапируемыми данными, разумно организовать через отдельный VPS для бэкапов и архива в другой локации — тогда даже полный отказ основного сервера не заденет копии.

Дедупликация работает не так, как ожидалось

Главное преимущество restic — content-defined chunking: файлы режутся на блоки переменного размера, и повторяющиеся блоки между снимками (и даже между разными файлами) хранятся один раз. Но иногда репозиторий растёт быстрее, чем ожидалось, и кажется, что дедупликация не работает.

restic stats --mode raw-data
restic stats --mode restore-size

Первая команда покажет реальный размер данных в репозитории после дедупликации и сжатия, вторая — сколько займут файлы при полном восстановлении. Разница между ними и есть эффект дедупликации и компрессии. Если разница небольшая, возможные причины две. Первая — данные уже сжаты или зашифрованы на уровне приложения (архивы, видео, зашифрованные бэкапы БД): у таких файлов почти нет повторяющихся блоков между версиями, и дедупликация естественным образом даёт мало выигрыша — это не поломка, а свойство данных. Вторая причина — репозиторий создан в старом формате (repository format 1), который не поддерживает компрессию блоков; начиная с версии 0.14 restic по умолчанию создаёт репозитории формата 2 со сжатием, но старые репозитории при обновлении клиента формат не меняют автоматически. Проверить и обновить формат:

restic cat config
restic migrate upgrade_repo_v2

Учтите, что миграция необратима и требует, чтобы все клиенты, пишущие в репозиторий, поддерживали формат 2 — старые версии restic после апгрейда перестанут с ним работать. Ориентировочно выигрыш от компрессии зависит от типа данных и может сильно отличаться — не берите чужие цифры как гарантию для своего случая, проверяйте stats до и после на реальных данных.

Память, CPU и кэш при больших объёмах данных

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

Кэш по умолчанию хранится в домашнем каталоге пользователя (обычно ~/.cache/restic) и содержит метаданные индексов репозитория для ускорения последующих операций. На сервере с бэкапом множества репозиториев или большим количеством снимков этот кэш может занять заметный объём на системном разделе — который часто гораздо меньше, чем раздел под сами бэкапы.

du -sh ~/.cache/restic
restic cache --cleanup

Если системный диск маленький, перенесите кэш явно через переменную RESTIC_CACHE_DIR на раздел с запасом места, или запускайте бэкап с --no-cache для разовых операций (это медленнее, но не тратит место). По памяти: операции check --read-data и prune на больших репозиториях требуют держать в памяти индекс всех блоков, и на сервере с ограниченным RAM это может привести к OOM-килу процесса restic посреди проверки. Планируя ресурсы под бэкап-сервер, закладывайте память не только под сам объём данных, но и под пиковую нагрузку при prune и полной проверке — ориентир по требуемым ресурсам для сервера под бэкапы разбирали отдельно в статье сколько ресурсов нужно VPS для бэкапов и архива. Если памяти объективно не хватает, запускайте check без --read-data в обычном режиме и полную проверку с чтением данных — реже, в отдельном окне, а не каждой ночью вместе с бэкапом.

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