BookStack

Обзор

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

Страницы редактируются визуально или в Markdown. Есть английский и русский интерфейс; с компьютера или телефона заходят через браузер, нативных мобильных и настольных клиентов в этом рецепте нет. BookStack заменяет документальную часть Notion или Confluence, но не повторяет базы данных Notion, проектные доски и все интеграции Confluence.

Рецепт закрепляет BookStack v26.09.2 в образе сообщества LinuxServer и MariaDB 11.4.13. Документация BookStack ссылается на сторонние контейнерные решения; этот образ выпускает не проект BookStack. Том /config хранит загрузки, приватные вложения, конфигурацию и темы; отдельный том MariaDB — аккаунты, текст страниц, историю правок и настройки. Резервная копия должна включать обе части и исходный APP_KEY.

BookStack распространяется под MIT; лицензия рецепта — отдельная MIT. OIDC, SAML и двухфакторная аутентификация TOTP встроены в приложение, но рецепт запускается с локальным входом по email и паролю и не настраивает провайдера идентификации. Вход через заголовок пользователя от прокси в рецепт не входит.

Ресурсы — ориентировочная оценка для небольшой установки: одно ядро CPU, минимум 1 ГБ RAM, рекомендовано 2 ГБ, от 5 ГБ диска без учёта документов и вложений. Образы выпускаются для amd64 и arm64; проверки запуска здесь выполнены только на amd64. Отдельная база и healthcheck включены, мониторинг и лимиты ресурсов — нет, поэтому уровень надёжного развёртывания частичный.

Источники: документация BookStack, варианты установки, образ LinuxServer, аутентификация и релиз v26.09.2.

Оценка безопасности

Начальные данные администратора общеизвестны; замените их до предоставления сетевого доступа. Используйте HTTPS, базу не публикуйте. Сохраняйте исходный APP_KEY вместе с зашифрованными копиями обоих томов вне сервера: он защищает зашифрованные данные приложения, включая секреты MFA. Рецепт использует сторонний контейнер LinuxServer. Сканирование уязвимостей образов здесь не выполнялось; проверка работоспособности не является аудитом безопасности.

Пошаговая инструкция

Требования и подготовка

Нужны 64-разрядные Ubuntu 22.04+ или Debian 12+, Docker Engine и Compose v2.24+. Ориентируйтесь на одно ядро CPU, минимум 1 ГБ RAM (рекомендуется 2 ГБ), 5 ГБ диска плюс документы. Оба образа выпускаются для amd64 и arm64; рецепт проверен на amd64.

mkdir -p ~/services/bookstack
cd ~/services/bookstack
# Скопируйте сюда файлы рецепта, включая backup.sh, restore.sh и proxy/.
cp .env.example .env
chmod 600 .env
# Вставьте весь результат base64:... в APP_KEY в .env.
printf 'base64:'; openssl rand -base64 32
# Два независимых пароля базы.
openssl rand -hex 32
openssl rand -hex 32

До запуска заполните .env. Все параметры:

Не оставляйте заглушки секретов. После инициализации смена паролей в .env требует соответствующей смены паролей пользователей БД. Скрипты backup/restore загружают локальный .env как доверенную конфигурацию shell: защищайте его и используйте простые сгенерированные значения.

Запуск и замена начальной учётной записи

docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 600
curl --fail http://127.0.0.1:6875/status
# Укажите свой email и имя. --initial заменяет общеизвестный начальный аккаунт.
docker compose exec bookstack php /app/www/artisan bookstack:create-admin \
  --initial --email=you@example.com --name='Ваше имя' --generate-password

Сохраните выданный пароль в надёжном месте. Начальные данные upstream — admin@admin.com / password: замените аккаунт до предоставления сетевого доступа. Откройте точный BOOKSTACK_APP_URL и войдите с новыми данными. Язык меняется в профиле, MFA включается в настройках аутентификации аккаунта. Не включайте публичный доступ или открытую регистрацию, если не собираетесь делиться содержимым.

VPS

Оставьте 6875 на loopback, базу не публикуйте. Задайте BOOKSTACK_APP_URL=https://docs.example.com, направьте DNS на сервер, настройте HTTPS и разрешите в firewall только SSH/HTTP/HTTPS. Замените начальный аккаунт до включения публичного прокси. Храните зашифрованные копии вне сервера. SMTP и внешняя аутентификация требуют дополнительных настроек по документации upstream.

Доверенная локальная сеть

Для одного человека используйте ssh -L 6875:127.0.0.1:6875 user@server и адрес http://localhost:6875 с соответствующим BOOKSTACK_APP_URL. Для совместного доступа поставьте HTTPS-прокси или привяжите порт к одному частному IP с ограничением firewall. Адрес браузера должен совпадать с настройкой; одной смены порта недостаточно.

Домен и HTTPS

Выберите пример из proxy/: Caddy получает сертификаты сам, Nginx ожидает готовые файлы сертификата, Traefik — entry point websecure и resolver letsencrypt. Примеры работают на хосте и обращаются к 127.0.0.1:6875; контейнерному прокси нужны общая Docker-сеть и внутренний порт приложения 80. Nginx допускает запросы до 50 МБ; лимит загрузки PHP тоже должен разрешать нужный размер файла.

Задайте точный внешний HTTPS URL до первого запуска. При смене существующего адреса сделайте копию, измените BOOKSTACK_APP_URL, пересоздайте приложение и обновите сохранённые ссылки:

docker compose up -d --wait --wait-timeout 600
docker compose exec bookstack php /app/www/artisan bookstack:update-url \
  http://localhost:6875 https://docs.example.com

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

