（二）Jenkins 与 CI/CD | 基于 VitePress 快速搭建静态网站

老实巴交的麻匪
259 阅读9分钟

系列文章：

（一）Jenkins 与 CI/CD | 容器化启动 Jenkins with docker in docker

（二）Jenkins 与 CI/CD | 基于 VitePress 快速搭建静态网站

（三）Jenkins 与 CI/CD | 在 GitHub 中发布静态网站

前言

第一篇文章介绍了以 Docker 容器启动 Jenkins 并初始配置。为了更好体会 Jenkins 在 CI/CD 中的作用，本文基于 VitePress 快速搭建静态网站，这是一个简单优雅，同时又非常有用的项目。本文手把手搭建技术博客，你将掌握此项技能，可根据个人需求搭建在线名片、学术网页、生活日志等网站，是一个非常简单但又时髦实用的技能。

本文不涉及 Jenkins 的使用，Jenkins 将会在后续的连载文章中登场。这样的安排是我精心设计的，阅读系列文章，相信你一定能获得超期待的收获！

项目地址：

静态博客

静态博客是一种基于静态网页搭建起来的博客形式。从网页构成看，它由单纯的静态文件组成，像 HTML、CSS 与 JavaScript。利用如 Hugo、Jekyll 这类静态站点生成器，把用 Markdown 等格式撰写的内容，依照设定模板“编译”成一系列静态网页，每个页面的内容与样式就此固定下来。

在部署方面，它相当简便，能托管在众多支持静态文件存储的平台，像是 GitHub Pages、Netlify 等，只需上传生成好的静态文件，就能让博客上线运营。日常更新时，博主新增或修改文章后，再次运行站点生成器，重新生成整套静态网页，替换掉旧的对应文件。它因没有后端数据库交互，加载速度飞快，访问体验流畅，还避开了数据库相关的安全风险，不过，它缺少动态交互功能，内容更新也不像有后台管理系统的动态博客那般便捷。

著名的静态博客类项目：

项目开发引擎GitHub Stars许可证主题模板
HugoGo77kApache-2.0300+
VitePressTypeScript + Vue13.6kMIT-
JekyllRuby49.4kMIT300+
HexoNode.js (TypeScript)39.8kMIT400+

Hugo： The world‘s fastest framework for building websites.

由 Go 语言开发，旨在为用户提供极佳的性能和高度的灵活性。通过先进的模板系统和快速的资源处理管道，能够在几秒钟内渲染完整的网站。Hugo 适用于创建各种类型的网站，包括公司网站、政府网站、非营利组织网站、教育网站、新闻网站、图像画廊、落地页、商业博客、个人博客、简历等

hugo-themes.png

VitePress： 由 Vite 和 Vue 驱动的静态站点生成器，将 Markdown 变成优雅的文档，只需几分钟。

该项目由 Vue 作者尤雨溪创建并维护。VitePress 的核心特点：

  • 专注内容：只需 Markdown 即可轻松创建美观的文档站点。
  • 享受 Vite 无可比拟的体验：服务器即时启动，闪电般的热更新，还可以使用基于 Vite 生态的插件。
  • 使用 Vue 自定义：直接在 Markdown 中使用 Vue 语法和组件，或者使用 Vue 组件构建自定义主题。
  • 速度真的很快：采用静态 HTML 实现快速的页面初次加载，使用客户端路由实现快速的页面切换导航。

VitePress.png

Jekyll： Transform your plain text into static websites and blogs.

Jekyll 是一个简单的、博客感知的静态网站生成器，非常适合个人、项目或组织网站。把它想象成一个基于文件的 CMS，没有所有的复杂性。Jekyll 获取您的内容，呈现 Markdown 和 Liquid 模板，并生成一个完整的静态网站，准备好由 Apache、Nginx 或其他 Web 服务器提供服务。Jekyll 是 GitHub Pages 背后的引擎，您可以使用它直接从 GitHub 存储库托管网站。

Jekyll-home.png

Hexo： 快速简洁且高效的博客框架。

Hexo 基于 Node.js 构建，通过简单的命令行工具和易于配置的文件，使得用户可以轻松地搭建和管理自己的博客或静态网站。

