# 部署文档

## 部署概述

本文档介绍如何将项目部署到生产环境。项目支持多种部署方式，包括静态文件部署、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
<!-- DNS 预解析 -->
<link rel="dns-prefetch" href="https://api.yourdomain.com">

<!-- 预连接 -->
<link rel="preconnect" href="https://api.yourdomain.com">

<!-- 预加载关键资源 -->
<link rel="preload" href="/assets/main.js" as="script">
<link rel="preload" href="/assets/main.css" as="style">
```

### 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
<!-- 在 index.html 中添加 -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_MEASUREMENT_ID');
</script>
```

#### 自定义性能监控

```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 <commit-hash>
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. 回滚检查清单

- [ ] 确认回滚原因和影响范围
- [ ] 备份当前版本
- [ ] 执行回滚操作
- [ ] 验证功能正常
- [ ] 通知相关人员
- [ ] 记录回滚日志

