VitePress 技术博客搭建计划

一、项目概述

基于 VitePress 搭建的技术博客，使用 Docker 容器化部署，通过 GitHub Actions CI/CD 自动推送到阿里云 ACR，服务器端使用 Watchtower 自动更新。

二、技术栈

组件	版本	用途
VitePress	^1.5.0	静态站点生成器
Vue	^3.5.13	VitePress 依赖
Node.js	20	构建环境
Nginx	Alpine	生产容器
Docker Compose	3.8	容器编排
Watchtower	latest	自动更新镜像
GitHub Actions	-	CI/CD

三、项目结构

static_blog/
├── docs/                      # VitePress 源文件
│   ├── .vitepress/
│   │   └── config.mts         # VitePress 配置
│   ├── posts/                 # 博客文章目录
│   │   └── welcome.md         # 示例文章
│   ├── index.md               # 首页
│   ├── about.md               # 关于页
│   └── dev-plan.md            # 开发计划（本文档）
├── .github/
│   └── workflows/
│       └── deploy.yml         # GitHub Actions 工作流
├── docker/
│   ├── Dockerfile             # 多阶段构建
│   └── nginx.conf             # Nginx 配置（可选）
├── docker-compose.yml         # 容器编排
├── package.json               # 项目配置
└── AGENTS.md                  # Agent 说明文档

四、部署流程

完整架构图

┌─────────────┐    push     ┌─────────────┐         ┌─────────────┐
│   本地开发   │ ──────────► │  GitHub     │  push   │   阿里云    │
│ (写 md)     │             │ (Actions)   │ ──────► │    ACR      │
└─────────────┘             └─────────────┘         └─────────────┘
       │                                                │
       │ npm run docs:build                            │ 定期轮询 (每5分钟)
       ▼                                                ▼
   构建静态文件                                   ┌─────────────┐
                                                  │   服务器    │
                                                  │  Watchtower │ ──► 自动更新
                                                  └─────────────┘

流程说明

1. 本地开发：编写 Markdown 文件，使用 npm run docs:dev 本地预览
2. 推送代码：git push 到 GitHub main 分支
3. CI 构建：GitHub Actions 自动构建 Docker 镜像
4. 推送到 ACR：镜像推送到阿里云容器镜像服务
5. 自动更新：Watchtower 每 5 分钟检查 ACR，发现新镜像后自动拉取并重启容器

五、阿里云 ACR 配置

1. 创建命名空间

登录 https://cr.console.aliyun.com/ → 容器镜像服务 → 选择「个人版」→ 创建命名空间（如 blog）

2. 创建镜像仓库

• 命名空间：选择上一步创建的
• 仓库名称：blog
• 仓库类型：公开

3. 获取访问凭证

设置访问密码，保存：

• 用户名：阿里云账号
• 密码：设置的密码

4. 获取 Registry 地址

在镜像仓库列表中查看地址，格式如：

crpi-xxxxx.cn-hangzhou.personal.cr.aliyuncs.com

六、GitHub Secrets 配置

在 GitHub 仓库 → Settings → Secrets 中添加：

Secret 名称	说明	示例值
ACR_REGISTRY	ACR 地址	crpi-xxx.cn-hangzhou.personal.cr.aliyuncs.com
ACR_NAMESPACE	命名空间	blog
ACR_USERNAME	阿里云账号	你的阿里云邮箱
ACR_PASSWORD	ACR 访问密码	前面设置的密码

七、服务器部署

方式一：手动部署

# 1. 克隆或上传 docker-compose.yml 到服务器
# 2. 修改 image 地址为完整的 ACR 地址
# 3. 拉取并启动
docker-compose pull
docker-compose up -d

方式二：Watchtower 自动更新（推荐）

# 直接启动，Watchtower 会每 5 分钟自动检查更新
docker-compose up -d

# 查看日志
docker-compose logs -f

# 手动触发更新
docker-compose pull && docker-compose up -d

docker-compose.yml 配置说明

version: '3.8'

services:
  blog:
    image: your-acr-registry/blog:latest  # 修改为你的 ACR 地址
    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

八、开发指南

本地开发

# 安装依赖
npm install

# 启动开发服务器
npm run docs:dev
# 访问 http://localhost:5173

# 构建静态文件
npm run docs:build

# 本地预览构建结果
npm run docs:preview

本地 Docker 测试

# 构建镜像
docker build -t blog .

# 运行容器
docker run -p 3000:80 blog

# 访问 http://localhost:3000

写博客

在 docs/posts/ 目录下创建 .md 文件：

---
title: 文章标题
date: 2024-01-01
---

# 文章标题

内容...

九、CI/CD 工作流说明

.github/workflows/deploy.yml 工作流程：

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
            ${{ secrets.ACR_REGISTRY }}/${{ secrets.ACR_NAMESPACE }}/blog:${{ github.sha }}

十、常见问题

Q1: 如何更新博客？

1. 本地编写 Markdown 文件
2. git add . && git commit -m "update: 添加新文章"
3. git push origin main
4. 等待 CI/CD 自动构建推送
5. 约 5 分钟后 Watchtower 自动更新服务器

Q2: 如何修改主题配置？

编辑 docs/.vitepress/config.mts，修改 themeConfig 部分。

Q3: 如何添加新页面？

在 docs/ 目录下创建 .md 文件即可，支持多层目录。

十一、后续扩展

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

十二、图片托管方案（未来考虑）

当前方案：本地存储

图片存放于 docs/posts/assets/ 目录下，随代码一起提交。

优点：

• 简单、无需额外配置
• 版本控制、可追溯

缺点：

• 增加仓库体积
• 每次构建需要重新处理图片

未来可选方案

1. 阿里云 OSS（推荐）

• 与阿里云 ACR 同一生态
• 免费额度：标准存储 50GB/月
• 国内访问速度快

配置步骤：

1. 创建 OSS Bucket
2. 获取 AccessKey
3. 上传图片，使用公网链接

2. GitHub LFS

• 适合大文件存储
• 免费额度：1GB

3. CDN + 对象存储

• Cloudflare + 云存储
• 全球访问加速

4. 第三方图床

• SM.MS、ImgURL 等
• 简单但存在服务稳定性风险

推荐迁移路径

1. 当前：继续使用本地存储
2. 当图片量大或仓库变慢时 → 迁移到阿里云 OSS

---

本文档最后更新：2024