Linux(Ubuntu)下安装和部署BookStack

大家常遇到的问题，我这边放在前面！

1. 如果您无任何技术基础，不建议安装和部署bookstack，以免浪费您的时间！！！
2. 安装部署的时候，强烈建议在非root用户下进行部署！！！
3. 给程序所在目录下的cache和store给予读写权限，以免图片等验证码无法正常显示等情况！！！
4. calibre极易由于下载失败而无法安装成功，根据您用calibre官方提供的脚本安装下载失败的版本，到GitHub（https://github.com/kovidgoyal/calibre/releases ）下载该版本放到/tmp/calibre-installer-cache目录下，再重复执行一次即可。
5. BookStack不是一定要依赖阿里云OSS！！！
6. 如果不需要全文搜索，服务器最低配置建议2C4G；如果需要全文搜索，请安装elasticsearch，并在管理后台进行配置，此时服务器最低配置建议在4C8G。

安装宝塔控制面板(非必须)

如果你已经有lnmp环境了，则不需要安装。

宝塔官网：http://www.bt.cn

安装命令：

1. wget -O install.sh http://download.bt.cn/install/install-ubuntu.sh && sudo bash install.sh

安装完宝塔控制面板之后，登录面板，安装”lnmp”（Linux、Nginx、MySQL、PHP）

安装默认的即可

安装宝塔面板，主要是为了方便管理站点，如反向代理、SSL等

安装中文字体（非必须，但是建议安装）

有的Linux服务器并没有支持中文字体，需要手动安装。

安装命令：

1. sudo apt install ttf-wqy-zenhei
2. sudo apt install fonts-wqy-microhei

安装中文字体支持，主要是为了避免Linux系统不支持中文的时候，导致导出文档的时候出现乱码。

安装Chrome(非必须)

直接使用命令一键安装：

1. sudo apt install chromium-browser

执行以下命令，如果能打印百度页面代码，则表示安装成功。

1. chromium-browser --headless --disable-gpu --dump-dom --no-sandbox https://www.baidu.com

这个主要用于在发布文档的时候，渲染未被渲染的markdown文档，以及强力模式下的网页采集。 安装chrome，是为了兼容以前的问题，并且自动安装puppeteer的一些chrome浏览器依赖。

安装puppeteer

这个主要用于在发布文档的时候，渲染未被渲染的markdown文档、渲染自定义封面、以及强力模式下的网页采集。

1. sudo apt install nodejs npm
2. sudo npm install -g n
3. sudo n stable
4. sudo npm install -g cnpm
5. sudo cnpm install puppeteer@2.0

注：

1. n是一个安装升级node.js的模块，用来升级node.js最新的稳定版
2. puppeteer要安装 2.0 的版本。这个当时2019年的时候最新的版本还只是2.0版本，现在这个版本帝已经更新到了16.2.0的版本了….

安装calibre

calibre官网：https://www.calibre-ebook.com/

安装命令：

1. sudo -v && wget -nv -O- https://download.calibre-ebook.com/linux-installer.py | sudo python -c "import sys; main=lambda:sys.stderr.write('Download failed\n'); exec(sys.stdin.read()); main()"

执行下面命令，能看到版本号，表示安装成功。

1. ebook-convert --version

注意：

• 这里要安装最新版的calibre，执行上述命令，安装的就是最新版的了。
• 如果出现warning的提示，直接不用理会即可;error级别的提示，网上搜下看下如何解决

calibre主要用于将文档导出生成pdf、epub、mobi文档。

本人已经使用Go语言对calibre导出pdf、epub、mobi文档进行了一层封装，欢迎大家给个star ==》https://github.com/TruthHun/converter

测试

随便创建一个txt文件

1. echo "Hello BookStack。你好，书栈。" > test.txt

转成pdf

1. ebook-convert test.txt test.pdf

查看测试的转化效果，主要看下转化的过程中有没有报错，以及转化后的文档有没有出现中文乱码。

安装Git

使用 git clone 的方式导入项目的时候需要使用git

1. sudo apt install git

安装supervisor

安装命令：

1. sudo apt install supervisor

判断是否安装成功:

1. supervisord --version

显示版本号，即表示安装成功。

supervisor主要用于将程序加入到系统守护进程

Supervisord 安装完成后有两个可用的命令行 supervisord 和 supervisorctl，命令使用解释如下：

