Восстановление Yandex Managed Service for Valkey™ из резервной копии WAL-G
Вы сможете восстановить данные кластера Yandex Managed Service for Valkey™ на пользовательской инфраструктуре из резервной копии, переданной в S3-бакет через WAL-G.
Перед началом работы
Для выполнения инструкции вам потребуются:
- Valkey™ и
valkey-cli: Лучше использовать ту же полную версию, что и у исходного сервера; более старая версия не подходит. Версию можно посмотреть в метаданных резервной копии. Если использовались модули, например JSON, Search или Bloom, понадобятся их совместимые версии. - WAL-G: Бинарный файл wal-g-pg для Redis/Valkey™ (скачать можно со страницы релизов
WAL-G). Название бинарника и настроекWALG_REDIS_*сохраняется и для Valkey™. Примеры ниже используют интерфейс WAL-G v3.0.9. - Ключ шифрования: Экспортированный из бакета ключ, используемый для защиты резервных копий.
- Доступ к бакету: Статический ключ (идентификатор статического ключа доступа и значение секретного ключа доступа) с правами на чтение бакета.
- Дисковое пространство: Свободное место на диске, достаточное для хранения данных в распакованном виде с учетом:
- Размера самой базы данных;
- Размера WAL-сегментов, которые будут восстанавливаться.
Команды ниже выполняются в bash от root. В примерах служба называется valkey-server, пользователь и группа — valkey:valkey, конфигурационный файл — /etc/valkey/valkey.conf, каталог данных — /var/lib/valkey. Если в вашей установке они отличаются, подставьте свои значения.
Чтобы расшифровать ключ шифрования резервной копии:
-
Скачайте из бакета файл
nacl-key-*.7z, который указан вclickhouse.key_archive.fileJSON файла конфигурации в папке__migration__/. -
Откройте архив и введите ключ, который ранее получили через форму запроса резервной копии. Если вы не сохранили ключ, то выгрузку резервной копии нужно запросить повторно. Чтобы раскрыть архив, используйте способ, подходящий для вашей операционной системы:
- Windows: 7-Zip.
- macOS: Keka.
- Linux: команда
7z x nacl-key-*.7z. Пароль вводите, когда 7z его спросит.
-
Используйте ключ, полученный из архива, для расшифровки резервной копии.
Передаваемые данные
| Ресурс | Содержимое |
|---|---|
basebackups_005/ |
Резервные копии WAL-G: метаданные и все объекты данных. Нужна полная копия с сохранением структуры каталогов. |
У шардированного кластера резервные копии передаются отдельно для каждого шарда. Нужны копии всех шардов из одного набора резервных копий и соответствие каталогов исходным идентификаторам шардов.
Восстановление базы данных
-
Установите WAL-G. Скачайте
wal-g-redisдля своей ОС и архитектуры. Например, для Ubuntu 24.04 x86-64:curl -fL \ https://github.com/wal-g/wal-g/releases/latest/download/wal-g-redis-24.04-amd64 \ -o /tmp/wal-g-redis install -m 0755 /tmp/wal-g-redis /usr/local/bin/wal-g-redis wal-g-redis --version wal-g-redis backup-fetch --helpВ
backup-fetchдолжны быть параметры-t rdb|aofи--redis-version. Версия WAL-G не связана с версией Valkey™. -
Добавьте ключ и настройте WAL-G:
install -d -m 0700 /etc/wal-g-restore install -m 0600 /path/to/received-private-key.pgp /etc/wal-g-restore/private.pgpСоздайте
/etc/wal-g-restore/wal-g.yaml:AWS_ACCESS_KEY_ID: "<ID статического ключа>" AWS_SECRET_ACCESS_KEY: "<секрет статического ключа>" AWS_ENDPOINT: "https://storage.yandexcloud.net" # или endpoint вашего S3 AWS_REGION: "ru-central1" AWS_S3_FORCE_PATH_STYLE: "true" WALG_S3_PREFIX: "s3://<bucket>/<каталог, где лежит basebackups_005/>" WALG_PGP_KEY_PATH: "/etc/wal-g-restore/private.pgp" # WALG_PGP_KEY_PASSPHRASE: "<пароль>" # только если ключ защищен паролем WALG_COMPRESSION_METHOD: "brotli" WALG_REDIS_DATA_PATH: "/var/lib/valkey" WALG_REDIS_APPENDONLY_PATH: "appendonlydir" WALG_REDIS_SERVER_PROCESS_NAME: "valkey-server" WALG_STREAM_RESTORE_COMMAND: "cat > /var/lib/valkey/dump.rdb"chmod 0600 /etc/wal-g-restore/wal-g.yaml export WALG_CONFIG=/etc/wal-g-restore/wal-g.yaml
WALG_S3_PREFIX указывает на родительский каталог basebackups_005/, а не на сам каталог или отдельный файл. Например, для объектов в s3://customer-backups/valkey-export/shard-1/basebackups_005/ укажите s3://customer-backups/valkey-export/shard-1. Имя бакета и внешний префикс могут отличаться от исходных, структура объектов внутри должна сохраниться.
Для другого S3-хранилища замените endpoint, регион и при необходимости AWS_S3_FORCE_PATH_STYLE.
brotli — сжатие по умолчанию в сервисе MDB. Если резервная копия сжата другим алгоритмом, укажите его: эта настройка нужна для поиска карты слотов командой backup-info --tag Slots.
Импортировать ключ в GPG не нужно — WAL-G читает его из файла. Пароль исходного Valkey™ для скачивания резервной копии тоже не нужен.
-
Проверьте доступ и выберите резервную копию:
wal-g-redis --config "$WALG_CONFIG" backup-listВыберите точное имя из списка и посмотрите метаданные:
export BACKUP_NAME="aof_20261004T223158Z" wal-g-redis --config "$WALG_CONFIG" backup-info "$BACKUP_NAME"Пример сокращенного вывода:
[ { "BackupName": "aof_20261004T223158Z", "StartLocalTime": "2026-10-04T22:31:58.891678Z", "FinishLocalTime": "2026-10-04T22:34:28.238213Z", "UserData": { "backup_id": "mdbmletglr2cuu7m51t5", "shard_name": "shard1" }, "DataSize": 1257101930, "BackupSize": 209362565, "BackupType": "aof", "Version": "9.1.2", "UsedMemory": 6437938008, "UsedMemoryRss": 6463381504, "MaxDBNumber": 0 } ]Из вывода понадобятся:
BackupName— имя для восстановления. Используйте его, а неUserData.backup_id.BackupType—rdbилиaof.Version— версия исходного Valkey™. Если поля нет, уточните версию у стороны, передавшей резервную копию.DataSize,BackupSize— объем данных и копии в байтах.UsedMemoryиUsedMemoryRssпоказывают потребление памяти исходным сервером, но не гарантируют такой же расход при восстановлении.MaxDBNumber— максимальный номер непустой логической БД. Число БД в конфигурационном файле должно быть больше этого номера.
StartLocalTimeиFinishLocalTime— время создания копии,UserData— дополнительные сведения о копии и исходном шарде. Отдельное поле можно прочитать черезbackup-info --tag, например:wal-g-redis --config "$WALG_CONFIG" backup-info --tag Version "$BACKUP_NAME" -
Проверьте целостность резервной копии:
-
Сохраните скрипт в файл
s3_test_script.sh.Код скрипта
#!/usr/bin/env bash set -u if [[ $# -lt 1 || $# -gt 2 || ! -f $1 || ! -r $1 ]]; then printf 'Usage: %s /path/to/wal-g-config [storage/directory]\n' "$0" >&2 exit 2 fi config=$1 directory=${2:-} directory=${directory#/} directory=${directory%/} wal_g=${WAL_G_BIN:-wal-g} listing=$(mktemp) || exit 2 trap 'rm -f "$listing"' EXIT if ! "$wal_g" --config "$config" st ls -r >"$listing"; then printf 'ERROR: wal-g st ls -r failed\n' >&2 exit 2 fi help=$({ "$wal_g" --config "$config" st cat --help || :; } 2>&1) if [[ $help == *--decode* ]]; then decode_flag=--decode elif [[ $help == *--decrypt* ]]; then decode_flag=--decrypt else printf 'ERROR: st cat supports neither --decode nor --decrypt\n' >&2 exit 2 fi if [[ $help != *--decompress* ]]; then printf 'ERROR: st cat does not support --decompress\n' >&2 exit 2 fi red='' reset='' if [[ -t 2 ]]; then red=$'\033[31m'; reset=$'\033[0m'; fi checked=0 decoded=0 raw=0 unknown=0 failed=0 while IFS= read -r line; do path='' case $line in obj\ *) read -r _ _ _ _ _ _ path <<<"$line" ;; [0-9]*) read -r _ _ _ _ _ path <<<"$line" ;; dir\ *|type\ *|size\ *|'') continue ;; *) printf 'UNPARSED listing line: %s\n' "$line" >&2; ((unknown += 1)); continue ;; esac if [[ -z $path ]]; then printf 'UNPARSED listing line: %s\n' "$line" >&2 ((unknown += 1)) continue fi if [[ -n $directory && $path != "$directory/"* ]]; then continue fi ((checked += 1)) case $path in *.br|*.lz4|*.lzma|*.zst|*.zstd|*.lzo) ((decoded += 1)) "$wal_g" --config "$config" st cat "$path" "$decode_flag" --decompress >/dev/null ;; *.json) ((raw += 1)) "$wal_g" --config "$config" st cat "$path" >/dev/null ;; *) ((raw += 1, unknown += 1)) printf 'RAW ONLY (unknown format): %s\n' "$path" >&2 "$wal_g" --config "$config" st cat "$path" >/dev/null ;; esac if [[ $? -ne 0 ]]; then printf '%sFAIL%s %s\n' "$red" "$reset" "$path" >&2 ((failed += 1)) fi done <"$listing" printf 'Checked: %d; decoded: %d; raw: %d; failed: %d; unknown: %d\n' \ "$checked" "$decoded" "$raw" "$failed" "$unknown" if ((failed > 0)); then exit 1; fi if ((checked == 0 || unknown > 0)); then exit 2; fi
-
Запустите скрипт:
WAL_G_BIN=wal-g-redis ./s3_test_script.sh */etc/wal-g/wal-g.yaml*При необходимости укажите директорию:
WAL_G_BIN=wal-g-redis ./s3_test_script.sh */etc/wal-g/wal-g.yaml* basebackups_005 # проверяет копииПример вывода:
FAIL test/corrupted_file_2.txt.br Checked: 2; decoded: 2; raw: 0; failed: 1; unknown:
-
-
Подготовьте Valkey™:
Установите нужную версию из публичных источников
. Если в исходном кластере использовались модули, установите их и подключите черезloadmoduleдо загрузки данных.Проверьте версию бинарного файла, который запускает служба, и остановите сервер:
valkey-server --version systemctl stop valkey-server systemctl is-active valkey-serverОжидаемый результат —
inactiveи ненулевой код возврата. Другие процессы Valkey™ тоже не должны использовать каталог восстановления.backup-fetchочищает каталог AOF, а также файлы*.rdbи*.aofв каталоге данных. Используйте отдельный каталог или заранее сохраните его прежнее содержимое, если оно еще нужно.install -d -o valkey -g valkey -m 0750 /var/lib/valkeyВ
/etc/valkey/valkey.confзадайте:bind 127.0.0.1 port 6379 protected-mode yes requirepass "<новый пароль Valkey™>" dir /var/lib/valkey dbfilename dump.rdb appenddirname appendonlydir appendfilename "appendonly.aof" aof-use-rdb-preamble yes appendfsync everysec # Для AOF-копии на шаге 5 замените на yes. appendonly no # Увеличьте, если MaxDBNumber >= 16. databases 16 cluster-enabled noПараметры
systemdи журналирования оставьте подходящими для вашей установки.dirдолжен совпадать сWALG_REDIS_DATA_PATH,appenddirname— сWALG_REDIS_APPENDONLY_PATH, а путь к RDB — с путем вWALG_STREAM_RESTORE_COMMAND.Пользователи, роли и настройки доступа не восстанавливаются из копии данных. Задайте новый пароль и введите его для локальных команд:
read -r -s -p "Пароль нового экземпляра Valkey™: " REDISCLI_AUTH export REDISCLI_AUTHvalkey-cliиспользует переменнуюREDISCLI_AUTH, несмотря на ее название. В новой сессии введите пароль заново. Если настроены отдельные ACL-пользователи, добавляйте к командам--user <имя>. -
Восстановите резервную копию. Выберите вариант по полю
BackupType. Valkey™ должен быть остановлен; запускайте его только после успешного завершенияbackup-fetch.
-
Вариант А — RDB
wal-g-redis --config "$WALG_CONFIG" backup-fetch "$BACKUP_NAME" -t rdb test -s /var/lib/valkey/dump.rdb chown -R valkey:valkey /var/lib/valkeyПри первом запуске в конфигурационном файле должно быть
appendonly no, чтобы Valkey™ загрузил восстановленныйdump.rdb, а не AOF.systemctl start valkey-server valkey-cli PING valkey-cli INFO persistenceДождитесь
PONGиloading:0. Если загрузка не завершилась, посмотрите журнал:journalctl -u valkey-server -n 100 --no-pagerЕсли дальше нужен AOF, включите его на уже загруженном сервере:
valkey-cli CONFIG SET appendonly yes valkey-cli INFO persistenceДождитесь завершения создания AOF. В
INFO persistenceдолжны быть:aof_enabled:1 aof_rewrite_in_progress:0 aof_rewrite_scheduled:0 aof_last_bgrewrite_status:ok aof_last_write_status:okПосле этого сохраните настройку:
valkey-cli CONFIG REWRITEЕсли команда не может записать конфигурационный файл, вручную замените в нем
appendonly noнаappendonly yes. Не перезапускайте сервер с включенным AOF до успешного создания его файлов.Для работы только с RDB оставьте
appendonly noи настройте расписание снимков. -
Вариант Б — AOF
Передайте полную версию установленного Valkey™ из
valkey-server --version. Например:export TARGET_VERSION="9.1.2" wal-g-redis --config "$WALG_CONFIG" backup-fetch "$BACKUP_NAME" \ -t aof --redis-version "$TARGET_VERSION"WAL-G восстановит многофайловый AOF в
/var/lib/valkey/appendonlydir: manifest и перечисленные в нем файлы. Объединять части или переименовывать их не нужно.ls -lah /var/lib/valkey/appendonlydir chown -R valkey:valkey /var/lib/valkeyВ
/etc/valkey/valkey.confвключите AOF:appendonly yes
Запустите сервер:
systemctl start valkey-server
valkey-cli PING
valkey-cli INFO persistence
journalctl -u valkey-server -n 100 --no-pager
Дождитесь PONG, loading:0 и aof_enabled:1. В журнале не должно быть ошибок чтения manifest, загрузки или усечения AOF.
-
Проверьте данные и настройте доступ
valkey-cli INFO keyspaceПроверьте список логических БД и несколько известных ключей: типы, значения, работу приложения. Для БД, отличной от DB 0, используйте
valkey-cli -n <номер>. В журнале не должно быть ошибок чтения данных, отсутствующих модулей или нехватки памяти.Ключи, у которых к моменту восстановления истек TTL, могут отсутствовать: восстановление не начинает срок их жизни заново. Поэтому число ключей может отличаться от числа на момент создания резервной копии.
Перед подключением приложения настройте пользователей и ACL,
bind, TLS и файрвол под свою сеть. Используйте новые учетные данные.
Восстановление шардированного кластера
Каждый исходный шард восстанавливается на отдельный новый мастер со своими исходными слотами. Сначала нужно собрать пустой кластер с нужным распределением слотов, затем остановить его, восстановить данные и запустить снова.
-
Выберите копии и получите карту слотов
Для каждого шарда подготовьте WAL-G по шагам 1–3: свой
WALG_S3_PREFIXи точное имя резервной копии. Выберите копии из одного набора резервных копий. Независимый выборLATESTдля каждого шарда может дать разные наборы.Запишите соответствие исходных шардов новым серверам. Например:
Исходный ID шарда S3-префикс BackupNameНовый сервер <source-shard-id-1>s3://.../shard-1<backup-name-1>10.0.0.11<source-shard-id-2>s3://.../shard-2<backup-name-2>10.0.0.12<source-shard-id-3>s3://.../shard-3<backup-name-3>10.0.0.13Прочитайте
BackupTypeиVersionкаждой резервной копии и отдельно извлеките карту слотов:wal-g-redis --config "$WALG_CONFIG" backup-info --tag Slots "$BACKUP_NAME"Пример:
{ "source-shard-id-1": [["0", "5460"]], "source-shard-id-2": [["5461", "10922"]], "source-shard-id-3": [["10923", "16383"]] }Ключи — исходные идентификаторы шардов, а не Node ID новых серверов и не обязательно
UserData.shard_name. Сопоставьте их с каталогами по сведениям, переданным вместе с копией. Обычныйbackup-infoкарту слотов не выводит.У шарда может быть несколько несмежных интервалов; обе границы включаются. Одиночный слот — пара одинаковых чисел. Если значение равно
null, у шарда нет назначенных слотов и команду их назначения нужно пропустить.Карты выбранных резервных копий должны согласовываться, а все диапазоны вместе — покрывать
0–16383без пропусков и пересечений.Если карта не читается, проверьте префикс, имя копии, полноту копии и
WALG_COMPRESSION_METHOD. Если карты нет или потеряно соответствие каталогов исходным ID, запросите эти сведения у стороны, передавшей копию.Важно
Не заменяйте исходную карту равномерным разбиением и не назначайте слоты через автоматическое
valkey-cli --cluster create: полученное распределение может не соответствовать данным в -
Подготовьте пустые узлы
На каждом сервере установите Valkey™ нужной версии и модули, подготовьте конфигурационный файл и каталог данных. Каталоги должны быть новыми, без старых данных и чужого
nodes.conf.В конфигурационном файле замените параметры сети и кластерного режима. Пример для первого сервера:
bind 127.0.0.1 10.0.0.11 cluster-enabled yes cluster-config-file /var/lib/valkey/nodes.conf cluster-node-timeout 15000 cluster-require-full-coverage yes cluster-announce-ip 10.0.0.11 cluster-announce-port 6379 cluster-announce-bus-port 16379 # Пока создается пустой кластер — для обоих типов копий. appendonly no databases 1На остальных серверах подставьте их собственные IP. Разрешите узлам соединяться друг с другом по портам
6379и16379. ЗадайтеrequirepassиREDISCLI_AUTH, как на шаге 4. До окончания восстановления приложение не должно писать в кластер.В Valkey™ 9.0+ число БД в кластерном режиме задает
cluster-databases: для обычного кластера с DB 0 добавьтеcluster-databases 1, а еслиMaxDBNumberбольше нуля — задайте число больше этого номера. В Valkey™ 7.2/8.x этого параметра нет.Запустите пустые серверы:
systemctl start valkey-server valkey-cli CLUSTER NODESНа каждом узле пока должна быть только собственная запись без слотов.
-
Назначьте слоты и объедините узлы:
До объединения задайте каждому узлу уникальный положительный config epoch и назначьте диапазоны из карты
Slots.Для карты из примера на первом сервере:
valkey-cli CLUSTER SET-CONFIG-EPOCH 1 valkey-cli CLUSTER ADDSLOTSRANGE 0 5460На втором сервере:
valkey-cli CLUSTER SET-CONFIG-EPOCH 2 valkey-cli CLUSTER ADDSLOTSRANGE 5461 10922На третьем:
valkey-cli CLUSTER SET-CONFIG-EPOCH 3 valkey-cli CLUSTER ADDSLOTSRANGE 10923 16383Используйте фактические диапазоны своей копии. Несколько интервалов можно передать одной командой, например
CLUSTER ADDSLOTSRANGE 0 100 500 700.С первого сервера познакомьте узлы друг с другом:
valkey-cli CLUSTER MEET 10.0.0.12 6379 valkey-cli CLUSTER MEET 10.0.0.13 6379Дождитесь обмена топологией. На каждом сервере проверьте и сохраните ее:
valkey-cli CLUSTER NODES valkey-cli CLUSTER INFO valkey-cli CLUSTER SAVECONFIGДолжны появиться все узлы с исходными диапазонами,
cluster_state:ok,cluster_slots_assigned:16384иcluster_slots_ok:16384.Остановите службу на всех серверах:
systemctl stop valkey-server systemctl is-active valkey-serverСохраните созданные
/var/lib/valkey/nodes.conf: они содержат новую топологию. Не удаляйте их при восстановлении и не заменяйте файлами исходного кластера. -
Восстановите данные шардов:
На каждом остановленном узле укажите его
WALG_CONFIGиBACKUP_NAME. Для AOF также задайтеTARGET_VERSION— полную версию установленного Valkey™.Выполните одну команду по типу резервной копии:
# RDB: wal-g-redis --config "$WALG_CONFIG" backup-fetch "$BACKUP_NAME" -t rdb # Или AOF: wal-g-redis --config "$WALG_CONFIG" backup-fetch "$BACKUP_NAME" \ -t aof --redis-version "$TARGET_VERSION"После успешного завершения проверьте восстановленные файлы, как на шаге 5, и исправьте владельца:
chown -R valkey:valkey /var/lib/valkeyВ конфигурационном файле установите
appendonly noдля RDB илиappendonly yesдля AOF. Кластерные параметры иnodes.confдолжны сохраниться.Когда восстановлены файлы всех шардов, запустите службы:
systemctl start valkey-serverПосле RDB-восстановления при необходимости включите AOF в порядке, описанном на шаге 5: сначала загрузка RDB, затем создание AOF и сохранение настройки. Пока запускаются остальные узлы и идет обмен топологией, возможно временное
cluster_state:fail. -
Проверьте кластер:
На каждом сервере выполните:
valkey-cli PING valkey-cli INFO persistence valkey-cli INFO keyspace valkey-cli CLUSTER INFO valkey-cli CLUSTER NODES journalctl -u valkey-server -n 100 --no-pagerПроверьте, что:
- Все узлы загрузили данные (
loading:0), в журналах нет ошибок чтения данных или модулей. - Состояние на всех узлах —
cluster_state:ok,cluster_slots_assigned:16384,cluster_slots_ok:16384,cluster_slots_fail:0иcluster_slots_pfail:0. - Каждый шард попал на нужный сервер, его диапазоны совпадают с
Slots. Нет незавершенных migrating/importing-слотов и узлов с флагамиfail/fail?. - Известные ключи читаются через клиент с поддержкой кластера. Для CLI используйте
valkey-cli -c.
- Все узлы загрузили данные (
После проверки настройте доступ и подключайте приложение. Клиенту нужны новые учетные данные и сетевой доступ к адресам, объявляемым всеми узлами.
Если восстановление не получилось
| Симптом | Что проверить |
|---|---|
backup-list пуст |
Префикс должен указывать на родителя basebackups_005/. Проверьте endpoint, бакет и права S3. |
S3 возвращает AccessDenied |
Ключи, права перечисления и чтения, регион и параметры адресации S3. |
| Ошибка расшифровки | Приватный PGP-ключ и его парольную фразу, если она задана. |
backup-info --tag Slots не находит объект |
Полноту копии, наличие карты в исходной резервной копии и WALG_COMPRESSION_METHOD. |
| WAL-G сообщает о несовместимой версии при восстановлении AOF | В --redis-version должна быть версия установленного Valkey™, не старее исходного. |
| После восстановления RDB база пустая или загружены другие данные | Каталог данных, dbfilename и первый запуск с appendonly no. |
| В ошибке RDB/AOF упоминается неизвестный тип модуля или команда | Установлены ли совместимые модули исходного кластера и подключены ли они через loadmodule. |
| Valkey™ не может открыть файлы | Владельца, права и совпадение путей в конфигурационных файлах WAL-G и Valkey™. |
CLUSTERDOWN после запуска всех узлов |
Сеть, объявляемые адреса, карту слотов, nodes.conf и загрузку каждого шарда. |
| Ключей меньше ожидаемого | Выбор резервной копии, наличие всех шардов и БД, истекшие TTL и журнал загрузки. |
После ошибки скачивания или загрузки исправьте причину и повторите восстановление при остановленном сервере. Частично созданные файлы не означают, что восстановление из копии произошло.