Создание резервной копии
Резервная копия базы данных нужна, чтобы восстановить заявки, пользователей, настройки, направления обмена и другие данные проекта после ошибки, неудачного обновления или сбоя на сервере.
Для создания резервных копий PostgreSQL в iEXExchanger используется инструмент iEX DB Backup. Он экспортирует основную базу приложения, базу Laravel Pulse и дополнительные базы PostgreSQL.
Каждая новая резервная копия проверяется перед сохранением и получает manifest с контрольной суммой SHA-256. Это позволяет убедиться, что файл не повреждён и относится к нужному профилю.
Где находится инструмент
Основная команда:
tools/db-backup/iex-db-backupПример конфигурации:
tools/db-backup/db-backup.example.jsonРабочая конфигурация:
tools/db-backup/db-backup.jsonСтандартный каталог резервных копий:
storage/app/backups/database/Логи:
storage/logs/db-backup/Все команды рекомендуется выполнять из корня Backend-проекта.
Для FASTPANEL путь обычно выглядит так:
Для чего нужен iEX DB Backup
Через инструмент можно:
создать резервную копию основной базы приложения;
отдельно сохранить базу Laravel Pulse;
подключить дополнительные базы PostgreSQL;
создать сжатый
.sql.gz;получить обычный
.sql;добавить метку к имени файла;
сохранить копию в стандартный или отдельный каталог;
проверить SQL-файл без подключения к рабочей базе;
сверить SQL-файл с manifest;
проверить контрольную сумму SHA-256;
выполнить контрольное восстановление в пустую базу;
настроить автоматическое копирование через CRON.
Инструмент не выполняет:
изменение Laravel
.env;Product Updates;
Laravel migrations;
очистку рабочей базы;
включение режима обслуживания;
удаление старых копий;
перезапись существующих backup-файлов.
iEX DB Backup сохраняет только базу данных.
Файлы Backend и Frontend, .env, изображения, пользовательские загрузки и содержимое каталога storage необходимо резервировать отдельно.
Как работает резервное копирование
После запуска инструмент:
загружает конфигурацию;
получает реквизиты выбранного профиля;
проверяет подключение к PostgreSQL;
запускает
pg_dump;создаёт временный SQL-файл;
проверяет содержимое SQL;
вычисляет SHA-256;
создаёт manifest;
публикует готовую резервную копию.
PostgreSQL экспортируется через транзакционно согласованный снимок. Приложение может продолжать работу, а все данные внутри резервной копии будут относиться к одному состоянию базы.
Если проверка не пройдена, файл не считается готовой резервной копией.
Существующие файлы не перезаписываются.
Что создаётся
Для каждого профиля создаются два файла:
<имя>.sql.gz
Сжатая SQL-копия PostgreSQL
<имя>.sql.gz.manifest.json
Manifest с информацией о резервной копии
По умолчанию файлы сохраняются в отдельный UTC-каталог:
Пример:
Каталог создаётся с правами:
SQL-файлы и manifest создаются с правами:
Manifest содержит:
имя профиля;
название профиля;
метку запуска;
тип базы данных;
тип сжатия;
размер файла;
SHA-256;
количество таблиц;
количество индексов;
первичные ключи;
уникальные ограничения;
внешние ключи;
количество строк.
Перед началом
Убедитесь, что:
PostgreSQL 18 установлен и работает;
Backend iEXExchanger подключён к PostgreSQL;
вы знаете пользователя Backend-сайта;
в корне проекта находятся
.envиartisan;каталог
tools/db-backup/присутствует;в
.envуказаны рабочие реквизиты PostgreSQL;на сервере установлен
pg_dump;на диске достаточно свободного места.
Go на сервер устанавливать не требуется. Launcher автоматически выбирает бинарный файл для архитектуры сервера.
Поддерживаются:
Linux amd64;
Linux arm64;
macOS arm64.
Проверьте версию инструмента:
Проверьте pg_dump:
Для PostgreSQL 18 рекомендуется использовать:
Проверка точного файла:
Инструкция по установке PostgreSQL 18:
Запускайте iEX DB Backup от пользователя Backend-сайта, а не от root.
Так резервные копии, временные файлы и логи получат правильного владельца.
Какие базы сохраняются
Для каждой базы используется отдельный профиль.
Если Laravel Pulse не используется
Отключите профиль:
После этого команда с --profile all обработает только остальные включённые профили.
Пошаговое создание резервной копии
Перейдите в Backend-проект
Для FASTPANEL:
Пример:
Проверьте текущий каталог:
Проверьте обязательные файлы:
Проверьте права на запуск:
Если право на запуск потерялось после загрузки или распаковки архива:
Создайте конфигурацию
Если db-backup.json ещё не существует:
Установите приватные права:
Для стандартного проекта используйте:
Проверьте права:
Ожидаемый результат:
db-backup.json может содержать пароли.
Не добавляйте его в Git, не размещайте в публичном каталоге и не используйте символическую ссылку.
Если конфигурация уже существует, не перезаписывайте её. Сначала проверьте текущие профили и сохраните защищённую копию.
Проверьте конфигурацию
Выполните:
Команда проверит:
структуру
db-backup.json;права конфигурационного файла;
параметры из
.env;подключения к PostgreSQL;
доступность профилей;
количество найденных объектов.
Успешный результат заканчивается сообщением:
config-check не создаёт резервную копию и не изменяет данные.
Сохраните копию вне сервера
Для каждого профиля сохраните оба файла:
Подходящие места хранения:
отдельный backup-сервер;
защищённое объектное хранилище;
локальный защищённый компьютер;
другой физический диск.
Не храните единственную резервную копию на сервере с проектом.
При повреждении диска или потере доступа к серверу копия может быть утрачена вместе с рабочей базой.
Проверка резервной копии
Команда inspect не подключается к рабочей базе и ничего в ней не изменяет.
Она проверяет:
файл является обычным файлом;
файл не является символической ссылкой;
gzip-поток не повреждён;
SQL относится к PostgreSQL;
размер файла;
SHA-256;
соответствие manifest;
имя файла;
профиль;
количество таблиц;
индексы;
первичные ключи;
уникальные ограничения;
внешние ключи;
команды
COPY;количество строк;
отсутствие запрещённых управляющих SQL-команд.
Пример успешного результата:
Наличие .sql.gz ещё не подтверждает успешное создание копии.
Должны выполняться все условия:
экспорт завершился кодом
0;показано
All selected profiles completed successfully;рядом создан manifest;
inspectзавершился успешно.
Хранение SQL и manifest
SQL и manifest необходимо хранить вместе:
Не переименовывайте только один файл.
Неправильно:
Manifest содержит исходное имя SQL-файла. Если переименовать только один файл, проверка завершится ошибкой.
Оба файла можно переместить в другой каталог, сохранив их имена.
Проверка старого SQL без manifest
Старый доверенный SQL-файл можно проверить без manifest:
В результате будет показано:
Для такого файла нельзя использовать:
Для новых резервных копий всегда сохраняйте manifest.
Метки резервных копий
Параметр --tag добавляет понятную метку в имя SQL-файла и manifest:
Примеры:
Допускаются:
латинские буквы;
цифры;
точка;
дефис;
подчёркивание.
Максимальная длина — 64 байта.
Используйте латиницу без пробелов, двоеточий и слешей.
Форматы резервных копий
Обычный SQL-файл
Чтобы получить несжатый .sql:
При --compression gzip имя должно заканчиваться на .gz.
При --compression none окончание .gz использовать нельзя.
Не сохраняйте рабочую базу с клиентскими данными в каталоге database/ и не добавляйте её в Git.
Каталог database/ можно использовать только для очищенного установочного snapshot.
Выбор каталога
Отдельный каталог
Чтобы сохранить копии в другом каталоге:
При --profile all значение --output всегда считается каталогом.
Каталог должен:
находиться вне
public;быть доступен пользователю сайта;
иметь приватные права;
не быть символической ссылкой.
Создайте каталог:
Установите права:
Убедитесь, что пользователь Backend-сайта может записывать в этот каталог.
Прямое подключение к PostgreSQL
Если Laravel подключается через pooler, а pg_dump должен обращаться напрямую к PostgreSQL, добавьте в .env:
Если параметры DB_DIRECT_* заполнены, инструмент использует их для экспорта основной базы.
Рабочее подключение Laravel при этом не изменяется.
Автоматическое резервное копирование
Автоматический запуск настраивается через CRON пользователя Backend-сайта.
Подготовьте каталог логов:
Откройте планировщик:
Для PostgreSQL 18 укажите путь к pg_dump:
Пример ежедневного запуска в 03:15:
flock запрещает запуск второго процесса, если предыдущий ещё работает.
Для каждого запуска создаётся новый UTC-каталог. Существующие файлы не перезаписываются.
iEX DB Backup не удаляет старые копии автоматически.
Следите за свободным местом и настройте собственную политику хранения.
Где находятся логи
Логи сохраняются в:
Пример:
Лог содержит:
выполненную команду;
выбранные профили;
путь к конфигурации;
путь к
.env;путь к результату;
прогресс;
размер файла;
SHA-256;
итоговый статус.
Пароли в лог не записываются.
Каталог логов должен иметь права:
Установите их при необходимости:
Логи создаются с правами:
Контрольное восстановление
Команда inspect проверяет SQL и manifest, но наиболее надёжная проверка — восстановление в отдельную пустую базу.
Не проверяйте восстановление на рабочей базе.
Создайте отдельную пустую базу, которая не используется приложением.
Создайте в FASTPANEL пустую PostgreSQL-базу:
Добавьте в db-backup.json профиль:
Проверьте подключение:
Выполните восстановление:
Параметры:
--profile restore_test
Пустая тестовая база
--from-profile main
Ожидаемый профиль исходной копии
--expect-tag before-update
Ожидаемая метка
--file
Путь к SQL-файлу
--require-manifest
Обязательная проверка manifest
--yes
Подтверждение восстановления
Если база содержит пользовательские объекты, команда остановится:
Инструмент не очищает базу автоматически.
Дополнительные базы PostgreSQL
Для дополнительной базы создайте отдельный профиль:
Каждый профиль должен использовать только один источник реквизитов:
"env": "main";"env": "pulse";"connection": {...}.
Одновременно указывать env и connection нельзя.
Запуск из другого каталога
Если команда запускается не из корня Backend, передайте абсолютные пути:
Для команды inspect Laravel-проект не требуется:
Хранение резервных копий
Пример базовой политики:
Ежедневная
7–14 последних копий
Еженедельная
4–8 последних копий
Перед обновлением
До подтверждения стабильной работы
Внешняя копия
Минимум одна актуальная проверенная
Критическая версия
По внутренней политике проекта
Не удаляйте предыдущую копию, пока:
новая копия не завершилась успешно;
рядом не создан manifest;
не выполнен
inspect;файлы не сохранены вне основного сервера.
Периодически выполняйте контрольное восстановление в отдельную тестовую базу.
Частые вопросы
Нужно ли останавливать сайт?
Нет. pg_dump создаёт транзакционно согласованный снимок PostgreSQL. Приложение может продолжать работу во время экспорта.
Можно ли запускать инструмент от root?
Для обычной работы используйте пользователя Backend-сайта. Это необходимо для правильных прав на резервные копии и логи.
Достаточно ли наличия файла .sql.gz?
Нет. Рядом должен находиться manifest, экспорт должен завершиться кодом 0, а inspect — без ошибок.
Можно ли переименовать резервную копию?
SQL и manifest связаны именем файла. Не переименовывайте только один из них.
Можно ли хранить копию только на сервере?
Не рекомендуется. Минимум одна актуальная проверенная копия должна находиться вне основного сервера.
Можно ли проверить восстановление на рабочей базе?
Нет. Для проверки создайте отдельную пустую базу PostgreSQL.
Нужно ли создавать копию Laravel Pulse?
Если Pulse используется, рекомендуется сохранять его вместе с основной базой через:
Если данные Pulse не нужны для восстановления проекта, профиль можно отключить.
Частые ошибки
Конфигурация требует права 0600
Сообщение:
Ошибка возникает, если конфигурация доступна другим пользователям.
Исправьте права:
Также проверьте, что файл не является символической ссылкой.
Не найден Laravel-проект
Сообщение:
Перейдите в корень Backend:
Либо передайте точные пути через --env и --config.
Версия pg_dump не соответствует PostgreSQL
Сообщение:
Проверьте версию:
Используйте бинарный файл PostgreSQL 18:
Резервная копия уже существует
Сообщение:
Используйте другую метку:
Не удаляйте старую копию до успешного создания и проверки новой.
Manifest не соответствует SQL
Сообщение:
Возможные причины:
SQL и manifest относятся к разным запускам;
один из файлов повреждён;
переименован только один файл;
SQL был изменён после экспорта.
Используйте исходную пару файлов.
Недостаточно свободного места
Проверьте диск:
Проверьте размер резервных копий:
При необходимости сохраните копию на другом диске:
Доступные команды
config-check
Проверить конфигурацию и подключения
export
Создать резервную копию
backup
Синоним export
inspect
Проверить SQL и manifest
import
Восстановить резервную копию
restore
Синоним import
Доступные параметры
config-check
--profile, --env, --config, --version
export / backup
--profile, --env, --config, --output, --compression, --tag, --version
inspect
--file, --profile, --require-manifest, --version
import / restore
--profile, --from-profile, --expect-tag, --file, --require-manifest, --yes, --version
Параметры одной операции нельзя передавать другой.
Например, --file нельзя использовать с командой export.
Рекомендации
Для большинства проектов рекомендуется:
использовать профили
mainиpulse;получать реквизиты из Laravel
.env;использовать
pg_dumpверсии 18;создавать копии в формате
.sql.gz;добавлять понятные метки через
--tag;проверять каждый SQL-файл через
inspect;хранить SQL и manifest вместе;
сохранять минимум одну копию вне сервера;
настроить ежедневный запуск через CRON;
периодически проверять восстановление;
контролировать свободное место на диске.
Перед Product Updates используйте метку:
Коротко
iEX DB Backup создаёт резервные копии основной базы PostgreSQL, Laravel Pulse и дополнительных баз.
Стандартный порядок:
перейдите в Backend-проект;
создайте
db-backup.json;выполните
config-check;запустите
export;проверьте каждый файл через
inspect;сохраните SQL и manifest вне сервера.
Основные команды:
Резервная копия считается готовой только после успешного inspect и сохранения файлов за пределами основного сервера.
Последнее обновление
Это было полезно?