Как сделать бэкап и обновить стек Docker Compose

Что должно входить в резервную копию стека Docker Compose

Резервная копия стека Docker Compose должна содержать четыре отдельных компонента, потеря любого из которых делает восстановление приложения невозможным: файл compose, файл .env рядом с ним, содержимое всех томов и дамп базы данных, созданный собственным клиентом этой СУБД. Копирование файлов базы данных во время работы контейнера не является резервным копированием. При обновлении используйте тот же список плюс одно правило: создавайте резервную копию перед выполнением pull, так как миграции схемы рассчитаны на прямое выполнение, и большинство проектов не предусматривают возможности отката.

Всё, что описано ниже, предполагает, что стек уже развёрнут и команда docker compose ps подтверждает его работу. В примерах используется каталог проекта /srv/myapp со службами app и db. Подставьте свои собственные имена. Команды намеренно оставлены универсальными, так как критически важные части — тома и база данных — работают одинаково независимо от приложения.

Определите, что именно хранит ваш стек

cd /srv/myapp
docker compose ps
docker compose config --volumes
docker volume ls --filter label=com.docker.compose.project=myapp

Команда docker compose config --volumes выводит краткие имена именованных томов, объявленных в вашем файле. Команда docker volume ls выводит имена, которые эти тома фактически имеют на диске. Эти два списка различаются, так как Compose добавляет имя проекта в начало: том, записанный как db_data в файле, существует как myapp_db_data. Имя проекта по умолчанию совпадает с именем директории, поэтому переименование директории переключает стек на новый набор пустых томов, оставляя старые тома заполненными вашими данными. Для каждой команды ниже требуется реальное имя из docker volume ls.

Bind mounts не отображаются ни в одном из списков. В файле compose это записи, где слева от двоеточия указан путь на хосте, например ./config:/app/config. Это обычные директории на хосте, поэтому к ним можно обратиться стандартными инструментами. Именованные тома находятся в /var/lib/docker/volumes/, а docker volume inspect --format '{{.Mountpoint}}' myapp_db_data выводит точный путь к конкретному тому. Тип тома, используемый в стеке, влияет на способ копирования данных, а в bind mounts против именованных томов подробно описаны различия между ними.

Теперь распределите найденные данные на две группы. Некоторые тома содержат состояние, которое невозможно воссоздать: загруженные файлы, сгенерированные ключи, саму базу данных и всё, что пользователь ввёл в приложение. Другие содержат производные данные, такие как миниатюры и поисковые индексы, которые приложение может пересоздать самостоятельно. Резервное копирование второй группы требует места на диске и времени на восстановление, не принося никакой пользы. Том кэша Redis — самый наглядный пример: его потеря означает лишь один медленный первый запрос.

Резервное копирование compose-файла и файла .env

Оба файла находятся на хосте рядом друг с другом, и ни один из них не входит в состав томов. Файл .env содержит пароль базы данных, секретный ключ приложения и любые API-токены, поэтому именно этот файл превращает набор томов обратно в работающее приложение. Обычно он также указан в .gitignore, что означает, что план «моя конфигурация в git» исключает единственный файл, который имеет наибольшее значение. Хранение секретов в env-файле — это правильный подход, и он накладывает на вас обязанность включить его в резервную копию.

sudo install -d -m 700 -o "$USER" -g "$(id -gn)" /srv/backups/myapp
cp -a compose.yaml .env /srv/backups/myapp/
chmod 600 /srv/backups/myapp/.env

Скопируйте каждый compose-файл, который использует стек, а не только первый. Стек, запущенный с помощью -f compose.yaml -f compose.prod.yaml, требует наличия обоих файлов для восстановления в исходном виде, а механизм объединения нескольких compose-файлов определяет, какие значения в конечном итоге попадут в контейнер.

Одно предостережение связывает .env с томами. Официальный образ Postgres считывает POSTGRES_PASSWORD только при инициализации пустой директории данных. Изменение этого значения позже не меняет пароль внутри самой базы данных. Если восстановить том за прошлый месяц вместе с текущим .env, приложение не сможет подключиться с ошибкой FATAL: password authentication failed for user "appuser", хотя при проверке оба файла будут выглядеть корректно. Храните .env и тома, относящиеся к одному и тому же моменту времени, вместе в одной резервной копии.

