基于 Laravel 开源项目 BookStack 构建知识管理与服务平台

项目简介

BookStack 是一个开源的、基于 Laravel + Vue.js 构建的知识管理和服务项目，我们可以基于它来快速构建文档、教程、wiki 管理系统，该项目开发过程中使用了以下技术栈：

• Laravel
• TinyMCE（富文本编辑器）
• CodeMirror（文本编辑器，适用于编辑代码）
• Vue.js
• Sortable & Vue.Draggable（排序和拖拽组件）
• Google Material Icons
• Dropzone.js（带预览功能的文件拖拽上传组件）
• clipboard.js（将文本复制到剪贴板）
• markdown-it & markdown-it-task-lists（Markdown 组件）
• BarryVD 提供的扩展包：Debugbar、Dompdf、Snappy (WKHTML2PDF)、Laravel IDE helper
• WKHTMLtoPDF（将 HTML 转化为 PDF）
• Draw.io（在线图表绘制应用）
• Laravel Stats

另外，该项目基于 PHP 7.0.5+ 和 MySQL 5.6+ 开发，安装使用前需要确保服务器环境具备这两个符合版本要求的软件。下面我们以本地 MacOS + Homestead 开发环境为例演示下 BookStack 的安装、配置和使用。

环境准备

首先在本地克隆 Github 项目代码到本地：

git clone https://github.com/BookStackApp/BookStack

然后进入项目根目录，通过 Composer 安装 PHP 依赖：

cd BookStack
composer install

再通过 NPM 安装前端依赖并编译前端资源：

npm install
npm run dev

以 .env.example 为模板创建环境配置文件 .env：

cp .env.example .env

通过 Artisan 命令生成应用密钥：

php artisan key:generate

再对开发环境数据库和邮箱进行配置：

APP_URL=https://bookstack.test

DB_HOST=127.0.0.1
DB_DATABASE=bookstack
DB_USERNAME=homestead
DB_PASSWORD=secret

MAIL_DRIVER=smtp

MAIL_HOST=smtp.163.com
MAIL_PORT=465
MAIL_USERNAME=youremail
MAIL_PASSWORD=yourpasswd
MAIL_ENCRYPTION=tls

此外，如果是在生产环境还要确保 storage、bootstrap/cache、public/uploads 这几个目录具备写权限，本地开发可以忽略。

最后，打开 Homestead 项目下的 Homestead.yaml 对虚拟机环境进行配置，和上篇教程一样，分别需要配置目录映射、Nginx 站点、数据库：

folders:
    ...
    - map: ~/Devlopment/php/laravel/BookStack
      to: /home/vagrant/bookstack

sites:
    ...
    - map: bookstack.test
      to: /home/vagrant/bookstack/public

databases:
    ...
    - bookstack

然后通过如下命令重启虚拟机让上述配置生效：

vagrant reload --provision

通过 homestead ssh 登录到虚拟机，进入项目根目录运行数据库迁移：

cd ~/bookstack
php artisan migrate

在宿主机 /etc/hosts 中配置域名映射：

192.168.10.10 bookstack.test 

然后信任 bookstack 站点证书（参考上篇教程设置方法），即可通过 https://bookstack.test 访问应用了。

使用入门

上面运行数据库迁移时，已经对数据库数据进行了初始化，所以我们可以通过 admin@admin.com/password 登录：

登录成功后即可访问应用首页：

接下来，咱们可以点击右上角用户名，在下拉框里面点击编辑用户资料链接，进入编辑页面对用户信息进行修改，比如用户名、密码、头像、首选语言等：

将首选语言设置为「简体中文」后即可看到中文界面：

接下来，我们可以在「书架」页面创建新「书架」：

在「图书」页面创建新的图书：

然后我们可以为这个图书创建页面和章节：

默认编辑器是富文本编辑器，我们可以在「设置」页面将其调整为「Markdown」：

然后我们来为「Laravel 6.0 中文文档」创建一个「目录索引」页面：

编辑完成后点击右上角「保存页面」进行保存，就会跳转到刚刚创建的「目录索引」页面：

然后咱们为「Laravel 6.0 中文文档」新建章节「序言」：

创建完成后为章节新增页面「新版特性」：

保存页面，跳转到「新版特性」详情页：

依次类推，将序言下的其他页面添加进来，完成一个章节的编写，再按照这个方式继续创建其它章节，直到把所有的 Laravel 6.0 中文文档维护进来。

最后我们回到书架，编辑「文档」这个书架，把「Laravel 6.0 中文文档」这本书添加进来：

就可以在书架「文档」列表中看到这本书了。