Hello，大家好，对接文档是每个开发人员不可避免都要写的，友好的文档可以大大的提升工作效率。

最近将项目的文档基于 Gitbook 和 Gitlab 的 Webhook 功能的在内网部署了一套实时的，使用起来特方便了。跟着步骤，教你部署自己的文档服务。

步骤

1. 安装 Node 和 NPM；
2. 安装 git， gitbook，gitbook-cli；
3. 配置 Gitlab Webhook；
4. 创建 Webhook 监听服务；
5. 编辑文档检查实时更新；

安装 Node，NPM

第一步我们先安装 Node 和 NPM，

# 下载压缩包
wget https://nodejs.org/dist/v9.10.1/node-v9.10.1-linux-x64.tar.gz
# 解压
tar xzvf node-v9.10.1-linux-x64.tar.gz
# 重命名
mv node-v9.10.1-linux-x64 node
# 移动到/usr/local/ 目录下
mv node* /usr/local/
# 创建软连接
ln -s /usr/local/node/bin/* /usr/sbin/
# 检查版本
node -v
# 正常输出，下面内容说明安装成功
> v9.10.1

正常安装完 Node 过后 NPM 会自动安装，通过npm -v 可以看到 NPM 的版本号。

Gitbook

Git 的安装就不演示了，给大家演示安装 Gitbook，依次执行下面的命令。

# 安装 Gitbook
npm install -g gitbook
# 安装 Gitbook 命令行工具
npm install -g gitbook-cli
# 创建软连接
ln -s /usr/local/node/bin/gitbook /usr/sbin/gitbook
# 查看 Gitbook 版本 注意大写的 V
 gitbook -V

安装完 Gitbook 过后，我们这个时候就可以部署服务了，我们先创建一个空文件夹 test-doc，然后进入文件夹执行gitbook init 命令，执行成功过后，我们可以看到生成了两个文件，分别是 README.md 以及 SUMMARY.md 文件。

[root@~]# mkdir test-doc
[root@~]# cd test-doc/
[root@test-doc]# gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished
[root@test-doc]# ll
总用量 8
-rw-r--r--. 1 root root 16 12月  6 19:15 README.md
-rw-r--r--. 1 root root 40 12月  6 19:15 SUMMARY.md

创建完成过后，我们在 test-doc 目录下执行命令 gitbook serve 

我们访问服务器的 4000 端口，正常可以看到

如果没有看到上面的内容或者访问不了 4000 端口，我们需要检查一下服务器的防火墙，先看下防火墙开放的端口，执行命令 firewall-cmd --list-ports 看看是否开放了 4000 端口，如果没有执行下面命令firewall-cmd --zone=public --add-port=4000/tcp --permanent 将 4000 端口进行开放，然后重新 reload，firewall-cmd --reload ，再次刷新浏览器即可。

后面的操作就是在文档中增加相应的内容即可，当然这里模拟的是本地创建文件夹，如果我们的文档已经存在仓库中，我们可以通过 git 将仓库拉下来，增加 README.md 和 SUMMARY.md 文件，然后编写相应内容即可，只需要在 SUMMARY.md 中增加相应的目录，同样启动就能访问。

Gitlab Webhook

截止到上面的内容我们已经部署了一套在线的文档服务，但是有个比较麻烦的事情，就是每次文档有所更新的时候，我们在修改完文档，推送到 Gitlab 仓库后，都需要手动登录服务器，然后重新 git pull 拉取最新的文档，接着重启 gitbook serve服务，难免会觉得比较麻烦。

好在 Gitlab 提供 Webhook 功能（GitHub 也一样提供），我们可以在 Gitlab 对应的仓库中配置 Webhook功能。Webhook 我们可以理解为钩子功能，允许我们在对仓库进行改动过后可以触发一个我们指定的服务，然后执行相应的动作。

比如我们这里想要的效果就是，在每次更新文档 push 的仓库过后，希望部署的在线文档服务能自动拉取最新的文档信息，然后自动重启 gitbook 服务，实现文档的及时更新。

实现上面的需求，我们需要两步，第一步在 Gitlab 对应的仓库里面设置 Webhook ，也就是每次执行 push 动作后需要调用的服务地址；第二步我们需要一个服务，这个服务需要提供一个接口，当被调用的时候执行拉取最新文档和重启 gitbook 服务的功能。

为了方便我们可以把拉取最新文档和重启 gitbook 服务的功能写成一个 shell 脚本，当接口被调用的时候，我们只需要执行 shell 脚本即可。

本站声明：
1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享；

2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关；

3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关；

4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除；

5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。