bolt Valebyte VPS от $4/мес — NVMe, запуск за 60 секунд.

Получить VPS arrow_forward
eco Начальный Туториал

Установка BookStack на VPS: личная вики и база знаний для команды

calendar_month May 31, 2026 schedule 17 мин. чтения visibility 37 просмотров
Установка BookStack на VPS: личная вики и база знаний для команды
info

Нужен сервер для этого гайда? Мы предлагаем выделенные серверы и VPS в 50+ странах с мгновенной настройкой.

Нужен сервер для этого гайда?

Разверните VPS или выделенный сервер за минуты.

Установка BookStack на VPS: личная вики и база знаний для команды

TL;DR

В этом подробном гайде мы шаг за шагом настроим BookStack — мощную и интуитивно понятную систему управления знаниями с открытым исходным кодом — на вашем собственном виртуальном сервере (VPS) под управлением Ubuntu 24.04 LTS. Вы получите полностью функциональную платформу для создания и хранения документации, доступную вашей команде или для личного использования, с автоматическим HTTPS, механизмом резервного копирования и базовой защитой.

  • Настраиваем BookStack версии 24.04+ на Ubuntu 24.04 LTS.
  • Используем стек PHP 8.3/8.4, MySQL 8.0 и веб-сервер Caddy для автоматического TLS.
  • Обеспечиваем базовую безопасность сервера с помощью UFW и Fail2ban.
  • Настраиваем автоматическое резервное копирование данных и базы данных.
  • Подробные команды и конфигурационные файлы готовы к копированию и выполнению.

Что мы настраиваем и зачем

Схема: Что мы настраиваем и зачем
Схема: Что мы настраиваем и зачем

Мы будем устанавливать BookStack — это бесплатная и открытая платформа для создания и организации документации, которая идеально подходит для личных заметок, командных вики, баз знаний, руководств по продуктам и многого другого. Она разработана с акцентом на простоту использования и чистый, современный интерфейс. BookStack позволяет структурировать информацию в виде "книг", "глав" и "страниц", поддерживает Markdown и WYSIWYG редакторы, а также имеет мощную систему поиска и контроля доступа.

В итоге вы получите полностью независимую, приватную и контролируемую вами базу знаний, доступную по вашему доменному имени. Это особенно ценно для стартапов, команд разработчиков, соло-фаундеров SaaS-проектов или любого, кто ценит конфиденциальность и полный контроль над своими данными.

Существуют различные альтернативы, такие как облачные решения (Confluence, Notion, GitLab Wiki, Google Docs) или другие self-hosted платформы (Wiki.js, MediaWiki). Облачные сервисы удобны, но часто имеют ежемесячную плату, ограничения по хранилищу и, самое главное, вы не владеете данными полностью, а доверяете их стороннему провайдеру. Self-hosted решения на VPS, напротив, дают вам полный суверенитет над вашей информацией, позволяют точно настраивать сервер под ваши нужды и, при правильном подходе, могут быть значительно экономичнее в долгосрочной перспективе, особенно если вы уже арендуете VPS для других задач. Вы также можете быть уверены в отсутствии скрытых "фич" и слежки, что критично для проектов, требующих высокой степени конфиденциальности.

Какой VPS-конфиг нужен под эту задачу

Схема: Какой VPS-конфиг нужен под эту задачу
Схема: Какой VPS-конфиг нужен под эту задачу

BookStack сам по себе не очень требователен к ресурсам, но для стабильной работы всей связки (операционная система, база данных, PHP-FPM, веб-сервер) требуются определенные минимальные характеристики. Эти требования актуальны для 2026 года, учитывая современные версии ПО.

Минимальные требования для небольшого проекта (до 5-10 активных пользователей, до 1000 страниц):

  • CPU: 1-2 vCPU. Для базовой работы одного ядра достаточно, но 2 ядра обеспечат лучшую отзывчивость при одновременной работе нескольких пользователей или фоновых задачах.
  • RAM: 2 GB. Этого будет достаточно для Ubuntu Server 24.04 LTS, PHP 8.3/8.4, MySQL 8.0 и Caddy. Если вы планируете запускать другие сервисы на том же VPS, рассмотрите 4 GB.
  • Диск: 40 GB SSD. Система займет около 10-15 GB. Остальное пойдет под базу данных BookStack, файлы изображений, вложения и логи. SSD критически важен для производительности базы данных и общей отзывчивости системы.
  • Сеть: 100 Mbps порт, 500 GB - 1 TB трафика в месяц. Для обычной вики этого более чем достаточно.