hexo-home.png

本文搭建 VitePress 站点作为例子。推荐大家可以在上述所列的网站中看一看，根据自己的需求选择合适的主题，动手搭建个人网站。

开始 VitePress

使用 VitePress 搭建个人网站，并使用 Docker 容器化部署

项目概述

  1. 前置准备：宿主机安装 docker、node 等开发环境
  2. 项目初始化：基于 VitePress 脚手架初始化项目
  3. 🌟项目开发与测试：启动项目，开发...
  4. 容器化：将项目打包为 Docker 镜像，定义 Dockerfile 和 docker-compose.yaml
  5. 预发布：在本地环境使用 Docker 容器启动项目
  6. 项目托管：将项目源代码推送到 GitHub（或 Gitlab Gitee）

前置准备

软件依赖包：

  • Node.js 18及以上版本
  • Docker、Docker Compose
  • 开发集成环境（IDE）: VSCode、WebStorm 等其一

在项目目录下（如 VscodeProjects 或 WebstormProjects），创建空项目文件夹 docker-vitepress

mkdir docker-vitepress && cd docker-vitepress

推荐使用 pnpm 启动 VitePress

# 安装pnpm
npm install -g pnpm@latest
pnpm add -D vitepress

项目初始化

VitePress 附带一个命令行设置向导，可以帮助快速构建一个初始化项目。

运行以下命令启动向导

pnpm vitepress init

根据命令提示，初始化项目

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
└  Done! Now run pnpm run docs:dev and start writing.

安装后项，项目目录结构下图所示：

.
├── README.md
├── docs
│    ├── api-examples.md
│    ├── index.md
│    └── markdown-examples.md
├── node_modules
│    └── vitepress -> .pnpm/vitepress@1.3.4_@algolia+client-search@4.24.0_postcss@8.4.47_search-insights@2.17.2/node_modules/vitepress
├── package.json
└── pnpm-lock.yaml

🌟功能开发与测试

查看 package.json 下启动脚本

