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

MAATRIX

Kopia — один из немногих бэкап-инструментов, у которых из коробки есть не только CLI, но и удобный веб-интерфейс, при этом дедупликация, сжатие и шифрование устроены не хуже, чем у restic или Borg. Именно архитектура «сервер плюс веб-UI плюс отдельные учётные записи» и подводит новых пользователей: путаница между паролем репозитория и логином в интерфейс, закрытый порт, снапшоты, которые «не удаляются» несмотря на политику хранения. Разберём частые ошибки Kopia на сервере по симптому, причине и решению — с командами.

Ошибка при создании и подключении репозитория

Первое, с чем сталкиваются: команда repository connect не работает, хотя репозиторий вроде бы уже создан, или наоборот — create падает с ошибкой доступа. Kopia различает создание нового репозитория и подключение к существующему, и это два разных действия, которые легко перепутать при повторном запуске скрипта на втором сервере.

kopia repository create filesystem --path=/mnt/backup/repo
kopia repository connect filesystem --path=/mnt/backup/repo

Если репозиторий уже создан (например, вы настраиваете второй клиент, который пишет в тот же репозиторий), нужен именно connect, а не create — повторный create завершится ошибкой вида repository already initialized. Пароль репозитория передавайте одинаково на всех клиентах: интерактивным вводом, флагом --password или переменной окружения:

export KOPIA_PASSWORD='ваш-пароль-репозитория'

Без переменной или флага автоматизация зависнет на приглашении ввести пароль в неинтерактивном режиме — это частая причина, почему бэкап по cron или systemd-таймеру «просто не запускается» без видимой ошибки в логе. Локальная конфигурация подключения хранится в ~/.config/kopia/repository.config того пользователя, от которого запущен kopia — если бэкап планируется от отдельного системного пользователя (что правильно, не стоит гонять его от root без необходимости), убедитесь, что connect выполнялся именно под этим пользователем, а не под вашим при ручной проверке, иначе на сервере при запуске по расписанию появится not connected to a repository. Для S3-совместимого хранилища подключение выглядит похоже, но с явным эндпоинтом:

kopia repository create s3 \
  --bucket=my-backups \
  --endpoint=s3.example.com \
  --access-key=<key> \
  --secret-access-key=<secret>

Держать хранилище копий физически отдельно от бэкапируемых данных разумно организовать через отдельный VPS для бэкапов и архива — тогда отказ основного сервера не заденет копии.

Веб-интерфейс недоступен снаружи

Kopia умеет поднимать встроенный сервер с веб-UI одной командой, но по умолчанию он слушает только localhost, и это первое, обо что спотыкаются при настройке на удалённом сервере: kopia server start отрабатывает без ошибок, а интерфейс не открывается по IP сервера.

kopia server start --address=0.0.0.0:51515 --tls-generate-cert

Флаг --address со связкой 0.0.0.0:порт явно указывает слушать все интерфейсы, а не только loopback. После этого нужно открыть порт в файрволе:

ufw allow 51515/tcp

Вторая проблема идёт сразу за первой: браузер или клиентский kopia, подключающийся к серверу, ругается на сертификат — Kopia по умолчанию генерирует самоподписанный TLS-сертификат (--tls-generate-cert). Для браузера это просто предупреждение, которое можно принять вручную, но клиенту kopia, подключающемуся к API сервера, потребуется явно указать отпечаток сертификата:

kopia server status --address=https://host:51515 \
  --server-cert-fingerprint=<fingerprint>

Отпечаток сервер печатает в лог при старте. Для продакшена куда правильнее не полагаться на самоподписанный сертификат вовсе, а поставить перед Kopia обратный прокси (nginx или Caddy) с настоящим сертификатом Let's Encrypt и слушать сам Kopia только на loopback — так браузерное предупреждение не будет мешать на каждом заходе в UI, а порт 51515 наружу вообще не открывается.

Пароль репозитория и логин в веб-интерфейс — это разные вещи

Самая частая логическая ошибка при первом знакомстве с Kopia: администратор помнит пароль репозитория (тот, что вводился при repository create), но не может войти в веб-интерфейс — сервер сообщает invalid credentials, хотя пароль вводится правильно. Причина в том, что доступ к репозиторию (шифрование данных) и вход в веб-UI — это два независимых механизма аутентификации.

Пароль репозитория расшифровывает данные и указывается один раз при подключении. А для входа в веб-интерфейс сервера нужна отдельная учётная запись пользователя, которую надо создать явно:

kopia server user add alice@myhost
kopia server user list