• supervisord，初始启动 Supervisord，启动、管理配置中设置的进程。
• supervisorctl stop programxxx，停止某一个进程(programxxx)，programxxx 为 [program:beepkg] 里配置的值，这个示例就是 beepkg。
• supervisorctl start programxxx，启动某个进程
• supervisorctl restart programxxx，重启某个进程
• supervisorctl stop groupworker: ，重启所有属于名为 groupworker 这个分组的进程(start,restart 同理)
• supervisorctl stop all，停止全部进程，注：start、restart、stop 都不会载入最新的配置文件。
• supervisorctl reload，载入最新的配置文件，停止原有进程并按新的配置启动、管理所有进程。
• supervisorctl update，根据最新的配置文件，启动新配置或有改动的进程，配置没有改动的进程不会受影响而重启。

部署程序

下载Linux版的程序

https://github.com/TruthHun/BookStack/releases

先行版用户的下载地址：https://github.com/TruthHun/BookStack-x/releases

在本地解压，修改配置文件

配置文件在conf目录。

配置项可能因版本不同而不同，所以请直接根据配置文件中的配置说明进行配置，以下配置仅供参考！

注意：conf文件夹下的 xxx.conf.example 的文件，需要全部修改为 xxx.conf 的文件。.example后缀的，只是作为示例配置！！！

配置数据库和文档导出项

把app.conf.example命名为app.conf,并根据提示，修改配置。

这里主要修改MySQL数据库的配置以及生成下载文档的配置。其他项能不改就不改。

1. # 程序名称
2. appname = BookStack
4. # 微信小程序 appid
5. appId=""
7. # 微信小程序appSecret
8. appSecret=""
10. # 是否限制API请求，也就是如果不是上述配置的微信小程序的appId请求的接口，则直接拒绝
11. limitReferer=false
13. # API 路由前缀，默认为 bookchat。API访问形式：https://您的域名/bookchat/api/v1/xxx
14. # 比如您把api前缀改为了 hello，则您在 BookChat 或者 BookChatApp 中，需要把 config.js 中的 host 常量配置为 https://您的域名/hello
15. apiPrefix=bookchat
17. # 是否显示小程序阅读码（需要配置了appScecret才会生效）
18. showWechatCode = false
20. # 比如你将static目录下的所有静态资源都放到了专门的服务器上，那么这个域名就行用来访问你的静态资源的域名。否则建议填写web网站的域名
21. # 如果您部署了微信小程序，则该值一定要填写。如填写：https://www.bookstack.cn
22. static_domain=
24. # 监听端口
25. httpport = 8181
27. # 运行模式。开发时，请设置为开发模式"dev"，即development；部署时，请设置为产品模式"prod"，即product。dev模式下，会打印各种调试信息
28. runmode = prod
30. # 是否开启session，这个必须开启，否则没法玩了。
31. sessionon = true
33. # session名称，这个你自己定。
34. sessionname = bookstack
35. copyrequestbody = true
37. # 启动gzip压缩，则设置为true，否则设置为false。建议启动
38. EnableGzip=true
40. # 要压缩的静态文件扩展名，其中.xml是sitemap站点地图压缩。建议按照这个来就行了
41. StaticExtensionsToGzip = .css, .js, .xml
43. #站点地图host（主要用于使用CDN的时候，host与实际host不一样，导致生成的sitemap不一样）
44. sitemap_host=www.bookstack.cn
46. # 默认Session生成Key的秘钥
47. beegoserversessionkey=bookstack
49. ########Session储存方式##############
50. #以文件方式储存
51. sessionprovider=file
52. sessionproviderconfig=store/session
54. # 静态目录。这个是站点地图的静态目录
55. StaticDir = sitemap:sitemap
58. # 站点可直接访问的静态文件【注意，这里千万不能配置.conf文件扩展名，否则会把.conf文件当做静态文件而被外部访问，导致数据库账号密码等泄露。按照默认的来即可】
59. StaticExt=.txt,.xml,.ico,.png,.jpg,.jpeg,.gif,.html
61. #评论时间间隔，每次发表评论，限定间隔秒数，避免被恶意刷评论
62. CommentInterval=10
64. # 生成下载文档时导出pdf文档的配置，这里建议把关于bookstack.cn的信息替换成你自己的就行，其他的建议不要动
65. exportHeader=<p style='color:#8E8E8E;font-size:12px;'>_SECTION_</p>
66. exportFooter=<p style='color:#8E8E8E;font-size:12px;'>本文档使用 <a href='http://www.bookstack.cn' style='text-decoration:none;color:#1abc9c;font-weight:bold;'>书栈(BookStack.CN)</a> 构建 <span style='float:right'>- _PAGENUM_ -</span></p>
67. exportFontSize=13
68. exportPaperSize=a4
69. exportCreator=书栈(BookStack.CN)
70. exportMarginLeft=36
71. exportMarginRight=36
72. exportMarginTop=36
73. exportMarginBottom=36
74. # 是否使用自定义的电子书封面，如果使用，则需要安装并启用puppeteer，否则不生效
75. exportCustomCover=true
78. ####################MySQL 数据库配置###########################
79. db_adapter=mysql
81. # 您的数据库host
82. db_host=
84. #您的数据库端口
85. db_port=3306
87. #您的数据库用户名
88. db_username=
90. # 您的数据库密码
91. db_password=
93. # utf8或者utf8mb4数据库。如果数据库还没创建，并且账号有创建权限，将自动创建。
94. db_database=bookstack
96. # 谷歌浏览器，用于发布内容的时候渲染未被渲染的markdown。建议安装最新版的Chrome浏览器，并把Chrome浏览器加入系统环境变量。
97. # 使用Chrome的headless去处理。之前考虑使用phantomjs的，但是phantomjs有些小问题，不如Chrome强大。
98. # chrome=chromium-browser
99. chrome=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
101. # 如果使用 puppeteer，则忽略chrome
102. puppeteer = false
104. #项目默认封面
105. cover=/static/images/book.png
107. #默认头像
108. avatar=/static/images/avatar.png
110. #默认阅读令牌长度
111. token_size=12
113. #上传文件的后缀
114. upload_file_ext=txt|doc|docx|xls|xlsx|ppt|pptx|pdf|7z|rar|jpg|jpeg|png|gif
116. ####################邮件配置######################
117. #是否启用邮件
118. enable_mail=true
119. #每小时限制指定邮箱邮件发送次数
120. mail_number=5
121. #smtp服务用户名
122. smtp_user_name=
123. #smtp服务器地址
124. smtp_host=
125. #smtp密码
126. smtp_password=
127. #端口号
128. smtp_port=25
129. #发送邮件的显示名称
130. form_user_name=
132. #接收回件的邮箱。留空则表示使用发送邮件的邮箱作为接收回件邮箱
133. reply_user_name=bookstack@qq.com
135. #邮件有效期30分钟
136. mail_expired=30
139. # 存储类型，后续扩展成本地存储(local)、阿里云OSS存储(oss)、七牛云存储(qiniu)、腾讯云存储(cos)、百度云存储(bos)和又拍云存储(upyun)
140. # 目前可选项：local、oss
141. store_type=local
144. # 不要修改
145. include "oss.conf"
146. include "oauth.conf"

