.. _administration: Администрирование ================= Раздел описывает операции сопровождения развёртывания, не относящиеся к повседневной работе с моделью в конфигураторе. .. _administration_docker_runtime_backup: Резервное копирование всех работающих 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`` оставляет контейнеры работающими, но архив может оказаться логически неконсистентным. Создание архива ~~~~~~~~~~~~~~~ Запускать из корня репозитория: .. code:: sh ./admin_scripts/docker/running_containers_backup.sh Основные параметры: .. list-table:: :header-rows: 1 :widths: 26 54 20 * - Параметр - Назначение - По умолчанию * - ``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`` Пример с явным именем архива: .. code:: sh ./admin_scripts/docker/running_containers_backup.sh \ --archive_name=project_runtime_backup.tar.gz Восстановление ~~~~~~~~~~~~~~ .. code:: sh ./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. Параметры восстановления: .. list-table:: :header-rows: 1 :widths: 26 54 20 * - Параметр - Назначение - По умолчанию * - ``archive`` - **Обязательный.** Путь к архиву ``running_containers_backup.sh``. - *(нет)* * - ``helper_image`` - Образ для очистки и распаковки хранилищ. - ``alpine:3.20`` * - ``assume_yes`` - ``1`` — перезаписывать существующие хранилища и контейнеры без вопросов. - ``0`` * - ``skip_stop`` - ``1`` — не останавливать контейнеры, использующие перезаписываемое хранилище; если хранилище занято, восстановление этого шага завершится ошибкой. - ``0`` * - ``skip_containers`` - ``1`` — восстановить только images и хранилища, контейнеры не запускать. - ``0`` .. warning:: Архив содержит Docker metadata, переменные окружения контейнеров и данные bind mounts. Храните его как конфиденциальный файл. .. note:: Скрипт восстановления не заменяет исходные compose-файлы. Он нужен для разворачивания сохранённого runtime-состояния. Сложные параметры Docker networks (например, статические IPAM-настройки) сохраняются в metadata, но автоматически восстанавливаются только имена сетей. .. _administration_ldap_backup: Резервное копирование и восстановление 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`` — справка выводится из любого каталога, проверка корня не выполняется. Пример: .. code:: sh 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`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 22 58 20 * - Параметр - Назначение - По умолчанию * - ``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`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 22 58 20 * - Параметр - Назначение - По умолчанию * - ``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/``): .. code:: sh ./admin_scripts/ldap/ldap_volume_backup.sh С явными параметрами: .. code:: 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 Восстановление без запроса подтверждения: .. code:: sh 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`` и абсолютный путь на хосте. .. warning:: Убедитесь, что архив соответствует той же развёртке (образ и схема LDAP), что и целевое окружение. Конфигурация ``slapd`` в образе задаётся при сборке; в типовом compose в том сохраняется прежде всего содержимое ``/var/lib/ldap``.