# 部署文档

## 📦 部署准备

### 环境要求
- **Node.js**: >= 16.0.0
- **npm**: >= 7.0.0
- **Web服务器**: Nginx / Apache
- **后端API**: Django (参考后端部署文档)

### 构建产物
```bash
npm run build
```
构建完成后，生成的文件在 `dist/` 目录下。

## 🚀 部署方式

### 方式一：静态文件部署

#### 1. 构建项目
```bash
# 安装依赖
npm install

# 构建生产版本
npm run build
```

#### 2. 部署到 Nginx
```nginx
server {
    listen 80;
    server_name example.com;
    
    root /path/to/dist;
    index index.html;
    
    # Vue Router 历史模式支持
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # API 代理
    location /api {
        proxy_pass http://backend:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    
    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml text/javascript 
               application/x-javascript application/xml+rss 
               application/javascript application/json;
}
```

#### 3. 配置生产环境变量
创建 `.env.production` 文件：
```env
# 生产环境配置
VITE_API_URL=https://api.example.com
VITE_PUBLIC_PATH=/
VITE_PORT=443
VITE_OUTPUT_DIR=dist
```

### 方式二：Docker 部署

#### 1. 创建 Dockerfile
```dockerfile
FROM node:16-alpine AS builder

WORKDIR /app

# 复制依赖文件
COPY package*.json ./

# 安装依赖
RUN npm ci

# 复制源代码
COPY . .

# 构建
RUN npm run build

# 生产环境
FROM nginx:alpine

# 复制构建产物
COPY --from=builder /app/dist /usr/share/nginx/html

# 复制 nginx 配置
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]
```

#### 2. 创建 docker-compose.yml
```yaml
version: '3.8'

services:
  web:
    build: .
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - backend
    restart: unless-stopped

  backend:
    image: django-backend:latest
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=mysql://user:password@db:3306/dbname
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=password
      - MYSQL_DATABASE=dbname
    volumes:
      - mysql_data:/var/lib/mysql
    restart: unless-stopped

volumes:
  mysql_data:
```

#### 3. 启动服务
```bash
docker-compose up -d
```

### 方式三：CDN 部署

#### 1. 使用对象存储
支持阿里云 OSS、腾讯云 COS、AWS S3 等。

#### 2. 配置要点
- 开启静态网站托管
- 配置 HTTPS
- 配置自定义域名
- 配置缓存策略
- 开启 CDN 加速

#### 3. 上传文件
```bash
# 安装工具（以阿里云 OSS 为例）
npm install -g ossutil

# 同步文件
ossutil cp -r dist/ oss://bucket-name/
```

## ⚙️ 环境变量配置

### 开发环境
`.env.development`
```env
VITE_API_URL=http://localhost:8000
VITE_PUBLIC_PATH=/
VITE_PORT=8080
```

### 生产环境
`.env.production`
```env
VITE_API_URL=https://api.example.com
VITE_PUBLIC_PATH=/
VITE_PORT=443
```

### 本地生产环境
`.env.local_prod`
```env
VITE_API_URL=http://localhost:8000
VITE_PUBLIC_PATH=/
VITE_PORT=8080
```

## 🔧 Nginx 详细配置

### 完整配置示例
```nginx
# 用户
user nginx;

# 工作进程数
worker_processes auto;

# 错误日志
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # 日志格式
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

    access_log /var/log/nginx/access.log main;

    # 基本设置
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;

    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml text/javascript
               application/json application/javascript application/xml+rss
               application/rss+xml font/truetype font/opentype
               application/vnd.ms-fontobject image/svg+xml;

    # 服务器配置
    server {
        listen 80;
        server_name example.com;
        root /usr/share/nginx/html;
        index index.html;

        # 网站根目录
        location / {
            try_files $uri $uri/ /index.html;
        }

        # API 代理
        location /api {
            proxy_pass http://127.0.0.1:8000;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_cache_bypass $http_upgrade;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }

        # 静态资源
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }

        # 禁止访问隐藏文件
        location ~ /\. {
            deny all;
            access_log off;
            log_not_found off;
        }
    }

    # HTTPS 配置
    server {
        listen 443 ssl http2;
        server_name example.com;

        ssl_certificate /path/to/cert.pem;
        ssl_certificate_key /path/to/key.pem;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers on;

        # 其他配置同 HTTP
    }
}
```

## 🔒 HTTPS 配置

### 使用 Let's Encrypt
```bash
# 安装 certbot
sudo apt-get install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d example.com

# 自动续期
sudo certbot renew --dry-run
```

### 使用阿里云 SSL 证书
1. 在阿里云控制台申请免费证书
2. 下载证书文件
3. 配置 Nginx

## 📊 性能优化

### 1. 开启 HTTP/2
```nginx
listen 443 ssl http2;
```

### 2. 启用 Gzip 压缩
见 Nginx 配置示例