配置OSS(可不配置)

1、登录你的阿里云，进入OSS，创建一个只读Bucket。

2、在本地随便创建一个txt文档，将下面两行粘贴进去：

1. styleName:cover,styleBody:image/resize,m_fill,w_175,h_230,limit_0/auto-orient,1/quality,q_100
2. styleName:avatar,styleBody:image/resize,m_fill,w_100,h_100,limit_0/auto-orient,1/quality,q_90

3、在OSS的图片处理–导入样式中，将该txt文档导入

4、将oss.conf.example修改成oss.conf，并根据您的阿里云OSS，配置该文件。

1. # 阿里云OSS配置
2. [oss]
4. # 是否是内网，如果您的阿里云服务器和OSS是同一内网，请设置为true，这样能更快地将文件移到oss上，否则设置为false。
5. # 一般情况下，在开发阶段，设置为false
6. IsInternal=false
8. # 内网Endpoint,如：oss-cn-hongkong-internal.aliyuncs.com
9. EndpointInternal=
11. # 外网Endpoint，如：oss-cn-hongkong.aliyuncs.com
12. EndpointOuter=
15. # 您的阿里云AccessKeyId
16. AccessKeyId=
18. # 您的阿里云AccessKeySecret
19. AccessKeySecret=
21. # 只读状态的Bucket，不要私有的，也不要公共读写的
22. Bucket=
24. # oss中绑定的域名，如果您没有绑定域名，则使用阿里云oss的自带域名也行
25. Domain=

配置第三方登录(可配置)

将oauth.conf.example重命名成oauth.conf,并根据提示修改配置。

