如何组建ap网络（一文教会你如何在内网搭建一套属于自己小组的在线 API 文档？）
Hello ，大家好 ，我是阿粉 ，对接文档是每个开发人员不可避免都要写的 ，友好的文档可以大大的提升工作效率 。
阿粉最近将项目的文档基于 Gitbook 和 Gitlab 的 Webhook 功能的在内网部署了一套实时的 ，使用起来特方便了 。跟着阿粉的步骤 ，教你部署自己的文档服务 。
步骤
安装 Node 和 NPM； 安装 git ， gitbook ，gitbook-cli； 配置 Gitlab Webhook； 创建 Webhook 监听服务； 编辑文档检查实时更新；安装 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 © COOCAA", "modify_label": "该文件修订时间：", "modify_format": "YYYY-MM-DD HH:mm:ss" } }, "styles": { "website": "./customStyle.css" }styles 下面可以增加我们自己写的样式 ，如果需要的话可以加入 。
总结
今天阿粉给大家分享了一个使用的技能 ，在工作中搭建起来 ，相信会很有帮助的 。有任何问题欢迎在评论区留言我们一起讨论~ ，原创不宜 ，如有帮助欢迎点赞分享 ，一键三连 。
更多优质内容欢迎关注公众号【Java 极客技术】 ，我准备了一份面试资料 ，回复【bbbb07】免费领取 。希望能在这寒冷的日子里 ，帮助到大家 。
创心域SEO版权声明：以上内容作者已申请原创保护，未经允许不得转载，侵权必究！授权事宜、对本内容有异议或投诉，敬请联系网站管理员，我们将尽快回复您，谢谢合作！