本页内容

• 前提条件
• 安装依赖项
• 配置 PHP
• 配置 MariaDB 服务器
• 下载 BookStack
• 配置 Apache2 虚拟主机
• 使用 SSL/TLS 证书保护 BookStack 安全
• 访问 BookStack
• 结语

BookStack 是一款免费且开源的 wiki 软件，使用 PHP 和 Laravel Web 框架编写。BookStack 旨在成为一个简单且可自托管的平台，用于存储和组织信息。

在本教程中，我们将一步步指导你在 Debian 12 服务器上完成 BookStack 的安装过程，以便你拥有自己的类 wiki 平台来发布信息。

前提条件

在开始之前，请确保你已具备以下条件：

• 一台 Debian 12 服务器。
• 一个具有 sudo 管理员权限的非 root 用户。
• 一个指向服务器 IP 地址的域名。

安装依赖项

BookStack 是一个使用 PHP 和 MySQL/MariaDB 编写的 wiki 平台。目前，它完全支持 PHP 8.2。在此阶段，你将安装 BookStack 的依赖项，包括 LAMP Stack（Apache2、MariaDB、PHP）软件包、Git 和 Composer。

使用以下命令更新并刷新你的 Debian 软件包索引。

sudo apt update

仓库更新后，执行以下 apt install 命令来安装 BookStack 的软件包依赖项。通过该命令，你将安装 LAMP Stack 软件包、Composer 和 Git。

sudo apt install apache2 mariadb-server composer curl php php-xml libapache2-mod-php php-fpm php-curl php-mbstring php-ldap php-tidy php-zip php-gd php-mysql git

输入 y 以继续安装。

依赖项安装完成后，通过执行以下命令来验证每个依赖项。

通过以下 systemctl 命令验证 apache2 服务，确保该服务正在运行且已启用。

sudo systemctl is-enabled apache2
sudo systemctl status apache2

以下输出将确认 apache2 服务正在运行且已启用。

现在使用以下命令验证 mariadb 服务。

sudo systemctl is-enabled mariadb
sudo systemctl status mariadb

输出应显示 mariadb 服务在你的系统上正在运行且已启用。

接下来，使用以下命令验证 PHP 版本并列出已启用的扩展。

php -v
php -m

根据以下输出，你的系统已安装 PHP 8.2。

最后，使用以下命令验证 Composer。这将定位 Composer 二进制文件并检查其版本。

which composer
sudo -u www-data composer -v

你应该会看到 Composer 2.5.5 已安装在 /usr/bin/composer 。

配置 PHP

安装依赖项后，下一步是通过修改你 Debian 机器上的 php.ini 文件来配置 PHP 安装。

使用以下 nano 编辑器命令打开默认的 PHP 配置文件 /etc/php/8.2/apache2/php.ini 。

sudo nano /etc/php/8.2/apache2/php.ini

使用以下配置更改一些默认设置。请务必根据你的服务器环境调整 date.timezone 和 memory_limit 参数。

date.timezone = Europe/Amsterdam
memory_limit = 512M

完成后保存文件并退出编辑器。

现在运行以下 systemctl 命令来重启 apache2 服务并应用你所做的更改。

sudo systemctl restart apache2

配置 MariaDB 服务器

既然已经配置好了 PHP，下一步你将使用 mariadb-secure-installation 实用工具来配置 MariaDB 服务器安装，该工具可让你为 MariaDB 设置基本安全性。随后，你还将创建一个供 BookStack 使用的新数据库和用户。

执行以下 mariadb-secure-installation 命令来保护你的 MariaDB 安装。

sudo mariadb-secure-installation

在此过程中，系统会询问你一些配置。输入 Y 表示同意并应用新的更改，或输入 n（否）以拒绝该配置。

