使用git、gitbook、openresty实现自动化部署文档中心

序

由于在项目管理中，发现文档的统一管理和传阅非常不方便。
例如使用word,excel等工具，文档零散且分享没有实时性；
使用svn或者git管理，文档可以统一，且可以追溯历史，但是对于分享而言，使用成本过高。

在无意中发现一个叫做gitbook的东西，可以将书籍用git的方式管理，阅读的时候时候则可以通过网站阅读，正好一次性解决了之前的问题。
在调研过程中，发现了许多问题，比如gitbook官方使用是收费的，并且在网络不稳定，而且资料公开在外网。
该文章就是为了解决上述问题而做出的一种实现。

思路

1. 通过git管理文档
2. 通过gitbook生成网站
3. 通过openresty访问网站和编写相应的gitbook自动部署
4. 通过gitbook的hook钩子触发gitbook自动部署

git

就是git的安装和使用，我这里使用的是gitea,相对gitlab来说，更轻量方便使用。
具体过程略，有需要的请自行百度/google。

gitbook

1.安装

这里使用npm安装，如果不了解了，请先行学习npm安装。
执行以下命令即可安装。

npm install gitbook-cli -g

如果已经安装过了，再次安装，有时候就会安装失败，并且之前的也不能用了。这时候需要先卸载gitbook-cli，命令如下

npm uninstall gitbook-cli -g

2.初始化

在创建好的目录中初始化gitbook

gitbook init

如果您希望将书籍创建到一个新目录中，可以通过运行 gitbook init ./directory 这样做

3.构建

使用下面的命令，会在项目的目录下生成一个 _book 目录，里面的内容为静态站点的资源文件

gitbook build

在这一步构建出来的_book就是我们可以直接通过openresty映射出来的文档网页了。

4.编写

由于网上有很多介绍gitbook如何编写和使用的资料，且这个不是该文章要说明的重点，这里就不重复说明了。

更多关于gitbook的详细说明请打开大佬的gitbook相关资料 [使用 Gitbook 打造你的电子书]。

5.提交git

编写好gitbook以后，就可以提交到git了，然后就是通过git的hook去触发自动部署了。

注意点

在.gitignore中，需要过滤node_modules/和_book/，过滤node_modules/是该文件内容太多，且容易出错；过滤_book/是我们的自动部署需要每次都重新生成，容易代码冲突，导致git pull拉取命令中断，从而中断了自动化部署的命令。

# 忽略 node_modules/ 文件夹下的所有文件
node_modules/

# 忽略_book
_book/

openresty

OpenResty® 是一个基于 Nginx 与 Lua 的高性能 Web 平台，其内部集成了大量精良的 Lua 库、第三方模块以及大多数的依赖项。用于方便地搭建能够处理超高并发、扩展性极高的动态 Web 应用、Web 服务和动态网关。

OpenResty® 通过汇聚各种设计精良的 Nginx 模块（主要由 OpenResty 团队自主开发），从而将 Nginx 有效地变成一个强大的通用 Web 应用平台。这样，Web 开发人员和系统工程师可以使用 Lua 脚本语言调动 Nginx 支持的各种 C 以及 Lua 模块，快速构造出足以胜任 10K 乃至 1000K 以上单机并发连接的高性能 Web 应用系统。

OpenResty® 的目标是让你的Web服务直接跑在 Nginx 服务内部，充分利用 Nginx 的非阻塞 I/O 模型，不仅仅对 HTTP 客户端请求,甚至于对远程后端诸如 MySQL、PostgreSQL、Memcached 以及 Redis 等都进行一致的高性能响应。

简单来说就是在nginx的基础上，多了可以编写lua命令的工具，这是我们自动化部署的一个重要部分。

1.安装

下载地址，大家也可以自行下载安装。

2.配置

安装好openresty以后，打开文件目录，进入conf文件夹打开nginx.conf文件。
开始进行nginx配置和编写自动化部署接口。
编写后的nginx.conf内容如下。

#user  nobody;
worker_processes  1;

#error_log  logs/error.log;
#error_log  logs/error.log  notice;
#error_log  logs/error.log  info;

#pid        logs/nginx.pid;


events {
    worker_connections  1024;
}


