VitePress 技术博客搭建全过程记录

前言

本文记录了使用 VitePress 搭建技术博客的完整过程，包括技术选型、Docker 部署、CI/CD 配置、安全检查等环节。

一、需求分析

目标

• 基于 VitePress 搭建技术博客
• 便于更新 Markdown 文档
• 支持 CI/CD 自动化部署
• 部署到自有服务器（Docker 容器）

技术选型

组件	选择	理由
静态站点生成器	VitePress	轻量、快速、Vue 生态
容器平台	Docker	跨平台、一致性部署
镜像仓库	阿里云 ACR 个人版	免费、 国内访问快
CI/CD	GitHub Actions	免费额度、集成方便
自动更新	Watchtower	简单、自动化

二、项目初始化

创建项目结构

static_blog/
├── docs/                      # VitePress 源文件
│   ├── .vitepress/
│   │   └── config.mts         # VitePress 配置
│   ├── posts/                 # 博客文章目录
│   ├── index.md               # 首页
│   └── about.md               # 关于页
├── .github/
│   └── workflows/
│       └── deploy.yml         # GitHub Actions 工作流
├── docker-compose.yml         # 容器编排
├── Dockerfile                 # 多阶段构建
├── package.json               # 项目配置
└── .env.example              # 环境变量模板

安装依赖

npm init -y
npm install -D vitepress vue

VitePress 配置

// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: "技术博客",
  description: "VitePress 技术博客",
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '文章', link: '/posts/' },
      { text: '关于', link: '/about' }
    ],
    socialLinks: [
      { 
        icon: 'github', 
        link: `https://github.com/${import.meta.env.VITE_GITHUB_USER}`
      }
    ]
  }
})

三、Docker 配置

Dockerfile（多阶段构建）

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run docs:build

FROM nginx:alpine
COPY --from=builder /app/docs/.vitepress/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

docker-compose.yml（含 Watchtower）

version: '3.8'

services:
  blog:
    image: blog:latest
    ports:
      - "3000:80"
    restart: unless-stopped
    labels:
      - "com.centurylinklabs.watchtower.scope=blog"

  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
    command: --scope blog --interval 300
    restart: unless-stopped

四、CI/CD 配置

GitHub Actions 工作流

name: Build and Push to ACR

on:
  push:
    branches:
      - main

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Alibaba Cloud ACR
        uses: docker/login-action@v3
        with:
          registry: ${{ secrets.ACR_REGISTRY }}
          username: ${{ secrets.ACR_USERNAME }}
          password: ${{ secrets.ACR_PASSWORD }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ${{ secrets.ACR_REGISTRY }}/${{ secrets.ACR_NAMESPACE }}/blog:latest

需要配置的 GitHub Secrets

Secret	说明
ACR_REGISTRY	ACR 地址（如 crpi-xxx.cn-hangzhou.personal.cr.aliyuncs.com）
ACR_NAMESPACE	命名空间
ACR_USERNAME	阿里云账号
ACR_PASSWORD	ACR 访问密码

五、自动部署流程

┌─────────────┐    push     ┌─────────────┐         ┌─────────────┐
│   本地开发   │ ──────────► │  GitHub     │  push   │   阿里云    │
│ (写 md)     │             │ (Actions)   │ ──────► │    ACR      │
└─────────────┘             └─────────────┘         └─────────────┘
                                                      │
                                                      │ 定期轮询 (每5分钟)
                                                      ▼
                                               ┌─────────────┐
                                               │   服务器    │
                                               │  Watchtower │ ──► 自动更新
                                               └─────────────┘

六、安全检查

检查项目

检查项	结果
外部链接有效性	⚠️ 存在占位符
敏感信息泄露	✅ 无
npm 依赖漏洞	✅ 无
Docker 安全	✅ 安全

环境变量配置

敏感信息通过 .env 文件管理：

# .env.example
VITE_GITHUB_USER=your-github-username
VITE_EMAIL=your-email@example.com

.env 文件已加入 .gitignore，不会被提交到仓库。

七、Playwright E2E 测试

测试计划

测试类别	测试项
页面加载	各页面 HTTP 200
首页	Hero, Features, Actions
导航	顶部导航、侧边栏
链接	外部链接、内部链接
SEO	Meta 标签

运行测试

npm run docs:dev  # 启动开发服务器
npx playwright install chromium
npx playwright test

八、Git 提交记录

提交	说明
docs: 添加 VitePress 文档源文件	初始文档
chore: 添加 package.json 项目配置	依赖配置
docker: 添加 Docker 构建配置	Docker 配置
ci: 添加 GitHub Actions 工作流	CI/CD 配置
config: 添加配置文件和 README	配置文件
docs: 添加 AGENTS.md 项目说明	Agent 说明
docs: 添加开发计划文档	开发计划
test: 添加 Playwright 测试计划与配置	测试配置
docs: 添加安全检查报告	安全检查
chore: 添加环境变量配置	环境变量

九、后续扩展

• [ ] 添加全文搜索功能
• [ ] 添加 RSS 订阅
• [ ] 添加评论功能
• [ ] 添加站点统计
• [ ] 自定义主题样式

总结

本文记录了从零搭建 VitePress 技术博客的完整过程，包括项目初始化、Docker 容器化、CI/CD 自动化、安全检查等环节。通过环境变量管理敏感信息，使用 Watchtower 实现自动更新，整个部署流程自动化程度很高。

---

本文档基于实际搭建过程整理，记录日期：2024