BookStack на сервере: частые ошибки и решения

MAATRIX

BookStack — удобная база знаний с понятной иерархией «книга → глава → страница» и простым WYSIWYG-редактором, но именно эта простота на этапе установки и эксплуатации иногда превращается в набор загадочных ошибок: белый экран вместо интерфейса, картинки, которые не грузятся, письма, которые не уходят. Ниже — разбор проблем, с которыми чаще всего сталкиваются на собственном VPS, и рабочие решения для каждой.

Белый экран или 500 ошибка после установки

Самая частая жалоба новичков: после composer install и настройки .env вместо страницы входа — белый экран или голая "500 Server Error" без деталей.

Причина обычно в правах на директории, которые Laravel (на нём построен BookStack) использует для кеша и логов:

cd /var/www/bookstack
sudo chown -R www-data:www-data storage bootstrap/cache public/uploads
sudo find storage bootstrap/cache -type d -exec chmod 775 {} \;
sudo find storage bootstrap/cache -type f -exec chmod 664 {} \;

Если после этого экран всё ещё пустой — включите вывод ошибок временно, поменяв в .env:

APP_DEBUG=true

Обновите страницу, посмотрите текст ошибки (обычно это либо «Permission denied» на конкретный файл в storage/logs, либо проблема с подключением к БД), исправьте и обязательно верните APP_DEBUG=false — открытый debug-режим на проде светит структуру путей и переменные окружения всем желающим.

Второй частый источник 500-й — не выполненные миграции БД:

php artisan migrate --force
php artisan cache:clear
php artisan config:clear

Ошибка подключения к базе данных

BookStack требует MySQL 8+ или MariaDB 10.4+. Классическая ошибка SQLSTATE[HY000] [1045] Access denied for user означает, что данные в .env не совпадают с реальными правами пользователя БД.

Проверьте блок подключения:

DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=ваш_пароль

И убедитесь, что пользователь реально может подключаться с указанным хостом:

CREATE DATABASE bookstack CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'ваш_пароль';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'localhost';
FLUSH PRIVILEGES;

Если BookStack и MySQL в разных Docker-контейнерах, DB_HOST=localhost не сработает — нужен DB_HOST=имя_сервиса_mysql из docker-compose.yml, а не localhost или 127.0.0.1. Это отдельная категория ошибок, характерная именно для контейнерных установок: сеть контейнера изолирована, и «localhost» внутри контейнера BookStack — это сам контейнер, а не хост базы. Общие подходы к диагностике таких проблем с MySQL разобраны в статье про бэкап MySQL на сервере — там тоже много про права доступа и подключения.

Неверный APP_URL: ссылки и стили ломаются

Если BookStack открывается, но страница выглядит «голой» — без стилей, картинки не грузятся, ссылки ведут на http://localhost вместо реального домена, — почти всегда виноват APP_URL в .env. Это значение должно точно совпадать с тем, как пользователи заходят на сайт, включая схему:

APP_URL=https://wiki.vash-domen.ru

Никаких слешей в конце, никакого порта, если он стандартный (80/443). После изменения — обязательно очистить кеш конфигурации, иначе Laravel продолжит использовать закешированное старое значение:

php artisan config:clear
php artisan cache:clear

Отдельно проверьте, что за реверс-прокси (Nginx, Caddy) действительно передаёт заголовки X-Forwarded-Proto и X-Forwarded-Host — без них BookStack за прокси иногда генерирует ссылки на http, даже если внешний доступ идёт по https, и браузер блокирует «смешанный контент». Если вы настраиваете прокси с нуля, пригодится статья Nginx как реверс-прокси на Ubuntu 24.04 — там показана правильная передача заголовков для именно такого сценария.

Не грузятся изображения и файлы в редакторе

Отдельная больная тема — вставка картинок в WYSIWYG-редакторе. Симптомы: спиннер крутится вечно, либо загрузка проходит, но изображение потом не открывается (404).

Первое, что нужно проверить, — лимиты PHP, которые часто занижены по умолчанию для приложения с картинками и вложениями:

; в php.ini или в пуле php-fpm для BookStack
upload_max_filesize = 20M
post_max_size = 25M
memory_limit = 256M
max_execution_time = 60

После правки — перезапуск PHP-FPM:

sudo systemctl restart php8.2-fpm

Второе — куда именно физически сохраняются файлы. По умолчанию BookStack хранит загрузки локально в public/uploads и storage/uploads, и оба пути должны принадлежать пользователю веб-сервера (см. команду chown выше). Если вы переключили хранилище на S3-совместимое (переменная STORAGE_TYPE=s3 в .env), а изображения всё равно не открываются — почти всегда проблема в правах доступа bucket'а (файлы загружаются, но недоступны публично) или в неверном STORAGE_URL, который должен указывать на реальный публичный адрес объектов.

