一、背景
业务系统产品化的时候，需要提供些文档来方便查阅。调研了好些开源免费的文档系统，语雀，相信很多人应该都听过，是支付宝内部孵化的一款文档与知识管理工具很强大，但感觉对我们有点笨重了。最终决定采用vuepress来做我们的文档管理系统，在搭建的过程中，官网文档中提到可以直接在github部署，我们内部用的gitlab来做代码管理器，第一感觉应该可以支持部署，所以在网上调研了一番，发现真有人尝试，但文档相对较少，所以整理了下摸索的过程，整个过程大概花了4个小时，从gitlab-ci的gitlab-runner到gitlab的pages一系列的ops流程部署。
二、VuePress 初识
官网是这样介绍的，Vue 驱动的静态网站生成器。
简洁至上
以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
Vue 驱动
享受 Vue + webpack 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题。
高性能
VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为 SPA 运行。
三、实践
1. 开启GitLab Pages功能
我们内部用的是11.4.0版本的gitlab社区版，搭建在ubuntu14上面，安装的时候默认是没有开启pages功能，所以先介绍下如何开启pages功能，编辑 etc/gitlab/gitlab.rb文件，修改如下两行：
##! Define to enable GitLab Pages
pages_external_url "http://your.domain.com/"
gitlab_pages['enable'] = true
配置完后，重启下gitlab:
gitlab-ctl reconfigure
使得Gitlab Pages功能生效。
2. 安装配置GitLab Runner
为了能够自动发布Pages，我们需要安装GitLab Runner，然后通过GitLab CI做到Pages内容的自动更新。
curl -LJO "https://gitlab-runner-downloads.s3.amazonaws.com/latest/deb/gitlab-runner_amd64.deb"
dpkg -i gitlab-runner_amd64.deb
安装好之后，就可以通过命令为我们的项目添加runner了，在命令行中输入以下命令，按照提示一步一步完成即可。
gitlab-runner register
其中需要填写URL和Token（在下图中的rul和令牌处），以及最重要的executor （我这边选择的是shell，因我gitlab服务器直接安装了这些环境）可以在GitLab项目的概览->Runners找到，类似下图：
3. 配置Pages服务的CI
在工程根目录下，创建.gitlab-ci.yml文件，文件内容可以通过GitLab内置的模板生产，如下图：
pages:
cache:
paths:
- node_modules/
- dist
stage: deploy
script:
- yarn install
- yarn build
artifacts:
paths:
- public
only:
- master
这样，当我们每次执行push动作后，就会触发pages的自动部署。将我们的pages页面发布到GitLab Pages服务中。
4. 如何访问Pages页面呢？
此部分内容网上说的都没有尝试成功，由于Gitlab Pages服务是直接部署到nginx中，我们可以直接配置nginx来访问我们的静态站点。
首先得找到Pages的发布位置，和GitLab内置Nginx的位置，分别如下：
1. Pages部署目录：/var/opt/gitlab/gitlab-rails/shared/pages
2. 内置Nginx目录：/var/opt/gitlab/nginx
然后编辑nginx目录下的conf/gitlab-pages.conf文件，内容如下：
server {
listen *:8081;
server_name your.domain.cn;
server_tokens off;
## Disable symlink traversal
disable_symlinks on;
## Real IP Module Config
## http://nginx.org/en/docs/http/ngx_http_realip_module.html
## Individual nginx logs for this GitLab vhost
access_log /var/log/gitlab/nginx/gitlab_pages_access.log gitlab_access;
error_log var/log/gitlab/nginx/gitlab_pages_error.log;
# Pass everything to pages daemon
location {
root var/opt/gitlab/gitlab-rails/shared/pages;
index index.html;
}
# Define custom error pages
error_page 403 403.html;
error_page 404 404.html;
}
配置好后重启Nginx：
gitlab-ctl restart nginx
还有一处需要注意的点就是vuepress本身的配置文件:config.js
base 的配置至关重要。这个路径影响打包后静态文件引用资源文件的相对路径。
5. 服务器node环境的安装
不能用apt-get install来安装，版本太低了，需要去官网下载高版本tar包，然后解压，设置好软链接
tar xvf usr/local/src/node-v14.17.6-linux-x64.tar.xz
ln -s usr/local/src/node-v14.17.6-linux-x64/bin/node usr/local/bin/node
ln -s usr/local/src/node-v14.17.6-linux-x64/bin/npm usr/local/bin/npm
npm install -g yarn
ln -s /usr/local/src/node-v14.17.6-linux-x64/bin/yarn /usr/local/bin/yarn
一切就绪，只欠东风～接下来就让我们见证奇迹，我们测试push一下代码。查看gitlab接下来做的事情，首先会自动触发runner的执行：
执行控制台日志：
直接访问我们的站点：
大功告成！
四、总结
在文章中，省去了一些知识点的介绍，比如gitlab的executor有好多种类，每一种的适用场景等，有兴趣的可以自行了解。如果你想搭建一个自己的博客系统，是个不错的选择。