### 3. 静态资源缓存
```nginx
location ~* \.(js|css)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}
```

### 4. 代码分割
Vite 已自动配置代码分割，生产环境会自动生成多个 chunk。

### 5. CDN 加速
- 将静态资源上传到 CDN
- 修改 `vite.config.ts` 中的 `base` 配置
- 配置 CDN 域名

## 🐛 故障排查

### 1. 页面白屏
- 检查控制台错误信息
- 检查路由配置
- 检查 API 地址配置

### 2. API 请求失败
- 检查后端服务是否正常运行
- 检查 Nginx 代理配置
- 检查跨域配置

### 3. 静态资源 404
- 检查 `VITE_PUBLIC_PATH` 配置
- 检查 Nginx root 配置
- 检查文件权限

### 4. 路由刷新 404
- 确保 Nginx 配置了 `try_files $uri $uri/ /index.html;`

## 📝 监控和维护

### 1. 日志查看
```bash
# Nginx 访问日志
tail -f /var/log/nginx/access.log

# Nginx 错误日志
tail -f /var/log/nginx/error.log

# 系统日志
journalctl -u nginx -f
```

### 2. 性能监控
- 使用 Google Analytics
- 使用 APM 工具
- 监控服务器资源使用

### 3. 定期维护
- 定期更新依赖
- 定期备份数据
- 监控错误日志
- 优化性能

## 🔄 更新部署

### 1. 更新前端
```bash
# 拉取最新代码
git pull origin master

# 安装新依赖
npm install

# 重新构建
npm run build

# 重启服务
sudo systemctl restart nginx
```

### 2. 回滚版本
```bash
# 切换到旧版本
git checkout v1.0.0

# 重新构建
npm run build

# 重启服务
sudo systemctl restart nginx
```

## ✅ 部署检查清单

### 部署前检查
- [ ] 环境变量已配置正确
- [ ] 后端 API 服务正常运行
- [ ] 数据库连接正常
- [ ] 静态资源已构建完成
- [ ] 域名解析已配置
- [ ] SSL 证书已安装（如需 HTTPS）

### 部署后检查
- [ ] 前端页面可以正常访问
- [ ] API 请求可以正常响应
- [ ] 静态资源加载正常
- [ ] 路由跳转正常
- [ ] 登录功能正常
- [ ] 文件上传功能正常
- [ ] 跨域配置正确

### 性能检查
- [ ] 页面加载速度 < 3 秒
- [ ] API 响应时间 < 1 秒
- [ ] Gzip 压缩已启用
- [ ] 静态资源已缓存
- [ ] CDN 加速已配置（如使用）

### 安全检查
- [ ] HTTPS 已启用
- [ ] 敏感信息不暴露在客户端
- [ ] 接口权限验证正常
- [ ] SQL 注入防护已配置
- [ ] XSS 攻击防护已配置

## 🔍 部署故障排查表

| 问题现象 | 可能原因 | 解决方案 |
|---------|---------|---------|
| 页面白屏 | JS 文件路径错误 | 检查 VITE_PUBLIC_PATH 配置 |
| API 404 | 后端服务未启动 | 启动后端服务 |
| 静态资源 404 | 文件权限问题 | chmod 755 静态文件 |
| 路由刷新 404 | Nginx 配置错误 | 检查 try_files 配置 |
| CORS 错误 | 跨域配置错误 | 配置后端 CORS |
| 登录失败 | Token 验证失败 | 检查 JWT 配置 |

## 📊 监控指标

### 性能监控
- **页面加载时间**：应 < 3 秒
- **API 响应时间**：应 < 1 秒
- **首屏渲染时间**：应 < 2 秒
- **资源加载时间**：应 < 5 秒

### 业务监控
- **每日访问量**：UV/PV 统计
- **API 调用次数**：接口监控
- **错误率**：异常统计
- **用户活跃度**：DAU/MAU

### 服务器监控
- **CPU 使用率**：应 < 80%
- **内存使用率**：应 < 85%
- **磁盘使用率**：应 < 90%
- **网络流量**：监控带宽使用

## 🔄 自动化部署示例

### GitHub Actions 部署
```yaml
name: Deploy

on:
  push:
    branches: [ master ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '16'
    - name: Install dependencies
      run: npm install
    - name: Build
      run: npm run build
    - name: Deploy to server
      uses: easingthemes/ssh-deploy@v2
      with:
        SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
        ARGS: "-rltgoDzvO"
        SOURCE: "dist/"
        REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
        REMOTE_USER: ${{ secrets.REMOTE_USER }}
        TARGET: "/var/www/html/"
```

---

**部署注意事项**：
1. 确保后端 API 服务正常运行
2. 配置正确的环境变量
3. 确保 HTTPS 配置正确
4. 定期备份重要数据
5. 监控服务器资源使用情况
6. 建立完整的监控告警机制