./backup.sh

Скрипт останавливает запись BookStack, снимает дамп MariaDB и собирает /config, .env и compose.yaml в один приватный backups/bookstack-<timestamp>.tar. MariaDB продолжает работать. Приложение, работавшее до копирования, запускается снова даже при ошибке копии. Зашифруйте архив и перенесите вне сервера: внутри документы, вложения, пароли БД и APP_KEY. Один дамп не восстановит файлы; один /config не восстановит страницы.

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

Восстановление заменяет базу и всё содержимое /config. Используйте только собственные доверенные архивы. Подготовьте рецепт с исходным APP_KEY и совместимыми версиями приложения и БД. Вручную сравните архивный configuration.env с .env; скрипт не загружает и не активирует архивную конфигурацию. На новом хосте сначала создайте контейнеры и дождитесь MariaDB.

docker compose up -d --wait --wait-timeout 600
./restore.sh ./backups/bookstack-TIMESTAMP.tar
curl --fail http://127.0.0.1:6875/status
docker compose logs --tail=100 bookstack

До замены скрипт проверяет обязательные файлы архива и сохраняет страховочную копию. При ошибке замены оставьте приложение остановленным и исправьте причину или повторите восстановление. Проверьте сохранённую страницу и вложение. Smoke-тест проверяет восстановление базы и файла на amd64.

Обновление

Прочитайте примечания к релизу, выполните ./backup.sh и перенесите архив вне сервера. Задайте в BOOKSTACK_VERSION точный проверенный релиз:

docker compose pull
docker compose up -d --wait --wait-timeout 600
docker compose logs --tail=100 bookstack

Не используйте latest. При запуске выполняются миграции БД. MariaDB закреплена отдельно в Compose; до смены версии изучите её процедуру обновления.

Откат

Не запускайте старый BookStack на базе после миграций нового. Оставьте MariaDB работающей, остановите приложение, верните BOOKSTACK_VERSION и APP_KEY из состояния до обновления, затем пересоздайте контейнер без запуска:

docker compose stop bookstack
# Сейчас верните в .env прежнюю точную версию и исходный APP_KEY.
docker compose pull bookstack
docker compose create bookstack
./restore.sh ./backups/bookstack-BEFORE-UPDATE.tar
curl --fail http://127.0.0.1:6875/status

Остановленный контейнер позволяет сделать страховочную копию без запуска старого приложения на новой базе. Не понижайте версию MariaDB на существующем физическом каталоге: если версия менялась, восстановите SQL-дамп в чистый совместимый том, сохранив прежний до проверки результата.

Остановка и удаление

docker compose down удаляет контейнеры, сохраняя оба тома. После проверки копии вне сервера docker compose down --volumes безвозвратно удалит базу, документы, загрузки, аккаунты и конфигурацию. Удаление каталога рецепта уничтожает и локальные копии; заранее сохраните архив в другом месте.

Источники: установка, образ и параметры LinuxServer, backup/restore, безопасность и CLI.

Сообщить о проблеме с рецептом

Рассказать, как прошло на вашем сервере

Откроется предзаполненный issue на GitHub. Нужен аккаунт GitHub; после отправки сообщение будет публичным.

Диагностика

Диагностика запуска и базы

docker compose ps
docker compose logs --tail=150 database bookstack
curl --fail http://127.0.0.1:6875/status

Первый запуск инициализирует MariaDB и выполняет миграции. /status должен вернуть HTTP 200 и true для database, cache и session. При ошибке БД проверьте оба пароля и healthcheck базы. Смена начальных паролей в .env не меняет пароль уже созданного пользователя MariaDB. Не удаляйте заполненный том для исправления реквизитов.

Отсутствует или неверен APP_KEY

Перед первым запуском создайте ключ командой printf 'base64:'; openssl rand -base64 32. Инициализированной установке нужен исходный ключ. Верните его из защищённой копии вместо генерации нового, особенно если включена MFA.

Неверный адрес входа, ссылок или ресурсов

BOOKSTACK_APP_URL должен точно совпадать с адресом браузера, включая HTTPS и порт. Для существующей установки выполните процедуру смены URL из installation.md, в том числе bookstack:update-url. После смены origin очистите cookies. Передавайте Host и X-Forwarded-Proto от доверенного HTTPS-прокси и блокируйте прямой доступ посторонних.

Не удаётся войти

Общеизвестный начальный аккаунт необходимо заменить. Команда bookstack:create-admin --initial предназначена для первичной настройки, а не произвольного сброса пароля. Для существующего аккаунта используйте процедуру восстановления upstream или настроенное восстановление по почте. Сначала проверьте отправку писем; этот рецепт не настраивает SMTP.

Ошибки загрузки или закончилось место

Проверьте docker system df и свободное место хоста Docker. Растут оба тома: /config и MariaDB; документы и вложения требуют места сверх слоёв образа. Согласуйте лимит запроса прокси и настройки загрузки LinuxServer/PHP. При ошибке прав проверьте PUID и PGID; не открывайте приватные файлы для записи всем пользователям.

Ошибка backup или restore

Проверьте логи БД, место и права на архив. Восстановление принимает четыре обязательных файла из backup.sh; нужен полный доверенный архив, а не отдельный дамп или /config. Не меняйте исходный архив. Сравните configuration.env с рабочим .env, не публикуя секреты. Если замена уже началась и завершилась ошибкой, держите BookStack остановленным до завершения восстановления. Не понижайте MariaDB на существующем физическом каталоге.

Источники: диагностика BookStack, backup/restore, CLI и образ LinuxServer.