Резервное копирование GitLab

Логотип GitLab: стилизованная голова лисицы

TL;DR

Резервные копии критичны для самоуправляемого GitLab: используйте встроенный скрипт для регулярных полноразмерных архивов, храните копии вне сервера (S3 или другое объектное хранилище), а также отдельно резервируйте конфигурационные и секретные файлы. Тестируйте восстановление и автоматизируйте удаление старых архивов или применяйте политики хранения в облаке.

Быстрые ссылки

Создание резервной копии по требованию
Что включено в резервную копию
Планирование резервных копий
Исключение типов данных
Резервное копирование в S3
Стратегия копирования (copy)
Не забудьте: конфигурация и секреты
Тестирование и восстановление
Рекомендации по безопасности и соответствию
Чек-листы и процедура восстановления

Организации, использующие самоуправляемый инстанс GitLab, полагаются на него для хранения исходного кода, управления проектами и операционных инструментов. Наличие надёжных резервных копий защищает данные при аппаратных сбоях, неудачных обновлениях сервера или злонамеренных действиях.

GitLab включает утилиту для создания полного архива данных установки. Архив можно восстановить на новом сервере с той же версией GitLab. Ниже показано, как настроить резервное копирование в локальную файловую систему или в S3-совместимое объектное хранилище. Эти шаги ориентированы на Omnibus-установки GitLab. Если инстанс собран из исходников, команды GitLab CLI нужно запускать с префиксом:

bundle exec rake

Если вы используете систему с Systemd вместо cron, уместно применить таймеры Systemd — в разделе планирования приведены примеры.

Создание резервной копии по требованию

Самый простой способ создать резервную копию — выполнить команду создания по запросу в shell:

sudo gitlab-backup create

Эта команда работает в GitLab 12.2 и новее. В старых версиях используйте альтернативу:

sudo gitlab-rake gitlab:backup:create

Резервная копия сохраняется как tar-архив в каталоге, указанном в конфигурации GitLab. Omnibus-установки по умолчанию используют /var/opt/gitlab/backups. Каждое архивное имя содержит временную метку создания и версию GitLab.

Важно: команда создает полный экспорт поддерживаемых GitLab-объектов. Для больших инстансов это может занять значительное время и место.

Что включено в резервную копию

Утилита резервного копирования GitLab экспортирует данные, созданные пользователями на вашем инстансе. Это включает:

Все содержимое базы данных GitLab (проекты, группы, пользователи, issues, merge requests, CI-пайплайны и т. д.).
Все on-disk Git-репозитории.
Загруженные вложения (uploads), логи CI/CD job’ов, GitLab Pages.
Docker-образы, сохранённые во встроенном реестре контейнеров (container registry).

Не включены в стандартный архив:

Пакеты, добавленные в регистрации пакетов GitLab (Package Registry) — их восстановление требует отдельного хранения или перекомпиляции.

Если вам нужно восстанавливать пакеты без ручной сборки, настройте их хранение во внешнем объектном хранилище.

Планирование резервных копий

GitLab не содержит встроенного планировщика резервных копий — настройте cron или systemd-таймер на сервере.

Пример задания cron для root (ежедневно в 21:00):

sudo crontab -e

# Добавьте:
0 21 * * * /opt/gitlab/bin/gitlab-backup create CRON=1

Переменная окружения CRON=1 отключает прогресс-бар, чтобы не получать письма от cron.

Важно управлять хранением архивов: по умолчанию cron будет оставлять все архивы навсегда. Для очистки локальных архивов используйте опцию backup_keep_time в /etc/gitlab/gitlab.rb:

gitlab_rails['backup_keep_time'] = 432000

Значение задаётся в секундах — в примере 432000 = 5 дней. После изменения файла выполните:

sudo gitlab-ctl reconfigure

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

Альтернативы cron:

Systemd timers — предпочтительны на современных системах, даёт лучшую интеграцию с логами и зависимостями.
Планировщик задач централизованного оркестра (Ansible Tower, Rundeck) для управляемых сред.

Пример systemd-timer и сервиса (упрощённо):

# /etc/systemd/system/gitlab-backup.service
[Unit]
Description=Создать резервную копию GitLab

[Service]
Type=oneshot
ExecStart=/opt/gitlab/bin/gitlab-backup create CRON=1

