Администрирование

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

Резервное копирование всех работающих Docker-контейнеров

Для переноса или аварийного восстановления всей текущей Docker-развёртки предусмотрены shell-скрипты в admin_scripts/docker/:

running_containers_backup.sh — создаёт единый .tar.gz архив всех контейнеров из docker ps и их хранилищ;
running_containers_restore.sh — загружает образы, восстанавливает хранилища и запускает контейнеры из архива.

Скрипты работают по текущему состоянию Docker, а не по списку compose-файлов. Поэтому в архив попадают не только контейнеры Пересвета, но и дополнительные контейнеры, запущенные в рамках проекта.

Что попадает в архив

running_containers_backup.sh сохраняет:

committed-образы всех работающих контейнеров;
данные всех Docker volumes, смонтированных в эти контейнеры;
данные bind mount-путей с хоста (если не задан --no_bind_mounts=1);
docker inspect metadata контейнеров, образов, volumes и сетей;
сгенерированный sh-фрагмент с командами повторного запуска контейнеров.

По умолчанию перед копированием хранилищ контейнеры останавливаются и после копирования запускаются обратно. Это уменьшает риск неконсистентного архива для PostgreSQL, LDAP, RabbitMQ и других сервисов с записью на диск. Режим --skip_stop=1 оставляет контейнеры работающими, но архив может оказаться логически неконсистентным.

Создание архива

Запускать из корня репозитория:

./admin_scripts/docker/running_containers_backup.sh

Основные параметры:

Параметр	Назначение	По умолчанию
`backup_dir`	Каталог для итогового архива: относительно корня репозитория или абсолютный путь.	`backups/docker_runtime`
`archive_name`	Имя итогового `.tar.gz`.	`docker_runtime_<дата>.tar.gz`
`helper_image`	Образ для архивации Docker volumes.	`busybox:stable`
`skip_stop`	`1` — не останавливать контейнеры перед копированием хранилищ.	`0`
`no_bind_mounts`	`1` — не включать bind mount-пути с хоста.	`0`
`keep_committed_images`	`1` — оставить временные committed-образы после создания архива.	`0`

Пример с явным именем архива:

./admin_scripts/docker/running_containers_backup.sh \
  --archive_name=project_runtime_backup.tar.gz

Восстановление

./admin_scripts/docker/running_containers_restore.sh \
  --archive=backups/docker_runtime/project_runtime_backup.tar.gz

При восстановлении:

images загружаются через docker load;
отсутствующие Docker volumes создаются автоматически;
если Docker volume уже существует, скрипт спрашивает, перезаписать его содержимое или пропустить восстановление этого volume;
если bind mount-путь уже существует, скрипт спрашивает, перезаписать его содержимое или пропустить восстановление этого bind mount;
пользовательские Docker networks из архива создаются по имени, если их ещё нет;
контейнеры запускаются из committed-образов с сохранёнными mount, port, hostname, restart policy и network-параметрами, которые удалось восстановить через Docker CLI.

Параметры восстановления:

Параметр	Назначение	По умолчанию
`archive`	Обязательный. Путь к архиву `running_containers_backup.sh`.	(нет)
`helper_image`	Образ для очистки и распаковки хранилищ.	`alpine:3.20`
`assume_yes`	`1` — перезаписывать существующие хранилища и контейнеры без вопросов.	`0`
`skip_stop`	`1` — не останавливать контейнеры, использующие перезаписываемое хранилище; если хранилище занято, восстановление этого шага завершится ошибкой.	`0`
`skip_containers`	`1` — восстановить только images и хранилища, контейнеры не запускать.	`0`

Предупреждение

Архив содержит Docker metadata, переменные окружения контейнеров и данные bind mounts. Храните его как конфиденциальный файл.

Примечание

Скрипт восстановления не заменяет исходные compose-файлы. Он нужен для разворачивания сохранённого runtime-состояния. Сложные параметры Docker networks (например, статические IPAM-настройки) сохраняются в metadata, но автоматически восстанавливаются только имена сетей.

Резервное копирование и восстановление OpenLDAP

Каталог OpenLDAP в контейнере хранит рабочие данные в каталоге /var/lib/ldap. В файлах Docker Compose этот путь монтируется во внешний том Docker (или в каталог на хосте при bind mount):

docker/compose/docker-compose.ldap.one_app.yml — том ldap_data_one_app;
docker/compose/docker-compose.ldap.yml — том ldap_data.

Имя тома в среде Docker обычно имеет вид <имя_проекта_compose>_<ключ_тома>, например compose_ldap_data_one_app. Проверка: docker volume ls | grep ldap.

Скрипты расположены в admin_scripts/ldap/:

ldap_volume_backup.sh — создание архива;
ldap_volume_restore.sh — восстановление из архива;
resolve_ldap_storage.py — вспомогательный модуль для shell-скриптов: по compose_file вызывается docker compose … config --format json и определяется монтирование /var/lib/ldap у сервиса (именованный том или bind mount); требуются docker и python3 в PATH.

Запуск из корня репозитория

Скрипты ldap_volume_backup.sh и ldap_volume_restore.sh нужно запускать из корня репозитория (того каталога, где лежат docker/compose/, admin_scripts/ и т.д.). Текущий каталог проверяется по pwd -P и должен совпадать с корнем, вычисленным по расположению скрипта. При запуске из другого каталога скрипт завершится с сообщением об ошибке. Исключение: вызов только -h или --help — справка выводится из любого каталога, проверка корня не выполняется.

