Бэкап и восстановление Directus

MAATRIX

Directus — не самостоятельная база данных, а слой поверх вашей существующей SQL-базы: коллекции, поля и права он хранит прямо в ней же, в системных таблицах directus_*, вперемешку с вашими рабочими данными. Из-за этого «бэкапнуть Directus» — это не одна команда, а как минимум три независимых слоя: сама база, загруженные файлы и настройки окружения. Если бэкапить только одно из трёх, восстановление на новом сервере закончится либо пустой админкой, либо битыми ссылками на изображения. Ниже — рабочая схема, которую можно поставить на cron и не думать об этом до дня X.

Что реально нужно бэкапить в Directus

Директус разворачивается обычно связкой из двух контейнеров: сам directus/directus и база данных (чаще PostgreSQL, реже MySQL/MariaDB). Плюс опционально Redis для кэша и очередей — его бэкапить не нужно, это эфемерное хранилище.

Что действительно критично сохранить:

Отдельно про KEY и SECRET — это не просто пароли для галочки. SECRET используется для подписи JWT-токенов сессий, а некоторые поля (например, настройки SSO-провайдеров) Directus хранит в базе в зашифрованном виде, завязанном на эти значения. Если восстановить дамп базы на новый сервер с другим KEY/SECRET, часть зашифрованных настроек станет нечитаемой, а все активные сессии пользователей разлогинятся. Правило простое: .env бэкапится вместе с базой, одним архивом, без исключений.

Если база у вас на отдельном VPS, посмотрите установку PostgreSQL на сервере — там про базовую настройку и права пользователей, которые пригодятся и здесь.

Бэкап базы данных PostgreSQL

Директус нормально переживает как логический дамп (pg_dump), так и физический (base backup), но для регулярных бэкапов почти всегда достаточно логического — он компактнее и переносится между версиями PostgreSQL спокойнее.

Если Postgres в Docker-контейнере рядом с Directus:

docker exec -t directus-db pg_dump \
  -U directus -d directus --format=custom \
  > /backups/directus/db_$(date +%F_%H%M).dump

Формат --format=custom даёт сжатие «из коробки» и позволяет восстанавливать выборочно (например, только структуру или только конкретную таблицу), в отличие от плоского SQL. Если хотите читаемый текстовый дамп для диффа между версиями — уберите --format=custom, получите .sql, но он будет заметно тяжелее.

Проверьте, что дамп не пустой и не битый, сразу после снятия:

pg_restore --list /backups/directus/db_2026-08-30_0300.dump | head -20

Если команда падает с ошибкой — бэкап нерабочий, и лучше узнать это сразу, а не в момент аварии.

Для MySQL/MariaDB-варианта Directus логика та же, но команда другая:

docker exec directus-db mysqldump \
  -u directus -p"$DB_PASSWORD" directus \
  --single-transaction --routines \
  > /backups/directus/db_$(date +%F).sql

Флаг --single-transaction важен: без него на активной базе дамп может получиться несогласованным, если в момент снятия шла запись.

Бэкап загруженных файлов

Файлы (assets) Directus хранит либо локально на диске, либо во внешнем S3-совместимом хранилище — это задаётся переменной STORAGE_LOCATIONS и связанными STORAGE_<LOCATION>_* в .env.

Локальное хранилище. Файлы лежат в volume, смонтированном в /directus/uploads внутри контейнера. Бэкапится как обычный tar-архив:

docker run --rm \
  -v directus_uploads:/data \
  -v /backups/directus:/backup \
  alpine tar czf /backup/uploads_$(date +%F).tar.gz -C /data .

Плюс локального хранилища — простота. Минус — при росте медиатеки в десятки гигабайт полный tar каждую ночь становится дорогим по времени и месту. В этом случае лучше переключиться на инкрементальный инструмент вроде restic или rclone с sync-режимом, а не гонять полный архив.

S3/MinIO хранилище. Если Directus настроен писать файлы напрямую в MinIO или внешний S3 (это частый выбор для продакшена — снимает нагрузку с диска сервера и упрощает горизонтальное масштабирование), бэкапить сам Directus-сервер в части файлов не нужно вообще — нужно бэкапить бакет отдельно, штатными средствами хранилища. Про разворачивание своего S3-совместимого хранилища есть отдельный разбор: MinIO в Docker Compose. Если бакет живёт там же на вашем сервере — это тоже точка отказа, и её нужно копировать наружу так же, как базу.