Рекомендуемый VPS-план для команды (до 20-30 активных пользователей, тысячи страниц, регулярные загрузки файлов):

  • CPU: 2 vCPU.
  • RAM: 4 GB.
  • Диск: 80 GB SSD.
  • Сеть: 1 Gbps порт, 2-3 TB трафика в месяц.

Для таких характеристик можно рассмотреть VPS с указанными характеристиками.

Когда нужен dedicated, а не VPS

Выделенный сервер (dedicated) становится оправданным, если:

  • Очень высокая нагрузка: Сотни одновременно активных пользователей, тысячи запросов в секунду.
  • Большой объем данных: Десятки тысяч страниц, терабайты вложений и файлов.
  • Требования к производительности: Нужна максимальная и предсказуемая производительность без "соседства" с другими клиентами провайдера.
  • Специфичное оборудование: Необходимость в особых RAID-массивах, GPU или других аппаратных решениях, недоступных на VPS.
  • Запуск множества других сервисов: Если помимо BookStack на сервере будут работать другие ресурсоемкие приложения (CI/CD, тяжелые базы данных, игровые серверы).

В большинстве случаев для BookStack достаточно хорошо сконфигурированного VPS. Если вы выбираете dedicated, убедитесь, что его характеристики соответствуют вашим потребностям, например, подходящий dedicated.

Локация: на что влияет

Выбор локации VPS влияет на несколько ключевых факторов:

  • Задержка (Latency): Чем ближе сервер к вашей основной аудитории или команде, тем быстрее будет отклик сайта. Для команды в Европе выбирайте европейские дата-центры.
  • Законодательство: Законы о хранении данных могут сильно различаться между странами. Убедитесь, что выбранная локация соответствует вашим требованиям к конфиденциальности и юридическим нормам.
  • Доступность сервисов: Некоторые облачные хранилища или CDN могут иметь лучшую интеграцию или производительность в определенных регионах.
  • Стоимость: Цены на VPS могут варьироваться в зависимости от локации.

Подготовка сервера

Схема: Подготовка сервера
Схема: Подготовка сервера

Перед установкой BookStack необходимо выполнить базовую настройку свежего сервера. Мы будем использовать Ubuntu Server 24.04 LTS.

1. Подключение к серверу

Подключитесь к вашему VPS по SSH. Если ваш провайдер предоставляет доступ под root, рекомендуется сразу создать нового пользователя с правами sudo.


ssh root@ВАШ_IP_АДРЕС_VPS

2. Создание нового пользователя и настройка sudo (если необходимо)

Если вы вошли как root, создайте нового пользователя, например, bookstackuser:


adduser bookstackuser
usermod -aG sudo bookstackuser

Затем выйдите и войдите под новым пользователем:


exit
ssh bookstackuser@ВАШ_IP_АДРЕС_VPS

3. Обновление системы

Всегда начинайте с обновления списка пакетов и установленных пакетов до последних версий. Это гарантирует, что у вас будут последние исправления безопасности и актуальные версии системных библиотек.


sudo apt update && sudo apt upgrade -y

4. Настройка брандмауэра (UFW)

Включите брандмауэр UFW и разрешите только необходимые порты. Это критически важно для безопасности.


sudo apt install ufw -y # Установка UFW, если еще не установлен
sudo ufw allow OpenSSH # Разрешить SSH (порт 22)
sudo ufw allow http # Разрешить HTTP (порт 80)
sudo ufw allow https # Разрешить HTTPS (порт 443)
sudo ufw enable # Включить UFW
sudo ufw status # Проверить статус брандмауэра

При запросе подтверждения на включение UFW введите y.

5. Установка Fail2ban

Fail2ban помогает защитить сервер от атак методом подбора пароля, блокируя IP-адреса, которые делают слишком много неудачных попыток входа.


sudo apt install fail2ban -y
sudo systemctl enable fail2ban # Включить автозапуск Fail2ban
sudo systemctl start fail2ban # Запустить Fail2ban

Для базовой настройки можно создать файл /etc/fail2ban/jail.local:


sudo nano /etc/fail2ban/jail.local

Вставьте следующее содержимое:


[sshd]
enabled = true
port = ssh
filter = sshd
logpath = /var/log/auth.log
maxretry = 3
bantime = 1h

Сохраните файл (Ctrl+O, Enter) и выйдите (Ctrl+X). Затем перезапустите Fail2ban:


sudo systemctl restart fail2ban

6. Установка базовых утилит

Установим необходимые утилиты, которые понадобятся в процессе установки BookStack.


sudo apt install git curl wget unzip -y

Установка ПО — пошагово

Схема: Установка ПО — пошагово
Схема: Установка ПО — пошагово

Теперь, когда сервер подготовлен, приступим к установке всех необходимых компонентов для BookStack: PHP, Composer, MySQL и Caddy.

1. Установка PHP и необходимых расширений

BookStack версии 24.04+ требует PHP 8.1 или выше. Мы установим PHP 8.3/8.4, который будет актуальным в 2026 году и обеспечит хорошую производительность. Для этого сначала добавим репозиторий ondrej/php, который содержит свежие версии PHP.


sudo apt install software-properties-common -y # Установка утилиты для работы с PPA
sudo add-apt-repository ppa:ondrej/php -y # Добавление репозитория PHP
sudo apt update # Обновление списка пакетов после добавления репозитория
sudo apt install php8.3-fpm php8.3-mysql php8.3-gd php8.3-mbstring php8.3-xml php8.3-bcmath php8.3-zip php8.3-curl php8.3-common php8.3-cli -y # Установка PHP 8.3 FPM и необходимых расширений
sudo systemctl enable php8.3-fpm # Включение автозапуска PHP-FPM
sudo systemctl start php8.3-fpm # Запуск PHP-FPM

Примечание: Если к 2026 году актуальной станет PHP 8.4, просто замените php8.3 на php8.4 во всех командах.

2. Установка Composer

Composer — это менеджер зависимостей для PHP, необходимый для установки компонентов BookStack.


php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" # Загрузка скрипта установки Composer
php composer-setup.php --install-dir=/usr/local/bin --filename=composer # Установка Composer глобально
php -r "unlink('composer-setup.php');" # Удаление установочного скрипта
composer --version # Проверка версии Composer

3. Установка MySQL Server

BookStack использует базу данных для хранения всей информации. Мы установим MySQL 8.0.


sudo apt install mysql-server -y # Установка MySQL Server 8.0
sudo systemctl enable mysql # Включение автозапуска MySQL
sudo systemctl start mysql # Запуск MySQL
sudo mysql_secure_installation # Запуск скрипта для безопасной настройки MySQL

Во время mysql_secure_installation следуйте инструкциям:

  • Установите плагин VALIDATE PASSWORD COMPONENT (рекомендуется).
  • Установите надежный пароль для пользователя root MySQL.
  • Ответьте Y на все остальные вопросы (удалить анонимных пользователей, запретить удаленный вход root, удалить тестовую базу данных, перезагрузить таблицы привилегий).

Создадим базу данных и пользователя для BookStack. Замените bookstack_db, bookstack_user и ВАШ_НАДЕЖНЫЙ_ПАРОЛЬ_ДЛЯ_БД на свои значения.


sudo mysql -u root -p # Вход в MySQL от имени root (потребуется введенный ранее пароль)

Внутри консоли MySQL выполните:


CREATE DATABASE bookstack_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstack_user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'ВАШ_НАДЕЖНЫЙ_ПАРОЛЬ_ДЛЯ_БД';
GRANT ALL PRIVILEGES ON bookstack_db. TO 'bookstack_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

4. Установка BookStack

Клонируем репозиторий BookStack в директорию /var/www/bookstack.


sudo mkdir -p /var/www/bookstack # Создание директории для BookStack
sudo chown bookstackuser:bookstackuser /var/www/bookstack # Изменение владельца директории
cd /var/www/bookstack # Переход в директорию
git clone https://github.com/BookStackApp/BookStack.git . # Клонирование репозитория в текущую директорию

Установим зависимости BookStack с помощью Composer.


composer install --no-dev # Установка зависимостей без dev-пакетов

Настроим права доступа для директорий BookStack.


