站点部署与运维方案
技术栈概述
- 静态站点生成器：VitePress 2.0.0-alpha.17
- 包管理器：pnpm
- 构建工具：Vite + Rollup
- 主题：自定义 VitePress 主题
- 部署目标：GitHub Pages 或其他静态托管服务
本地开发环境
环境要求
- Node.js >= 18.0.0
- pnpm >= 8.0.0
- Git >= 2.30.0
安装依赖
bash
pnpm install本地开发
bash
# 启动开发服务器
pnpm run docs:dev
# 默认访问地址：http://localhost:5174/构建生产版本
bash
# 构建静态站点
pnpm run docs:build
# 预览构建结果
pnpm run docs:preview部署方案
GitHub Pages 自动部署
方法一：GitHub Actions
在 .github/workflows/deploy.yml 中配置：
yaml
name: Deploy to GitHub Pages
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'pnpm'
- name: Setup pnpm
run: npm install -g pnpm
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Build
run: pnpm run docs:build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: docs/.vitepress/dist方法二：手动部署
bash
# 1. 构建站点
pnpm run docs:build
# 2. 推送到 gh-pages 分支
git checkout -b gh-pages
git add -f docs/.vitepress/dist
git commit -m "Deploy to GitHub Pages"
git push origin gh-pages
# 3. 在 GitHub 仓库设置中启用 Pages
# Source: Deploy from a branch
# Branch: gh-pages / (root)其他部署选项
Vercel
- 连接 GitHub 仓库
- 设置构建命令：
pnpm run docs:build - 设置输出目录：
docs/.vitepress/dist - 自动部署
Netlify
- 连接 GitHub 仓库
- 设置构建命令：
pnpm run docs:build - 设置发布目录：
docs/.vitepress/dist - 自动部署
运维维护
定期维护任务
每周检查
- [ ] 验证构建状态：
pnpm run docs:build - [ ] 检查死链：运行
pnpm run docs:build查看警告 - [ ] 更新依赖：
pnpm update - [ ] 检查 SEO：验证 robots.txt 和 sitemap.xml
每月维护
- [ ] 清理 node_modules：
rm -rf node_modules && pnpm install - [ ] 更新 VitePress：
pnpm update vitepress - [ ] 验证所有页面可访问
- [ ] 检查性能：页面加载时间 < 3秒
监控与告警
构建监控
- GitHub Actions 状态检查
- 构建日志分析
- 错误邮件通知
内容监控
- 定期检查外部链接有效性
- OCR 资料完整性验证
- 文档状态更新跟踪
备份策略
- 代码仓库：GitHub 主分支
- 构建产物：GitHub Pages 分支
- 资料备份：定期导出 docs/ 目录
- 配置备份：package.json, vitepress 配置
故障排除
常见问题
构建失败
问题：ENOTEMPTY 或 EPERM 错误
解决：
bash
# Windows
rd /s /q docs\.vitepress\dist
# Linux/Mac
rm -rf docs/.vitepress/dist端口冲突
问题：Port 5173 is in use
解决：
bash
# 指定端口
pnpm run docs:dev --port 5175依赖问题
问题：安装依赖失败
解决：
bash
# 清理缓存
pnpm store prune
rm -rf node_modules
pnpm install性能优化
构建优化
- 启用
--minify（默认启用） - 配置
build.rollupOptions.output.manualChunks - 使用动态导入减少包体积
运行时优化
- 启用本地搜索缓存
- 优化图片资源
- 配置 CDN 加速
版本管理
版本号规则
- 主版本：重大功能更新
- 次版本：内容更新
- 修订版本：错误修复
更新日志
更新日志保存在 docs/维护与报告/更新日志/ 目录下，按版本号命名。
联系与支持
- 维护者：Azek431
- 仓库地址：https://github.com/Azek431/cysj-data
- 问题反馈：GitHub Issues
- 贡献指南：
docs/维护与报告/社区贡献与维护指南.md - 支持自动构建与分支预览。
- 推荐命令同上。
方案 C：阿里云 OSS + CDN
- 适合国内访问优化。
- 将静态构建产物上传到 OSS，并绑定 CDN 域名。
- 适用场景：需稳定国内访问且有备案的站点。
自动构建方案
GitHub Actions 示例
yaml
name: deploy-docs
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v2
with:
version: 8
- run: pnpm install
- run: pnpm run docs:build
- run: echo "部署到你的托管平台或上传至 OSS"资源与性能优化
- 启用 VitePress 的
cleanUrls和本地搜索。 - 静态资源建议压缩，并通过 CDN 分发。
- 图片资源建议使用
docs/public/静态资源目录，避免运行时热加载。
容灾与备份
- 代码仓库即是最重要的备份。
- 若使用 Vercel/Netlify，可启用自动构建历史；若使用 OSS/CDN，应定期保存构建产物快照。
- 站点出现故障时，优先回滚到上一个可用 commit。
停更与应急预案
- 若维护者停止更新，应在
docs/关于.md和仓库 README 中声明当前停止维护状态。 - 保留最近 3 个版本的构建产物和部署日志。
- 备用方案：将仓库调整为纯静态备份页面，保留核心导航与说明。