GitBook，GitLab实现5分钟搭建企业级Wiki

---

一. 概述

本文主要介绍如何使用GitBook，GitLab，并集成GitLab CI实现一个企业级或个人的Wiki系统
这里简单介绍下GitBook：GitBook是一款文档编辑工具，支持多人协作，同时支持Git

下面从0到1开始搭建基于GitBook，GitLab的企业级Wiki

二. 环境准备

安装前，需要准备如下环境，主要包括：

1. 一台Linux服务器，系统：Centos7
2. 安装npm，node环境

三. 安装Git

通过下列命令，在机器上安装git：

## 通过下列命令安装git
yum install git
## 查看当前git版本
git --version

四. 安装GitLab

1. 下载gitlab的rpm包
   地址：https://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/yum/el7/gitlab-ce-9.5.9-ce.0.el7.x86_64.rpm
2. 执行安装

## 安装rpm包
rpm -ivh gitlab-ce-9.5.9-ce.0.el7.x86_64.rpm

3. 修改访问URL

vim /etc/gitlab/gitlab.rb
## 修改以下内容并保存
external_url "http://10.0.112.65"

4. 重装配置

## 依次执行下面命令 
gitlab-ctl reconfigure
gitlab-ctl restart

五. 安装GitBook

通过下列命令安装即可：

npm install gitbook-cli -g

六. 安装GitLab Runner

1. 下载GitLab Runner
   通过 uname --m 命令查看 Linux 系统的位数，然后下载对应的安装包

# x86-64
sudo wget -O /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
# x86
sudo wget -O /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-386
# arm
sudo wget -O /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-arm

2. 文件放置
   文件已经放置于 /usr/local/bin/gitlab-runner，需要配置相应权限

chmod +x /usr/local/bin/gitlab-runner

3. 安装GitLab Runner

## 下载
npm install gitbook-cli -g
## 安装
gitlab-runner install --user=root --working-directory=/software/gitlab-runner
## 启动
gitlab-runner start

七. 打通GitLab与GitBook

1. 创建wiki的工程，如下所示：
   
2. 注册GitLab Runner

## 注册
gitlab-runner register
然后依次输入以下参数：
## 1. GitLab的url，参考下图
## 2. Token，参考下图
## 3. 描述，随便写一个
## 4. Runner描述，随便写一个
## 5. shell，意思是执行方式，这里用shell即可

配置完成后，可以在GitLab看到Runner已经注册上来了，如下所示：

3. 项目配置CI
   在项目中新增.gitlab-ci.yml文件，内容如下：

stages:
  - build
xx-wiki:
  stage: build
  script:
    - p=`pwd`
    - echo $p
    - gitbook install
    - gitbook build
    - setsid nohup sh startup.sh > nohup.out 2>&1 &

在项目中新增startup.sh文件，内容如下：

#!/bin/bash
for i in `ps -ef | grep gitbook | grep serve`; do kill -9 $i ; done;
gitbook serve

提交到GitLab后，通过Pipelines菜单查看任务执行情况：

八. 验证

修改Wiki内容，然后推送到GitLab，可以看到GitLab上的任务被执行：

访问http://IP:4000，可以看到对应的Wiki被更新，证明WiKi搭建完成，并能实时更新

九. 遇到的问题

1. runner一直处于Pending状态

这是由于在注册gitlab runner完成后，有一个配置项需要修改，否则不会执行，详见以下链接：
https://www.daxiblog.com/gitlab-pages无法运行，一直处于pending状态的原因/

2. runner一直处于running

这是由于直接通过gitbook serve启动时，没有以后台方式启动。最后通过setsid解决

十. 扩展

1. GitBook的常用插件

GitBook提供了非常多通用的插件，可以让我们的Wiki看起来更炫酷，功能更强大，下面是Wiki项目的book.json：

{
  "title": "zz gitbook",
  "author": "zz",
  "description": "zz gitbook",
  "plugins": [
    "chapter-fold",
    "code",
    "todo",
    "pageview-count",
    "popup",
    "page-treeview",
    "back-to-top-button",
    "splitter",
    "edit-link",
    "tbfed-pagefooter"
  ],
  "pluginsConfig": {
    "tbfed-pagefooter": {
      "copyright":"",
      "modify_label": "该文件最后修改时间：",
      "modify_format": "YYYY-MM-DD HH:mm:ss"
    },
    "edit-link": {
      "base": "//10.0.112.65/xx/xx-wiki/edit/master",
      "label": "编辑此页面"
    },
    "page-toc-button": {
      "maxTocDepth": 2,
      "minTocSize": 2
    },
    "page-treeview": {
      "copyright": "Copyright © aleen42",
      "minHeaderCount": "2",
      "minHeaderDeep": "2"
    }
  },
}

主要插件包括：

1. chapter-fold：左侧目录折叠
2. code：代码可复制
3. todo：出现代办项
4. pageview-count：文章计数器
5. popup：图片点击显示(以新窗口的方式)
6. page-treeview：在页面顶部显示目录
7. back-to-top-button：回到顶部的button
8. splitter：侧边栏宽度可调节
9. edit-link：修改页面内容
10. tbfed-pagefooter：页面增加页脚
    这里仅举例一些通用的插件，更多插件请参考GitBook官网的可用插件列表

十一. 总结

最后的最后，做个小总结：

1. 本文主要描述如何使用GitBook结合GitLab实现Wiki系统
2. Wiki支持多人协作，支持自动更新
3. 由于文档保存在GitLab上，因此不会丢失，适合团队协作或者个人博客