# 部署文档 ## 📦 部署准备 ### 环境要求 - **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. 建立完整的监控告警机制