一文教会你如何在内网搭建一套属于自己小组的在线 API 文档？

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 脚本即可。

配置 Webhook

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

点进去过后我们看到如下页面，需要填写服务的地址，这里我们服务还没有创建，不过我们可以先进行定义，比如阿粉这里就填了 http://xxxx:6666/autobuild，服务器的地址就填写安装了 Gitbook 的服务器；在 Secret Token 一栏我们设置一个秘钥，接口到时候也需要填写，只要对应上就行，比如 autobuild。

第三个是下面的 Trigger，这里默认选择的是 Push events，我们不用改，如果需要其他的也可以设置。

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

部署接口服务

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

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

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 脚本的内容如下：

#! /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的内容如下：

{
  "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 安装一下即可。

{
    "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 下面可以增加我们自己写的样式，如果需要的话可以加入。

总结

今天阿粉给大家分享了一个使用的技能，在工作中搭建起来，相信会很有帮助的。有任何问题欢迎在评论区留言我们一起讨论~，原创不宜，如有帮助欢迎点赞分享，一键三连。


更多优质内容欢迎关注公众号【Java 极客技术】，我准备了一份面试资料，回复【bbbb07】免费领取。希望能在这寒冷的日子里，帮助到大家。

posted @ 2022-12-03 12:27  zi-you  阅读(1260)  评论(0)  编辑  收藏  举报