Команда запросит отдельный пароль именно для этого пользователя UI — он может (и для ясности лучше должен) отличаться от пароля репозитория. Если вы запускали kopia server start без единого добавленного пользователя, войти в интерфейс попросту не получится, каким бы правильным ни был пароль репозитория. Проверьте список пользователей сервера, если вход не проходит:

kopia server user list --address=https://localhost:51515

Отдельно у сервера есть учётные данные для собственного управляющего API (флаги вида --server-username/--server-password при старте) — они нужны утилитам вроде kopia server status, чтобы управлять уже запущенным сервером, и это третий слой аутентификации, который иногда путают с первыми двумя. Три разных пароля для одного инструмента — не самая интуитивная конструкция, и именно поэтому стоит сразу документировать в рантайм-заметках сервера, какой пароль за что отвечает, а не полагаться на память через полгода после настройки.

Политики хранения не сокращают число снапшотов

Настроили политику keep-daily=7, снапшоты продолжают копиться, старые не удаляются — это вторая по частоте жалоба, и она почти всегда объясняется тем, что политика хранения (retention policy) и фактическое удаление данных — два разных этапа в Kopia.

kopia policy set /data \
  --keep-latest=10 \
  --keep-daily=7 \
  --keep-weekly=4 \
  --keep-monthly=6

Политика определяет, какие снапшоты помечаются на удаление при следующей проверке, но реальная очистка происходит только во время maintenance — фоновой операции, которая физически удаляет неиспользуемые блоки данных. Пока maintenance не отработал, kopia snapshot list может по-прежнему показывать снапшоты, формально попадающие под удаление, а объём в хранилище не уменьшается. Проверить действующую (с учётом наследования) политику для конкретного пути:

kopia policy show /data

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

kopia policy set --global --keep-daily=14

Но политика, явно заданная для конкретного /data, полностью перекрывает глобальную для этого пути, а не дополняет её — если после этого глобальная политика «перестала работать» именно на одном источнике, скорее всего, для него когда-то была задана локальная политика, про которую забыли. Сбросить локальную политику и вернуться к наследованию от глобальной:

kopia policy delete /data

Maintenance, кэш и рост объёма хранилища

Даже с правильно настроенной политикой хранения объём репозитория может расти быстрее ожидаемого, если maintenance не запускается вовсе. У Kopia есть концепция «владельца» обслуживания репозитория — обычно им автоматически становится тот клиент, который создал репозиторий, и именно он должен периодически выполнять полное обслуживание:

kopia maintenance info
kopia maintenance run --full

Если бэкапы пишутся с нескольких эфемерных клиентов (например, из контейнеров, которые пересоздаются), а «владелец» обслуживания давно не запускался, снапшоты формально истекают по политике, но блоки данных физически не освобождаются — репозиторий продолжает расти. Планируйте регулярный запуск kopia maintenance run на постоянно работающем сервере или отдельным systemd-таймером, если не используете встроенный планировщик.

Второй источник неожиданного расхода места — не сам репозиторий, а локальный кэш метаданных клиента, который по умолчанию лежит в ~/.cache/kopia и растёт при работе с большим числом снапшотов:

du -sh ~/.cache/kopia
kopia cache info
kopia cache clear

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

Восстановление и монтирование снапшотов не работает

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

kopia snapshot restore <snapshot-id> /path/to/restore

А вот монтирование снапшота как файловой системы (kopia mount) — удобный способ достать один файл без полного восстановления — на «голом» сервере часто падает с ошибкой отсутствия FUSE. Kopia использует FUSE для монтирования на Linux, и в минимальных серверных образах этот пакет обычно не установлен по умолчанию:

apt install fuse3
kopia mount <snapshot-id> /mnt/kopia-view

Если после установки FUSE монтирование всё равно не проходит с правами доступа, проверьте, что пользователь, от которого запущен kopia, состоит в группе, которой разрешено использовать /dev/fuse (обычно fuse), и что точка монтирования существует и пуста перед командой. Отдельно стоит проверить .kopiaignore в корне источника бэкапа, если после восстановления не хватает каких-то файлов, которые точно были на сервере — это не ошибка восстановления, а следствие того, что файлы вообще не попали в снапшот из-за правил исключения, унаследованных из политики или локального игнор-файла:

kopia policy show /data | grep -A5 ignore

Регулярно проверяйте, что восстановление реально работает на тестовом стенде, а не только создание снапшотов — это касается любого инструмента бэкапа, не только Kopia, и стоит потраченного времени куда меньше, чем цена невосстановимой копии в реальной аварии.

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