在 Ubuntu 20.04 上通过 Nginx 部署 BookStack 开源知识库平台教程

本教程适用于以下操作系统版本

Ubuntu 20.04（Focal Fossa）
Ubuntu 16.04（Xenial Xerus）

本页内容

准备工作
第 1 步 - 配置防火墙
第 2 步 - 安装 Git
第 3 步 - 安装 PHP 及扩展
第 4 步 - 安装并配置 MariaDB
第 5 步 - 安装 Composer
第 6 步 - 下载并安装 BookStack
第 7 步 - 安装 Let's Encrypt SSL
第 8 步 - 安装并配置 Nginx 配置 PHP-FPM 配置 Nginx
第 9 步 - 运行 BookStack
备份与恢复 BookStack 备份 BookStack 恢复 BookStack
更新 BookStack
总结

配置 PHP-FPM
配置 Nginx

备份 BookStack
恢复 BookStack

BookStack 是一个自托管的开源平台，易于使用，可用于组织和存储信息。它可用于多种用途，例如 Wiki、文档网站和笔记应用。它基于 Laravel PHP 框架构建，并使用 MySQL 存储数据。在编辑方面，它提供在 WYSIWYG（所见即所得）编辑器与 Markdown 编辑器之间进行选择的功能。它支持多因素认证和深色模式，并且是多语言的。

本教程将教你如何在基于 Ubuntu 20.04 的服务器上安装 BookStack。

准备工作

一台运行 Ubuntu 20.04 的服务器
一个指向该服务器的完全限定域名（FQDN）。
一个具有 sudo 权限的非 root 用户。
PHP 7.3 或更高版本。
MySQL>=5.6 且 MariaDB>=10.0
Git 和 Composer。

第 1 步 - 配置防火墙

第一步是配置防火墙。Ubuntu 默认自带 ufw（Uncomplicated Firewall，简易防火墙）。

检查防火墙是否正在运行。

$ sudo ufw status

你应该会看到类似以下输出。

Status: inactive

允许 SSH 端口，以免启用防火墙时中断当前连接。

$ sudo ufw allow OpenSSH

同时允许 HTTP 和 HTTPS 端口。

$ sudo ufw allow 80
$ sudo ufw allow 443

启用防火墙

$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

再次检查防火墙状态。

$ sudo ufw status

你应该会看到类似的输出。

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80                         ALLOW       Anywhere
443                        ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80 (v6)                    ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)

第 2 步 - 安装 Git

第一步是安装 Git。下载和更新 BookStack 都需要它。运行以下命令安装 Git。

$ sudo apt install git

验证安装。

$ git --version

第 3 步 - 安装 PHP 及扩展

由于 BookStack 依赖于 PHP，你需要安装 PHP 及其扩展。

Ubuntu 自带的 PHP 版本较旧。首先，我们需要添加 Ondrej 的 PHP 仓库。

$ sudo add-apt-repository ppa:ondrej/php

接下来，安装 BookStack 所需的 PHP 及其扩展。

$ sudo apt install php7.4-fpm php7.4-mbstring php7.4-gd php7.4-xml unzip php7.4-bcmath php7.4-curl php7.4-mysql

验证安装。

$ php --version
PHP 7.4.25 (cli) (built: Oct 22 2021 12:34:33) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.25, Copyright (c), by Zend Technologies

第 4 步 - 安装并配置 MariaDB

Ubuntu 自带的 MariaDB 版本较旧。要安装最新版本，请添加官方 MariaDB 仓库。运行以下命令添加该仓库。

$ curl -LsS -O https://downloads.mariadb.com/MariaDB/mariadb_repo_setup
$ sudo bash mariadb_repo_setup --mariadb-server-version=10.6

运行以下命令安装 MariaDB 服务器。

$ sudo apt install mariadb-server

加固 MariaDB 安装。

$ sudo mysql_secure_installation

你会遇到各种提示。请按如下方式回答。