# /etc/systemd/system/gitlab-backup.timer
[Unit]
Description=Таймер резервного копирования GitLab

[Timer]
OnCalendar=*-*-* 21:00:00
Persistent=true

[Install]
WantedBy=timers.target

После создания активируйте и включите таймер:

sudo systemctl daemon-reload
sudo systemctl enable --now gitlab-backup.timer

Стратегии хранения и оценки объёма

Перед настройкой хранения оцените требуемое пространство:

Оцените размер самой большой категории данных (репозитории, реестр контейнеров, uploaded files).
Для стратегии copy потребуется дополнительное место, равное размеру самой большой категории.
Для потоковой стратегии (по умолчанию) достаточно пространства для финального архива плюс небольшие временные файлы.

Рассмотрите политики хранения:

Локальное хранение с ротацией (backup_keep_time).
Внешнее объектное хранилище (S3) — лучше для долговременного и геоизбыточного хранения.
Гибрид: краткосрочные резервные копии локально + ежедневная отправка в S3.

Факторы выбора: скорость восстановления, стоимость хранения, пропускная способность сети, требования к соответствию и конфиденциальности.

Исключение типов данных

Можно исключать отдельные типы данных, задав переменную окружения SKIP со списком через запятую. Опции поддерживаемых типов перечислены в документации GitLab.

Пример: исключить содержимое реестра контейнеров:

sudo gitlab-backup create SKIP=registry

Исключение registry часто существенно уменьшает размер архива и ускоряет процесс. Для команд, которые могут воссоздать образы по Dockerfile, это приемлемо.

Замечание: исключённые типы данных не будут восстановлены из архива. Оцените риски и протестируйте восстановление без этих данных.

Резервное копирование в S3

GitLab может автоматически загружать архивы в S3-совместимое хранилище. В /etc/gitlab/gitlab.rb раскомментируйте и заполните:

gitlab_rails['backup_upload_connection'] = {
  "provider" => "AWS",
  "region" => "eu-west-1",
  "aws_access_key_id" => "access_key",
  "aws_secret_access_key" => "secret_key",
  # "endpoint" => "https://..."
}

gitlab_rails['backup_upload_remote_directory'] = 'gitlab-backups'

provider: обычно AWS, но для S3-совместимых сервисов указывайте endpoint.
region: стандартный идентификатор участка (AWS) или пропустите для некоторых провайдеров.
endpoint: обязательный для локальных совместимых сервисов (MinIO, Ceph, DigitalOcean Spaces и т. п.).

Выполните reconfigure:

sudo gitlab-ctl reconfigure

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

Советы по S3-хранению:

Используйте отдельный бакет или префикс для бэкапов.
Включите серверную шифровку (SSE) на стороне хранилища или добавьте клиентское шифрование перед загрузкой.
Создайте IAM-пользователя с минимально необходимыми правами (putObject, getObject, listBucket, deleteObject) и задайте ему краткоживущие ключи.
Настройте lifecycle policies для автоматического удаления или перехода на дешёвое хранилище (Glacier, Coldline) через заданное время.
Включите версионирование на бакете, если хотите иметь возможность восстановить предыдущие версии файлов конфигурации, но это увеличит используемое пространство.

Ограничения:

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

Стратегия копирования (copy)

По умолчанию GitLab формирует tar-архив, читая данные напрямую. В очень активных инстансах это может приводить к ошибкам “file changed as we read it”. Решение — STRATEGY=copy:

sudo gitlab-backup create STRATEGY=copy

Поведение copy:

Все данные сначала копируются во временную директорию, затем архивируются оттуда.
Исключает ошибки чтения «вживую», но требует дополнительного места на диске и увеличивает время операции.
GitLab выполняет бэкап поэтапно по типам данных, поэтому необходимо дополнительное место, равное размеру крупнейшего типа данных, а не сумме.

Проверяйте свободное место и планируйте windows резервирования, чтобы избежать одновременных пиков использования диска и операции копирования.

Не забудьте: конфигурация и секреты

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

/etc/gitlab/gitlab.rb — основной конфигурационный файл GitLab. Содержит настройки внешних сервисов, URL’ы, интеграции.
/etc/gitlab/gitlab-secrets.json — содержит ключи шифрования базы данных, секреты для двухфакторной аутентификации и другие уникальные данные. Потеря этого файла может сделать восстановление невозможным.