• 对于默认未设置 root 密码的 MariaDB 服务器安装，当被询问密码时，按 ENTER 键。
• MariaDB root 用户的本地身份验证默认是安全的，当被询问是否将身份验证方法更改为 'unix_socket' 时，输入 'n' 。
• 输入 'Y' 以创建新的 MariaDB root 密码。然后，输入你的 MariaDB root 用户的强密码并重复输入。
• 当被询问是否禁用 MariaDB root 用户的远程身份验证时，输入 'Y' 表示同意。
• 默认的 MariaDB 服务器安装自带 'test' 数据库，并允许匿名用户访问它。对这两项设置都输入 'Y' ，以删除默认的 'test' 数据库并移除匿名权限。
• 最后，输入 'Y' 以确认重新加载表权限。

配置完 MariaDB 后，你将通过 mariadb 客户端命令创建一个供 BookStack 使用的新 MariaDB 数据库和用户。

使用以下 mariadb 命令登录到 MariaDB 服务器。当系统提示时，输入你的 MariaDB root 密码。

sudo mariadb -u root -p

现在运行以下查询，为 BookStack 创建一个新数据库和用户。在本示例中，你将创建一个名为 bookstack 的新数据库和用户，密码为 p4ssword 。

CREATE DATABASE bookstack;
CREATE USER bookstack@localhost IDENTIFIED BY 'p4ssword';
GRANT ALL ON bookstack.* TO bookstack@localhost WITH GRANT OPTION;
FLUSH PRIVILEGES;

接下来，运行以下查询来验证用户 bookstack 的权限。

SHOW GRANTS FOR bookstack@localhost;

你应该会看到用户 bookstack 被允许访问和管理将由 BookStack 使用的 bookstack 数据库。

输入 quit 退出 MariaDB 服务器。

下载 BookStack

既然已经配置好了 PHP 和 MariaDB 服务器，你就可以安装 BookStack 了。在本节中，你将通过 Git 和 Composer 安装 BookStack。

首先，创建新目录 /var/www/.config 和 /var/www/.cache ，供 Composer 用于存储依赖项缓存和配置。然后，你还必须将这两个目录的所有权更改为 www-data 用户。

mkdir -p /var/www/{.config,.cache}
sudo chown -R www-data /var/www/{.config,.cache}

切换到 /var/www 目录，并将 BookStack 源代码下载到 bookstack 目录。你的 BookStack 安装目录应为 /var/www/bookstack 。

cd /var/www
git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack

现在将 /var/www/bookstack 目录的所有权更改为 www-data 用户，并进入该目录。

sudo chown -R www-data:www-data /var/www/bookstack
cd /var/www/bookstack

接下来，将 .env.example 文件复制为 .env ，并使用以下 nano 编辑器命令打开新文件。

sudo -u www-data cp .env.example .env
sudo -u www-data nano .env

将你的域名输入到 APP_URL 选项中，并将你的 MariaDB 数据库详细信息输入到下面的 DB_ 设置中。

# The application URL
APP_URL=http://bookstack.howtoforge.local    
# Database values also need to be modified
# If you follow previous command, you only need to add your DB_PASSWORD
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=p4ssword

完成后保存并关闭文件。

接下来，运行以下命令通过 Composer 安装 PHP 依赖项。

sudo -u www-data composer install --no-dev --no-plugins

在安装过程中，将显示以下输出。

PHP 依赖项安装完成后，执行以下命令来生成密钥并迁移数据库。

sudo -u www-data php artisan key:generate --no-interaction --force
sudo -u www-data php artisan migrate --no-interaction --force

.env 文件上的密钥将被更新，以下是数据库迁移过程中的内容。

一切完成后，运行以下命令将某些目录的所有权更改为 www-data 用户，并确保这些目录可写。

sudo chown www-data:www-data -R bootstrap/cache public/uploads storage 
sudo chmod u+rw bootstrap/cache public/uploads storage

最后，运行以下命令将 .env 文件的权限更改为 640 。这将确保只有 www-data 用户能够修改该文件。

