【非广告】Gitbook 接入 Gitlab Webhook 功能,实现文档实时在线更新

Hello,大家好,我是阿粉,对接文档是每个开发人员不可避免都要写的,友好的文档可以大大的提升工作效率。阿粉最近将项目的文档基于 Gitbook 和 Gitlab 的 Webhook 功能的在内网部署了一套实时的,使用起来特方便了。跟着阿粉的步骤,教你部署自己的文档服务。

步骤

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

安装 Node,NPM

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 下载压缩包
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,依次执行下面的命令。

1
2
3
4
5
6
7
8
# 安装 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 文件。

1
2
3
4
5
6
7
8
9
10
11
[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 脚本即可。

配置 Webhook

找到仓库的设置,不同版本的 Gitlab 可以页面显示不一样,大家自行找一找就好,

点进去过后我们看到如下页面,需要填写服务的地址,这里我们服务还没有创建,不过我们可以先进行定义,比如阿粉这里就填了 http://xxxx:6666/autobuild,服务器的地址就填写安装了 Gitbook 的服务器;在 Secret Token 一栏我们设置一个秘钥,接口到时候也需要填写,只要对应上就行,比如 autobuild。第三个是下面的 Trigger,这里默认选择的是 Push events,我们不用改,如果需要其他的也可以设置。

再点击下面的Add webhook 按钮保存即可。

部署接口服务

我们在刚刚部署了 gitbook 的服务器上面创建一个名为 webhook 的文件夹,在文件夹里面我们创建三个文件,分别是 index.jspackage.jsonauto_build.sh

index.js 内容如下:这里我们的接口名字和 secret需要跟在 Gitlab 上面配置的一样

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
var http = require('http');
var spawn = require('child_process').spawn;
# 导入 Gitlab  webhook
var createHandler = require('gitlab-webhook-handler');
var handler = createHandler({ path: '/autobuild', secret: 'autobuild' });
http.createServer(function (req, res) {
  handler(req, res, function (err) {
    res.statusCode = 404;
    res.end('no such locationsssssssss');
  });
}).listen(6666);
handler.on('error', function (err) {
  console.error('Error:', err.message)
});
handler.on('push', function (event) {
  console.log('Received a push event for %s to %s',
    event.payload.repository.name,
    event.payload.ref);
  runCommand('sh', ['/root/webhook/auto_build.sh'], function( txt ){
    console.log(txt);
  });
});
function runCommand( cmd, args, callback ){
    var child = spawn( cmd, args );
    var response = '';
    child.stdout.on('data', function( buffer ){ response += buffer.toString(); });
    child.stdout.on('end', function(){ callback( response ) });
    child.stderr.on('data', (data) => {
    	console.log(`stderr: ${data}`);
    });
}

简单介绍一下上面的 JS 代码,创建一个服务监听 6666 端口,提供一个名叫 autobuild 的接口,在收到 push 操作的时候就执行/root/webhook/auto_build.sh 路径下的脚本。

auto_build.sh 脚本的内容如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
#! /bin/bash
SITE_PATH='/root/test-doc'
#USER='admin'
#USERGROUP='admin'
cd $SITE_PATH
#git reset --hard origin/master
#git clean -f
git pull
# 切换到 dev 分支,可以自己设定
git checkout dev
# 启动 gitbook
nohup gitbook serve > /dev/null 2>&1 &
#chown -R $USER:$USERGROUP $SITE_PATH

脚本里面主要就是拉取这新的内容,然后切换到 dev 分支,再执行gitbook serve 命令,采用的是nohup gitbook serve > /dev/null 2>&1 &

package.json的内容如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "name": "autobuild",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "gitlab-webhook-handler": "1.0.1"
  }
}

启动服务器之前,先执行npm install 安装依赖,然后执行nohup node index.js &,启动成功过后我们就可以进行文档修改然后 push 到Gitlab 上面,观察是否及时更新。这里注意一个点,我们的脚本里面使用的是 dev 分支,所以要 push 到 dev 分支。我们可以在 Gitlab 的 Webhook 下面看到我们 push 过后触发的详情,可以看到是否成功。这里如果不成功,我们再检查下防火墙是否开启了 6666 端口,没有的话,按照上面的操作开启即可。

到这里我们整个基于 Gitbook 和 Gitlab Webhook 实现文档实时更新的效果就达成了,后续在使用的时候,我们只需要修改内容,然后 push 到对应的仓库,然后在网站上就能看到最新的修改,大家感兴趣可以自己试试哦。

Tips

Gitbook 可以支持插件以及自定义样式,我们只需要在 test-doc 目录下面,创建一个名叫 book.json 的文件,可以在这个文件中自定义一些特定的内容,增加了插件,在启动的时候需要使用gitbook install 安装一下即可。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "title": "XXXX对接API",
    "description": "这是 Gitbook 与 Gitlab Webhook 集成的项目",
    "author": "Java 极客技术",
    "plugins": ["splitter","tbfed-pagefooter","expandable-chapters-small"],
    "pluginsConfig": {
    "tbfed-pagefooter": {
        "copyright":"Copyright &copy COOCAA",
        "modify_label": "该文件修订时间:",
        "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    },
    "styles": {
        "website": "./customStyle.css"
    }

styles 下面可以增加我们自己写的样式,如果需要的话可以加入。

总结

今天阿粉给大家分享了一个使用的技能,在工作中搭建起来,相信会很有帮助的。有任何问题可以在公众号下面留言,或者在知识星球中提问,阿粉看到会解答的。

写在最后

最后邀请你加入我们的知识星球,这里有 1800+ 优秀的人与你一起进步,如果你是小白那你是稳赚了,很多业内经验和干货分享给你;如果你是大佬,那可以进来我们一起交流分享你的经验,说不定日后我们还可以有合作,给你的人生多一个可能。

Java Geek Tech wechat
欢迎订阅 Java 极客技术,这里分享关于 Java 的一切。