1. # 第三方登录配置
2. [oauth]
4. ##### Gitee(码云) ####
5. # 申请地址（需要先登录）：https://gitee.com/oauth/applications
7. # 您的ClientId
8. giteeClientId=
10. # 您的ClientSecret
11. giteeClientSecret=
13. # 回调地址，把下面的bookstack.cn的域名换成你的即可
14. giteeCallback=http://www.bookstack.cn/login/gitee
16. # 下面这两项不要动
17. giteeAccesstoken=https://gitee.com/oauth/token
18. giteeUserInfo=https://gitee.com/api/v5/user
22. ######## GitHub ########
23. # 申请地址(需要先登录你的GitHub)：https://github.com/settings/developers
25. # 您的ClientId
26. githubClientId=
28. # 您的ClientSecret
29. githubClientSecret=
31. # 回调地址，把下面的bookstack.cn的域名换成你的即可
32. githubCallback=http://www.bookstack.cn/login/github
34. # 下面这两项不要动
35. githubAccesstoken=https://github.com/login/oauth/access_token
36. githubUserInfo=https://api.github.com/user
40. #### QQ ####
41. # 申请地址（需要先登录你的QQ）:https://connect.qq.com/manage.html
43. #ClientId，即 APP ID
44. qqClientId=
46. #ClientSecret，即 APP Key
47. qqClientSecret=
49. # 回调地址，把下面的bookstack.cn的域名换成你的即可
50. qqCallback=http://www.bookstack.cn/login/qq
52. # 下面这三项不要动
53. qqAccesstoken=https://graph.qq.com/oauth2.0/token
54. qqOpenId=https://graph.qq.com/oauth2.0/me
55. qqUserInfo=https://graph.qq.com/user/get_user_info
57. ### TODO 微信和微博登录，主要是我这边忘记了以前注册的个人开发者信息，当前没开发，后续会开发出来 ####

上传和部署

1、将修改和配置好了的程序压缩，上传到站点根目录下，解压。

2、执行数据库安装。程序安装一些站点配置项、SEO项等。命令：

1. ./BookStack install

注意：没有SQL文件，也不需要SQL文件，执行上述命令之后，会自动初始化表结构和数据！！！

3、配置反向代理

宝塔面板用户，直接在站点的设置里面配置反向代理，但是需要注意的是，需要修改缓存，如把下面两句注释掉：

1. add_header X-Cache $upstream_cache_status;
3. expires 12h;

Nginx反向代理配置参考(宝塔的配置)：

1. server
2. {
3. listen 80;
4. server_name demo.bookstack.cn;
5. index index.php index.html index.htm default.php default.htm default.html;
6. root /www/wwwroot/demo.bookstack.cn;
9. location /
10. {
11. proxy_pass http://localhost:8181;
12. proxy_set_header Host $host;
13. proxy_set_header X-Real-IP $remote_addr;
14. proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
15. proxy_set_header REMOTE-HOST $remote_addr;
17. #缓存相关配置
18. #proxy_cache cache_one;
19. #proxy_cache_key $host$request_uri$is_args$args;
20. #proxy_cache_valid 200 304 301 302 1h;
22. #持久化连接相关配置
23. #proxy_connect_timeout 30s;
24. #proxy_read_timeout 86400s;
25. #proxy_send_timeout 30s;
26. #proxy_http_version 1.1;
27. #proxy_set_header Upgrade $http_upgrade;
28. #proxy_set_header Connection "upgrade";
29. }
31. location ~ .*\.(php|jsp|cgi|asp|aspx|flv|swf|xml)?$
32. {
33. proxy_set_header Host $host;
34. proxy_set_header X-Real-IP $remote_addr;
35. proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
36. proxy_set_header REMOTE-HOST $remote_addr;
37. proxy_pass http://localhost:8181;
39. }
40. #PROXY-END
42. include enable-php-54.conf;
43. #PHP-INFO-END
45. #REWRITE-START URL重写规则引用,修改后将导致面板设置的伪静态规则失效
46. include /www/server/panel/vhost/rewrite/demo.bookstack.cn.conf;
47. #REWRITE-END
49. #禁止访问的文件或目录
50. location ~ ^/(\.user.ini|\.htaccess|\.git|\.svn|\.project|LICENSE|README.md)
51. {
52. return 404;
53. }
55. access_log off;
56. }

加入系统守护进行

1、进入supervisor的配置目录

1. cd /etc/supervisor/conf.d/

2、配置守护进程 创建bookstack.conf文件，并配置。

1. [program:BookStack]
2. directory = 你的程序目录
3. command =你的程序执行命令
4. autostart = true
5. autorestart=true
6. user = 启动该程序的用户
7. redirect_stderr = true
8. stdout_logfile = 日志地址

配置示例：

1. [program:BookStack]
2. directory = /www/wwwroot/demo.bookstack.cn
3. command =/www/wwwroot/demo.bookstack.cn/BookStack
4. autostart = true
5. autorestart=true
6. user = root
7. redirect_stderr = true
8. stdout_logfile = /var/log/supervisor/BookStack.log

配置完成之后，重启supervisor

1. supervisorctl reload

默认管理员账号和密码

admin admin

v2.0 正式版开始，默认管理员账号密码调整为：

1. admin
2. admin888

总结

安装BookStack，需要先配置环境，安装依赖：Nginx、MySQL、calibre、chorme（chromium-browser）、supervisor，然后修改配置文件，配置MySQL数据库、OSS和第三方登录，然后上传部署和配置反向代理以及加入守护进程。

感谢您的来访，获取更多精彩文章请收藏。