BookStack 手动部署手册

599 阅读4分钟

image.png

BookStack 是一款极易上手且完全免费的 Wiki 系统。前段时间做 Wiki 系统的选型时发现非常好用,不同于 Wiki.jsMediaWikiDokuWikiOutline,BookStack 是 MIT 许可证,方便二次开发后商用。

BookStack 是 php 技术栈,做为前端开发的我完全没了解,因为有定制化的需求,需要改源码导致无法使用 Docker 部署方案 ,只得从零开始进行手动部署。官方的手动部署方案不是很详细,中间遇到了很多问题,特此记录下来。

必要条件

BookStack 依赖如下组件:

  • PHP >= 7.4
    为了便于安装和维护,需要能够从命令行运行 php;
    所需扩展:OpenSSL, PDO, MBstring, Tokenizer, GD, MySQL, SimpleXML 和 DOM。
  • MySQL >= 5.7 or MariaDB >= 10.2
    用于存储 BookStack 的内容和数据。
  • Composer >= v2.0
    用于安装和管理 PHP 依赖。
  • 兼容 PHP 的 Web 服务器 - NGINX

下面会详细介绍各组件的安装。

PHP

以 PHP 8.0.20 版本为例。

  1. 从 php 的官方网站下载安装源码包 - php-8.0.20.tar.gz

  2. 解压安装包

tar -zxvf php-8.0.20.tar.gz
  1. 配置 这一步我们需要指定在文档最开始提到的 php 扩展,运行 ./configure --help 命令可以获得完整的可用选项清单。
cd php-8.0.20

./configure --enable-fpm --with-curl --with-openssl --enable-mbstring --with-pdo-mysql --enable-gd --with-zlib

注意:执行 ./configure 命令可能会出现不限于下面的错误。

configure: error: Package requirements (libxml-2.0 >= 2.9.0) were not met:

No package 'libxml-2.0' found

解决办法:执行命令 yum install libxml2-devel

configure: error: Package requirements (sqlite3 > 3.7.4) were not met:

No package 'sqlite3' found

解决办法:执行命令 yum install sqlite-devel

对于其它可能出现的报错采用类似的解决办法即可。

  1. 编译安装
make
sudo make install
  1. 创建配置文件
cp php.ini-development /usr/local/php/php.ini
cp /usr/local/etc/php-fpm.d/www.conf.default /usr/local/etc/php-fpm.d/www.conf
cp /usr/local/etc/php-fpm.conf.default /usr/local/etc/php-fpm.conf
cp sapi/fpm/php-fpm /usr/local/bin
  1. 检查安装是否成功
php -v

出现下面的信息表示安装成功。

PHP 8.0.20 (cli) (built: Jun 27 2022 10:06:36) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.0.20, Copyright (c) Zend Technologies

  1. 修改配置文件 打开 php.ini 并定位到 cgi.fix_pathinfo= 并将其修改为如下所示:
cgi.fix_pathinfo=0

执行下面的命令添加用户和所属组:

adduser www-data
groupadd www-data

打开 php-fpm.conf,找到以下内容并修改:

; 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 = www-data
group = www-data
  1. 启动 php-fpm 服务
/usr/local/bin/php-fpm

至此完成了 PHP 8.0.20 版本的安装。

MySQL

以 MySQL 5.7.38 版本为例。

  1. 检查是否已安装 MySQL
rpm -qa | grep mysql

如果已安装会出现下面的信息:

mysql-community-common-5.7.38-1.el7.x86_64
mysql57-community-release-el7-10.noarch
mysql-community-libs-5.7.38-1.el7.x86_64
mysql-community-libs-compat-5.7.38-1.el7.x86_64
mysql-community-server-5.7.38-1.el7.x86_64
mysql-community-client-5.7.38-1.el7.x86_64

确认版本是否 >= 5.7。

否则,进入下面的安装步骤。

  1. 下载官方 MySQL 包
wget -i -c http://dev.mysql.com/get/mysql57-community-release-el7-10.noarch.rpm
  1. 安装
yum -y install mysql57-community-release-el7-10.noarch.rpm

这一步的安装过程一般需要几分钟,耐心等待吧。

  1. 启动 MySQL 服务
systemctl start mysqld.service
  1. 查看 MySQL 运行状态
service mysqld status
  1. 查询 MySQL 的初始密码
grep 'password' /var/log/mysqld.log
  1. 修改初始密码 进入数据库,这里要输入初始密码。
mysql -u root -p

修改初始密码。

ALTER USER USER() IDENTIFIED BY 'XXXX';

退出数据库。

exit;

用新的密码重新进入数据库。

mysql -u root -p
  1. 允许远程登录 进入数据库,依次执行下面的命令。
use mysql;
update user set host = '%' where user = 'root';
FLUSH PRIVILEGES;

至此完成了 MySQL 5.7.38 版本的安装。

Composer

直接执行下面的命令进行安装。

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === '55ce33d7678c5a611085589f1f3ddf8b3c52d662cd01d4ba75c0ee0459970c2200a51f492d557530c71c15d8dba01eae') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"

执行下面的命令,保证 Composer 全局可用。

sudo mv composer.phar /usr/local/bin/composer

至此完成了 Composer 的安装。

NGINX

NGINX 作为服务器基础组件一般都有安装,这里就不再赘述。

但是,为了能让 BookStack 这样的 php 项目在 nginx 中正常运行,需要对 nginx 配置进行修改。

server {
  listen 8080;
  listen [::]:8080;

  server_name localhost;

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

  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }

  location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param SCRIPT_NAME $fastcgi_script_name;
    include fastcgi_params;
  }
}

保存配置文件并重启 nginx 服务。

开始安装 BookStack

  1. 从代码仓库克隆 BookStack 代码

  2. 进入应用根目录,执行下面的命令安装 php 依赖

composer install --no-dev
  1. 拷贝 .env.example 到 .env 并更新配置信息
# Application URL
# 修改默认的 URL
APP_URL=https://example.com

# Application timezone
# 设置时区为 亚洲/上海
APP_TIMEZONE=Asia/Shanghai

# Application default language
# 设置语言为 中文
APP_LANG=zh_CN

# Database details
# 这里修改成服务器上 MySQL 的连接信息
DB_HOST=localhost
DB_DATABASE=database_database
DB_USERNAME=database_username
DB_PASSWORD=database_user_password
  1. 生成应用唯一 key 在应用根目录执行下面的命令。
php artisan key:generate
  1. 更新数据库 在应用根目录执行下面的命令。
php artisan migrate

到这里,我们就在服务器上完成了对 BookStack 的手动部署。

接下来,打开浏览器,输入配置好的应用 URL,输入默认的用户名 admin@admin.com 和密码 password 就能打开页面啦。