自动构建知识库

MkDocs+Jenkins+Gitee+Nginx

实现效果：当代码推送到笔记仓库后，立即触发 Jenkins 构建任务，并发布笔记到云服务器上。

适用场景：

• 个人知识库
• 技术分享
• 简历加分

准备

流程

服务器

• 服务商：腾讯云轻量级服务器
• ip:114.132.62.78
• 版本：Ubuntu20.04

如果是腾讯云的 ubuntu20.04，需要先执行以下准备工作：

# 初始化root用户
$ sudo passwd root

# 开启ssh远程访问
$ echo 'PermitRootLogin yes' >> /etc/ssh/sshd_config
$ sudo service ssh restart

添加新用户

本文默认都是使用 cifer 用户进行操作。

# 添加用户
sudo adduser cifer

# 添加到sudo组
sudo usermod -aG sudo cifer

# 切换用户
su cifer

Gitee 仓库

自己创建一个专门存放笔记的项目仓库。

Python3

apt 工具包更新后自带 Python3.8.10

# 更新本地包
sudo apt update

# 检查python版本
python3 -V

安装 mkdocs 相关依赖

• mkdocs
• mkdocs-material

# 安装virtualenv
$ apt install python3-virtualenv

# 创建虚拟环境
$ mkdir ~/envs
$ cd ~/envs
$ virtualenv mk

# 激活虚拟环境
$ source ~/envs/mk/bin/activate

# 安装mkdocs
$ pip install mkdocs
# 检查mkdocs版本
$ mkdocs -V

# 安装mkdocs-material
$ pip install mkdocs-material

备注：如果安装库网速慢，可以给pip install加上豆瓣镜像选项，例如：

pip install mkdocs -i https://pypi.douban.com/simple

mkdocs的配置文件mkdocs.yml:

site_name: 百里测试小站
site_description: 百里测试小站
site_author: 百里

theme:
  name: material
markdown_extensions:
  - attr_list
  - admonition
  - toc:
      permalink: true
  - pymdownx.tasklist:
      custom_checkbox: true

Java11

# 安装openjdk
$ apt install openjdk-11-jdk

# 检查安装结果
$ java -version

记住 Java 可执行文件路径：/usr/lib/jvm/java-11-openjdk-amd64，后面配置 Jenkins 代理节点需要。

Docker

预备依赖

# 更新本地包
$ sudo apt update

# 安装必要的一些依赖
$ sudo apt install apt-transport-https ca-certificates curl software-properties-common

# 为Docker仓库添加GPG key：
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

# 把Docker仓库添加到APT源：
$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"

# 安装docker
$ sudo apt install docker-ce

# 验证安装结果
$ docker --version

# 添加分组（避免每次输入sudo）
$ sudo usermod -aG docker cifer

# 切换用户（这时需要输入密码）
$ su - cifer

# 检查权限（预期：cifer sudo docker）
$ groups

Nginx

# 初始化挂载目录
$ mkdir -p ~/nginx_mount/conf
$ mkdir -p ~/nginx_mount/html
$ mkdir -p ~/nginx_mount/logs

# 修改目录权限（以便mkdocs生成的资源可以拷贝覆盖其中）
$ chmod 777 ~/nginx_mount/html

# 添加配置文件
$ vi ~/nginx_mount/conf/nginx.conf

配置信息内容，并保存。

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       80;

        location / {
            root   html;
            index  index.html index.htm;
        }

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

启动 nginx 容器：

# 启动Nginx容器
$ docker run -d --name nginx-cifer -p 80:80 -v ~/nginx_mount/conf/nginx.conf:/etc/nginx/nginx.conf -v ~/nginx_mount/html:/etc/nginx/html -v ~/nginx_mount/logs:/var/log/nginx nginx

备注：记得在云服务器中的安全组（阿里云）/防火墙（腾讯云）中开放80端口。

Jenkins

1 运行容器

cd ~

# 初始化挂载目录
$ mkdir jenkins_mount

# 修改权限
$ chmod 777 jenkins_mount

# 启动Jenkins容器
$ docker run -d -p 8080:8080 -p 50000:50000 -v $PWD/jenkins_mount:/var/jenkins_home --name jenkins-cifer jenkins/jenkins:lts

# 查看容器运行情况
$ docker ps

备注：记得在云服务器中的安全组（阿里云）/防火墙（腾讯云）中开放以上端口。

2 初始化

访问地址：http://114.132.62.78:8080/

• 解锁 Jenkins

获取管理员密码：

# 查询Jenkins解锁密码
$ cat ~/jenkins_mount/secrets/initialAdminPassword

解释：因为是容器，所以用容器挂载目录～/jenkins_mount 替换/var/jenkins_home 即可。

• 初始化插件

添加用户

3 安装插件

• Gitee：用来实现 WebHook 触发构建

  菜单路径：http://114.132.62.78:8080/pluginManager/

4 添加代理

菜单路径：http://114.132.62.78:8080/computer/

• 新建节点

• 配置代理节点

绑定 Ubuntu20.04 宿主机作为节点，用来实际执行 python3 脚本。

选项	来源	值
名字	自定义	tencent-ubuntu
描述	自定义	腾讯云的服务器
Numbers of executors	默认	1
远程工作目录	自定义	/home/cifer/jenkins_dir
标签	自定义	ubuntuOnTencent
用法	自定义	Use this node as much as possible
启动方式	自定义	Launch agents via SSH 主机：114.132.62.78 Credentials：手工添加 Ubuntu 用户的凭证 Host Key Verification Strategy：Non 端口：22 Java 路径：/usr/lib/jvm/java-11-openjdk-amd64/bin/java
可用性	默认	尽量保持代理上线
节点属性	自定义	工具位置 名称：(Git) Default 目录：/usr/bin/git

• 启动代理

如果日志提示：Agent successfully connected and online，则表示代理节点启动成功。

代理节点正常时的节点列表状态：

5 创建任务

• 面板：General

• 限制项目的运行节点

标签表达式：填入代理节点的名称，例如tencent-ubuntu

• 面板：源码管理

• Git

具体选项	操作	值
Repository URL	修改	https://gitee.com/amoyshmily/testie.git
Credentials	修改	添加凭证（username with password）
Branches to build	默认	*/master
源码库浏览器	默认	（自动）
Additional Behaviours	默认

|

• 面板：构建触发器
• Gitee webhook 触发构建

具体选项	操作	值
Gitee 触发构建策略	修改	- [x] 推送代码
Gitee WebHook 密码	修改	手动点击生成
更新 Pull Requests	默认
评论内容的正则表达式	默认	Retry build
构建指令过滤	默认
允许触发构建的分支	默认

备注：此选项只有在 Jenkins 安装了 Gitee 插件后才可以使用。

生成密码后，可以进入 Gitee 仓库的管理菜单中，进行 webhook 的配置： URL：当前选项自动生成的地址 WebHook 密码：当前生成的密码串 选择事件： Push

• 面板：构建

选择：执行 shell

#!/bin/bash

# 激活虚拟环境
source /home/cifer/envs/mk/bin/activate

# 构建项目
mkdocs build

# 修改文件权限
chmod 777 site/*

# 拷贝到nginx目录
cp -r ~/jenkins_mount/workspace/testie-notes/site/. ~/nginx_mount/html/

备注：testie-notes为 Jenkins 的 job 名称。

如果非虚拟环境，则加上python3 -m 来执行：

python3 -m mkdocs build

到此，任务已经配置完毕，可以尝试手工触发执行 job，验证构建结果是否成功。