BookStack 是一款极易上手且完全免费的 Wiki 系统。前段时间做 Wiki 系统的选型时发现非常好用,不同于 Wiki.js,MediaWiki,DokuWiki,Outline,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 版本为例。
-
从 php 的官方网站下载安装源码包 - php-8.0.20.tar.gz
-
解压安装包
tar -zxvf php-8.0.20.tar.gz
- 配置
这一步我们需要指定在文档最开始提到的 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
对于其它可能出现的报错采用类似的解决办法即可。
- 编译安装
make
sudo make install
- 创建配置文件
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
- 检查安装是否成功
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
- 修改配置文件
打开 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
- 启动 php-fpm 服务
/usr/local/bin/php-fpm
至此完成了 PHP 8.0.20 版本的安装。
MySQL
以 MySQL 5.7.38 版本为例。
- 检查是否已安装 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。
否则,进入下面的安装步骤。
- 下载官方 MySQL 包
wget -i -c http://dev.mysql.com/get/mysql57-community-release-el7-10.noarch.rpm
- 安装
yum -y install mysql57-community-release-el7-10.noarch.rpm
这一步的安装过程一般需要几分钟,耐心等待吧。
- 启动 MySQL 服务
systemctl start mysqld.service
- 查看 MySQL 运行状态
service mysqld status
- 查询 MySQL 的初始密码
grep 'password' /var/log/mysqld.log
- 修改初始密码 进入数据库,这里要输入初始密码。
mysql -u root -p
修改初始密码。
ALTER USER USER() IDENTIFIED BY 'XXXX';
退出数据库。
exit;
用新的密码重新进入数据库。
mysql -u root -p
- 允许远程登录 进入数据库,依次执行下面的命令。
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
-
从代码仓库克隆 BookStack 代码
-
进入应用根目录,执行下面的命令安装 php 依赖
composer install --no-dev
- 拷贝 .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
- 生成应用唯一 key 在应用根目录执行下面的命令。
php artisan key:generate
- 更新数据库 在应用根目录执行下面的命令。
php artisan migrate
到这里,我们就在服务器上完成了对 BookStack 的手动部署。
接下来,打开浏览器,输入配置好的应用 URL,输入默认的用户名 admin@admin.com 和密码 password 就能打开页面啦。