{
  "devDependencies": {
    "vitepress": "^1.3.4"
  },
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

项目根目录启动终端，执行

pnpm run docs:dev
# or
vitepress dev docs

根据提示，在浏览器中打开 http://localhost:5173/ ，可查看到 VitePress 默认页面。

项目停止

# MacOS
Command+C
# Windows
Ctrl+C

容器打包，默认在项目 docs/.vitepress 下生成 dist 包，该包是为静态资源，用于生产发布

pnpm run docs:build
# or
vitepress build docs

容器化

前端资源在生产环境中部署时，将源文件打包为 dist，然后 Nginx 作为 Web 服务器对静态资源代理。

构建镜像

创建并配置 Dockerfile，它定义了镜像打包过程

只需将源代码复制到镜像中，在镜像中构建项目。项目根目录下创建 .dockerignore 文件：

docs/.vitepress/cache

/node_modules/
/docs/.vitepress/dist/
.idea
.gitignore

项目根目录下新建 Dockerfile

touch Dockerfile

如果在阿里云或华为云上构建镜像失败，请自行改资源镜像。

粘贴如下 Dockerfile 模板，根据个人信息更改部分内容。安装 npm 和 pnpm 时默认使用腾讯云资源镜像加速。

FROM node:22-alpine3.20 AS build-stage
# 作者信息
LABEL authors="xing.xiaolin@foxmail.com"

# 设置工作目录
WORKDIR /app

# 复制所有文件到工作目录
COPY . .

# 安装 pnpm Qcloud 腾讯云加速
RUN npm install -g pnpm --registry=http://mirrors.cloud.tencent.com/npm/

# 安装依赖 Qcloud 腾讯云加速
RUN pnpm install --registry=http://mirrors.cloud.tencent.com/npm/

# 构建生产环境下到 Vue 项目
RUN pnpm run docs:build

FROM nginx:alpine3.20-perl

COPY nginx.conf /etc/nginx/conf.d/default.conf

COPY --from=build-stage /app/docs/.vitepress/dist /usr/share/nginx/html

# 暴露端口
EXPOSE 8080

# 启动Nginx服务
CMD ["nginx", "-g", "daemon off;"]

构建服务镜像，并将其命名为 my-vitepress/vitepress-docs:0.0.1

docker build -t my-vitepress/vitepress-docs:0.0.1 .
# buildx 构建
docker buildx build -t my-vitepress/vitepress-docs:0.0.1 .

完成镜像构建，检查

docker ps | grep vitepress-docs

预发布（启动容器化服务）

以下两种方式任选其一。

完成后，在浏览器中打开 http://localhost 可查看预发布效果。

awesome-vite.png

Docker Cli 启动

在终端中执行

# 以 my-vitepress/vitepress-docs:0.0.1 为镜像启动容器
# 以后台方式运行
# 映射容器端口号 8080 到本地端口 80
# 容器命名为 hello-vitepress
docker run -d --name hello-vitepress -p 80:8080 my-vitepress/vitepress-docs:0.0.1

停止容器

docker stop hello-vitepress

删除容器

docker rm hello-vitepress

Docker Compose 启动

在项目根目录下创建 docker-compose.yaml 配置文件

networks:
  vitepress-network:
    external: false

services:
  docker-vitepress:
    image: my-vitepress/vitepress-docs:0.0.1
    container_name: vitepress-test
    ports:
      - '80:8080'
    networks:
      - vitepress-network
    # 设置上海时区
    environment:
      TZ: Asia/Shanghai

创建并启动

docker-compose up -d
# docker compose up -d

停止并卸载

docker-compose down
# docker compose down

项目托管

将项目托管到 GitHub，方便项目分发。任何拥有Docker环境的服务器都可以快速部署该项目。

将本项目托管到 GitHub 或 Gitee（码云，GitHub国内版），以 GitHub 为例

注册并登录GitHub

过程概述

项目托管建议参考GitHub官方文档 Get started

  1. 注册并登录：github.com/
  2. 设置 github-ssh 密钥
    1. 在 .ssh 目录下生成非对称密钥对：id_ed25519 与 id_ed25519.pub
    2. 将公钥 id_ed25519.pub 添加到 GitHub 设置
  3. 创建项目仓库： docker-vitepress
  4. 本地 Git 仓库与 GitHub 仓库关联，推送本地项目

核心步骤

生成密钥对

# 1. 进入 home 目录下的 .ssh 目录，如果没有则创建
cd ~/.ssh
# 2. 创建密钥对，邮箱信息自行更改
ssh-keygen -t ed25519 -C "xing.xiaolin@foxmail.com"

配置 .gitignore

.gitignore 文件的作用是定义哪些文件或文件夹应该被 Git 版本控制系统忽略，不被跟踪和提交到仓库中。

touch .gitignore

忽略 Git 仓库中 IDE 配置文件以及其他依赖包、目标文件，仅保留项目源代码

docs/.vitepress/cache
docs/.vitepress/dist/
node_modules
# Jetbrains软件配置文件
.idea

使用 Git 推送项目过程略。

总结

本文首先介绍静态资源站点框架，并列举著名的开源项目 Hugo、VitePress、Jekyll 和 Hexo。然后，从头开始创建 VitePress 项目，并将项目打包为 Docker 镜像并启动容器。最后，将项目源代码托管到 GitHub 平台，便于项目迁移。

下一步，将该 VitePress 站点项目进行生产发布，有两种方式：

  • GitHub 发布：使用 GitHub Actions、 GitHub Pages 免费托管项目
  • 云服务器发布：云服务器（支持公网 ip 访问）发布项目

这两种方式在后续的文章中都会实现！

关注微信公众号，获取运维资讯

如果此篇文章对你有所帮助，感谢你的点赞与收藏，也欢迎在评论区友好交流。

微信搜索关注公众号：持续运维

参考

  1. Hugo 官网 gohugo.io/
  2. VitePress 官网 vitepress.dev/
  3. Jekyll 官网 jekyllrb.com/
  4. Jamstack Themes jamstackthemes.dev/
  5. Hexo 中文官网 hexo.io/zh-cn/
  6. Hexo 主题 hexo.io/themes/
  7. GitHub 文档，开始你的旅程，docs.github.com/zh/get-star…
avatar
文章
阅读
粉丝