Enter current password for root (enter for none): Press Enter
Switch to unix_socket authentication [Y/n] Type y
Change the root password? [Y/n] Type n
Remove anonymous users? [Y/n] Type y
Disallow root login remotely? [Y/n] Type y
Remove test database and access to it? [Y/n] Type y
Reload privilege tables now? [Y/n] Type y

使用以下命令连接到 MariaDB shell。

$ sudo mysql

为 BookStack 创建一个新数据库。

$ create database bookstack;

创建一个新数据库用户。

$ CREATE USER 'bookstackuser'@'localhost' identified by 'bookstackpassword';

选择一个强密码。

将该数据库的权限授予该用户。

$ grant CREATE,ALTER,SELECT,INSERT,UPDATE,DELETE on `bookstack`.* to 'bookstackuser'@'localhost';

退出 MySQL shell。

$ exit

第 5 步 - 安装 Composer

Composer 是 PHP 的依赖管理工具，BookStack 所基于的 Laravel 需要它。

下载 Composer 安装脚本。

$ curl -sS https://getcomposer.org/installer -o composer-setup.php

运行以下命令验证安装程序。

$ HASH=`curl -sS https://composer.github.io/installer.sig`
$ echo $HASH
$ php -r "if (hash_file('SHA384', 'composer-setup.php') === '$HASH') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

以上命令会获取安装程序的哈希值，并将其与你下载的脚本进行比对。如果安装程序可以安全运行，你应该会看到以下输出。

Installer verified

安装 Composer。

$ sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

通过查看其版本来验证安装。

$ composer --version
Composer version 2.1.9 2021-10-05 09:47:38

第 6 步 - 下载并安装 BookStack

为 BookStack 应用创建根目录文件夹。

$ sudo mkdir -p /var/www/bookstack

将 /var/www/bookstack 目录的所有权更改为当前登录的用户。

$ sudo chown -R $USER:$USER /var/www/bookstack

将 BookStack Github 仓库的 release 分支克隆到新创建的文件夹中。

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

不要遗漏 clone 命令末尾的点号。它确保所有文件都被下载到当前目录，而不是创建一个新目录。

从 /var/www/bookstack 目录运行 Composer 安装程序。

$ composer install --no-dev

将 .env.example 文件复制为 .env，以存储安装所需的环境变量。

$ cp .env.example .env

打开该文件进行编辑。

$ sudo nano .env

填写应用 URL 和数据库信息。如果你打算使用邮件功能，请填写 SMTP 信息，否则将其从文件中删除。

APP_URL=https://example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstackuser
DB_PASSWORD=bookstackpassword

完成后按 Ctrl + X，并在提示时输入 Y 保存文件。还有更多设置可以配置。要了解更多信息，请打开 .env.example.complete 文件，并将你需要的设置复制到你的 .env 文件中。

生成唯一的应用密钥。该值会自动填入 .env 文件。输入 yes 以继续执行该命令。

$ php artisan key:generate
**************************************
*     Application In Production!     *
**************************************

 Do you really wish to run this command? (yes/no) [no]:
 > yes

Application key set successfully.

更新数据库。

$ php artisan migrate
**************************************
*     Application In Production!     *
**************************************

 Do you really wish to run this command? (yes/no) [no]:
 > yes
Migration table created successfully.
Migrating: 2014_10_12_000000_create_users_table
Migrated:  2014_10_12_000000_create_users_table (0.12 seconds)
.......

第 7 步 - 安装 Let's Encrypt SSL

要使用 Let's Encrypt 安装 SSL 证书，我们需要安装 Certbot 工具。

我们将使用 Snapd 软件包安装器来完成。大多数 Ubuntu 服务器默认不自带 Snap 工具。为此，请安装 Snap。

$ sudo apt install snapd

确保你的 Snapd 版本是最新的。

$ sudo snap install core 
$ sudo snap refresh core

安装 Certbot。

$ sudo snap install --classic certbot

使用以下命令，通过创建指向 /usr/bin 目录的符号链接，确保 Certbot 命令可以运行。

$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

验证安装。

$ certbot --version
certbot 1.20.0

生成 SSL 证书。

$ sudo certbot certonly --standalone --agree-tos --preferred-challenges http -m 
[email protected]
 -d example.com

