跳转至

自动构建知识库

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 安装插件

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,验证构建结果是否成功。