使用BookStack，搭建你自己的Gitbook或者看云

BookStack，基于MinDoc，使用Beego开发的在线文档管理系统，基于Apache开源协议，功能类似Gitbook和看云。

开源地址：

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

Gitee:https://gitee.com/truthhun/BookStack

下面我们来介绍使用Ubuntu搭建站点。

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

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

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

安装命令：

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

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

安装默认的即可

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

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

有的Linux服务器并没有支持中文字体，需要手动安装。
地址：http://www.hc-cms.com/thread-41-1-1.html

安装命令：

apt install ttf-wqy-zenhei
apt install fonts-wqy-microhei

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

安装calibre

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

安装命令：

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()"

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

ebook-convert --version

注意：

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

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

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

测试

随便创建一个txt文件

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

转成pdf

ebook-covert test.txt test.pdf

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

安装Chrome

直接使用命令一键安装：

apt install chromium-browser

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

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

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

安装supervisor

安装命令：

apt install supervisor

判断是否安装成功:

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

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

配置文件在conf目录。

配置数据库和文档导出项

把app.conf.example命名为app.conf,并根据提示，修改配置。这里主要修改MySQL数据库的配置以及生成下载文档的配置。其他项能不改就不改。

# 程序名称
appname = BookStack

# 程序版本
version = v1.0.0

# 监听端口
httpport = 8181

# 运行模式。开发时，请设置为开发模式"dev"，即development；部署时，请设置为产品模式"prod"，即product。dev模式下，会打印各种调试信息
runmode = dev

# 是否开启session，这个必须开启，否则没法玩了。
sessionon = true

# session名称，这个你自己定。
sessionname = bookstack
copyrequestbody = true

# 启动gzip压缩，则设置为true，否则设置为false。建议启动
EnableGzip=true

# 要压缩的静态文件扩展名，其中.xml是sitemap站点地图压缩。建议按照这个来就行了
StaticExtensionsToGzip = .css, .js, .xml


# 默认Session生成Key的秘钥
beegoserversessionkey=bookstack

########Session储存方式##############
#以文件方式储存
sessionprovider=file
sessionproviderconfig=store/session

# 静态目录。这个是站点地图的静态目录
StaticDir = sitemap:sitemap

#生成下载文档的时间间隔。也就是距离用户第一次点击生成下载文档到第二次点击生成下载文档的时间间隔，避免用户频繁点击生成下载文档而导致大量耗费服务器资源导致服务器宕机
GenerateInterval=300

# 站点可直接访问的静态文件【注意，这里千万不能配置.conf文件扩展名，否则会把.conf文件当做静态文件而被外部访问，导致数据库账号密码等泄露。按照默认的来即可】
StaticExt=.txt,.xml,.ico,.png,.jpg,.jpeg,.gif,.html

#评论时间间隔，每次发表评论，限定间隔秒数，避免被恶意刷评论
CommentInterval=10

# 生成下载文档时导出pdf文档的配置，这里建议把关于bookstack.cn的信息替换成你自己的就行，其他的建议不要动
exportHeader=
_SECTION_
exportFooter=
本文档使用 书栈(BookStack.CN) 构建 - _PAGENUM_ -
exportFontSize=14
exportPaperSize=a4
exportCreator=书栈(BookStack.CN)
exportMarginLeft=72
exportMarginRight=72
exportMarginTop=72
exportMarginBottom=72

#时区设置
timezone = Asia/Shanghai

####################MySQL 数据库配置###########################
db_adapter=mysql

# 您的数据库host
db_host=

#您的数据库端口
db_port=3306

#您的数据库用户名
db_username=

# 您的数据库密码
db_password=

#您使用的数据库
db_database=bookstack



# 静态资源域名，没有则留空。比如你将static目录下的所有静态资源都放到了专门的服务器上，那么这个域名就行用来访问你的静态资源的域名。
static_domain=http://static.bookstack.cn

# 谷歌浏览器，用于发布内容的时候渲染未被渲染的markdown。建议安装最新版的Chrome浏览器，并把Chrome浏览器加入系统环境变量。
# 使用Chrome的headless去处理。之前考虑使用phantomjs的，但是phantomjs有些小问题，不如Chrome强大。
chrome=chromium-browser

#项目默认封面
cover=/static/images/book.png

#默认头像
avatar=/static/images/avatar.png

#默认阅读令牌长度
token_size=12

#上传文件的后缀
upload_file_ext=txt|doc|docx|xls|xlsx|ppt|pptx|pdf|7z|rar|jpg|jpeg|png|gif

####################邮件配置######################
#是否启用邮件
enable_mail=true
#每小时限制指定邮箱邮件发送次数
mail_number=5
#smtp服务用户名
smtp_user_name=
#smtp服务器地址
smtp_host=
#smtp密码
smtp_password=
#端口号
smtp_port=25
#发送邮件的显示名称
form_user_name=

#接收回件的邮箱。留空则表示使用发送邮件的邮箱作为接收回件邮箱
reply_user_name=

#邮件有效期30分钟
mail_expired=30


################Active Directory/LDAP################
#是否启用ldap
ldap_enable=false
#ldap主机名
ldap_host=ad.example.com
#ldap端口
ldap_port=3268
#ldap内哪个属性作为用户名
ldap_attribute=sAMAccountName
#搜索范围
ldap_base=DC=example,DC=com
#第一次绑定ldap用户dn
ldap_user=CN=ldap helper,OU=example.com,DC=example,DC=com
#第一次绑定ldap用户密码
ldap_password=superSecret
#自动注册用户角色：0 超级管理员 /1 管理员/ 2 普通用户 
ldap_user_role=2
#ldap搜索filter规则,AD服务器: objectClass=User, openldap服务器: objectClass=posixAccount ,也可以定义为其他属性,如: title=mindoc
ldap_filter=objectClass=posixAccount