Дамп базы данных с помощью собственного клиента

Сервер базы данных постоянно записывает данные в файлы. tar, созданный с помощью /var/lib/postgresql/data во время работы сервера, копирует некоторые страницы до записи, а некоторые — после, поэтому архив содержит смесь состояний, которые могут не восстановиться. Инструмент для создания дампов считывает данные в рамках одной транзакции, поэтому файл содержит один согласованный момент времени. Эта разница отделяет резервную копию от простой копии файлов.

docker compose exec -T db sh -c \
  'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
  > /srv/backups/myapp/db-$(date +%F).dump

Обязательно используйте -T. Он отключает выделение TTY; если TTY подключен, Docker преобразует поток вывода по пути к вашей оболочке, что повреждает бинарный дамп. Вы не узнаете об этом, пока не возникнет ошибка при восстановлении. Одинарные кавычки также важны: они предотвращают раскрытие $POSTGRES_USER вашей хостовой оболочкой, поэтому переменная раскрывается внутри контейнера, используя значения, уже заданные в файле compose. -Fc записывает данные в пользовательском формате, который сжимается «на лету» и позволяет pg_restore извлекать отдельные объекты позже.

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

docker compose exec -T db sh -c 'pg_dumpall -U "$POSTGRES_USER" --globals-only' \
  > /srv/backups/myapp/globals.sql

Затем проверьте, что файл является дампом, а не сообщением об ошибке:

ls -lh /srv/backups/myapp/
head -c 5 /srv/backups/myapp/db-$(date +%F).dump

Дамп в пользовательском формате начинается с пяти байтов PGDMP. Файл нулевого размера или файл, начинающийся с pg_dump:, означает, что команда завершилась неудачей. Оболочка создает выходной файл до запуска команды, поэтому неудачный дамп оставляет после себя файл с правдоподобным именем и временной меткой. Это самая распространенная причина скрытых сбоев резервного копирования.

Для MariaDB или MySQL клиент меняется, но принцип остается прежним:

docker compose exec -T db sh -c \
  'mariadb-dump -u root -p"$MARIADB_ROOT_PASSWORD" --single-transaction --databases "$MARIADB_DATABASE"' \
  > /srv/backups/myapp/db-$(date +%F).sql

--single-transaction создает согласованный дамп таблиц InnoDB без блокировки записи. В образе MySQL команда называется mysqldump, а переменные — MYSQL_ROOT_PASSWORD и MYSQL_DATABASE. В текущих образах MariaDB mysqldump по-прежнему работает как псевдоним для mariadb-dump. Учтите, что пароль, переданный в командной строке, виден в списке процессов контейнера всё время, пока выполняется дамп.

SQLite требует особого подхода. База данных представляет собой один файл, но недавние транзакции могут находиться в отдельном файле -wal рядом с ним, поэтому копирование только .db приведет к потере последних записей. Если в образе есть клиент, sqlite3 /data/app.db ".backup '/data/app-backup.db'" создаст согласованную копию во время работы приложения. Если клиента нет, остановите контейнер и скопируйте файл .db вместе с его спутниками -wal и -shm.

Если ваша база данных работает на хосте, а не внутри стека, применяются те же команды без префикса docker compose exec, и статью запуск базы данных в Docker или на хосте стоит прочитать перед следующей пересборкой системы.

Архивация томов

Именованный том не имеет пути на хосте, который следовало бы редактировать вручную, поэтому подключите его к временному контейнеру и создайте архив оттуда.

docker run --rm \
  -v myapp_uploads:/data:ro \
  -v /srv/backups/myapp:/backup \
  alpine:3 tar czf /backup/uploads.tar.gz -C /data .