Рекомендуется иметь отдельный cron или процесс, который периодически копирует эти файлы в защищённое хранилище. Пример простого скрипта для копирования в S3 (используя aws-cli):

#!/bin/bash
set -e
TIMESTAMP=$(date -u +%Y%m%dT%H%M%SZ)
DEST=s3://gitlab-backups/configs/$TIMESTAMP/
aws s3 cp /etc/gitlab/gitlab.rb $DEST
a ws s3 cp /etc/gitlab/gitlab-secrets.json $DEST

Шифруйте и ограничивайте доступ к местам хранения этих файлов, так как они содержат чувствительные данные.

Тестирование и восстановление

Резервное копирование бесполезно без регулярного тестирования восстановления. Рекомендуемая процедура проверки:

Восстановление на отдельный тестовый сервер с такой же версией GitLab.
Проверка целостности архива: распаковка tar и проверка наличия ожидаемых файлов.
Проверка функциональности: логин пользователей, просмотр репозиториев, CI-пайплайны, страницы проектов.
Проверка восстановления контейнерного реестра (если он был в бэкапе).

Шаги восстановления на тестовой системе (упрощённо):

Скопируйте архив в /var/opt/gitlab/backups (или укажите свой путь).
Обновите конфигурацию и секреты (/etc/gitlab/gitlab.rb и gitlab-secrets.json) предварительно.
Остановите службы GitLab (по инструкции для вашей установки).
Выполните команду восстановления:

sudo gitlab-backup restore BACKUP=TIMESTAMP_XXX

После восстановления выполните reconfigure и перезапустите сервисы:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

Не забудьте восстановить версии пакетов и внешние хранилища, если они требуются для корректной работы.

Проверка целостности архива

Рекомендуется проверять целостность бэкапов при их создании и периодически после загрузки в S3:

Локально: распаковка в временную директорию и проверка структуры.
В S3: проверить, что объект успешно загружен и доступен для скачивания.
Сравнить контрольные суммы (например, sha256) исходных файлов и распакованных.

Пример получения sha256 для архива:

sha256sum /var/opt/gitlab/backups/.tar

Для автоматизации можно записывать и хранить контрольные суммы вместе с метаданными архива.

Процедура восстановления после сбоя (runbook)

Краткий план действий при полном выходе из строя узла GitLab:

Оцените ситуацию и выберите целевой сервер для восстановления.
Установите ту же версию GitLab, что и в момент создания резервной копии.
Разверните базовую систему и установите необходимые зависимости.
Восстановите /etc/gitlab/gitlab.rb и gitlab-secrets.json из защищённого хранилища.
Скопируйте нужный архив в каталог бэкапов на целевой сервер.
Остановите GitLab (если запущен) и выполните команду gitlab-backup restore.
Выполните gitlab-ctl reconfigure и перезапустите сервисы.
Выполните проверку работоспособности (логин, репозиторий, CI, registry).
Сообщите заинтересованным сторонам о восстановлении и проведите пост-инцидентный анализ.

Критерии приёмки: система доступна, данные (проекты, issues) соответствуют ожидаемому состоянию, CI-пайплайны и реестр функционируют, пользователи могут аутентифицироваться.

Отладка распространённых ошибок

“file changed as we read it” — используйте STRATEGY=copy или временно приостановите активность записи.
Ошибки доступа к S3 — проверьте ключи, права IAM и endpoint.
Недостаточно дискового пространства — оцените размер данных и примените copy-стратегию только при наличии места.
Отсутствие восстановленных пакетов — пакеты не входят в стандартный бэкап, храните их отдельно.

Чек-листы по ролям

Администратор GitLab:

Настроить автоматическое создание бэкапов (cron или systemd).
Проверить и зашифровать хранение конфигурационных и секретных файлов.
Настроить мониторинг свободного дискового пространства.
Планировать и проводить тесты восстановления регулярно.

Оператор резервного копирования:

Контролировать успешность заданий бэкапа (логи, exit-коды).
Периодически проверять целостность случайных архивов.
Управлять политиками хранения в S3.

Команда безопасности:

Контролировать доступ к ключам и бакетам.
Обеспечивать шифрование данных в покое и при передаче.
Проводить аудит доступа к /etc/gitlab и к резервным хранилищам.