include "oss.conf"
include "oauth.conf"

配置OSS

1、登录你的阿里云，进入OSS，创建一个只读Bucket。
2、在本地随便创建一个txt文档，将下面两行粘贴进去：

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

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

1516802da0987a00.png

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

# 阿里云OSS配置
[oss]

# 是否是内网，如果您的阿里云服务器和OSS是同一内网，请设置为true，这样能更快地将文件移到oss上，否则设置为false。
# 一般情况下，在开发阶段，设置为false
IsInternal=false

# 内网Endpoint,如：oss-cn-hongkong-internal.aliyuncs.com
EndpointInternal=

# 外网Endpoint，如：oss-cn-hongkong.aliyuncs.com
EndpointOuter=


# 您的阿里云AccessKeyId
AccessKeyId=

# 您的阿里云AccessKeySecret
AccessKeySecret=

# 只读状态的Bucket，不要私有的，也不要公共读写的
Bucket=

# oss中绑定的域名，如果您没有绑定域名，则使用阿里云oss的自带域名也行
Domain=

配置第三方登录

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

# 第三方登录配置
[oauth]

##### Gitee(码云) ####
# 申请地址（需要先登录）：https://gitee.com/oauth/applications

# 您的ClientId
giteeClientId=

# 您的ClientSecret
giteeClientSecret=

# 回调地址，把下面的bookstack.cn的域名换成你的即可
giteeCallback=http://www.bookstack.cn/login/gitee

# 下面这两项不要动
giteeAccesstoken=https://gitee.com/oauth/token
giteeUserInfo=https://gitee.com/api/v5/user



######## GitHub ########
# 申请地址(需要先登录你的GitHub)：https://github.com/settings/developers

# 您的ClientId
githubClientId=

# 您的ClientSecret
githubClientSecret=

# 回调地址，把下面的bookstack.cn的域名换成你的即可
githubCallback=http://www.bookstack.cn/login/github

# 下面这两项不要动
githubAccesstoken=https://github.com/login/oauth/access_token
githubUserInfo=https://api.github.com/user



#### QQ ####
# 申请地址（需要先登录你的QQ）:https://connect.qq.com/manage.html

#ClientId，即 APP ID
qqClientId=

#ClientSecret，即 APP Key
qqClientSecret=

# 回调地址，把下面的bookstack.cn的域名换成你的即可
qqCallback=http://www.bookstack.cn/login/qq

# 下面这三项不要动
qqAccesstoken=https://graph.qq.com/oauth2.0/token
qqOpenId=https://graph.qq.com/oauth2.0/me
qqUserInfo=https://graph.qq.com/user/get_user_info

### TODO 微信和微博登录，主要是我这边忘记了以前注册的个人开发者信息，当前没开发，后续会开发出来 ####

上传和部署

1、将修改和配置好了的程序压缩，上传到站点根目录下，解压。
2、执行数据库安装。程序安装一些站点配置项、SEO项等。命令：

./BookStack install

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

add_header X-Cache $upstream_cache_status;
        
expires 12h;

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

server
{
    listen 80;
    server_name demo.bookstack.cn;
    index index.php index.html index.htm default.php default.htm default.html;
    root /www/wwwroot/demo.bookstack.cn;
    
    
    location / 
    {
        proxy_pass http://localhost:8181;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header REMOTE-HOST $remote_addr;
        
        #缓存相关配置
        #proxy_cache cache_one;
        #proxy_cache_key $host$request_uri$is_args$args;
        #proxy_cache_valid 200 304 301 302 1h;
        
        #持久化连接相关配置
        #proxy_connect_timeout 30s;
        #proxy_read_timeout 86400s;
        #proxy_send_timeout 30s;
        #proxy_http_version 1.1;
        #proxy_set_header Upgrade $http_upgrade;
        #proxy_set_header Connection "upgrade";
    }
    
    location ~ .*\.(php|jsp|cgi|asp|aspx|flv|swf|xml)?$
    {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header REMOTE-HOST $remote_addr;
        proxy_pass http://localhost:8181;
        
    }
    #PROXY-END

    include enable-php-54.conf;
    #PHP-INFO-END
    
    #REWRITE-START URL重写规则引用,修改后将导致面板设置的伪静态规则失效
    include /www/server/panel/vhost/rewrite/demo.bookstack.cn.conf;
    #REWRITE-END
    
    #禁止访问的文件或目录
    location ~ ^/(\.user.ini|\.htaccess|\.git|\.svn|\.project|LICENSE|README.md)
    {
        return 404;
    }
    
    access_log  off;
}

加入系统守护进行

1、进入supervisor的配置目录

cd /etc/supervisor/conf.d/

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

[program:BookStack]
directory = 你的程序目录
command =你的程序执行命令
autostart = true
autorestart=true
user = 启动该程序的用户
redirect_stderr = true
stdout_logfile = 日志地址

配置示例：

[program:BookStack]
directory = /www/wwwroot/demo.bookstack.cn
command =/www/wwwroot/demo.bookstack.cn/BookStack
autostart = true
autorestart=true
user = root
redirect_stderr = true
stdout_logfile = /var/log/supervisor/BookStack.log

配置完成之后，重启supervisor

supervisorctl reload

总结

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