Schema snapshot — второй, независимый слой бэкапа

У Directus есть встроенный механизм экспорта структуры — коллекций, полей, связей и прав — в один YAML-файл, отдельно от данных:

docker exec directus npx directus schema snapshot ./snapshot.yaml
docker cp directus:/directus/snapshot.yaml /backups/directus/schema_$(date +%F).yaml

Это не замена дампу базы, а дополнение к нему. Разница в применении: дамп базы восстанавливает всё как было, байт в байт, вместе с данными. Snapshot восстанавливает только структуру — его применяют командой directus schema apply ./snapshot.yaml на чистой базе, когда нужно поднять новое окружение с той же конфигурацией коллекций, но без переноса самих записей (staging-копия, локальная разработка, тестовый сервер).

Держать snapshot в git-репозитории рядом с кодом расширений — хорошая практика: изменения структуры коллекций становятся ревьюабельными через diff, а не невидимыми правками через админку, о которых через полгода никто не вспомнит, почему они появились.

Автоматизация: единый скрипт и расписание

Собираем всё в один bash-скрипт, который снимает базу, файлы и snapshot синхронизированно (в один момент времени, чтобы состояния не разъезжались) и складывает в датированную папку:

#!/bin/bash
set -euo pipefail

DEST="/backups/directus/$(date +%F_%H%M)"
mkdir -p "$DEST"

# 1. База данных
docker exec -t directus-db pg_dump \
  -U directus -d directus --format=custom \
  > "$DEST/db.dump"

# 2. Файлы (если хранилище локальное)
docker run --rm \
  -v directus_uploads:/data \
  -v "$DEST":/backup \
  alpine tar czf /backup/uploads.tar.gz -C /data .

# 3. Schema snapshot
docker exec directus npx directus schema snapshot /tmp/snapshot.yaml
docker cp directus:/tmp/snapshot.yaml "$DEST/snapshot.yaml"

# 4. Конфигурация
cp /opt/directus/.env "$DEST/env.backup"

# 5. Ротация — храним 14 последних снимков
find /backups/directus -maxdepth 1 -mtime +14 -type d -exec rm -rf {} \;

echo "Backup done: $DEST"

Ставим в cron на ночное время, когда нагрузка минимальна:

0 3 * * * /opt/scripts/directus-backup.sh >> /var/log/directus-backup.log 2>&1

Локальная копия на том же сервере не защищает от отказа диска или самого сервера — это база гигиены, не полноценный бэкап. Финальный шаг — синхронизация папки /backups/directus во внешнее хранилище: другой сервер, S3-бакет или репозиторий restic с шифрованием и дедупликацией. Если ещё не выбрали инструмент, посмотрите restic в Docker Compose — он умеет инкрементальные снимки с шифрованием «из коробки» и хорошо ложится поверх такого скрипта одной командой restic backup /backups/directus.

Восстановление Directus из бэкапа

Порядок действий на новом сервере — важна именно эта последовательность, не в разнобой:

1. Поднимите тот же образ и версию Directus. Это критично: у Directus есть встроенная система миграций (directus_migrations), привязанная к версии. Если восстановить дамп от Directus 11.x в контейнер с более новой версией, при первом старте автоматически запустятся миграции схемы — обычно безопасно, но необратимо и без предупреждения. Если хотите сохранить возможность отката — сначала поднимите точно ту же версию, что была на момент бэкапа, и только потом решайте, обновляться ли.

services:
  directus:
    image: directus/directus:11.7.2   # та же версия, что в бэкапе

2. Восстановите .env до запуска контейнеров — особенно KEY и SECRET из бэкапа, иначе получите проблему с зашифрованными полями, описанную выше.

3. Поднимите пустую базу и накатите дамп:

docker compose up -d directus-db
docker exec -i directus-db pg_restore \
  -U directus -d directus --clean --if-exists \
  < /backups/directus/2026-08-30_0300/db.dump

4. Восстановите файлы в volume:

docker run --rm \
  -v directus_uploads:/data \
  -v /backups/directus/2026-08-30_0300:/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/uploads.tar.gz -C /data"

5. Запустите Directus и проверьте логи на предмет ошибок миграций:

docker compose up -d directus
docker compose logs -f directus

6. Сверьте контрольные точки — зайдите в админку, откройте пару коллекций с файлами, проверьте, что превью изображений грузятся (это подтверждает, что и база, и volume файлов синхронизировались правильно), и что кастомные роли/права на месте.

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

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