sudo chown -R www-data:www-data /var/www/bookstack # Изменение владельца файлов на пользователя веб-сервера
sudo chmod -R 755 /var/www/bookstack # Установка прав на чтение/запись для файлов
sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache # Установка прав на запись для критических директорий

5. Установка Caddy Web Server

Caddy — это мощный веб-сервер, который автоматически управляет сертификатами HTTPS (Let's Encrypt), что значительно упрощает настройку. Это отличная альтернатива Nginx и Apache.


sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https # Установка необходимых пакетов
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg # Добавление GPG ключа
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list # Добавление репозитория Caddy
sudo apt update # Обновление списка пакетов
sudo apt install caddy -y # Установка Caddy
sudo systemctl enable caddy # Включение автозапуска Caddy
sudo systemctl start caddy # Запуск Caddy

Теперь Caddy установлен и готов к работе. На следующем этапе мы его сконфигурируем.

Конфигурация

Схема: Конфигурация
Схема: Конфигурация

После установки всех компонентов необходимо настроить BookStack и веб-сервер Caddy для их совместной работы.

1. Настройка файла .env BookStack

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


cd /var/www/bookstack
cp .env.example .env

Теперь откройте файл .env для редактирования:


sudo nano .env

Найдите и отредактируйте следующие строки, заменив значения на свои:

  • APP_URL: Укажите полный URL вашего BookStack (например, https://your-bookstack-domain.com).
  • DB_DATABASE: Имя вашей базы данных MySQL (например, bookstack_db).
  • DB_USERNAME: Имя пользователя MySQL для BookStack (например, bookstack_user).
  • DB_PASSWORD: Пароль пользователя MySQL для BookStack.

Пример отредактированных строк:


APP_URL=https://your-bookstack-domain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=bookstack_db
DB_USERNAME=bookstack_user
DB_PASSWORD=ВАШ_НАДЕЖНЫЙ_ПАРОЛЬ_ДЛЯ_БД

Сохраните файл (Ctrl+O, Enter) и выйдите (Ctrl+X).

2. Генерация ключа приложения

BookStack требует уникального ключа приложения для шифрования и безопасности. Выполните следующую команду в директории BookStack:


php artisan key:generate

Эта команда автоматически сгенерирует ключ и добавит его в ваш файл .env.

3. Выполнение миграций базы данных

Теперь необходимо создать таблицы в базе данных BookStack.


php artisan migrate --force # Выполнение миграций базы данных

При запросе подтверждения введите yes.

4. Настройка Caddyfile

Caddy автоматически управляет HTTPS, что делает его идеальным для BookStack. Отредактируйте файл конфигурации Caddy по умолчанию:


sudo nano /etc/caddy/Caddyfile

Удалите все содержимое файла и вставьте следующую конфигурацию. Замените your-bookstack-domain.com на ваш фактический домен:


your-bookstack-domain.com {
    # Указываем корневую директорию BookStack
    root  /var/www/bookstack/public

    # Включаем сервер статических файлов
    file_server

    # Проксируем PHP запросы к PHP-FPM
    php_fastcgi unix//run/php/php8.3-fpm.sock

    # Настраиваем логирование доступа
    log {
        output file /var/log/caddy/access.log
        format json
    }

    # Обработка ошибок
    handle_errors {
        rewrite  /index.php
    }

    # Быстрое перенаправление HTTP на HTTPS
    # Caddy делает это автоматически, но эта строка может помочь в некоторых случаях
    # Или можно использовать {
    #   redir https://{host}{uri}
    # }
}

Примечание: Убедитесь, что php8.3-fpm.sock соответствует версии PHP, которую вы установили. Если вы устанавливали PHP 8.4, замените на php8.4-fpm.sock.

Создайте директорию для логов Caddy:


sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy # Установка владельца для директории логов

Сохраните файл (Ctrl+O, Enter) и выйдите (Ctrl+X).

5. Проверка и перезапуск Caddy

Проверьте конфигурацию Caddy на ошибки:


sudo caddy validate --config /etc/caddy/Caddyfile

Если ошибок нет, перезапустите Caddy, чтобы применить новую конфигурацию:


sudo systemctl reload caddy

Убедитесь, что Caddy работает корректно:


sudo systemctl status caddy

Статус должен быть active (running).

6. Проверка работоспособности

Теперь BookStack должен быть доступен по вашему доменному имени с HTTPS. Откройте веб-браузер и перейдите по адресу https://your-bookstack-domain.com.

Вы должны увидеть страницу входа BookStack. Начальные учетные данные для входа:

Обязательно измените эти данные сразу после первого входа!

Вы также можете проверить доступность с сервера:


curl -I https://your-bookstack-domain.com

В ответе должны быть заголовки HTTP/2 200 OK.

Бэкапы и обслуживание

Схема: Бэкапы и обслуживание
Схема: Бэкапы и обслуживание

Регулярное резервное копирование — это краеугольный камень любой production-системы. BookStack хранит данные в базе данных и файлы (изображения, вложения) на диске. Обслуживание включает в себя обновление ПО и мониторинг.

1. Что бэкапить

  • База данных BookStack: Содержит все страницы, книги, главы, пользователей, настройки. Это самое важное.
  • Файлы BookStack: Включают загруженные изображения, вложения, а также файл .env (с конфиденциальными данными, такими как ключ приложения и учетные данные БД).

2. Простой скрипт автобэкапа

Создадим простой скрипт для резервного копирования. Рекомендуется хранить резервные копии не на том же сервере.


sudo nano /usr/local/bin/bookstack_backup.sh

Вставьте следующее содержимое, заменив ВАШ_НАДЕЖНЫЙ_ПАРОЛЬ_ДЛЯ_БД и bookstack_db на свои значения:


#!/bin/bash

# Конфигурация
DB_NAME="bookstack_db"
DB_USER="bookstack_user" # Лучше создать отдельного пользователя MySQL только для бэкапов с правами SELECT, LOCK TABLES
DB_PASS="ВАШ_НАДЕЖНЫЙ_ПАРОЛЬ_ДЛЯ_БД"
BOOKSTACK_PATH="/var/www/bookstack"
BACKUP_DIR="/var/backups/bookstack"
DATE=$(date +%Y%m%d%H%M%S)
FILENAME_DB="${DB_NAME}_${DATE}.sql"
FILENAME_FILES="bookstack_files_${DATE}.tar.gz"

# Создание директории для бэкапов, если не существует
mkdir -p "${BACKUP_DIR}"

echo "Начинаем резервное копирование BookStack..."

# 1. Бэкап базы данных
echo "Бэкап базы данных..."
mysqldump --user="${DB_USER}" --password="${DB_PASS}" "${DB_NAME}" > "${BACKUP_DIR}/${FILENAME_DB}"
if [ $? -eq 0 ]; then
    echo "Бэкап базы данных успешно создан: ${FILENAME_DB}"
else
    echo "Ошибка при создании бэкапа базы данных."
    exit 1
fi

# 2. Бэкап файлов BookStack (за исключением кэша и логов)
echo "Бэкап файлов BookStack..."
tar -czf "${BACKUP_DIR}/${FILENAME_FILES}" -C "${BOOKSTACK_PATH}" \
    --exclude='storage/uploads/images/' \
    --exclude='storage/uploads/files/' \
    --exclude='storage/logs/' \
    --exclude='bootstrap/cache/' \
    --exclude='vendor/' \
    .
# Дополнительно сохраняем только .env и uploads отдельно, чтобы их легко было восстановить
cp "${BOOKSTACK_PATH}/.env" "${BACKUP_DIR}/bookstack_env_${DATE}.env"
tar -czf "${BACKUP_DIR}/bookstack_uploads_images_${DATE}.tar.gz" -C "${BOOKSTACK_PATH}/storage/uploads" images
tar -czf "${BACKUP_DIR}/bookstack_uploads_files_${DATE}.tar.gz" -C "${BOOKSTACK_PATH}/storage/uploads" files

if [ $? -eq 0 ]; then
    echo "Бэкап файлов BookStack успешно создан: ${FILENAME_FILES}"
else
    echo "Ошибка при создании бэкапа файлов BookStack."
    exit 1
fi

# 3. Удаление старых бэкапов (например, старше 7 дней)
echo "Удаление старых бэкапов..."
find "${BACKUP_DIR}" -type f -name ".sql" -mtime +7 -delete
find "${BACKUP_DIR}" -type f -name ".tar.gz" -mtime +7 -delete
find "${BACKUP_DIR}" -type f -name ".env" -mtime +7 -delete

echo "Резервное копирование завершено."

Сохраните файл и сделайте его исполняемым:


sudo chmod +x /usr/local/bin/bookstack_backup.sh

3. Автоматизация бэкапов с помощью Cron

Добавим скрипт в планировщик Cron для ежедневного выполнения.


sudo crontab -e

Выберите текстовый редактор (если предложит) и добавьте следующую строку в конец файла, чтобы выполнять бэкап каждый день в 3:00 ночи:


0 3    /usr/local/bin/bookstack_backup.sh >> /var/log/bookstack_backup.log 2>&1

Сохраните и выйдите. Теперь бэкапы будут создаваться автоматически.

4. Куда складывать бэкапы

Никогда не храните все бэкапы только на том же сервере, что и основной сервис! Если сервер выйдет из строя, вы потеряете всё.

  • Внешнее S3-совместимое хранилище: Amazon S3, DigitalOcean Spaces, Backblaze B2. Это надежный и относительно недорогой вариант. Можно использовать утилиты вроде s3cmd или rclone для автоматической синхронизации.
  • Отдельный VPS: Арендуйте небольшой, дешевый VPS исключительно для хранения бэкапов и синхронизируйте их туда по SFTP/RSYNC.
  • Локальный сетевой диск (NAS): Если у вас есть собственная инфраструктура.

Например, для отправки бэкапов на S3, вы можете добавить в скрипт bookstack_backup.sh после создания архивов команду s3cmd put "${BACKUP_DIR}/${FILENAME_DB}" s3://your-s3-bucket/bookstack/ (потребуется установка и настройка s3cmd).

5. Обновления: rolling vs maintenance window

Регулярные обновления критически важны для безопасности и получения новых функций.

  • Системные обновления (ОС, PHP, MySQL):
    • Rolling (постоянные): Для некритичных патчей безопасности можно настроить автоматическое обновление (например, с помощью unattended-upgrades).
    • Maintenance Window (окно обслуживания): Для мажорных обновлений PHP, MySQL или ядра Linux рекомендуется планировать окно обслуживания, так как они могут потребовать перезагрузки сервера или привести к временной неработоспособности сервиса. Тестируйте обновления на стейджинг-сервере, если это возможно.
    
    sudo apt update && sudo apt upgrade -y # Обновление системы
    
  • Обновления BookStack:

    BookStack обновляется через Git и Composer. Рекомендуется выполнять их в окно обслуживания.

    
    cd /var/www/bookstack
    git pull # Загрузка последних изменений из репозитория
    composer install --no-dev # Обновление зависимостей
    php artisan migrate --force # Выполнение миграций базы данных (если есть)
    php artisan cache:clear # Очистка кэша BookStack
    php artisan view:clear # Очистка кэша представлений
    sudo chown -R www-data:www-data /var/www/bookstack # Убедитесь, что права верны после pull
    sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache
    sudo systemctl reload php8.3-fpm # Перезапуск PHP-FPM
    sudo systemctl reload caddy # Перезапуск Caddy
    

    Всегда проверяйте официальную документацию BookStack перед обновлением, так как процесс может меняться.

Troubleshooting + FAQ

Мой BookStack не работает, я вижу ошибку 500 или пустую страницу. Что делать?

Ошибка 500 (Internal Server Error) обычно указывает на проблему в работе PHP или приложения. В первую очередь проверьте логи:

  • Логи Caddy: sudo tail -f /var/log/caddy/access.log и sudo journalctl -u caddy -f. Ищите ошибки, связанные с проксированием PHP.
  • Логи PHP-FPM: sudo tail -f /var/log/php8.3-fpm.log (или соответствующая версия PHP).
  • Логи BookStack: sudo tail -f /var/www/bookstack/storage/logs/laravel.log. Это наиболее важный лог для отладки проблем самого BookStack.

Частые причины: неправильные права доступа к файлам/директориям (особенно storage и bootstrap/cache), ошибки в файле .env (неверные учетные данные БД, неправильный APP_URL), отсутствующие PHP-расширения, проблемы с подключением к базе данных.

Какой VPS-конфиг минимально подойдёт для BookStack?

Для небольшого личного использования или команды из 2-3 человек с не очень большим объемом данных, минимально подойдет VPS с 1-2 vCPU, 2 ГБ оперативной памяти и 40 ГБ SSD-диска. Этого достаточно для стабильной работы Ubuntu 24.04 LTS, PHP 8.3/8.4, MySQL 8.0 и Caddy с BookStack. Важно, чтобы диск был SSD для хорошей производительности базы данных.

Что выбрать — VPS или dedicated для этой задачи?

Для большинства сценариев использования BookStack (личная вики, база знаний для небольшой или средней команды до 30-50 человек) VPS является оптимальным выбором. Он предлагает достаточную производительность, гибкость и значительно ниже по стоимости. Выделенный сервер стоит рассматривать, если у вас очень большая команда (сотни пользователей), огромный объем данных, критические требования к производительности без каких-либо компромиссов, или если вы планируете размещать множество других ресурсоемких приложений на том же сервере.

Я изменил доменное имя. Что нужно обновить?

Если вы изменили доменное имя, необходимо обновить как минимум два места:

  1. Файл .env BookStack: Измените значение APP_URL на новое доменное имя (например, APP_URL=https://new-domain.com).
  2. Caddyfile: Отредактируйте /etc/caddy/Caddyfile и замените старое доменное имя на новое в первой строке (например, new-domain.com { ... }).
После изменений не забудьте перезапустить Caddy: sudo systemctl reload caddy и очистить кэш BookStack: php artisan cache:clear && php artisan view:clear.

Как обновить BookStack до новой версии?

Процесс обновления BookStack обычно включает в себя: переход в директорию BookStack (cd /var/www/bookstack), получение последних изменений из Git (git pull), обновление PHP-зависимостей через Composer (composer install --no-dev), выполнение миграций базы данных (php artisan migrate --force) и очистку кэша BookStack (php artisan cache:clear && php artisan view:clear). Всегда рекомендуется прочитать официальные инструкции по обновлению для конкретной версии BookStack, так как могут быть специфические шаги.

BookStack выдает ошибку "Access Denied" при попытке подключения к MySQL.

Эта ошибка означает, что BookStack не может подключиться к базе данных MySQL с предоставленными учетными данными. Проверьте следующее:

  • Файл .env: Убедитесь, что DB_USERNAME, DB_PASSWORD и DB_DATABASE в файле /var/www/bookstack/.env точно соответствуют тем, что вы создали в MySQL.
  • Пользователь MySQL: Убедитесь, что пользователь bookstack_user существует в MySQL и имеет правильные привилегии на базу данных bookstack_db. Вы можете проверить это, войдя в MySQL от имени root и выполнив SELECT user, host FROM mysql.user; и SHOW GRANTS FOR 'bookstack_user'@'localhost';.
  • Служба MySQL: Проверьте, что служба MySQL запущена: sudo systemctl status mysql.

Выводы и следующие шаги

Схема: Выводы и следующие шаги
Схема: Выводы и следующие шаги

Поздравляем! Вы успешно установили и настроили BookStack на вашем VPS, создав надежную и контролируемую вами платформу для управления знаниями. Теперь у вас есть мощный инструмент для организации информации, будь то личные заметки, документация по проекту или обширная база знаний для вашей команды. Вы получили полный контроль над данными и инфраструктурой, обеспечив конфиденциальность и безопасность.

Куда двигаться дальше?

  • Настройка пользователей и ролей: В BookStack вы можете создавать пользователей, группы и назначать им различные права доступа к книгам, главам и страницам. Начните с создания учетных записей для вашей команды и настройки соответствующих разрешений.
  • Кастомизация внешнего вида: BookStack позволяет изменять логотип, цветовую схему и добавлять пользовательский CSS, чтобы брендировать вашу вики в соответствии с вашим стилем.
  • Интеграция с внешними сервисами: Рассмотрите возможность настройки единого входа (SSO) через LDAP, SAML2 или социальные провайдеры, если это актуально для вашей команды.
  • Мониторинг сервера: Установите системы мониторинга (например, Prometheus + Grafana или Zabbix) для отслеживания загрузки CPU, RAM, диска и состояния сервисов, чтобы оперативно реагировать на потенциальные проблемы.

Поделиться этой записью:

установка bookstack на vps: личная вики и база знаний для команды
support_agent
Valebyte Support
Usually replies within minutes
Hi there!
Send us a message and we'll reply as soon as possible.