以上命令会将证书下载到服务器上的 /etc/letsencrypt/live/etherpad.example.com 目录。

生成 Diffie-Hellman 组证书。

$ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

为 Let's Encrypt 自动续期创建验证用的 web 根目录。

$ sudo mkdir -p /var/lib/letsencrypt

创建一个用于续期 SSL 的 Cron 任务。它会每天运行以检查证书并在需要时续期。为此，首先创建文件 /etc/cron.daily/certbot-renew 并打开进行编辑。

$ sudo nano /etc/cron.daily/certbot-renew

粘贴以下代码。

#!/bin/sh
certbot renew --cert-name bookstack.example.com --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"

按 Ctrl + X，并在提示时输入 Y 保存文件。

更改任务文件的权限，使其可执行。

$ sudo chmod +x /etc/cron.daily/certbot-renew

第 8 步 - 安装并配置 Nginx

Ubuntu 自带的 Nginx 版本较旧。要安装最新版本，你需要下载官方 Nginx 仓库。

添加 Nginx 稳定版的仓库。

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

安装 Nginx。

$ sudo apt install nginx

验证安装。

$ nginx -v
nginx version: nginx/1.20.1

启用 Nginx 服务。

$ sudo systemctl enable nginx

配置 PHP-FPM

打开文件 /etc/php/7.4/fpm/pool.d/www.conf 。

$ sudo nano /etc/php/7.4/fpm/pool.d/www.conf

我们需要将 PHP 进程的 Unix 用户/组设置为 nginx。在文件中找到 user=www-data 和 group=www-data 这两行，并将它们修改为 nginx。

...
; Unix user/group of processes
; Note: The user is mandatory. If the group is not set, the default user's group
;       will be used.
user = nginx
group = nginx
...

同时，在文件中找到 listen.owner=www-data 和 listen.group=www-data 这两行，并将它们修改为 nginx。

listen.owner = nginx
listen.group = nginx

按 Ctrl + X，并在提示时输入 Y 保存文件。

重启 PHP-fpm 进程。

$ sudo systemctl restart php7.4-fpm

配置 Nginx

创建并打开文件 /etc/nginx/conf.d/bookstack.conf 进行编辑。

$ sudo nano /etc/nginx/conf.d/bookstack.conf

在其中粘贴以下代码。

server {
    listen       443 ssl http2;
    listen       [::]:443 ssl http2;
    server_name  bookstack.example.com;

    access_log  /var/log/nginx/bookstack.access.log;
    error_log   /var/log/nginx/bookstack.error.log;
    
    ssl_certificate      /etc/letsencrypt/live/bookstack.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/bookstack.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/bookstack.example.com/chain.pem;

    ssl_session_timeout  5m;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;

    root /var/www/bookstack/public;
    index index.php index.html;

    location / {
      try_files $uri $uri/ /index.php?$query_string;
    }
  
    location ~ \.php$ {
      fastcgi_split_path_info ^(.+\.php)(/.+)$;
      include fastcgi_params;
      fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
      fastcgi_param PATH_INFO $fastcgi_path_info;
      fastcgi_pass unix:/run/php/php7.4-fpm.sock;
    }
}

# enforce HTTPS
server {
    listen       80;
    listen       [::]:80;
    server_name  bookstack.example.com;
    return 301   https://$host$request_uri;
}

完成后按 Ctrl + X，并在提示时输入 Y 保存文件。

打开文件 /etc/nginx/nginx.conf 进行编辑。

$ sudo nano /etc/nginx/nginx.conf

在 include /etc/nginx/conf.d/*.conf; 这一行之前添加以下行。

server_names_hash_bucket_size  64;

按 Ctrl + X，并在提示时输入 Y 保存文件。再次验证 Nginx。

验证 Nginx 配置文件的语法。

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

最后，启动 Nginx 服务以启用新配置。

$ sudo systemctl start nginx

将该目录的所有权更改为 nginx 用户，以便 Web 服务器能够访问并向该文件夹写入。

$ sudo chown -R nginx:nginx /var/www/bookstack