Политика тестирования и критерии приёмки

Минимум: восстановление тестовой копии раз в квартал.
Полная проверка: восстановление в изолированной сети и проверка функциональности.
Критерии приёмки: совпадение ключевых сущностей проекта (число репозиториев, набор пользователей, открытые issues) и работоспособность CI.

Риск-матрица и mitigations

Риск	Вероятность	Влияние	Митигирующие меры
Потеря gitlab-secrets.json	Низкая	Критическая	Резервное копирование в зашифрованное хранилище, офлайн-копии, ограниченный доступ
Повреждение архивов на локальном диске	Средняя	Высокое	Дублирование в S3, контрольные суммы, регулярные тесты восстановления
Неправильные IAM-права	Средняя	Высокое	Принцип наименьших привилегий, аудит доступа
Большие задержки при загрузке в S3	Высокая	Средняя	Планирование окон загрузки, многочастичная загрузка, использование WAN-оптимизации

Безопасность и соответствие

Шифруйте конфигурационные и секретные файлы в покое и при передаче.
Ограничьте доступ к ключам и бакетам на уровне IAM.
Для региональных требований соответствия храните копии в одобренных регионах.
Для GDPR: документируйте, какие личные данные содержатся в бэкапах и как долго они хранятся. Обеспечьте процессы удаления данных по запросу, если это применимо.

Совместимость и миграции

Omnibus vs исходники: Omnibus предоставляет команды gitlab-backup и gitlab-ctl. При сборке из исходников команды нужно запускать через bundle exec rake.
При смене версии GitLab: восстанавливайте архивы только на тот же минорный релиз или внимательно читайте release notes на предмет несовместимостей.

Альтернативные подходы

Репликация базы и файлов в реальном времени на второй хост (подходит для RTO близкого к нулю, но сложнее в управлении).
Использование внешних систем резервного копирования уровня блоков/файлов для снапшотов томов (быстро, но может не захватить состояния GitLab консистентно без координации).
Комбинация: периодические полные бэкапы GitLab + репликация логов для быстрой подстановки.

Мини-методология выбора стратегии

Определите RTO (время восстановления) и RPO (точку восстановления).
Оцените объёмы данных: репозитории, реестр, uploaded files.
Выберите хранение: локально + S3 для долговременного хранения.
Настройте автоматизацию и тестирование восстановления.
Документируйте процесс и обновляйте после изменений в инфраструктуре.

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

Простой cron-скрипт с логированием и уведомлением при ошибке:

#!/bin/bash
LOGFILE=/var/log/gitlab-backup.log
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
{
  echo "=== Backup started $TIMESTAMP ==="
  /opt/gitlab/bin/gitlab-backup create CRON=1 || { echo "Backup failed"; exit 1; }
  echo "=== Backup finished $(date -u +%Y-%m-%dT%H:%M:%SZ) ==="
} >> $LOGFILE 2>&1

Визуальное принятие решения

flowchart TD
  A[Нужен бэкап GitLab?] --> B{Требуется быстрое восстановление}
  B -- Да --> C[Репликация и снапшоты]
  B -- Нет --> D[Регулярные полные бэкапы GitLab]
  D --> E{Хранение локально или в облаке}
  E -- Локально --> F[backup_keep_time и ротация]
  E -- В облаке --> G[S3 + lifecycle, шифрование]
  C --> H[Мониторинг репликации]
  F --> I[Тесты восстановления ежемесячно]
  G --> I

FAQ

В: Нужно ли бэкапить registry?

О: Если реестр содержит критичные и нереконструируемые образы, да. Если образы можно воссоздать из Dockerfile, возможно, можно исключить registry, чтобы сократить размер бэкапа.

В: Сколько места нужно для STRATEGY=copy?

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

В: Как часто тестировать восстановление?

О: Минимум раз в квартал; для критичных систем — ежемесячно.

Итог

Резервное копирование GitLab — это не только запуск команды. Планируйте хранение, шифрование и ротацию, включайте конфигурационные и секретные файлы в процесс, автоматизируйте и регулярно тестируйте восстановление. Комбинируйте локальные копии и внешнее хранилище для оптимального баланса восстановления и затрат.

Резервное копирование GitLab — руководство