Пример:

cd /путь/к/peresvet
./admin_scripts/ldap/ldap_volume_backup.sh

Формат параметров

Все параметры задаются в виде --имя=значение; имена только в нижнем регистре. Исключение: справка — -h или --help (без =), только отдельным аргументом.

Логические значения для флагов skip_stop, skip_compose_stop, assume_yes: истина — 1, true, yes, YES; всё остальное интерпретируется как ложь (в т.ч. 0 и пустая строка).

Приоритет выбора цели бэкапа/восстановления: если задан ldap_docker_volume, используется именованный Docker-том (полное имя); иначе, если задан ldap_data_dir, используется каталог на хосте; иначе цель определяется по compose_file (сервис ldap_service, монтирование /var/lib/ldap).

Параметры: `ldap_volume_backup.sh`

Параметр	Назначение	По умолчанию
`compose_file`	Путь к compose-файлу с сервисом LDAP: относительно корня репозитория или абсолютный. По нему вызывается `docker compose` и при отсутствии переопределений ниже — разбор тома/bind.	`docker/compose/docker-compose.ldap.one_app.yml`
`compose_project_name`	Имя проекта Docker Compose (флаг `-p`). Пустое значение: как у `docker compose` без `-p` (в т.ч. переменная окружения `COMPOSE_PROJECT_NAME`, если задана снаружи).	(пусто)
`ldap_service`	Имя сервиса в compose, у которого ищется том на `/var/lib/ldap`.	`ldap`
`backup_dir`	Каталог для создаваемых `.tar.gz`: относительно корня репозитория или абсолютный путь.	`backups/ldap`
`ldap_docker_volume`	Принудительно: полное имя Docker-тома с данными LDAP (игнорируется разбор compose для выбора цели).	(пусто)
`ldap_data_dir`	Принудительно: каталог на хосте с данными LDAP (bind mount). Не используется, если задан `ldap_docker_volume`.	(пусто)
`backup_helper_image`	Образ для контейнера `docker run`, в котором выполняется `tar` при снимке именованного тома.	`busybox:stable`
`skip_stop`	При `1`: не останавливать контейнеры, использующие том, перед бэкапом (имеет смысл в сочетании с `skip_compose_stop=1`; риск неконсистентного архива).	`0`
`skip_compose_stop`	При `1`: не вызывать `docker compose stop/start` для `ldap_service`. Для именованного тома тогда перед снимком выполняется остановка контейнеров с этим томом (если не `skip_stop=1`).	`0`

Параметры: `ldap_volume_restore.sh`

Параметр	Назначение	По умолчанию
`archive`	Обязательный. Путь к файлу архива `.tar.gz`: относительно корня репозитория или абсолютный.	(нет)
`compose_file`	Как в бэкапе: для `docker compose stop/start` и для разбора цели.	`docker/compose/docker-compose.ldap.one_app.yml`
`compose_project_name`	Как в бэкапе (флаг `-p` у `docker compose`).	(пусто)
`ldap_service`	Как в бэкапе.	`ldap`
`ldap_docker_volume`	Как в бэкапе: принудительный том для распаковки архива.	(пусто)
`ldap_data_dir`	Как в бэкапе: принудительный каталог на хосте.	(пусто)
`restore_helper_image`	Образ для `docker run` при очистке точки монтирования и `tar xzf` (нужны `find` и `tar`).	`alpine:3.20`
`assume_yes`	При `1`: не спрашивать подтверждение перед перезаписью данных.	`0`
`skip_stop`	При `1` и режиме тома: если контейнеры всё ещё используют том, скрипт завершится ошибкой (запись без остановки запрещена).	`0`
`skip_compose_stop`	При `1`: не вызывать `docker compose stop/start`; для тома перед восстановлением останавливаются контейнеры с этим томом (если не `skip_stop=1`).	`0`

Примеры

Создание бэкапа (остановка ldap через compose по умолчанию, архив в backups/ldap/):

./admin_scripts/ldap/ldap_volume_backup.sh

С явными параметрами:

cd /путь/к/peresvet
./admin_scripts/ldap/ldap_volume_backup.sh \
  --compose_file=docker/compose/docker-compose.ldap.one_app.yml \
  --compose_project_name=myproj \
  --backup_dir=backups/ldap

Восстановление без запроса подтверждения:

cd /путь/к/peresvet
./admin_scripts/ldap/ldap_volume_restore.sh \
  --assume_yes=1 \
  --archive=backups/ldap/ИМЯ_АРХИВА.tar.gz

Вспомогательный `resolve_ldap_storage.py`

Основной интерфейс для администратора — shell-скрипты выше. Python-скрипт вызывается ими автоматически. При ручной отладке аргументы позиционные (не в формате --имя=значение):

compose_file — абсолютный или относительный путь к compose-файлу;
compose_project_name (необязательно) — имя проекта для docker compose -p; пустая строка означает вызов без -p;
ldap_service (необязательно) — имя сервиса, по умолчанию ldap.

Переменная окружения RESOLVE_CWD: рабочий каталог для docker compose (оболочечные скрипты передают корень репозитория).

Стандартный вывод: одна строка из двух полей, разделённых символом табуляции: режим volume и полное имя Docker-тома, либо режим bind и абсолютный путь на хосте.