Earth Guardian

You are not LATE!You are not EARLY!

0%

Gitlab 搭建个人 Blog

发表于 更新于 分类于

介绍

Gitlab 已经越来越强大，同时也可以使用它提供的 pages 搭建个人静态博客
官网 pages 介绍
官网 doc

搭建步骤

  • Fork 官网推荐模板
    模板支持很多种静态博客：hugo, hexo, jekyll 等
    这里选用 hexo：hexo模板链接
  • Enable shared Runners
    在 Settings -- CI / CD -- Runners settings 中检查，是否打开该功能
  • Configure your project (optional)
    在 Settings -- General -- Advanced settings -- Rename repository中，将仓库名称和路径都修改为 username.gitlab.io
  • Manually run a pipeline
    下载该仓库修改并提交后，触发一次自动编译
    在 CI / CD -- Pipelines 中，查看任务是否执行成功
  • Visit your site!
    搭建完毕！直接访问 https://username.gitlab.io 即可
    如果无法访问，可能会存在一点延时，过几分钟后再访问

Hexo 环境搭建

介绍

Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown（或其他渲染引擎）解析文章，在几秒内即可利用靓丽的主题生成静态网页。

安装 Node.js 和 git

Hexo 安装依赖 Node.js 和 git，所以需要先安装这两个环境

  • Node.js
    Node.js 官网 下载 Windows 下的稳定安装包，一路 Next 安装完毕后，重新开启 window cmd 终端，查看版本号测试是否安装成功： 
1
2
$ npm --version
3.10.10

安装 Hexo

Windows 下的 Node.js 和 git 环境准备好后，在 windows cmd 终端中，只需一条命令就可以安装 Hexo ：
npm install -g hexo-cli
官网安装文档

windows cmd 终端中查看版本号： 

1
2
3
4
5
6
7
8
9
10
11
12
$ hexo --version
hexo-cli: 1.0.3
os: Windows_NT 6.1.7601 win32 x64
http_parser: 2.7.0
node: 6.11.4
v8: 5.1.281.108
uv: 1.11.0
zlib: 1.2.11
ares: 1.10.1-DEV
icu: 58.2
modules: 48
openssl: 1.0.2l

gitlab 博客本地环境预览

本地安装好 Hexo 环境后，可以本地预览 gitlab 中写的博客了。Hexo 相关命令建议在 windows cmd 中输入，打印信息会比 git bash 中的多

  • hexo 初始化博客目录
    cmd 中执行如下命令，等待初始化完毕，并产生 node_modules 目录
    E:\01_work\00_My\06_blog> hexo init username.gitlab.io
  • 安装 hexo-server
    Hexo 3.0 把服务器独立成了个别模块，必须先安装 hexo-server 才能使用：
    npm install hexo-server --save
    注意：搭建时如果没有先安装该模块，也可以直接执行 hexo server ；但是当安装完本地搜索 hexo-generator-searchdb 后，提示需要安装该模块，而此时再安装 hexo-server ，会导致 hexo server 运行后，无法预览网页。
  • 下载博客
    git-bash 在同级目录中下载 gitlab 博客仓库：
    git clone git@gitlab.com:username/username.gitlab.io.git username.gitlab
  • 重命名博客目录并拷贝第一步生成的 node_modules 目录
    将前面 hexo 命令生成的 username.gitlab.io 目录重命名 delete
    将 git 下载的博客目录由 username.gitlab 更换为 username.gitlab.io
    将 delete 目录中的 node_modules 拷贝到 username.gitlab.io 中
    也就是从 gitlab 中下载的博客目录需要 hexo 初始化命令生成的 node_modules
    （这里也可以简单的使用比较工具 BeyondCompare 将 git 管理的仓库，合入到 hexo 建立的博客目录中，这样效率比较高）
  • cmd 开启服务验证 
1
2
3
E:\01_work\00_My\06_blog\username.gitlab.io>hexo server -l
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/username.gitlab.io/. Press Ctrl+C to stop.

浏览器中打开 http://localhost:4000/username.gitlab.io 验证！如果有时读取失败或者读取的内容不对，可以清空浏览器的缓存，再重新登录查看！

设置主题和样式 NexT

介绍