Вспомогательный контейнер подключает том в режиме только для чтения по пути /data, а каталог для резервной копии — по пути /backup, после чего записывает архив на сторону хоста. Флаг --rm удаляет вспомогательный контейнер сразу после завершения tar. Параметр :ro важен, так как в случае опечатки в команде tar исходные данные не будут повреждены. Использование -C /data . гарантирует, что при восстановлении файлы попадут в нужное место: пути сохраняются относительно корня тома. Если указать tar czf /backup/uploads.tar.gz /data, каждый путь получит ведущий data/, из-за чего при восстановлении внутри тома будет создан каталог /data/data, и приложение увидит пустую директорию. Архив принадлежит пользователю root, так как команда tar выполнялась от имени root внутри контейнера. Выполните sudo chown "$USER" /srv/backups/myapp/uploads.tar.gz, если это мешает работе, и ознакомьтесь с разделом как PUID и PGID определяют владельца файла, если после восстановления файлы оказываются недоступными для чтения приложением.

Выполняйте эту процедуру для каждого именованного тома. Для bind mounts контейнер не требуется: tar czf /srv/backups/myapp/config.tar.gz -C /srv/myapp/config . выполняет ту же задачу непосредственно на хосте.

Для каждого тома решайте отдельно, нужно ли останавливать приложение. Создание архива «на лету» для тома, в который приложение постоянно записывает данные, может привести к захвату файла в процессе записи. Для каталога загрузок, где файлы записываются один раз, а затем только читаются, этот риск невелик. В остальных случаях останавливайте сервис на время копирования с помощью docker compose stop app, а затем docker compose start app. Команда stop оставляет контейнеры и тома на месте, что и требуется в данном случае, и перед использованием любой из них стоит уточнить разницу между down и stop.

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

Порядок выполнения операций

1. Скопируйте файлы compose и .env в каталог резервного копирования.
2. Выполните дамп базы данных, пока она запущена.
3. Остановите контейнер приложения, если его тома изменяются на месте.
4. Заархивируйте каждый именованный том и каждый каталог с bind-mount.
5. Запустите всё, что было остановлено, затем выполните проверку с помощью docker compose ps.
6. Запишите теги образов и дайджесты, которые использует стек.
7. Скопируйте весь каталог резервного копирования с этого сервера.

Шаг 7 — это то, что обычно откладывают на потом.

Копирование данных с сервера

Резервная копия, хранящаяся на том же диске, что и рабочие данные, защищает только от ваших собственных ошибок. Выход из строя накопителя, удаление сервера или потеря доступа к аккаунту приведут к одновременной потере обоих экземпляров. Регулярно копируйте директорию в стороннее хранилище, не связанное с данным VPS, и настройте политику хранения. В статье резервное копирование с VPS с помощью restic описаны настройка репозитория, флаги хранения и команда проверки, поэтому здесь эти вопросы не рассматриваются.

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

docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
  | restic backup --stdin --stdin-filename db.dump

Какой бы инструмент вы ни использовали, настройте расписание через systemd timer или cron и обеспечьте уведомление об ошибках выполнения задачи. Скрипт резервного копирования, вывод которого никуда не направляется, может перестать работать на полгода, и вы об этом не узнаете.

Проверка работоспособности резервной копии через тестовое восстановление

Резервная копия, которую никто не восстанавливал, — это лишь предположение. Приведенная ниже процедура выполняет восстановление во второй стек, работающий параллельно с основным, поэтому продуктовая среда продолжает обслуживать запросы, и ваши действия не затронут её.

Механизм основан на имени проекта. Compose берет его из имени каталога и добавляет к каждому контейнеру и тому, которые он создает. Скопируйте резервную копию в новый каталог, и восстановленный стек автоматически получит собственные тома.

sudo install -d -m 700 -o "$USER" -g "$(id -gn)" /srv/myapp-restore
cd /srv/myapp-restore
cp /srv/backups/myapp/compose.yaml /srv/backups/myapp/.env .

Отредактируйте скопированный файл compose, чтобы опубликованный порт хоста не конфликтовал с работающим стеком: используйте 18080:8080 вместо 8080:8080 или измените переменную, которая задает его в скопированном .env. Затем создайте контейнеры и их пустые тома, не запуская сами сервисы:

docker compose create
docker volume ls --filter label=com.docker.compose.project=myapp-restore

Вторая команда должна вывести те же имена томов, что и в продуктовой среде, с префиксом myapp-restore_. Заполните их, запустите базу данных отдельно и загрузите дамп:

docker run --rm -v myapp-restore_uploads:/data -v /srv/backups/myapp:/backup \
  alpine:3 tar xzf /backup/uploads.tar.gz -C /data
docker compose up -d db
docker compose exec -T db sh -c \
  'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists' \
  < /srv/backups/myapp/db-2026-08-16.dump

--clean --if-exists удаляет каждый объект перед его повторным созданием, что делает процесс восстановления повторяемым. Без этого флага повторный запуск в базу данных, которая уже содержит эти таблицы, завершится ошибкой pg_restore: error: could not execute query: ERROR: relation "users" already exists.

Затем запустите остальные сервисы и проверьте их так, как это сделал бы пользователь:

docker compose up -d --wait
docker compose exec -T db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "\dt"'
docker compose logs --tail=50

docker compose up -d --wait блокирует выполнение до тех пор, пока каждый сервис не сообщит о статусе running или healthy, и завершается с ненулевым кодом, если этого не произошло, что позволяет автоматизировать этот шаг. Если сервис не переходит в состояние healthy, docker compose ps покажет его текущее состояние, а Compose healthchecks объяснит, что именно отображается в этом столбце. После этого откройте приложение на альтернативном порту и войдите под реальной учетной записью. Создайте одну запись и откройте один файл, который хранится в томе. Эта пара действий является доказательством: дамп восстановлен, том восстановлен, и они согласованы между собой. Тест, который подтверждает только отображение страницы входа, ничего не доказывает относительно сохранности ваших данных.

Удалите тестовый стек после успешного завершения проверки:

docker compose down -v

Это единственный случай, когда -v является корректным флагом. В рабочем каталоге та же команда удалит тома, которые вы пытаетесь защитить.

Как обновить стек Compose

Изучите примечания к выпуску для каждой версии в промежутке между текущей и целевой, обращая внимание на слова breaking и migration. Проекты, не поддерживающие переход через несколько мажорных версий, указывают это в документации. Миграция, которая завершается с ошибкой, часто сообщает об этом только после того, как часть схемы базы данных уже была изменена.

Зафиксируйте текущее состояние перед внесением любых изменений:

docker compose images
docker image inspect --format '{{index .RepoDigests 0}}' postgres:16.4

docker compose images выводит образ и тег, которые использует каждый сервис в данный момент. Digest — единственное значение, однозначно определяющее образ, так как тег может быть в любой момент перенаправлен на другую версию.

Создайте резервную копию согласно инструкциям из предыдущих разделов и скопируйте её за пределы сервера. Делайте это даже при установке патч-релизов. Проблемы чаще всего возникают при обновлении, к которому не подготовились.

Зафиксируйте версию в файле compose, так как latest не является версией:

services:
  db:
    image: postgres:16.4

При использовании image: postgres:latest команда docker compose pull загружает то, на что указывает тег в текущий момент, и у вас нет возможности узнать, какая именно версия работала вчера. Фиксация тега превращает обновление в изменение одной строки, которое можно увидеть через git diff и отменить повторным редактированием. Аналогичным образом зафиксируйте образ приложения, взяв точную версию со страницы релизов проекта.

Загрузите образы и пересоздайте контейнеры:

docker compose pull
docker compose up -d --wait

docker compose up -d сравнивает файл конфигурации с запущенными контейнерами и пересоздаёт только те сервисы, для которых изменился образ или настройки. Команда не затрагивает именованные тома, поэтому новый контейнер запускается с существующими данными. В этом заключается смысл операции и основной риск, так как при первом запуске новой версии обычно выполняется миграция схемы данных.

Отслеживайте процесс:

docker compose ps
docker compose logs -f --tail=100 app

