文章目录
- 一. 概述
- 二. 环境准备
- 三. 安装Git
- 四. 安装GitLab
- 五. 安装GitBook
- 六. 安装GitLab Runner
- 七. 打通GitLab与GitBook
- 八. 验证
- 九. 遇到的问题
- 1. runner一直处于Pending状态
- 2. runner一直处于running
- 十. 扩展
- 1. GitBook的常用插件
- 十一. 总结
一. 概述
本文主要介绍如何使用GitBook,GitLab,并集成GitLab CI实现一个企业级或个人的Wiki系统
这里简单介绍下GitBook:GitBook是一款文档编辑工具,支持多人协作,同时支持Git
下面从0到1开始搭建基于GitBook,GitLab的企业级Wiki
二. 环境准备
安装前,需要准备如下环境,主要包括:
- 一台Linux服务器,系统:Centos7
- 安装npm,node环境
三. 安装Git
通过下列命令,在机器上安装git:
## 通过下列命令安装git
yum install git
## 查看当前git版本
git --version
四. 安装GitLab
- 下载gitlab的rpm包
地址:https://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/yum/el7/gitlab-ce-9.5.9-ce.0.el7.x86_64.rpm - 执行安装
## 安装rpm包
rpm -ivh gitlab-ce-9.5.9-ce.0.el7.x86_64.rpm
- 修改访问URL
vim /etc/gitlab/gitlab.rb
## 修改以下内容并保存
external_url "http://10.0.112.65"
- 重装配置
## 依次执行下面命令
gitlab-ctl reconfigure
gitlab-ctl restart
五. 安装GitBook
通过下列命令安装即可:
npm install gitbook-cli -g
六. 安装GitLab Runner
- 下载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
- 文件放置
文件已经放置于 /usr/local/bin/gitlab-runner,需要配置相应权限
chmod +x /usr/local/bin/gitlab-runner
- 安装GitLab Runner
## 下载
npm install gitbook-cli -g
## 安装
gitlab-runner install --user=root --working-directory=/software/gitlab-runner
## 启动
gitlab-runner start
七. 打通GitLab与GitBook
- 创建wiki的工程,如下所示:
- 注册GitLab Runner
## 注册
gitlab-runner register
然后依次输入以下参数:
## 1. GitLab的url,参考下图
## 2. Token,参考下图
## 3. 描述,随便写一个
## 4. Runner描述,随便写一个
## 5. shell,意思是执行方式,这里用shell即可
配置完成后,可以在GitLab看到Runner已经注册上来了,如下所示:
- 项目配置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"
}
},
}
主要插件包括:
- chapter-fold:左侧目录折叠
- code:代码可复制
- todo:出现代办项
- pageview-count:文章计数器
- popup:图片点击显示(以新窗口的方式)
- page-treeview:在页面顶部显示目录
- back-to-top-button:回到顶部的button
- splitter:侧边栏宽度可调节
- edit-link:修改页面内容
- tbfed-pagefooter:页面增加页脚
这里仅举例一些通用的插件,更多插件请参考GitBook官网的可用插件列表
十一. 总结
最后的最后,做个小总结:
- 本文主要描述如何使用GitBook结合GitLab实现Wiki系统
- Wiki支持多人协作,支持自动更新
- 由于文档保存在GitLab上,因此不会丢失,适合团队协作或者个人博客