Hexo 可以非常方便的更换主题，而且官网及第三方精美主题也很多，本博客选用了国内最流行主题之一： NexT
Hexo 官网及主题
NexT github
NexT 文档
NexT 作者博客
5-7版本
8及以上版本

下载 NexT 主题

Hexo 所有主题都在目录 theme\ 下，直接下载 NexT 主题到该目录：
git clone --branch v5.1.3 https://github.com/iissnan/hexo-theme-next themes/next
下载好后，删掉目录中的 .git, .github 目录，并将该目录整体提交到博客仓库中

更换博客主题

修改站点配置文件，仓库根目录下 _config.yml ，更换主题为 next ： 

1
2
3
4
5
6
7
8
9
10
11
diff --git a/_config.yml b/_config.yml
index 5cb4781..fcb21db 100644
--- a/_config.yml
+++ b/_config.yml
@@ -64,7 +64,8 @@ pagination_dir: page
 # Extensions
 ## Plugins: https://hexo.io/plugins/
 ## Themes: https://hexo.io/themes/
-theme: landscape
+#theme: landscape
+theme: next

更换博客样式

修改主题配置文件，文件路径 theme\next\_config.yml，本博客采用和主题作者一直的样式 Pisces ：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
diff --git a/themes/next/_config.yml b/themes/next/_config.yml
index f12e1a1..7bc85a8 100644
--- a/themes/next/_config.yml
+++ b/themes/next/_config.yml
@@ -99,9 +99,9 @@ menu_icons:
 # ---------------------------------------------------------------

 # Schemes
-scheme: Muse
+#scheme: Muse
 #scheme: Mist
-#scheme: Pisces
+scheme: Pisces
 #scheme: Gemini

参考官网文档对这几种样式有基本的介绍及效果展示：

设置语言，支持中文

修改站点配置文件，仓库根目录下 _config.yml ，设置语言为 zh-Hans 支持中文： 

1
2
3
4
5
6
7
8
9
10
11
diff --git a/_config.yml b/_config.yml
index fcb21db..486f8b5 100644
--- a/_config.yml
+++ b/_config.yml
@@ -7,7 +7,7 @@ title: Hexo
 subtitle:
 description:
 author: John Doe
-language:
+language: zh-Hans
 timezone:

设置菜单

常见菜单有：主页、标签、分类、归档，NexT 默认只有主页和归档，需要添加标签和分类 

1
2
3
4
5
6
7
8
9
10
11
12
13
// 1. hexo 命令新建标签页面
E:\01_work\00_My\06_blog\username.gitlab.io>hexo new page tags
INFO  Created: E:\01_work\00_My\06_blog\username.gitlab.io\source\tags\index.md

// 2. 修改产生的文件，添加页面类型
// 在 source\tags\index.md 文件中添加 'type: "tags"' ，将页面的类型设置为 tags
---
title: tags
date: 2017-10-12 09:54:34
type: "tags"
---

// 3. 同样方式新建分类页面
  • 添加新菜单支持
    修改主题配置文件，文件路径 theme\next\_config.yml，把 tags 和 categories 注释取消掉
1
2
3
4
5
6
7
8
9
menu:
  home: / || home
  #about: /about/ || user
  tags: /tags/ || tags
  categories: /categories/ || th
  archives: /archives/ || archive
  #schedule: /schedule/ || calendar
  #sitemap: /sitemap.xml || sitemap
  #commonweal: /404/ || heartbeat

添加本地搜索

添加百度/谷歌/本地 自定义站点内容搜索

  • 安装 hexo-generator-searchdb
    在站点的根目录下执行以下命令： 
1
2
3
4
5
E:\01_work\00_My\06_blog\username.gitlab.io>npm install hexo-generator-searchdb --save
hexo-site@0.0.0 E:\01_work\00_My\06_blog\username.gitlab.io
`-- hexo-generator-searchdb@1.0.8
  +-- ejs@1.0.0
  `-- striptags@3.1.0
  • 编辑站点配置文件，新增以下内容到任意位置： 
1
2
3
4
5
search:
  path: search.xml
  field: post
  format: html
  limit: 10000
  • 编辑主题配置文件，启用本地搜索功能： 
1
2
3
# Local search
local_search:
  enable: true

设置站点相关信息