Контейнер, который завершился с ошибкой, отображает Exited (1) в столбце STATUS команды docker compose ps, а причина ошибки находится в последних строках лога. Ошибки миграции видны только там. Когда логи стабилизируются, войдите в систему и протестируйте приложение в течение минуты.

Если docker compose pull останавливается с ошибкой no space left on device, обычно это связано с наличием старых слоёв образов. Очистка неиспользуемых образов Docker поможет освободить место. Выполняйте очистку только после того, как убедитесь в работоспособности обновления, так как старые слои необходимы для быстрого отката.

Как выполнить откат при неудачном обновлении

Существует два сценария, и они требуют совершенно разных усилий. Если новая версия не меняла схему данных, откат выполняется одной командой: верните старый тег в файл compose и выполните docker compose up -d. Контейнер будет заменён, тома останутся на месте, и старый код сможет прочитать данные, которые он записал ранее.

Если новая версия выполнила миграцию схемы, старый код больше не сможет с ней работать. Миграции пишутся для выполнения в прямом направлении, и большинство проектов не содержат скриптов для отката. В результате старая версия запускается, но завершается ошибкой при первом же запросе к переименованному или удалённому столбцу, выдавая ошибки вида ERROR: column "avatar_url" does not exist. Единственный путь назад — это дамп, который вы сделали перед обновлением: верните старый тег, удалите том базы данных, создайте его заново пустым, восстановите в него дамп и запустите сервис. Без этого дампа пути назад нет, именно поэтому резервное копирование выполняется перед обновлением.

Мажорные версии Postgres — самый критичный случай, и они часто застают врасплох, так как ошибка возникает при самом обновлении, а не при попытке отката. Формат данных на диске меняется с каждым мажорным релизом. Измените postgres:16.4 на postgres:17.2, выполните docker compose up -d, и новый сервер откажется запускаться:

FATAL:  database files are incompatible with server
DETAIL:  The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17.2.

Образ не выполняет pg_upgrade автоматически. Поддерживаемый путь в рамках стека Compose выглядит так: дамп, замена, восстановление. Сделайте дамп, пока работает старая версия, выполните docker compose down, удалите том базы данных, установите новый тег, выполните docker compose create для создания свежего пустого каталога данных, запустите базу данных, восстановите дамп и запустите остальные сервисы. Храните старый дамп до тех пор, пока новая мажорная версия не проработает под реальной нагрузкой хотя бы сутки. Минорные обновления внутри одной мажорной версии, например с 16.4 на 16.9, не требуют этих действий, так как формат данных в них стабилен и контейнер просто запускается.

Являются ли снимки (snapshots) VPS резервной копией?

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

Для всего остального это плохой инструмент. Гранулярность снимка — это вся машина целиком, поэтому для восстановления одной удалённой таблицы придётся разворачивать весь сервер где-то ещё и извлекать таблицу оттуда. Срок хранения снимков обычно невелик. Копии, как правило, хранятся в той же учётной записи провайдера, что и сервер, поэтому при потере доступа к аккаунту вы лишаетесь и сервера, и всех его снимков. Кроме того, снимок работающей машины фиксирует состояние базы данных в процессе записи, поэтому при первом запуске база выполняет crash recovery, а все транзакции, находившиеся в процессе выполнения, теряются.

Используйте и то, и другое. Снимок — это кнопка «отмена» на время проведения обновлений. Дамп — это копия, которая сохранится даже при удалении аккаунта. различия между снимками и резервными копиями подробно описывает, от каких именно сбоев защищает каждый из этих методов. Тот же каталог с резервными копиями позволяет превратить перенос стека на новый VPS в рутинную задачу, а не в восстановление системы по памяти.

Что идет не так и что вы увидите

Флаг volumes при выполнении down. docker compose down -v удаляет именованные тома, объявленные в файле, и Compose подтверждает это строкой Volume myapp_db_data Removed. Отменить это действие невозможно. Обычная команда docker compose down оставляет их без изменений. Используйте полную форму docker compose down --volumes, чтобы деструктивный флаг был словом, которое вы ввели осознанно.

