Документация по восстановлению BookStack + MariaDB (Production)

Назначение документа

Данный документ описывает полный процесс восстановления
продакшн-инстанса BookStack, развернутого в Docker с отдельным
контейнером MariaDB.

Документ предназначен для быстрого восстановления системы в случае: -
смены домена - удаления контейнера БД - ошибки APP_KEY - ошибки 500
Internal Server Error - проблем с Docker-сетями - ошибок подключения к
базе данных

------------------------------------------------------------------------

Архитектура

Компоненты

- BookStack: lscr.io/linuxserver/bookstack
- MariaDB: lscr.io/linuxserver/mariadb
- Сеть: user-defined docker network (bookstack-net)
- Хранение данных: bind mount

Пути хранения

BookStack config: /home/med1f/docker/bookstack/data
MariaDB data: /home/med1f/docker/bookstack/data/databases

------------------------------------------------------------------------

Типовые проблемы и решения

------------------------------------------------------------------------

1. Контейнер MariaDB удалён

Проверка наличия данных

Проверить наличие файлов БД:

ls -la /home/med1f/docker/bookstack/data/databases

Критически важные файлы: - ibdata1 - ib_logfile0 - aria_log\* - папка
mysql/ - папка bookstack/

Если файлы присутствуют --- данные НЕ потеряны.

Восстановление контейнера MariaDB

docker run -d --name sweet_tanthep-main_app-1 -e
MYSQL_ROOT_PASSWORD=ROOT_PASSWORD -v
/home/med1f/docker/bookstack/data/databases:/var/lib/mysql -p 3306:3306
--restart unless-stopped lscr.io/linuxserver/mariadb:latest

------------------------------------------------------------------------

2. Ошибка: APP_KEY is missing

Причина: linuxserver/bookstack требует APP_KEY в ENV.

Генерация ключа

docker run -it --rm --entrypoint /bin/bash
lscr.io/linuxserver/bookstack:latest appkey

Скопировать сгенерированный ключ формата: base64:XXXXXXXXXXXXXXXX

------------------------------------------------------------------------

3. Ошибка 500 Internal Server Error

Чаще всего причина --- неправильные параметры БД.

Проверка файла .env

Файл расположен:

/home/med1f/docker/bookstack/data/www/.env

Проверить блок БД:

DB_HOST=sweet_tanthep-main_app-1 DB_DATABASE=bookstack
DB_USERNAME=bookstack DB_PASSWORD=Passwd55

Важно: В .env используется DB_USERNAME, а НЕ DB_USER.

После изменений:

docker restart bookstack

------------------------------------------------------------------------

4. Ошибка: Name does not resolve

Причина: Контейнеры находятся в default bridge сети. Default bridge НЕ
поддерживает DNS по именам контейнеров.

Решение --- создать user-defined сеть

docker network create bookstack-net

Подключить MariaDB:

docker network connect bookstack-net sweet_tanthep-main_app-1

Запускать BookStack в этой сети:

--network bookstack-net

------------------------------------------------------------------------

5. Ошибка: Access denied for user

Причина: Пользователь БД создан только для localhost или пароль не
совпадает.

Проверка:

docker exec -it sweet_tanthep-main_app-1 mysql -u root -p

SELECT user, host FROM mysql.user;

Если нет bookstack@%:

CREATE USER 'bookstack'@'%' IDENTIFIED BY 'Passwd55'; GRANT ALL
PRIVILEGES ON bookstack.\* TO 'bookstack'@'%'; FLUSH PRIVILEGES;

------------------------------------------------------------------------

Финальная рабочая команда запуска BookStack

docker run -d --name bookstack --network bookstack-net -e
APP_URL=https://wiki.anonix.org -e APP_KEY='base64:YOUR_KEY' -e
PUID=1000 -e PGID=1000 -v /home/med1f/docker/bookstack/data:/config -p
6875:80 --restart unless-stopped lscr.io/linuxserver/bookstack:latest

------------------------------------------------------------------------

Рекомендации для Production

1. Использовать docker-compose.
2. Использовать отдельную user-defined сеть.
3. Регулярно делать бэкап БД.
4. Делать бэкап папки /config.
5. Не использовать default bridge для production.

------------------------------------------------------------------------

Бэкап

Бэкап базы

docker exec sweet_tanthep-main_app-1 mysqldump -u bookstack -p bookstack
\> bookstack_backup.sql

Бэкап config

tar -czf bookstack_config_backup.tar.gz
/home/med1f/docker/bookstack/data

------------------------------------------------------------------------

Статус

Система полностью восстановлена. Данные сохранены. Сеть корректна.
Ошибки устранены.