cms静态页面生成原理java 搭建静态页面

转载

云端小悟空 2024-04-25 16:07:04

文章标签 cms静态页面生成原理java docker git 模版 文章分类 Java 后端开发

一、背景和介绍

背景简单说下，需要一个静态页面来呈现说明某些文档，浏览器可以直接访问，接入成本要低
这里主要介绍mkdocs，mkdocs接入成本低，语法简单

二、准备

git：用于托管文档代码，版本迭代方便
docker：用于快速构建mkdocs环境依赖
jenkins：用于SCM自动同步代码到静态页面
注：

如果不用docker也可以，可以单独配置mkdocs的依赖环境，主要依赖python3，pip，mkdocs包（建议使用mkdocs-materia主题，比较好看，当然你也可以选用别的主题）
如果不实用jenkins实现自动同步代码，也可以使用git hook来实现，本文不做深入介绍

三、搭建步骤

本地安装下mkdocs的依赖，先安装python3，再执行pip install mkdocs，pip install mkdocs-material即可
idea或其他编译器创建工程，mkdocs xxx执行后即可创建出一个基础的mkdocs工程，稍加修改，添加本地material模版文件（用于自定义使用，可以对前端代码稍作修改，比如不想展示模版中的某个icon，想修改原模版某个控件的长宽比例等等，修改需要基本的js和html技术基础），模版文件可以从github下下载，https://github.com/squidfunk/mkdocs-material，粘贴到自己新建工程的根路径下，如图所示即可代码上传到git上（可以是github，也可以是自己搭建的git远程仓库，也可以是公司的git私有远程仓库，看个人需求）；当然之前如果有mkdocs的模版，也可复制之前的模版，都弄完后，项目工程路径结构如下：

material模版文件如果本地配置，需要在mkdocs.yml中指定本地路径

# Project information
site_name: 'xxx'
site_author: 'xxx'
docs_dir: docs
nav:
  - 首页: 'index.md'
  - 自媒体测试工具:
    - UI自动化图片对比: 'wemedia/ui_compare.md'
    - Mock热替换: 'wemedia/mock_hot_update.md'


# Repository
#repo_name: 'squidfunk/mkdocs-material'
#repo_url: 'https://github.com/squidfunk/mkdocs-material'

## Copyright
copyright: 'Copyright © xxx'

# Configuration
theme:
  name: 'material'
  custom_dir: 'material'###这里可以需要指定本地模版文件路径，如果不配置，则直接拉取安装的默认material模版
  language: 'zh'
  palette:
    primary: 'teal'
    accent: 'blue'
  font:
    text: 'Bree'
    code: 'Bree Serif'
  feature:
    tabs: false

执行mkdocs serve启动mkdocs服务，就可以在浏览上访问静态文档页面了，至此，成功了一半了

准备docker 镜像（需要自行安装docker，比较简单，自行百度即可）

docker相关

制作Dockerfile

FROM squidfunk/mkdocs-material
MAINTAINER xx@xxx.com
WORKDIR /docs
ADD doc.tar.gz /docs

进入服务器或测试机器，执行以下命令，mkdir -p /home/worker/docs && cd /home/worker/docs && docker pull squidfunk/mkdocs-material && docker build -t xxx-mkdocs . && docker run -d -p 9998:8000 xxx-mkdocs"，服务器上的mkdocs就以docker形式启动起来了，访问http://服务器ip:9998即可访问到静态页面了
至此，成功了90%了，还剩最后一步，结合jenkins，实现更新mkdocs代码自动部署到服务器上，实现实时更新静态mkdocs文档

创建jenkins job（当然如果你使用的gitlab托管mkdocs代码，你可以使用gitlab的pipeline来替代jenkins，更简单；如果你熟悉git的hook使用方式，也可以替代jenkins，也比较简单，看你自己熟悉哪一种方式）

新建jenkins job，说下关键地方的配置

构建方式选择定时轮训仓库代码变化，频率建议1或2分钟轮训一次
将上一步的shell脚本添加到job的build的shell脚本中，这里设计公司内部地址，不粘贴了，大概命令如下

#找到你之前定义的Dockerfile，至于放在哪，你自己决定，构建脚本中拉取到Dockerfile就行，我直接把Dockerfile放到了git代码上，和mkdocs的代码在一起托管，获取Dockerfile的脚本，自己写一下对应的shell脚本吧
#ci部署脚本中还需要检查之前是否已经部署了相同的docker镜像，如果有，需要删掉原来的容器和镜像，删除后再部署镜像
cmd="docker ps -a|grep xxx|wc -l"
RESPONSE=`ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 worker@测试机器ip "$cmd"`
ret=$?

if [ "$RESPONSE" != '0' ]; then
    cmd="docker ps -a| grep xxx |awk '{print \$1}'| xargs docker rm -f"
    RESPONSE=`ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 worker@${host} "$cmd"`
    echo $?
fi

cmd="docker ps |grep xxx|wc -l"
RESPONSE=`ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 worker@测试机器ip "$cmd"`
ret=$?

if [ "$RESPONSE" != '0' ]; then
    cmd="docker ps | grep xxx |awk '{print \$1}'| xargs docker stop"
    RESPONSE=`ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 worker@测试机器ip "$cmd"`
    echo $?
fi


#如果涉及到jenkins的slave机器与实际配置mkdocs的机器不是同一个机器，需要ssh命令，可参考如下命令
cmd="mkdir -p /home/worker/docs && cd /home/worker/docs && docker pull squidfunk/mkdocs-material && docker build -t xxx-mkdocs . && docker run -d -p 9998:8000 xxx-mkdocs"
RESPONSE=`ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 worker@测试机器ip 
 "$cmd"`

至此，配置完成了，之后你每次更新mkdocs的代码，然后push到git上，就可以自动更新服务器上的静态文件了