修改站点配置文件，仓库根目录下 _config.yml ，添加站点相关信息： 

1
2
3
4
5
6
7
# Site
title: Earth Guardian
subtitle: You are not LATE!You are not EARLY!
description: 地球卫士
author: redspider110
language: zh-Hans
timezone: Asia/Shanghai

其他主题设置

修改主题配置文件，文件路径 theme\next\_config.yml

  • 站点建立时间
    取消如下字段的注释： since: 2017

  • 开启页面统计
    找到 busuanzi_count 设置项，按照如下方法修改 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
$ git diff themes/next/_config.yml
diff --git a/themes/next/_config.yml b/themes/next/_config.yml
index e9b0371..2d757eb 100644
--- a/themes/next/_config.yml
+++ b/themes/next/_config.yml
@@ -478,18 +478,19 @@ leancloud_visitors:
 # Get more information on http://ibruce.info/2015/04/04/busuanzi/
 busuanzi_count:
   # count values only if the other configs are false
-  enable: false
+  enable: true
   # custom uv span for the whole site
-  site_uv: true
+  site_uv: false
   site_uv_header: <i class="fa fa-user"></i>
   site_uv_footer:
   # custom pv span for the whole site
-  site_pv: true
+  site_pv: false
   site_pv_header: <i class="fa fa-eye"></i>
   site_pv_footer:
   # custom pv span for one page only
   page_pv: true
-  page_pv_header: <i class="fa fa-file-o"></i>
+  #page_pv_header: <i class="fa fa-file-o"></i>
+  page_pv_header: <i class="fa fa-eye"></i> 阅读次数
   page_pv_footer:
  • 开启页面阅读进度
    scrollpercent: true

gitlab/github 混合发布

最近（2018.3.1之后） gitlab pages 功能异常，每次提交后 CI/CD 都会出错，提示 hexo 找不到，具体错误如下： 

1
2
3
4
5
6
7
8
9
├── moment@2.21.0
├── cheerio@0.20.0 (entities@1.1.1, dom-serializer@0.1.0, css-select@1.2.0, htmlparser2@3.8.3, jsdom@7.2.2)
├── warehouse@2.2.0 (graceful-fs@4.1.11, is-plain-object@2.0.4, JSONStream@1.3.2, cuid@1.3.8)
└── lodash@4.17.5
npm info ok 
$ hexo deploy
ERROR Local hexo not found in /builds/***/hexo
ERROR Try running: 'npm install hexo --save'
ERROR: Job failed: exit code 1

提了个 issues ，后期再找解决方案。当前先采用 gitlab/github 混合发布的方法提交：

  • github
    发布的时候，提交上去的只有转换好的 html 文件，当做 pages 使用。
  • gitlab
    保存文本及所有提交记录，方便后续追溯。

环境准备

按照上面的方法搭建 gitlab 环境及 hexo 博客，参考静态博客搭建指南 搭建 github pages，生成对应的仓库，并添加 ssh-key。

修改配置文件

上一步拿到了 github pages 仓库地址：git@github.com:***/***.github.io.git，修改当前博客的配置文件 _config.yml： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
diff --git a/_config.yml b/_config.yml
index a7356be..e3ea455 100644
--- a/_config.yml
+++ b/_config.yml
@@ -12,9 +12,11 @@ timezone: Asia/Shanghai

 # URL
 ## If your site is put in a subdirectory, 
 # set url as 'http://yoursite.com/child' and root as '/child/'
-url: /
-root: "/***.gitlab.io/"
+url: http://***.github.io
+root: /
 permalink: :year/:month/:day/:title/
 permalink_defaults:

@@ -79,9 +81,9 @@ theme: next
 # Deployment
 ## Docs: https://hexo.io/docs/deployment.html
 deploy:
-  type:git
-  repo:git@gitlab.com:***/***.gitlab.io.git
-  branch:master
+  type: git
+  repo: git@github.com:***/***.github.io.git
+  branch: master

注意：有些公司可能会屏蔽 github 的 ssh 连接，因此 repo 中需要使用 https 的免密方式来访问 github 。

  • 问题描述
    使用 ssh 来测试是否能正确访问 github ，提示 22 端口被 reset ；原因是公司可能开防火墙等封了这种访问方式。 
    1
    2
    $ ssh -T git@github.com
    Connection reset by 52.74.223.119 port 22
  • 解决方案
    在 _config.xml 中使用 https 方式，显示指定账号密码来访问： 
    1
    2
    #  repo: git@github.com:***/***.github.io.git
      repo: https://username:password@github.com/username/username.github.io.git