Третье, что стоит проверить, если у вас Nginx перед BookStack — лимит на размер тела запроса на уровне самого веб-сервера, который блокирует загрузку раньше, чем запрос вообще доходит до PHP:

client_max_body_size 25M;

Не приходят письма (сброс пароля, приглашения)

BookStack умеет отправлять email — приглашения новым пользователям, сброс пароля, уведомления об изменениях страниц. Если письма не уходят, а в логах Laravel видна ошибка вроде Connection could not be established with host smtp..., проблема почти всегда в блокировке исходящих SMTP-портов на стороне провайдера или в неверных данных подключения.

Настройки почты — тоже в .env:

MAIL_DRIVER=smtp
MAIL_HOST=smtp.yandex.ru
MAIL_PORT=465
MAIL_USERNAME=noreply@vash-domen.ru
MAIL_PASSWORD=пароль_или_apppassword
MAIL_ENCRYPTION=ssl
MAIL_FROM_NAME="BookStack"

Порт 587 (STARTTLS) или 465 (SSL) — многие хостинги режут исходящий 25-й порт по умолчанию для борьбы со спамом, и это нормально: 25-й нужен только для прямой отправки без релея, а через внешний SMTP (Yandex, Mailgun, SendGrid) достаточно 465/587. Проверить, что порт вообще открыт наружу, можно так:

telnet smtp.yandex.ru 465

Если соединение зависает — порт заблокирован фаерволом хостинга или облачным провайдером, и тут нужно либо открывать порт в панели, либо использовать сторонний SMTP-релей, у которого исходящие порты уже открыты по умолчанию.

Медленная загрузка страниц и высокая нагрузка на CPU

Когда база знаний разрастается до сотен страниц, некоторые администраторы замечают, что интерфейс начинает тормозить, особенно поиск и страница со списком книг. Здесь обычно помогают три вещи по порядку значимости:

1. Кеширование конфигурации и роутов — если вы правили .env и забыли пересобрать кеш, Laravel на каждый запрос заново парсит конфиг:

php artisan config:cache
php artisan route:cache
php artisan view:cache

1. OPcache для PHP — без байткод-кеша каждый запрос компилирует PHP-файлы заново, что для Laravel-приложения ощутимо:

opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=10000
opcache.validate_timestamps=0

Обратите внимание на validate_timestamps=0 — с этой настройкой изменения в коде не подхватятся автоматически, после любого обновления BookStack нужно вручную сбрасывать OPcache (systemctl restart php8.2-fpm обычно достаточно).

1. Индекс поиска — если полнотекстовый поиск стал медленным после массового импорта страниц, помогает пересборка поискового индекса:

php artisan bookstack:regenerate-search

На большинстве установок с несколькими десятками-сотнями страниц 2 vCPU и 4 ГБ RAM хватает с большим запасом — узкое место почти всегда в конфигурации, а не в мощности сервера, но если вы одновременно держите BookStack, MySQL и, скажем, Nginx с несколькими другими сайтами на одной машине, ресурсы стоит закладывать с запасом.

Ошибки после обновления версии

Обновление BookStack (через git pull + composer install или пересборку Docker-образа) иногда ломает то, что до этого работало. Типичный сценарий — обновились, а сайт снова выдаёт 500-ю или предупреждение о несовместимой версии PHP.

Порядок безопасного обновления:

# бэкап перед любым обновлением — база и файлы
mysqldump -u bookstack -p bookstack > bookstack_backup_$(date +%F).sql
tar -czf uploads_backup_$(date +%F).tar.gz public/uploads storage/uploads

# сама процедура обновления
php artisan down
git pull origin release
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan cache:clear
php artisan config:cache
php artisan up

php artisan down включает страницу технических работ и отключает доступ на время миграции — без этого пользователь может открыть страницу ровно в момент, когда схема БД наполовину обновлена, и словить непредсказуемые ошибки. Если после обновления сайт не поднимается — первым делом проверьте лог storage/logs/laravel.log, там почти всегда явно написано, какой миграции или зависимости не хватает.

Если BookStack развёрнут в Docker — процедура проще и безопаснее: достаточно подтянуть новый тег образа и пересоздать контейнер, база данных при этом не трогается, если она в отдельном volume. Общие принципы безопасного docker-compose для продакшена, включая грамотное разделение volume и рестарт-политики, описаны в статье Docker Compose для продакшена на Ubuntu 24.04.

Частые вопросы