Дамп без магической строки. pg_restore: error: did not find magic string in file header означает, что файл не является архивом. Частая причина — отсутствие -T в docker compose exec, так как при подключенном TTY поток данных преобразуется по пути к вашей оболочке, и бинарный дамп повреждается. Снимите дамп повторно с помощью -T, затем проверьте первые пять байтов командой head -c 5.

Пароль, который не меняется. FATAL: password authentication failed for user "appuser" после восстановления означает, что .env и каталог с данными относятся к разным моментам времени. Образ устанавливает пароль только при создании пустого каталога данных, поэтому последующее редактирование .env не меняет ничего внутри базы данных. Восстановите соответствующий .env или измените пароль внутри базы данных с помощью ALTER USER.

Второй, пустой том. Docker создает том по запросу, поэтому docker run -v myapp_upload:/data при отсутствии s запишет данные в новый пустой том и сообщит об успешном завершении. Команда docker volume ls затем покажет оба имени, одно из которых будет пустым. Копируйте имена томов из docker volume ls, а не вводите их по памяти.

Восстановление, направленное на продуктивную среду. Выполнение команд восстановления в /srv/myapp вместо /srv/myapp-restore перезаписывает рабочие данные резервной копией, при этом команды выглядят идентично в обоих случаях. Проверяйте pwd перед каждой командой восстановления и храните тренировочные файлы в отдельном каталоге.

FAQ

Удаляет ли docker compose down мои данные?

Нет. docker compose down удаляет контейнеры и сеть по умолчанию, но не затрагивает именованные тома и bind mounts. docker compose down -v удаляет именованные тома, указанные в вашем файле, и это действие необратимо. Bind mounts — это каталоги на хосте, поэтому Compose никогда их не удаляет. Если вы хотите остановить сервисы для резервного копирования, не затрагивая остальное, используйте docker compose stop.

Можно ли скопировать каталог данных Postgres вместо запуска pg_dump?

Только при остановленном контейнере. Пока сервер работает, файлы постоянно изменяются, и копия может содержать несогласованные данные, которые невозможно восстановить. Пофайловое копирование также привязано к конкретной мажорной версии Postgres, поэтому оно не запустится на другой версии. Остановите контейнер, заархивируйте том, запустите его снова и рассматривайте этот метод как способ быстрого восстановления, а не как единственную резервную копию. Дамп — это переносимая копия, из которой следует выполнять восстановление.

Как обновить Postgres до новой мажорной версии в Compose?

Простого изменения тега недостаточно. Новый сервер откажется запускаться с каталогом данных старой версии и запишет в лог The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17.2. Выполните pg_dump, пока работает старая версия, затем docker compose down, удалите том базы данных, укажите новый тег, выполните docker compose create для создания пустого тома, запустите базу данных и восстановите в неё дамп. Сохраняйте старый дамп, пока новая версия не проработает под реальной нагрузкой некоторое время.

Как часто нужно делать резервные копии и как долго их хранить?

Интервал должен соответствовать объему работы, который вы готовы выполнить повторно в случае потери данных. Ежедневное копирование подходит для личных проектов или небольших команд, плюс одна дополнительная копия вручную непосредственно перед любым обновлением. Что касается хранения, держите достаточное количество копий, чтобы покрыть повреждения, которые вы не заметили сразу, так как поврежденная в пятницу таблица не восстановится из копии за четверг. restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune — разумная политика для начала. Независимо от расписания, выполняйте восстановление из копии раз в квартал. Пока вы этого не сделали, у вас нет резервных копий, у вас есть просто файлы.

Нужно ли останавливать весь стек для создания резервной копии?

Обычно нет. Дамп базы данных остается консистентным во время работы сервера, поэтому простой базы данных не требуется. Основной вопрос — тома. Если приложение только добавляет файлы (например, каталог загрузок), создание архива «на лету» достаточно безопасно. Если приложение перезаписывает файлы на месте, остановите этот конкретный сервис на время копирования с помощью docker compose stop app, а затем запустите его снова. Остановка приложения при работающей базе данных — это обычно самый короткий безопасный способ выполнения резервного копирования.