安装 hexo-deployer-git

  • 安装
    npm install --save hexo-deployer-git ，安装 hexo-deployer-git 发布工具。
  • 配置
    安装完 hexo-deployer-git 工具后，执行 hexo d -g 后会在当前 blog 目录下，生成 .deployer-git 目录，它是一个 .git 仓库，我们使用 hexo d 命令发布时，也就是将该 .git 仓库提交到远程目标仓库上。
    使用 git config user.name/email 配置远程仓库的访问账号。

提交和发布

  • 提交
    提交是指提交到 gitlab 中，使用常用的 git 命令 commit 就行。
  • 发布
    发布是指发布到 github pages 中，使用 hexo d -g 命令发布，同时会在 github 中生成提交记录，但这个提交记录可读性非常差，通常为生成 html 更新所有目录。

问题排查过程

问题描述：代码推送(git push) 到 gitlab 仓库后， CI/CD 中 Pipelines 总是出错，导致博客主页无法显示最新的修改。整理排查流程如下：

Pipelines 中查看问题原因

  • 在 gitlab/CI/CD/pipeline 查看具体的 JobId
  • 点开这个 JobId 查看具体的出错原因；可以看出是 hexo generator 失败

0001-pipeline-jobid.png

0001-pipeline-jobid-error-details.png

本地直接执行验证

本地执行 hexo generator 验证发现是成功的，继续查看上面的日志，发现 gitlab 中使用的是 hexo 4.x 而本地是安装的 hexo 3.x ：

  • 本地升级 hexo 版本，重新按照新建博客本地环境，并拷贝 node_modules ；合入 hexo 3.x 的配置文件，在新博客目录下再次验证发现仍然失败
  • hexo init myblog.io 重新初始化一个空博客，在这个空博客中验证本地环境，结果是正常显示；说明 hexo 环境没问题
  • 切换自己博客主题为 hexo 默认主题 landscape ，验证结果正常显示；说明是自己博客选的第三方主题 NexT 的兼容性问题
  • 到 NexT 官网查看，发现当前 NexT 的版本 5.x 只支持 hexo 3.x ，参考 NexT upgrade from 5.x
  • 升级 NexT 到最新的 7.x ，并合入 5.x 的配置文件，再次本地验证，能够正常显示；说明本地环境全部正常了
  • 推送到 gitlab 发现 Pipelines 还是失败，原因仍然是 hexo generator 失败；怀疑本地环境和 gitlab 环境不一致
  • 因为 gitlab 博客是在 docker 环境发布的，在 gitlab hexo pages 主页 查看最新 .gitlab-ci.yml 配置文件
  • 将最新的 .gitlab-ci.yml 替换本地配置文件重新提交到 gitlab 后， Pipelines 运行通过！！
  • 查看博客网址验证，全部正常，至此问题全部解决

如果遇到其他问题，也可以在 gitlab hexo pages 主页 中提 issues ，或者查看其他人是否有遇到过类似问题。

常见问题

css is missing

访问博客时，没有任何 css 样式，解决方案为在 _config.yml 文件中修改 root 目录： 

1
2
3
4
5
6
7
8
9
10
11
diff --git a/_config.yml b/_config.yml
index 78c62ed..5cb4781 100644
--- a/_config.yml
+++ b/_config.yml
@@ -13,7 +13,8 @@ timezone:
 # URL
 ## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
 url: /
-root: "/hexo/"
+#root: "/hexo/"
+root: "/yourusernname.gitlab.io/"

hexo version 查看版本号提示本地没有 hexo

错误信息如下，查看版本提示并没有 hexo 命令？

1
2
3
E:\01_work\00_My\06_blog> hexo version
ERROR Local hexo not found in E:\01_work\00_My\06_blog
ERROR Try running: 'npm install hexo --save'

这是因为当前博客目录已经包含了 hexo 相关配置文件了，需要重新在 Windows cmd 终端中运行上述命令，生成 node_modules 目录。

参考