# 部署文档
## 部署概述
本文档介绍如何将项目部署到生产环境。项目支持多种部署方式,包括静态文件部署、Docker 部署等。
## 前置要求
- Node.js >= 16.0.0
- npm >= 7.0.0 或 yarn
- Web 服务器(Nginx、Apache、IIS 等)或 Docker(可选)
## 构建生产版本
### 1. 配置生产环境变量
在项目根目录创建 `.env.production` 文件:
```env
# API 基础路径(生产环境)
VITE_API_URL=https://your-api-domain.com/api/
# 公共路径(根据部署路径配置)
# 如果部署在根目录,使用: /
# 如果部署在子目录,使用: /subdirectory/
VITE_PUBLIC_PATH=/
# 构建输出目录
VITE_DIST_PATH=dist
```
### 2. 执行构建命令
```bash
# 标准生产构建
npm run build
# 或使用 yarn
yarn build
```
构建完成后,生成的文件位于 `dist/` 目录。
### 3. 构建输出说明
构建后的 `dist/` 目录结构:
```
dist/
├── assets/ # 静态资源(JS、CSS、图片等)
│ ├── index.[hash].js
│ ├── index.[hash].css
│ └── ...
├── index.html # 入口 HTML 文件
├── favicon.ico # 网站图标
└── version-build # 版本文件(用于版本检查)
```
## 构建优化
### 1. 构建分析
分析构建产物大小,优化打包体积:
```bash
# 安装分析插件
npm install --save-dev rollup-plugin-visualizer
# 在 vite.config.ts 中添加配置
import { visualizer } from 'rollup-plugin-visualizer';
export default defineConfig({
plugins: [
// ...其他插件
visualizer({
open: true,
gzipSize: true,
brotliSize: true,
}),
],
});
# 构建后会自动打开分析页面
npm run build
```
### 2. 代码分割优化
项目已配置代码分割(`vite.config.ts`):
```typescript
manualChunks: {
vue: ['vue', 'vue-router', 'pinia'],
echarts: ['echarts'],
}
```
可以根据实际情况调整分割策略。
### 3. 压缩优化
Vite 默认会压缩代码,可以通过配置进一步优化:
```typescript
build: {
minify: 'terser', // 使用 terser 压缩(需要安装 terser)
terserOptions: {
compress: {
drop_console: true, // 生产环境移除 console
drop_debugger: true, // 移除 debugger
},
},
}
```
## 环境变量配置
### 生产环境变量
在部署前,确保正确配置 `.env.production`:
```env
# API 地址(必须配置为生产环境的后端地址)
VITE_API_URL=https://api.yourdomain.com/api/
# 公共路径
# 根目录部署: /
# 子目录部署: /subdirectory/
VITE_PUBLIC_PATH=/
# 构建输出目录
VITE_DIST_PATH=dist
```
### 多环境部署
如果需要支持多个环境(开发、测试、生产),可以创建不同的环境文件:
- `.env.development` - 开发环境
- `.env.staging` - 测试环境
- `.env.production` - 生产环境
构建时指定环境:
```bash
# 构建测试环境
vite build --mode staging
# 构建生产环境
vite build --mode production
```
## 部署检查清单
- [ ] 环境变量已正确配置(`.env.production`)
- [ ] 已执行生产构建(`npm run build`)
- [ ] 构建产物已上传到服务器
- [ ] Web 服务器配置正确(支持 SPA 路由)
- [ ] API 地址配置正确(后端服务可访问)
- [ ] HTTPS 已配置(生产环境推荐)
- [ ] 静态资源缓存策略已配置
- [ ] Gzip 压缩已启用
- [ ] 安全头已配置
- [ ] 跨域问题已解决(如需要)
- [ ] 版本检查功能正常
## HTTPS 配置详解
### 1. 使用 Let's Encrypt 免费证书
```bash
# 安装 Certbot
sudo apt-get update
sudo apt-get install certbot python3-certbot-nginx
# 获取证书(自动配置 Nginx)
sudo certbot --nginx -d your-domain.com -d www.your-domain.com
# 测试自动续期
sudo certbot renew --dry-run
# 证书会自动续期(通过 cron 任务)
```
### 2. 手动配置 SSL 证书
如果使用其他证书提供商:
```nginx
server {
listen 443 ssl http2;
server_name your-domain.com;
# SSL 证书路径
ssl_certificate /path/to/certificate.crt;
ssl_certificate_key /path/to/private.key;
# SSL 证书链(如果提供)
# ssl_trusted_certificate /path/to/chain.crt;
# SSL 优化配置
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
ssl_stapling on;
ssl_stapling_verify on;
# HSTS(HTTP Strict Transport Security)
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
}
```
### 3. SSL 测试
使用在线工具测试 SSL 配置:
- [SSL Labs](https://www.ssllabs.com/ssltest/)
- [SSL Checker](https://www.sslshopper.com/ssl-checker.html)
## 性能优化建议
### 1. 启用 Gzip 压缩
参考上述 Nginx/Apache 配置示例。
**压缩效果检查**:
```bash
# 检查响应头是否包含 Content-Encoding: gzip
curl -H "Accept-Encoding: gzip" -I https://your-domain.com
```
### 2. 启用 Brotli 压缩(更高效)
```nginx
# 安装 Brotli 模块
# Ubuntu/Debian
sudo apt-get install nginx-module-brotli
# 在 nginx.conf 中加载模块
load_module modules/ngx_http_brotli_filter_module.so;
load_module modules/ngx_http_brotli_static_module.so;
# 配置 Brotli
brotli on;
brotli_comp_level 6;
brotli_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
```
### 3. 配置静态资源缓存
```nginx
# Nginx 示例
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
# 启用压缩
gzip_static on;
brotli_static on;
}
# HTML 文件不缓存
location ~* \.html$ {
expires -1;
add_header Cache-Control "no-cache, no-store, must-revalidate";
add_header Pragma "no-cache";
}
```
### 4. CDN 加速
将静态资源(JS、CSS、图片)部署到 CDN,提升加载速度。
**CDN 选择建议**:
- 国内: 阿里云 CDN、腾讯云 CDN、七牛云
- 国外: Cloudflare、AWS CloudFront、Fastly
**CDN 配置要点**:
- 设置合适的缓存策略
- 配置 HTTPS
- 启用 HTTP/2
- 配置回源规则
### 5. 代码分割和懒加载
项目已配置代码分割(`vite.config.ts` 中的 `manualChunks`),将 Vue 核心库和 ECharts 单独打包。
**路由懒加载**:
```typescript
// 路由配置中使用动态导入
const routes = [
{
path: '/company',
component: () => import('/@/views/system/company/index.vue'),
},
];
```
### 6. 图片优化
- 使用 WebP 格式(现代浏览器)
- 压缩图片大小
- 使用响应式图片(srcset)
- 懒加载图片(Intersection Observer)
### 7. 预加载关键资源
在 `index.html` 中添加:
```html
```
### 8. 性能监控
使用性能监控工具:
- **Google Analytics**: 页面性能分析
- **Google PageSpeed Insights**: 性能评分
- **WebPageTest**: 详细性能分析
- **Lighthouse**: Chrome DevTools 内置工具
## CI/CD 持续集成部署
### 1. GitHub Actions 配置
创建 `.github/workflows/deploy.yml`:
```yaml
name: Build and Deploy
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
env:
VITE_API_URL: ${{ secrets.VITE_API_URL }}
VITE_PUBLIC_PATH: ${{ secrets.VITE_PUBLIC_PATH }}
- name: Deploy to server
uses: easingthemes/ssh-deploy@main
env:
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
REMOTE_USER: ${{ secrets.REMOTE_USER }}
SOURCE: "dist/"
TARGET: "/var/www/zheda-admin/"
```
### 2. GitLab CI 配置
创建 `.gitlab-ci.yml`:
```yaml
stages:
- build
- deploy
build:
stage: build
image: node:18
script:
- npm ci
- npm run build
artifacts:
paths:
- dist/
expire_in: 1 hour
deploy:
stage: deploy
image: alpine:latest
before_script:
- apk add --no-cache openssh-client
- eval $(ssh-agent -s)
- echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
- mkdir -p ~/.ssh
- chmod 700 ~/.ssh
script:
- scp -r dist/* $DEPLOY_USER@$DEPLOY_HOST:/var/www/zheda-admin/
only:
- main
```
### 3. Jenkins 配置
创建 `Jenkinsfile`:
```groovy
pipeline {
agent any
environment {
NODE_VERSION = '18'
}
stages {
stage('Checkout') {
steps {
checkout scm
}
}
stage('Install') {
steps {
sh 'npm ci'
}
}
stage('Build') {
steps {
sh 'npm run build'
}
}
stage('Deploy') {
steps {
sh '''
rsync -avz --delete dist/ user@server:/var/www/zheda-admin/
'''
}
}
}
}
```
#### 日志轮转配置
创建 `/etc/logrotate.d/nginx`:
```
/var/log/nginx/*.log {
daily
missingok
rotate 52
compress
delaycompress
notifempty
create 0640 www-data adm
sharedscripts
postrotate
[ -f /var/run/nginx.pid ] && kill -USR1 `cat /var/run/nginx.pid`
endscript
}
```
### 3. 性能监控
使用性能监控工具分析页面性能。
#### Google Analytics
```html
```
#### 自定义性能监控
```typescript
// 监控页面加载性能
window.addEventListener('load', () => {
const perfData = performance.getEntriesByType('navigation')[0];
console.log('DNS查询耗时:', perfData.domainLookupEnd - perfData.domainLookupStart);
console.log('TCP连接耗时:', perfData.connectEnd - perfData.connectStart);
console.log('请求耗时:', perfData.responseEnd - perfData.requestStart);
console.log('DOM解析耗时:', perfData.domContentLoadedEventEnd - perfData.domContentLoadedEventStart);
console.log('页面加载耗时:', perfData.loadEventEnd - perfData.fetchStart);
});
```
## 常见问题
### 1. 页面刷新 404
**问题**: 刷新页面或直接访问路由时出现 404
**原因**: Web 服务器未配置 SPA 路由支持
**解决方案**: 参考上述 Nginx/Apache/IIS 配置,确保所有路由都指向 `index.html`
### 2. API 请求失败
**问题**: 前端无法访问后端 API
**解决方案**:
- 检查 `VITE_API_URL` 配置是否正确
- 检查后端服务是否正常运行
- 检查跨域配置(CORS)
- 检查网络防火墙设置
### 3. 静态资源加载失败
**问题**: CSS、JS 文件加载失败
**解决方案**:
- 检查 `VITE_PUBLIC_PATH` 配置是否正确
- 检查 Web 服务器配置
- 检查文件路径是否正确
### 4. 版本更新后用户看不到新版本
**问题**: 用户浏览器缓存了旧版本
**解决方案**:
- 项目已集成版本检查功能,会自动提示用户刷新
- 可以配置更激进的缓存策略,确保 HTML 文件不被缓存
```nginx
# HTML 文件不缓存
location ~* \.html$ {
expires -1;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
```
## 备份和恢复
### 1. 备份策略
#### 文件备份
```bash
# 创建备份脚本 backup.sh
#!/bin/bash
BACKUP_DIR="/backup/zheda-admin"
DATE=$(date +%Y%m%d_%H%M%S)
DEPLOY_DIR="/var/www/zheda-admin"
# 创建备份目录
mkdir -p $BACKUP_DIR
# 备份部署文件
tar -czf $BACKUP_DIR/zheda-admin_$DATE.tar.gz -C $DEPLOY_DIR .
# 保留最近 7 天的备份
find $BACKUP_DIR -name "zheda-admin_*.tar.gz" -mtime +7 -delete
echo "备份完成: $BACKUP_DIR/zheda-admin_$DATE.tar.gz"
```
#### 自动化备份
使用 cron 定时任务:
```bash
# 编辑 crontab
crontab -e
# 每天凌晨 2 点备份
0 2 * * * /path/to/backup.sh >> /var/log/backup.log 2>&1
```
### 2. 恢复流程
```bash
# 停止服务(如果需要)
sudo systemctl stop nginx
# 恢复备份
cd /var/www/zheda-admin
tar -xzf /backup/zheda-admin_20240101_020000.tar.gz
# 重启服务
sudo systemctl start nginx
# 验证恢复
curl -I https://your-domain.com
```
### 3. 版本管理
使用 Git 标签管理版本:
```bash
# 创建版本标签
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0
# 查看所有标签
git tag
# 切换到指定版本
git checkout v1.0.0
```
## 回滚方案
如果部署后出现问题,可以快速回滚:
### 1. 快速回滚(保留旧版本)
部署前备份当前版本:
```bash
# 部署前备份
cp -r /var/www/zheda-admin /var/www/zheda-admin.backup.$(date +%Y%m%d_%H%M%S)
# 部署新版本
rsync -avz --delete dist/ /var/www/zheda-admin/
# 如果出现问题,快速回滚
rm -rf /var/www/zheda-admin
cp -r /var/www/zheda-admin.backup.* /var/www/zheda-admin
```
### 2. Git 版本回滚
```bash
# 查看提交历史
git log --oneline
# 回滚到指定版本
git checkout
npm run build
# 重新部署
rsync -avz --delete dist/ /var/www/zheda-admin/
```
### 3. 蓝绿部署
使用蓝绿部署策略,实现零停机回滚:
```bash
# 部署到绿色环境
rsync -avz --delete dist/ /var/www/zheda-admin-green/
# 测试绿色环境
curl https://green.your-domain.com
# 切换流量(更新 Nginx 配置)
sudo nginx -s reload
# 如果出现问题,立即切换回蓝色环境
```
### 4. 回滚检查清单
- [ ] 确认回滚原因和影响范围
- [ ] 备份当前版本
- [ ] 执行回滚操作
- [ ] 验证功能正常
- [ ] 通知相关人员
- [ ] 记录回滚日志