技术

BookStack 搭建

2026年2月15日域主留下评论

BookStack 是一个基于PHP Laravel的文档网站应用程序，主要特点是采用了Material Design的UI外观，具有书籍（单行手册）与书架（收藏专栏）两种文档的管理概念，以及便于编辑的在线编辑器界面。

本文以Webinoly提供的LNMP环境，记录安装BookStack的过程。

目前，安装BookStack要求的配置是：

命令行访问权限 并安装 gnupg git unzip curl 软件包
PHP 版本>= 8.2
- 需要在命令行执行php命令的权限
- 要求开启的PHP扩展：gd, dom, iconv, mbstring, mysqlnd, openssl, pdo, pdo_mysql, tokenizer, xml, zip
- 可选扩展：ldap （用于 LDAP 身份验证），exif （用于图像处理）
- 对于PHP MySQL数据库驱动，首选 nd (Native Driver) 扩展，否则使用默认 mysql 驱动扩展。
MySQL 版本>= 8.0 或MariaDB 版本>= 10.6
- 用于存储 BookStack 内容和数据
- 建议单独创建拥有所有权限的单个数据库
Git 用于下载与更新
Composer 版本>= v2.2.0 用于安装和管理依赖项
兼容 PHP 的 Web 服务器 例如 Nginx

创建网站

先通过Webinoly的site命令创建PHP网站、及其对应目录与数据库。顺带配置SSL证书：

site domain.ltd -php -mysql
site domain.ltd -ssl=on 
# 可选：自定义证书参数 -ssl-crt=[证书位置] -ssl-key=[证书私钥位置]

手动安装

前往 /var/www/domain.ltd/ 目录，克隆BookStack的Git存储库：

cd /var/www/domain.ltd/ 
git clone https://source.bookstackapp.com/bookstack.git --branch release --single-branch bookstack

进入bookstack目录，执行Composer安装：

cd ./bookstack
composer install --no-dev

基本配置

基于.env.example 模板复制，创建 .env 配置文件，填入网址和数据库信息：

# Application URL
APP_URL=https://example.com

# Database details
DB_HOST=localhost
DB_DATABASE=database_database
DB_USERNAME=database_username
DB_PASSWORD=database_user_password

后续可通过命令 php artisan bookstack:update-url 更新应用网址也就是APP_URL：

随后在终端执行生成应用密钥的命令：

php artisan key:generate

配置Nginx

下文的Nginx配置，以book.lan域名并以HTTP（仅80端口）访问为例：

# WebinolyNginxServerStart
server {
	listen 80;
	listen [::]:80;

	server_name book.lan;

	access_log /var/log/nginx/book.lan.access.log we_log;
	error_log /var/log/nginx/book.lan.error.log;

	root /var/www/book.lan/bookstack/public;

	index index.php index.html index.htm;

	include common/auth.conf;

	# WebinolyCustom
	  location / {
	    try_files $uri $uri/ /index.php?$query_string;
	  }
  
	  location ~ \.php$ {
	    include fastcgi_params;
	    fastcgi_pass unix:/run/php/php-fpm.sock;
	  }
	# WebinolyCustomEnd

	#include common/phpx.conf;
	include common/locations.conf;
	include common/header.conf;
	include /var/www/book.lan/*-nginx.conf;
	include /etc/nginx/conf.d/*.conf.srv;
}

分析：

Webinoly默认的php配置 include common/phpx.conf;
不适用Bookstack要求的query_string，需要将其注释而不调用。

官方文档位于 location ~ \.php$ { 部分的配置行： include snippets/fastcgi-php.conf;
也不适用于目前Webinoly安装的配置（没有这个目录与文件），不然会无法调用PHP FastCGI导致白屏。

取而代之的是：include fastcgi_params;
后者文件实际位置位于nginx目录根。