sudo chmod -R 640 /var/www/bookstack/.env

配置 Apache2 虚拟主机

在接下来的部分中，你将创建一个新的 Apache2 虚拟主机配置，用于运行 BookStack。因此，你必须确保已经准备好你的域名，并确保其指向服务器 IP 地址。

在创建虚拟主机配置之前，执行以下命令以启用 Apache2 上的 rewrite 模块。

sudo a2enmod rewrite

现在使用以下 nano 编辑器命令创建一个新的虚拟主机配置文件 /etc/apache2/sites-available/bookstack.conf 。

sudo nano /etc/apache2/sites-available/bookstack.conf

插入以下配置，并确保更改 ServerName 选项中的域名。以下示例将使用域名 bookstack.howtoforge.local 进行 BookStack 安装。

<VirtualHost *:80>
    ServerName bookstack.howtoforge.local
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/bookstack/public/
    <Directory /var/www/bookstack/public/>
        Options Indexes FollowSymLinks
        AllowOverride None
        Require all granted
        <IfModule mod_rewrite.c>
            <IfModule mod_negotiation.c>
                Options -MultiViews -Indexes
            </IfModule>
            RewriteEngine On
            # Handle Authorization Header
            RewriteCond %{HTTP:Authorization} .
            RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
            # Redirect Trailing Slashes If Not A Folder...
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_URI} (.+)/$
            RewriteRule ^ %1 [L,R=301]
            # Handle Front Controller...
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteRule ^ index.php [L]
        </IfModule>
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/bookstack-error.log
    CustomLog ${APACHE_LOG_DIR}/bookstack-access.log combined
</VirtualHost>

完成后保存并关闭文件。

接下来，运行以下命令以激活虚拟主机文件 bookstack.conf 并验证你的 Apache2 语法。

sudo a2ensite bookstack.conf
sudo apachectl configtest

如果你使用了正确的语法，输出 "Syntax OK" 将被打印到你的终端上。

最后，运行以下 systemctl 命令来重启 apache2 服务并应用你所做的更改。

sudo systemctl restart apache2

使用 SSL/TLS 证书保护 BookStack 安全

在本指南中，你将使用 SSL/TLS 证书保护 BookStack 的安全，这些证书可以通过 Certbot 工具从 Letsencrypt 生成。

通过以下 apt install 命令安装 Certbot 和 Certbot Apache 插件。输入 y 确认并继续安装。

sudo apt install certbot python3-certbot-apache

现在运行以下 certbot 命令来生成 SSL/TLS 证书并保护你的 BookStack 安装。请务必更改以下命令中的域名和电子邮件地址。

sudo certbot --apache --agree-tos --redirect --hsts --staple-ocsp --email 
[email protected]
 -d bookstack.howtoforge.local

过程完成后，你的 SSL/TLS 证书将在 /etc/letsencrypt/live/bookstack.howtoforge.local 目录中可用。此外，你的 BookStack 安装将自动配置为使用 HTTPS，这是通过 Certbot Apache 插件配置的。

访问 BookStack

至此，所有内容都已配置完成，你的 BookStack 安装已结束。你现在可以访问你的 BookStack 安装。

启动你的网页浏览器，访问你的 BookStack 安装域名，例如 https://bookstack.howtoforge.local/ ，你将被重定向到 BookStack 登录页面。

输入默认电子邮件地址 [email protected] ，密码为 password ，然后点击 Login 。

如果成功，你应该会看到如下所示的 BookStack 仪表板：

结语

总结一下，你已经在 Debian 12 服务器上一步步成功安装了 BookStack。你通过 Git、Composer 以及 LAMP Stack（Apache2、MariaDB 和 PHP）软件包安装了 BookStack。你还使用来自 Letsencrypt 的 SSL/TLS 证书保护了 BookStack 的安全。从这里开始，你现在可以填充你的信息并构建你自己的文档。