Vben Admin 部署方案总结
已完成的工作
1. ✅ 修改 Vite 配置
文件: vite.config.mts
添加了生产环境 base 路径配置：
typescript
base: process.env.NODE_ENV === 'production' ? '/web/' : '/';这确保所有静态资源在生产环境下正确指向 /web/ 路径。
2. ✅ 创建 Jenkinsfile
文件: Jenkinsfile
基于 ruoyi-office-doc 的成功经验，创建了优化的 Pipeline：
特点:
- 使用 pnpm 作为包管理器（Monorepo 支持）
- 自动检测并安装 pnpm
- 使用 Publish Over SSH 插件部署
- 6 个清晰的构建阶段
- 详细的日志输出和错误提示
- post 处理（成功/失败/清理）
阶段:
- 拉取代码
- 环境检查（Node、npm、pnpm）
- 安装依赖（pnpm install）
- 构建应用（pnpm build）
- 部署到 Nginx（Publish Over SSH）
- 验证部署
3. ✅ 创建 Nginx 配置
文件: nginx/web-antd.conf
配置要点:
location /web使用alias指向部署目录- SPA 路由支持：
try_files $uri $uri/ /web/index.html - 静态资源缓存（30天）
- Gzip 压缩
- 预留 API 代理配置（注释状态）
4. ✅ 创建完整部署文档
文件: 部署.md
内容包括:
- 项目信息和部署架构
- 详细的部署步骤（10 个步骤）
- 故障排查指南（7 个常见问题）
- 配置文件说明
- 与 ruoyi-office-doc 的对比
- 注意事项和参考文档
5. ✅ 创建辅助脚本
build-local.sh
本地构建验证脚本，用于：
- 检查 pnpm 是否安装
- 在根目录安装依赖
- 执行构建并验证产物
- 显示构建结果和下一步操作
verify-nginx-config.sh
Nginx 配置验证脚本，用于：
- 检查部署目录是否存在
- 验证 Nginx 配置是否包含 location /web
- 检查配置语法
- 测试访问
README_DEPLOY.md
快速部署指南，包含：
- 快速开始步骤
- 文件说明
- 关键配置
- 常见问题
- 对比表格
DEPLOYMENT_CHECKLIST.md
详细的部署操作清单，包含：
- 部署前检查清单
- 分步骤操作指南
- 每步的检查点
- 验证清单
- 快速修复方案
- 回滚操作
文件清单
创建/修改的文件：
ruoyi-office-vben/apps/web-antd/
├── vite.config.mts # 已修改：添加 base 配置
├── Jenkinsfile # 新建：Jenkins Pipeline 配置
├── nginx/
│ └── web-antd.conf # 新建：Nginx 配置模板
├── 部署.md # 新建：完整部署文档
├── build-local.sh # 新建：本地构建验证脚本
├── verify-nginx-config.sh # 新建：Nginx 配置验证脚本
├── README_DEPLOY.md # 新建：快速部署指南
├── DEPLOYMENT_CHECKLIST.md # 新建：部署操作清单
└── 部署总结.md # 新建：本文件部署流程图
┌─────────────────────────────────────────────────────────────┐
│ 部署流程 │
└─────────────────────────────────────────────────────────────┘
1. 准备阶段
├─ Jenkins 安装 pnpm
├─ 配置 Publish Over SSH
└─ Nginx 创建部署目录和配置
2. Jenkins Pipeline 执行
├─ 拉取代码（Git）
├─ 环境检查（Node、pnpm）
├─ 安装依赖（pnpm install）
├─ 构建应用（pnpm build）
├─ 部署文件（Publish Over SSH）
└─ 验证部署
3. 验证阶段
├─ 检查文件传输
├─ 浏览器访问测试
└─ 功能验证
4. 成功部署
└─ http://127.0.0.1/web ✅关键配置对比
与 ruoyi-office-doc 的主要区别
| 配置项 | ruoyi-office-doc | ruoyi-office-vben/web-antd |
|---|---|---|
| 包管理器 | npm | pnpm (Monorepo) |
| 构建命令 | npm run docs:build | pnpm build |
| 产物目录 | docs/.vitepress/dist | apps/web-antd/dist |
| 访问路径 | /ruoyi-office-doc | /web |
| Base 配置 | 不需要 | base: '/web/' |
| 工作目录 | 项目根目录 | apps/web-antd |
| 依赖安装 | 单项目 | Monorepo 工作空间 |
| Nginx 配置 | location /ruoyi-office-doc | location /web |
部署要点
1. Monorepo 依赖处理
由于 web-antd 依赖 workspace 中的其他包，必须：
- 在项目根目录执行
pnpm install - 使用
--frozen-lockfile确保依赖一致性 - Jenkinsfile 已正确处理
2. Base 路径配置
生产环境必须配置 base: '/web/'：
- 确保静态资源路径正确
- 开发环境使用
base: '/' - 通过
process.env.NODE_ENV区分
3. Nginx Location 配置
使用 alias 而非 root：
nginx
location /web {
alias /usr/share/nginx/html/web; # 使用 alias
try_files $uri $uri/ /web/index.html; # SPA 路由
}4. pnpm 安装
Jenkins 容器需要安装 pnpm：
- Jenkinsfile 会自动检测并安装
- 或手动安装：
npm install -g pnpm
快速开始
最简步骤
配置 Jenkins（5 分钟）
bash# 安装 pnpm docker exec jenkins npm install -g pnpm # 创建 Pipeline 任务 # 仓库: git@codeup.aliyun.com:676b69e335730943ed494c52/ruoyi-office/ruoyi-office-vben.git # 脚本: apps/web-antd/Jenkinsfile配置 Nginx（3 分钟）
bash# 创建目录 mkdir -p /data/nginx/html/web # 添加配置（参考 nginx/web-antd.conf） vi /data/nginx/conf/conf.d/default.conf # 重新加载 docker exec nginx nginx -s reload执行部署（3-5 分钟）
- Jenkins 点击"立即构建"
- 等待构建完成
访问验证
- 浏览器打开: http://127.0.0.1/web
- 验证页面正常显示
总耗时: 约 15 分钟
验证清单
部署成功的标志
- ✅ Jenkins 构建状态为成功（绿色）
- ✅ 构建日志显示所有阶段完成
- ✅ 文件已传输到
/data/nginx/html/web/ - ✅ 浏览器可以访问 http://127.0.0.1/web
- ✅ 页面显示 Vben Admin 登录界面
- ✅ 样式和静态资源正常加载
- ✅ 控制台无错误（F12 查看）
后续优化建议
1. 性能优化
- [ ] 启用 HTTP/2
- [ ] 配置 CDN
- [ ] 优化构建配置（代码分割、Tree Shaking）
- [ ] 启用 Brotli 压缩
2. 安全加固
- [ ] 配置 HTTPS（SSL 证书）
- [ ] 添加安全响应头
- [ ] 配置 CSP（内容安全策略）
- [ ] 限制访问频率
3. 监控告警
- [ ] 配置 Jenkins 构建通知
- [ ] 接入应用性能监控（APM）
- [ ] 配置 Nginx 访问日志分析
- [ ] 设置错误日志告警
4. 自动化增强
- [ ] 配置 Git Webhook 自动部署
- [ ] 添加自动化测试
- [ ] 配置多环境部署（测试/预发/生产）
- [ ] 实现灰度发布
支持文档
| 文档 | 用途 | 适用场景 |
|---|---|---|
部署.md | 完整部署指南 | 首次部署、详细了解 |
README_DEPLOY.md | 快速开始 | 快速上手、日常参考 |
DEPLOYMENT_CHECKLIST.md | 操作清单 | 执行部署、逐步检查 |
部署总结.md | 方案总结 | 了解全貌、技术决策 |
常见问题
Q1: 为什么使用 pnpm 而不是 npm？
A: 因为项目使用 Monorepo 架构，pnpm 对 workspace 支持更好，且速度更快、占用空间更小。
Q2: 为什么需要配置 base 路径？
A: 因为应用部署在 /web 子路径下，不配置 base 会导致静态资源路径错误（404）。
Q3: 可以不使用 Publish Over SSH 插件吗？
A: 可以，可以使用 sshagent + tar + ssh 方式，但 Publish Over SSH 更简洁、日志更清晰。
Q4: 构建需要多长时间？
A: 首次构建约 3-5 分钟（需要安装依赖），后续构建约 2-3 分钟。
Q5: 如何回滚到上一个版本？
A: 参考 DEPLOYMENT_CHECKLIST.md 中的回滚操作部分。
成功案例
参考 ruoyi-office-doc 的成功部署经验：
- ✅ 使用 Publish Over SSH 插件
- ✅ 清晰的阶段划分
- ✅ 详细的日志输出
- ✅ 完善的错误处理
现在应用到 Vben Admin 项目，并针对 Monorepo 和 Vue SPA 特点进行了优化。
联系方式
如有问题，请：
- 查看相关文档
- 检查 Jenkins 构建日志
- 检查 Nginx 错误日志
- 参考故障排查部分
部署方案已完成，祝部署顺利！ 🚀