http {
    include       mime.types;
    default_type  application/octet-stream;

    #log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
    #                  '$status $body_bytes_sent "$http_referer" '
    #                  '"$http_user_agent" "$http_x_forwarded_for"';

    #access_log  logs/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    #keepalive_timeout  0;
    keepalive_timeout  65;

    #gzip  on;    

    server {
        listen       80;
        server_name  localhost;


        location / {
            root   D:/gitbook_book/web;
            index  index.html index.htm;
        }


        location ^~ /gitbook_pull {
            # 动态拉取文档代码并重新bulid
            default_type text/plain;                      
            content_by_lua_block {
                local uri = ngx.var.uri;  -- 获取uri                
                local doc = uri.gsub(uri,'/gitbook_pull/','');
                local cmd = "D: & cd D:/gitbook_book/code/"..doc.." & git pull & gitbook build & xcopy /s/e/y D:\\gitbook_book\\code\\"..doc.."\\_book D:\\gitbook_book\\web\\"..doc.."\\";
                os.execute(cmd);     
                ngx.say(cmd);           
                ngx.say("ok");
            }
        }

        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   html;
        }
    }
}

解说

location / {
            root   D:/gitbook_book/web;
            index  index.html index.htm;
        }

此处是代理项目路径,我们将gitbook bulid出来的_book文件中的内容复制到该处，从而实现多个gitbook，只要通过名称就都可以访问的目的（如http://127.0.0.1/demo-doc）。

这里说一下项目结构

D
    gitbook_book
        code
            demo-doc
        web
            demo-doc

demo-doc是文档名称，我这边是将git的名称作为统一命名
code下的demo-doc。
第一次需要手动初始化，需要先从git上下载该项目到该路径，然后进行gitbook install的初始化，web下的demo-doc就不需要管，通过自动部署命令会自动创建。

location ^~ /gitbook_pull {
            # 动态拉取文档代码并重新bulid
            default_type text/plain;                      
            content_by_lua_block {
                local uri = ngx.var.uri;  -- 获取uri                
                local doc = uri.gsub(uri,'/gitbook_pull/','');
                local cmd = "D: & cd D:/gitbook_book/code/"..doc.." & git pull & gitbook init & gitbook build & xcopy /s/e/y D:\\gitbook_book\\code\\"..doc.."\\_book D:\\gitbook_book\\web\\"..doc.."\\";
                os.execute(cmd);     
                ngx.say(cmd);           
                ngx.say("ok");
            }
        }

这个接口时用来执行自动部署的，我这边说明下原理。
如请求127.0.0.1/gitbook_pull/demo-doc接口时，
1. 首先解析uri，获取到文档名称是demo-doc。
2. 然后打开 D:/gitbook_book/code/demo-doc 目录
3. 执行git pull 拉取代码命令
4. 然后再执行 gitbook build命令进行网页创建
5. 执行xcopy命令将文件夹复制到web目录下的demo-doc，该处命令需要根据系统环境自行编写，这里是windows环境。(注意： /s/e/y 跳过命令过程的提示中断；复制到的目录最后要加/，如D:\gitbook_book\web\demo-doc\，不然会中断提示是否是文件夹，导致命令中断)

以上就是openresty的配置了，配置好以后，直接运行在openresty安装目录下的nginx就可以启动了，如果需要重启，在openresty目录执行 ./nginx -s reload就可以重启了。

git hook

这是最后一步，在相应的git中添加钩子，在项目推送时访问127.0.0.1/gitbook_pull/demo-doc接口就可以在git推送时，自动部署gitbook了。

总结

完成以后，相关编写人员，只要去git去下载相应的文档，编写好以后，推送以后，其他的人就可以通过文档访问的网页直接查看了，查看资料的人员，不需要学习任何东西，就可以直接看了；而编写人员，则可以通过优美的markdown编写出美观的文档，并由于使用了git，每个文档都可以追溯历史资料。

不足

1. 无法使用gitbook editor，因为gitbook editor只能提交https,如果条件允许，那编写人员的学习成本就更低了，而且内容中的插入图片就变得很简便了。
2. 图片插入繁琐，由于markdown不能上传图片，所以，如果文中需要用到图片，建议复制图片到assets文件夹下，并且按业务分开，然后使用markdown引用该图片即可。